你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

在 GitHub 或 Azure Repos 中添加和配置目录

本文说明了如何在 Azure 部署环境开发人员中心或项目中添加和配置目录

目录可用于为开发团队提供一组精选的基础结构即代码 (IaC) 模板(即环境定义)来创建环境。 可以从 GitHub 或 Azure Repos 附加你自己的源代码管理存储库作为目录,并使用环境定义指定文件夹。 部署环境将扫描文件夹以获取环境定义,使其可供开发团队创建环境。

为了进一步保护模板,将会对目录进行加密;Azure 部署环境支持使用平台托管的加密密钥进行静态加密,这些密钥由 Microsoft 为 Azure 服务托管。

  • 若要了解如何在 GitHub 中托管存储库,请参阅 GitHub 入门
  • 若要了解如何在 Azure Repos 项目中托管 Git 存储库,请参阅 Azure Repos

Microsoft 提供了一个可以添加到开发人员中心或项目的快速启动目录,以及一个可以用作存储库的示例目录 你也可以使用自己的专用存储库,或者对示例目录中的环境定义创建分支并进行自定义。

在本文中,学习如何:

  1. 配置项目级目录
  2. 配置托管标识
  3. 从 Azure Repos 或 GitHub 添加目录
  4. 更新目录
  5. 删除目录
  6. 排查目录同步错误

配置项目级目录

在项目级别附加目录使平台工程师能够提供特定于开发团队的精选环境定义。 此外,它还使被指定为项目管理员的开发团队主管能够管理为其团队提供的环境定义。

平台工程师可以完全控制项目级的目录的使用。 必须先在开发人员中心级别启用项目级别目录的使用,然后才能将目录添加到项目中。 平台工程师还可以配置可以在项目级别使用哪些类型的目录项,例如环境定义。

默认情况下,禁用项目级别的目录的使用,并且未启用任何目录项类型。 项目级别目录中的环境定义在两种情况下同步并可用。 首先,必须在相应的开发中心级别启用基于项目的目录。 其次,必须启用项目的环境定义。

将目录添加到项目

必须先在开发中心级别启用项目级别目录,然后才能将目录添加到项目。 还应在项目级别启用环境定义。

在开发中心级别启用项目级别目录:

  1. Azure 门户中,导航到开发人员中心。

  2. 在左侧菜单中的“设置”下选择“配置”

    屏幕截图显示开发中心的“概述”页,其中突出显示了“配置”。

  3. 在“项目级别目录”窗格中,选择“为每个项目启用目录”,然后选择“应用”

    屏幕截图显示“项目级别目录”窗格,其中突出显示了“为每个项目启用目录”。

在项目中启用环境定义:

  1. Azure 门户中导航到你的项目。

  2. 在左侧菜单中的“设置”下,选择“目录”。

    屏幕截图显示项目的“概述”页,其中突出显示了“目录”。

  3. 在“目录”页上,选择“目录项权限”

    屏幕截图显示“目录”窗格,其中突出显示了“目录项权限”。

  4. 在“目录项设置”窗格中选择“Azure 部署环境定义”,以便在项目级别启用环境定义。

    屏幕截图显示“目录项设置”窗格,其中选择了“Azure 部署环境定义”。

现在可以向项目添加目录了。

对于使用托管标识或个人访问令牌 (PAT) 进行身份验证的目录,必须为项目分配托管标识。 对于使用 PAT 的目录,必须将 PAT 存储在密钥保管库中,并授予托管标识对密钥保管库机密的访问权限。

配置托管标识

在将目录附加到开发人员中心或项目之前,必须先配置托管标识(也称为托管服务标识 (MSI))。 可以附加系统分配的托管标识(系统分配的 MSI)或用户分配的托管标识(用户分配的 MSI)。 然后,将角色分配给托管标识,以允许开发人员中心或项目在订阅中创建环境类型,并读取包含目录存储库的 Azure Repos 项目。

如果开发人员中心或项目未附加 MSI,请按照配置托管标识中的步骤创建一个,然后分配托管标识的角色。

要详细了解托管标识,请参阅什么是 Azure 资源的托管标识?

