浏览和编辑Azure开发人员 CLI 模板文件

Azure开发人员 CLI (azd) 模板是一个标准存储库,其中包含配置和基础结构资产,可用于azd预配和部署项目。 无论是生成新模板还是从现有模板开始,你仍负责在项目发展过程中查看和维护其文件。

本文介绍如何检查和编辑主模板文件。 有关完整结构的概念说明,请参阅Azure开发人员 CLI 模板。

本文使用 hello-azd 示例模板,以便查看每个文件在实际项目中执行的操作。 相同的概念适用于为自己的应用生成的模板。

初始化示例模板

若要继续学习,请完成 快速入门先决条件,选择语言,并在空目录中初始化其模板。 该 . 参数将项目保留在当前目录中:

此选项使用 hello-azd-python 示例存储库。

azd init --template hello-azd-python .

这两个模板都将容器化应用部署到 Azure 容器应用,并通过 Bicep 预配提供支持的 Azure 资源。 它们使用以下文件夹结构,其中每个主要资产映射到本文中的一部分:

.
├── azure.yaml                # Project configuration (Explore azure.yaml)
├── infra/                    # Infrastructure as code (Infrastructure files)
│   ├── main.bicep            # Deployment entry point
│   ├── main.parameters.json  # Parameter values that azd supplies
│   ├── abbreviations.json    # Resource name abbreviations
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

具体结构因项目而异,azure.yaml 标识 azd 使用的路径。 以下部分介绍如何编辑每个资产。

在进行重大更改之前,请提交或保存模板的已知良好版本。 查看嵌入凭据、不必要的资源、过多的权限、网络公开、服务层和环境特定值的所有更改。

探索 azure.yaml

该文件 azure.yaml 定义项目,并说明 azd 如何预配基础结构、打包应用程序代码和部署每个服务。 它可以定义服务、基础结构设置、挂钩、工作流和其他项目行为。

这两个模板都定义了一个名为 的服务。 选择一种语言以查看其服务定义:

name: hello-azd-python
metadata:
  template: hello-azd-python
services:
  aca:
    project: ./src
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

每个属性都 azd 说明如何处理服务:

  • aca 是服务名称。 azd使用它将服务与托管它的Azure资源匹配。 有关详细信息,请参阅 配置服务发现。
  • project: ./src 指向由 azd 打包并部署的应用程序源代码。
  • language 将应用程序语言标识为 python 或 csharp。
  • host: containerapp告知azd将服务部署到Azure 容器应用。
  • docker从src目录中的Dockerfile构建容器映像。
  • remoteBuild指示azd使用 Azure 容器注册表 (ACR) 生成容器映像。

添加服务定义

在azd下,为services应部署的每个其他应用程序添加一个条目。 服务定义指定其源目录、语言和Azure托管目标。 例如,选择一种语言来描述新的 API 项目:

services:
  api:
    project: ./src/api
    language: python
    host: appservice

移动应用程序代码时,更新相应的 project 路径。 更改托管体系结构时,请更新服务定义和预配主机的基础结构。

有关所有可用属性和支持的值,请参阅 azure.yaml 架构。

源代码

应用程序源是可选的。 具有可部署应用程序的模板通常组织目录中的 src 源代码,但不需要使用特定的文件夹名称或布局。 azure.yaml 中每个服务的 project 属性会告诉 azd 其源代码所在的位置。

在这两个示例模板中,aca服务集project: ./src,因此azd将应用打包到src目录中,并将其部署到Azure 容器应用。 .NET 源包括位于 src/Components 下的 Blazor 应用,Python 源包含位于 src/app 下的 FastAPI 应用。 由于每个服务还设置了 docker 配置,因此 azd 会在部署前从 src 目录中的 Dockerfile 构建容器映像。

azd 支持在受支持的 Azure 主机上运行 Node.js、Python、.NET、Java 和 Go。 模板还可以部署容器。 有关当前语言、框架和主机组合,请参阅 支持的语言和环境。

像在任何应用程序存储库中一样编辑源代码。 如果添加服务或移动其源目录,请更新其 azure.yaml 服务定义。 如果应用程序需要新的Azure资源,请更新基础结构,并通过配置将所需的终结点或资源名称传递给应用程序。

更改服务源目录

例如,如果将应用从 src 移动到 src/web,请更新 aca 服务的 project 值:

services:
  aca:
    project: ./src/web
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

基础设施文件

该infra目录包含定义模板Azure资源的Bicep或 Terraform 文件。 这两个示例模板都使用Bicep,并包含以下关键资产:

  • main.bicep 是 azd 运行以预配资源的标准部署入口点。
  • main.parameters.json 为 main.bicep 提供参数值。
  • core包含用于存储、标识、Azure 容器注册表和Azure 容器应用等资源的重点模块。

main.bicep 在 azd up 期间如何运行

当你运行 azd up 时,预配阶段会部署 infra/main.bicep。 该文件面向订阅范围,创建资源组,然后调用模块来预配应用所需的资源。 选择一种语言以查看每个模板中的相关标识符:

targetScope = 'subscription'

var abbreviations = loadJsonContent('./abbreviations.json')

