Azure 开发人员 CLI 的 azure.yaml 架构

2025-08-15

azd 模板是蓝图存储库，其中包括用 Bicep 或 Terraform 编写的概念证明应用程序代码、编辑器/IDE 配置和基础结构代码。这些模板旨在根据特定的应用程序要求进行修改和调整，然后使用 Azure 开发人员 CLI（azd）在 Azure 上获取应用程序。 azure.yaml 架构定义并描述这些模板中包含的 Azure 资源的应用和类型。

样本

下面是模板所需的azd通用示例azure.yaml。

name: yourApp
metadata:
  template: yourApp@0.0.1-beta
services:
  web:
    project: ./src/web # path to your web project
    dist: build # relative path to service deployment artifacts
    language: js # one of the supported languages
    host: appservice # one of the supported Azure services

与 azure.yaml中的进行比较：

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

属性说明

元素名称	必填	描述
`name`	Y	（string）应用程序的名称。
`resourceGroup`	N	（string） Azure 资源组的名称。指定后，重写用于基础结构预配的资源组名称。
`metadata`	N	（对象）有关详细信息，请参阅元数据属性。
`infra`	N	（对象）为 Azure 基础结构预配提供额外的配置。有关详细信息，请参阅基础结构属性。
`services`	Y	（object）构成应用程序的服务的定义。有关详细信息，请参阅服务属性。
`pipeline`	N	（对象）持续集成管道的定义。有关更多详细信息，请参阅管道属性。
`hooks`	N	命令级别挂钩。挂钩应与前缀为 `azd` 或 `pre` 的 `post` 命令名称匹配，具体取决于脚本的执行时间。指定路径时，它们应相对于项目路径。有关详细信息，请参阅使用命令和事件挂钩自定义 Azure 开发人员 CLI 工作流。
`requiredVersions`	N	此项目的一系列受支持的 `azd` 版本。 `azd`如果版本超出此范围，则项目无法加载。可选（如果不存在，则允许所有版本）。示例：`>= 0.6.0-beta.3`

`metadata` 属性

元素名称	必填	描述	例
`template`	N	（string）创建应用程序的模板的标识符。	`todo-nodejs-mongo@0.0.1-beta`

`infra` 属性

元素名称	必填	描述	例
`provider`	N	（string）应用程序的 Azure 资源的基础结构提供程序。（默认值：bicep）。	请参阅 Terraform 示例。 `bicep`，`terraform`
`path`	N	（string）包含指定提供程序的 Azure 预配模板的位置的相对文件夹路径。（默认值：基础结构）。
`module`	N	（string）使用 Azure 预配模板的默认模块的名称。（默认值：main）。

Terraform 作为 IaC 提供程序示例

name: yourApp-terraform
metadata:
  template: yourApp-terraform@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
      language: js
      host: appservice
infra:
  provider: terraform

`services` 属性

元素名称	必填	描述	例
`resourceName`	N	（string）实现服务的 Azure 资源的名称。如果未指定，`azd`则按`azd-env-name`标记查找资源。`azd-service-name` 如果未找到，它将查找从当前环境名称构造的资源名称，并将其与服务名称（`<environment-name><resource-name>`）连接起来。	`prodapi`
`project`	Y	（string）服务源代码目录的路径。
`host`	Y	（string）用于服务实现的 Azure 资源类型。如果省略，则假定应用服务。	`appservice`、`containerapp`、`function`、`staticwebapp`、`aks`（仅适用于可通过 `kubectl apply -f`部署的项目），`springapp`（启用启用时 - 详细了解 alpha 功能）
`language`	Y	（string）服务实现语言。	`dotnet`、`csharp`、`fsharp`、`py`、`python`、`js`、`ts`、`java`
`module`	Y	（string）用于部署服务相对于根基础结构文件夹的服务的路径。如果省略，CLI 假定模块名称与服务名称相同。
`dist`	Y	（string）服务部署项目的相对路径。 CLI 使用此路径下的文件来创建部署项目（.zip 文件）。如果省略，则包含服务项目目录下的所有文件。	`build`
`docker`	N	仅在 `hostcontainerapp` 时才适用。不能包含额外的属性。	请参阅自定义 Docker 示例。 `path` （string）：Dockerfile 的路径。默认值：`./Dockerfile`;`context`（string）：docker 生成上下文。指定后，重写默认上下文。默认值：`.`;`platform`（string）：平台目标。默认值：`amd64`;`remoteBuild`（布尔）：启用远程 ACR 生成。默认值：`false`
`k8s`	N	Azure Kubernetes 服务（AKS）配置选项。	请参阅 AKS 示例。 `deploymentPath` （string）：可选。从服务路径到 K8s 部署清单的相对路径。设置后，它将替代 K8s 部署清单的默认部署路径位置。默认值：`manifests`;`namespace`（string）：可选。已部署资源的 K8s 命名空间。指定后，将创建一个新的 K8s 命名空间（如果尚不存在）。默认值：`Project name`;`deployment`（object）：请参阅部署属性;`service`（对象）：请参阅服务属性;`ingress`（object）：请参阅入口属性。
`hooks`	N	服务级别挂钩。挂钩应与前缀为 `service` 或 `pre` 的 `post` 事件名称匹配，具体取决于脚本的执行时间。指定路径时，它们应相对于服务路径。	有关详细信息，请参阅使用命令和事件挂钩自定义 Azure 开发人员 CLI 工作流。
`apiVersion`	N	部署由 Azure 容器应用托管的服务时，指定显式 `api-version`。此功能有助于避免使用不兼容的 API 版本，并使部署更加松散耦合，以避免在 JSON 封送到硬编码的 Azure SDK 库版本期间丢失自定义配置数据。	`apiVersion: 2024-02-02-preview`