添加目录

可以从 Azure Repos 存储库或 GitHub 存储库添加目录。 可以选择通过向 MSI 分配权限或使用存储在密钥保管库中的 PAT 进行身份验证。

为要使用的存储库和身份验证类型选择选项卡。

要添加目录,请完成以下任务:

  • 在 Azure Repos 中为托管标识分配权限。
  • 将存储库作为目录添加。

在 Azure Repos 中为托管标识分配权限

必须向托管标识授予 Azure Repos 中存储库的权限。

  1. 登录到你的 Azure DevOps 组织

    注意

    Azure DevOps 组织必须与包含开发人员中心或项目的 Azure 订阅位于同一目录中。

  2. 选择 “组织设置”。

    屏幕截图显示 Azure DevOps 组织页面,其中突出显示了“组织设置”。

  3. 在“概述”页上,选择“用户”。

    屏幕截图显示“组织概述”页面,其中突出显示了“用户”。

  4. 在“用户”页上,选择“添加用户”。

    屏幕截图显示“用户”页面,其中突出显示了“添加用户”。

  5. 输入或选择以下信息完成“添加新用户”,然后选择“添加”:

    名称
    用户或服务主体 输入开发人员中心或项目的名称。
    使用系统分配的 MSI 时,请指定开发人员中心或项目的名称,而不是托管帐户的对象 ID。 使用用户分配的 MSI 时,请使用托管帐户的名称。
    访问级别 选择“基本”。
    添加到项目 选择包含存储库的项目。
    Azure DevOps 组 选择“项目读取者”。
    发送电子邮件邀请(仅限用户) 清除该复选框。

    屏幕截图显示“添加用户”,其中突出显示了示例条目和“添加”。

将存储库作为目录添加

Azure 部署环境支持附加 Azure Repos 存储库和 GitHub 存储库。 你可以将一组特选的 IaC 模板存储在存储库中。 将存储库作为目录附加到开发人员中心或项目,使开发团队能够访问模板,并使其能够快速创建一致的环境。

借助以下步骤,可以附加 Azure Repos 存储库。

  1. Azure 门户中,导航到开发人员中心或项目。

  2. 在左侧菜单中的“环境配置”下选择“目录”,然后选择“添加”。

    显示“目录”窗格的屏幕截图。

  3. 在“添加目录”中,输入以下信息,然后选择“添加”:

    字段
    名称 输入目录的名称。
    目录位置 选择“Azure DevOps”。
    身份验证类型 选择“托管标识”。
    组织 选择 Azure DevOps 组织。
    Project 从项目列表中,选择存储存储库的项目。
    存储库 从存储库列表中,选择要添加的存储库。
    分支 选择分支。
    文件夹路径 Dev Box 检索分支中的文件夹列表。 选择存储 IaC 模板的文件夹。

    屏幕截图显示“添加目录”窗格,其中突出显示了示例条目和“添加”。

  4. 在开发人员中心或项目的“目录”中,验证目录是否显示。 连接成功后,“状态”会显示为“同步成功”。 首次连接到目录可能需要几分钟时间。

查看同步的目录项

无论使用的存储库类型如何,都可以查看从目录中同步的目录项。

  1. 在开发人员中心或项目的左侧菜单中的“环境配置”下,选择“目录”

  2. 在“目录”窗格中,选择目录名称

    显示“目录”窗格的屏幕截图,其中突出显示了附加的目录名称。

  3. 你将看到已成功同步的目录项的列表。

    显示从附加目录成功同步的目录项的屏幕截图。

更新目录

如果更新附加存储库中的定义或模板内容,则可通过同步目录向开发团队提供最新的环境定义集。 可以手动或自动同步目录。

手动同步目录

手动同步目录时,部署环境将扫描存储库,并向开发人员中心内所有关联项目提供最新的环境定义列表。

  1. 在开发人员中心的左侧菜单中的“环境配置”下,选择“目录”

  2. 选择特定目录,然后在命令栏中选择“同步”

    显示命令栏中的“同步”按钮的屏幕截图。

自动同步目录