resource resourceGroup 'Microsoft.Resources/resourceGroups@2021-04-01' = {
  name: !empty(resourceGroupName) ? resourceGroupName : '${abbreviations.resourcesResourceGroups}${environmentName}'
  location: location
  tags: tags
}

module storage './core/storage/storage-account.bicep' = {
  name: 'storage'
  scope: resourceGroup
  params: {
    name: !empty(storageAccountName) ? storageAccountName : '${abbreviations.storageStorageAccounts}${resourceToken}'
    location: location
    tags: tags
    containers: [
      { name: 'attachments' }
    ]
    tables: [
      { name: 'tickets' }
    ]
  }
}

module web './core/host/container-app.bicep' = {
  name: serviceName
  scope: resourceGroup
  // ...
}

该文件main.bicep预配用户分配的托管标识、Azure 存储帐户、Azure 容器应用环境和注册表,以及承载aca服务的容器应用。 它还分配了允许托管标识访问存储的角色。 模块将每个资源保留在其自己的文件中,因此 main.bicep 保持可读性。

向 main.bicep 添加资源

对于简单资源或一次性资源,直接将资源声明添加到 infra/main.bicep 中。 在以下情况下,请将资源拆分到单独的 Bicep 模块中:需要重用这些资源时、某个资源需要多个相关资源配合时,或者希望保持 main.bicep 的可读性时。 与示例一样,许多模板将可重用模块归类在 infra/core 下。

对于常见的Azure资源,首选Azure已验证模块而不是从头开始创作模块。 已验证的模块Microsoft维护,遵循安全性和可靠性最佳做法,并减少在模板中维护的基础结构代码量。

有关将新资源添加到任一示例模板的完整演练,请参阅 扩展模板。

main.parameters.json 文件将由 azd 维护的值映射到 Bicep 参数中。 这两个示例模板都使用以下参数:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
  }
}

每个条目都将一个 Bicep 参数绑定到由 azd 在环境中维护的值,例如环境名称、位置以及执行部署的主体。 对于因环境或部署而异的值,请使用 main.parameters.json,例如环境名称、位置或由 azd 生成的资源名称。 将那些在不同环境之间不会变化的稳定值保留为参数默认值或 main.bicep 中的字面量。 这种方法可使同一个 Bicep 在不同环境中复用,而无需针对每次部署进行编辑。

添加或编辑基础结构时:

  • 使资源配置环境保持独立。 使用参数和环境 azd 值,而不是嵌入订阅 ID、资源名称、位置或凭据。
  • 对敏感值使用安全输出,不要将机密以纯文本形式作为部署输出暴露出来。
  • 对托管标识应用最小权限角色分配。
  • 使服务定义 azure.yaml 与目标资源保持一致。
  • 查看服务层级、缩放限制、冗余和保留设置对成本的影响。

有关 Bicep 语言和模块相关指导,请参阅 Bicep 文档。 有关基于 Terraform 的模板,请参阅将 Terraform 与Azure开发人员 CLI 配合使用。

配置服务发现

默认情况下,azd通过查找其azd-service-name标记与服务名称azure.yaml匹配的资源来发现服务的Azure资源。 如果重命名了服务,请更新相应的资源标签,或在 azure.yaml 中显式配置资源名称。

例如,在这两个示例模板中,aca 服务名称都与容器应用资源上的 azd-service-name 标记匹配。 azure.yaml 服务定义设置了名称。 选择一种语言以查看其定义:

services:
  aca:
    project: ./src
    language: python
    host: containerapp

中的 infra/core/host/container-app.bicep 容器应用模块应用匹配标记:

tags: union(tags, { 'azd-service-name': serviceName })

配置非标准基础结构路径

azure.yaml 的 infra 部分标识出基础设施提供程序和入口点。 使用默认Bicep布局时,这些值是可选的,但声明这些值可以使非标准布局更易于理解:

infra:
  provider: bicep
  path: infra
  module: main

环境配置

该 .azure 目录包含本地环境状态和创建值 azd ,例如所选订阅、位置、资源名称和部署输出。 将此目录视为本地状态,而不是可重用的模板资产。 不要提交包含机密或特定于环境的值的环境文件。

添加基础设施输出

运行azd provision以部署Bicep时,它会将基础结构入口点的输出捕获为azd环境值。 为应用程序服务或挂钩所需的资源终结点、资源名称和托管标识客户端 ID 添加输出。 例如,示例模板都输出容器注册表和托管标识详细信息,main.bicep

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name

当可以通过托管标识或 密钥保管库 引用提供访问权限时,不要输出机密信息。 预配后,通过运行 azd env get-values检查捕获的值。

有关详细信息,请参阅 “管理环境变量”。

测试您的更改

运行 azd up 以预配基础结构并部署任何应用程序服务:

azd up

如果打算共享模板,请在干净目录中初始化模板,并使用新环境部署它。 此测试有助于识别不属于模板的本地文件、缓存值或特定于环境的假设。

请求帮助

有关如何提交 bug、请求帮助或为 Azure 开发人员 CLI 提出新功能的信息,请访问 troubleshooting and support 页。