Docker 选项示例

在以下示例中，我们声明容器应用的 Docker 选项。

name: yourApp-aca
metadata:
    template: yourApp-aca@0.0.1-beta
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
    docker:
      path: ./Dockerfile
      context: ../
  web:
    project: ./src/web
    language: js
    host: containerapp
    docker:
      remoteBuild: true

AKS `deployment` 属性

元素名称	必填	描述	例
`name`	N	（string）可选。部署期间要使用的 K8s 部署资源的名称。在部署期间用于确保 K8s 部署推出是否已完成。如果未设置，请搜索包含服务名称的同一命名空间中的部署资源。默认值：`Service name`	`api`

AKS `service` 属性

元素名称	必填	描述	例
`name`	N	（string）可选。用作默认服务终结点的 K8s 服务资源的名称。用于确定默认服务资源的终结点。如果未设置，请搜索包含服务名称的同一命名空间中的部署资源。（默认值：服务名称）	`api`

AKS `ingress` 属性

元素名称	必填	描述	例
`name`	N	（string）可选。用作默认服务终结点的 K8s 入口资源的名称。用于确定默认入口资源的终结点。如果未设置，请搜索包含服务名称的同一命名空间中的部署资源。默认值：`Service name`	`api`
`relativePath`	N	（string）可选。入口控制器根目录中的服务的相对路径。设置后，追加到入口资源路径的根目录。

具有服务级别挂钩的 AKS 示例

metadata:
  template: todo-nodejs-mongo-aks@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: aks
    hooks:
      postdeploy:
        shell: sh
        run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}
  api:
    project: ./src/api
    language: js
    host: aks
    k8s:
      ingress:
        relativePath: api
    hooks:
      postdeploy:
        shell: sh
        run: azd env set REACT_APP_API_BASE_URL ${SERVICE_API_ENDPOINT_URL}

`pipeline` 属性

元素名称	必填	描述	例
`provider`	N	（string）用于持续集成的管道提供程序。（默认值：`github`）。	`github`，`azdo`

Azure Pipelines （AzDo）作为 CI/CD 管道示例

name: yourApp
services:  
  web:    
    project: src/web
    dist: build
    language: js
    host: appservice
pipeline: 
  provider: azdo

`workflows` 属性

元素名称	类型	必填	描述
向上	对象	不	指定后，将替代 azd up 工作流的默认行为。

`up` 属性

元素名称	类型	必填	描述
步骤	数组	是的	在工作流中执行的步骤。

`steps` 属性

元素名称	类型	必填	描述
azd	字符串	是的	要执行的 azd 命令的名称和参数。

示例工作流

以下 azure.yaml 文件更改 azd up 的默认行为，以使用工作流在 azd package 步骤之后移动 azd provision 步骤。在生成或打包过程中需要知道资源的 URL 的情况下，可以使用此示例。

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
workflows:
  up: 
    steps:
      - azd: provision
      - azd: deploy --all

请求帮助

有关如何提交 bug、请求帮助或为 Azure 开发人员 CLI 提出新功能的信息，请访问故障排除和支持页。

后续步骤

反馈

此页面是否有帮助？

通过

Azure 开发人员 CLI 的 azure.yaml 架构

样本

属性说明

metadata 属性

infra 属性

Terraform 作为 IaC 提供程序示例

services 属性

Docker 选项示例

AKS deployment 属性

AKS service 属性

AKS ingress 属性