将目录配置为自动同步时,部署环境将每 30 分钟扫描一次存储库,并向开发人员中心内所有关联项目提供最新的环境定义列表。

  1. 在开发人员中心或项目的左侧菜单中的“环境配置”下,选择“目录”

  2. 选择特定目录,然后选择“编辑”。

    显示目录的“编辑”按钮的屏幕截图。

  3. 在“编辑目录”窗格中,选择“自动同步此目录”,然后选择“保存”

    显示目录的“编辑详细信息”窗格的屏幕截图,其中突出显示了“自动同步此目录”。

如果自动同步失败,则应执行手动同步。在手动同步成功之前,部署环境不会进行任何进一步的自动同步尝试。

删除目录

可以删除目录,以将其从 Azure 部署环境开发人员中心或项目中移除。 在开发团队部署新环境时,将无法使用已删除目录中的模板。 更新使用已删除目录中的环境定义创建的任何现有环境的环境定义引用。 如果未更新引用并重新部署环境,则会导致部署失败。

若要删除目录,请执行以下操作:

  1. 在开发人员中心或项目的左侧菜单中的“环境配置”下,选择“目录”

  2. 选择特定目录,然后选择“删除”

  3. 在“删除目录”对话框中,选择“继续”以删除目录。

排查目录同步错误

添加或同步目录时,可能会遇到同步错误或警告。 同步错误指示目录无法成功同步,同步警告指示部分或所有目录项都存在错误。 可以在 Azure 门户中查看同步状态和错误,或使用 Azure CLI 和 REST API 排查和解决错误。

查看目录同步状态

在 Azure 门户中,可以通过选择状态链接获取有关目录同步状态以及任何警告或错误的详细信息。 点击状态链接将打开一个窗格,其中显示了同步状态、已添加的环境定义数量以及已忽略或失败的环境定义数量。

查看目录同步失败

  1. 在开发人员中心或项目的左侧菜单中的“环境配置”下,选择“目录”

  2. 在“状态”列中,选择同步失败的目录的状态链接

    显示“目录”窗格的屏幕截图,其中突出显示了失败的同步。

  3. 你将看到一个结果窗格,其中显示了上次同步的变化、同步错误数量和错误类型。

    显示“目录同步失败”窗格的屏幕截图。

查看目录同步警告

  1. 在开发人员中心或项目的左侧菜单中的“环境配置”下,选择“目录”

  2. 在“状态”列中,选择已同步但报告警告的目录的状态链接

    显示“目录”窗格的屏幕截图,其中突出显示了三个项中的错误。

  3. 你将看到一个细节窗格,其中显示了上次同步的变化、项错误数量以及每个错误的类型和源。

    显示“目录同步错误”窗格的屏幕截图。

  4. 可以查看从也报告同步错误的目录成功同步的项。 在“目录”窗格中,选择目录名称

    显示“目录”窗格的屏幕截图,其中突出显示了目录名称。

  5. 你将看到已成功同步的目录项的列表。

    显示成功同步的目录项的屏幕截图。

使用 Azure CLI 排查目录同步错误

使用 Azure CLI 或 REST API 来 GET 目录。 GET 响应会显示错误类型:

  • 忽略了检测为重复项的环境定义。
  • 由于架构、引用或验证错误而失败的环境定义无效。

解决忽略的环境定义错误

如果添加两个或更多具有相同名称的环境定义,则会发生被忽略的环境定义错误。 可以通过重命名环境定义来解决此问题,以便每个环境定义在目录中具有唯一的名称。

解决无效的环境定义错误

环境定义无效错误可能出于各种原因:

  • 清单架构错误。 确保环境定义环境文件与所需的架构匹配。

  • 验证错误。 请检查以下各项以解决验证错误:

    • 确保正确配置环境文件的引擎类型。
    • 确保环境定义名称介于 3 到 63 个字符之间。
    • 确保环境定义名称仅包含对 URL 有效的字符,即字母数字字符和以下符号:~ ! , . ' ; : = - _ + ( ) * & $ @
  • 引用错误。 确保环境文件引用的模板路径是指向存储库中文件的有效相对路径。