Azure 开发人员 CLI 架构参考

该文件 azure.yaml 是 Azure 开发人员 CLI （azd） 项目的配置文件。 将其置于项目的根目录中，以定义构成应用程序的服务、Azure 资源、基础结构、挂钩和 CI/CD 管道。 运行命令（或 azd upazd provisionazd deployCLI）时，会读取此文件以了解应用的结构以及如何将其部署到 Azure。

本文是 azure.yaml 架构的完整参考。 有关模板入门 azd ，请参阅 Azure 开发人员 CLI 模板概述。

样本

下面是模板文件的azure.yaml一般示例azd。 有关实际示例，请参阅 azure.yamlToDo NodeJs Mongo 模板：

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

顶级属性

name

（字符串，必需） 应用程序名称。 只允许小写字母、数字和连字符 （-） 。 名称必须以字母或数字开头和结尾。 最小长度：2 个字符。

name: my-app

resourceGroup

（string） Azure 资源组的名称。 指定后，重写用于基础结构预配的资源组名称。 支持环境变量替换。 必须介于 3 到 64 个字符之间。

resourceGroup: rg-my-app-${AZURE_ENV_NAME}

metadata

（对象） 有关应用程序模板的元数据。

metadata:
  template: todo-nodejs-mongo@0.0.1-beta

infra

（对象） 为 Azure 基础结构预配提供其他配置。

infra.layers

（对象数组） 定义 Azure 基础结构的预配层。 每个层表示独立的预配单元。

infra:
  provider: bicep
  layers:
    - name: core
      path: ./infra/core
    - name: services
      path: ./infra/services
      dependsOn:
        - core
      hooks:
        postprovision:
          shell: sh
          run: ./scripts/post-provision.sh

Terraform 作为 IaC 提供程序示例

若要使用 Terraform 而不是 Bicep，请将它 provider 设置为 terraform。 有关详细信息，请参阅 将 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

（object） 构成应用程序的服务的定义。 每个密钥都是服务名称，值是服务配置对象。

服务属性

主机类型

该 host 属性确定用于服务实现的 Azure 资源的类型，并控制哪些其他属性有效。

ai.endpoint 配置

（对象，需要何时hostai.endpoint） 为 Azure AI 联机终结点部署提供其他配置。

AI 组件配置

AI 部署配置

从 AI 组件配置继承所有属性，以及：

services:
  myendpoint:
    project: ./src/endpoint
    host: ai.endpoint
    config:
      workspace: my-ai-project
      deployment:
        path: ./deployment
        environment:
          MODEL_NAME: ${AZURE_OPENAI_MODEL}

docker

（对象） 服务的 Docker 配置。 仅适用于支持容器（containerapp、、 aks、 ai.endpoint） azure.ai.agent的主机。

k8s

（对象） Azure Kubernetes 服务 （AKS） 配置选项。 仅当 host 为 aks.

部署配置

服务配置

入口配置

Helm 配置

repositories 数组项：

releases 数组项：

Kustomize 配置

服务挂钩

服务级别挂钩在服务生命周期事件期间执行。 挂钩应与前缀为 pre 或 post. 指定路径时，它们应相对于服务路径。 有关详细信息，请参阅 使用命令和事件挂钩自定义 Azure 开发人员 CLI 工作流。

支持的服务挂钩：prerestore、、、postrestoreprebuildpostbuildprepackagepostpackageprepublish、。 postpublishpredeploypostdeploy

每个挂钩都使用 挂钩定义 格式。

服务示例

使用 Docker 选项的容器应用

services:
  api:
    project: ./src/api
    language: js
    host: containerapp
    docker:
      path: ./Dockerfile
      context: ../
  web:
    project: ./src/web
    language: js
    host: containerapp
    docker:
      remoteBuild: true

预生成的映像中的容器应用

services:
  api:
    image: myregistry.azurecr.io/myapp:latest
    host: containerapp

具有服务级别挂钩的 AKS

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}

resources

（对象） 应用程序使用的 Azure 资源的定义。 每个键都是资源名称，值是资源配置对象。 可以通过属性由服务 uses 引用资源。

常见资源属性

资源类型

该 type 属性确定 Azure 资源的类型，并控制哪些附加属性可用。

host.appservice 属性

runtime 对象：

resources:
  web:
    type: host.appservice
    port: 8080
    runtime:
      stack: node
      version: 22-lts
    uses:
      - db

host.containerapp 属性

ai.openai.model 属性

model 对象：

resources:
  chatModel:
    type: ai.openai.model
    model:
      name: gpt-4o
      version: "2024-08-06"

ai.project 属性

models 数组项：

sku 对象：

ai.search 属性

db.cosmos 属性

containers 数组项：

messaging.eventhubs 属性

messaging.servicebus 属性

storage 属性

keyvault 属性

资源示例

resources:
  db:
    type: db.postgres
  cache:
    type: db.redis
  chatModel:
    type: ai.openai.model
    model:
      name: gpt-4o
      version: "2024-08-06"
  web:
    type: host.containerapp
    port: 3100
    uses:
      - db
      - chatModel

pipeline

（对象） 持续集成管道的定义。

pipeline:
  provider: azdo
  variables:
    - CUSTOM_SETTING
  secrets:
    - API_KEY

hooks

（对象） 命令级别挂钩。 挂钩应与前缀为 azd 或 pre 的 post 命令名称匹配，具体取决于脚本的执行时间。 指定路径时，它们应相对于项目路径。 有关详细信息，请参阅 使用命令和事件挂钩自定义 Azure 开发人员 CLI 工作流。

支持的命令挂钩：preprovision、、postprovision、preinfracreatepostinfracreate、。 preinfradeletepostinfradeletepredownpostdownpreuppostupprepackagepostpackageprepublishpostpublishpredeploypostdeployprerestorepostrestore

每个挂钩都使用 挂钩定义 格式。

hooks:
  preprovision:
    shell: sh
    run: ./scripts/setup.sh
  postdeploy:
    shell: sh
    run: azd env set APP_URL ${SERVICE_WEB_ENDPOINT_URL}

挂钩定义

挂钩可以是单个挂钩对象或挂钩对象的数组。 每个挂钩对象具有以下属性：

挂钩执行程序配置

该 config 属性接受不同的属性，具体取决于 kind 值。

JavaScript 和 TypeScript （js， ts） 配置

Python 配置

.NET （dotnet） 配置

Shell （sh， pwsh） 配置

Shell 执行程序目前 config 不支持属性。

挂钩示例

特定于平台的挂钩

hooks:
  preprovision:
    windows:
      shell: pwsh
      run: ./scripts/setup.ps1
    posix:
      shell: sh
      run: ./scripts/setup.sh

具有种类的 Python 挂钩

hooks:
  postprovision:
    kind: python
    run: ./scripts/seed-data.py
    dir: ./scripts
    config:
      virtualEnvName: .venv

单个事件的多个挂钩

hooks:
  postprovision:
    - shell: sh
      run: ./scripts/step1.sh
    - shell: sh
      run: ./scripts/step2.sh

requiredVersions

（对象） 为所需的版本 azd 和扩展提供其他配置。

requiredVersions:
  azd: ">= 0.6.0-beta.3"
  extensions:
    azure.ai.agents: ">=1.0.0"
    my-extension: latest

state

（对象） 为状态管理提供其他配置。

state.remote

Azure Blob 存储配置

state:
  remote:
    backend: AzureBlobStorage
    config:
      accountName: mystorageaccount
      containerName: azd-state

platform

（对象） 为特定于平台的功能（例如 Azure 开发人员中心）提供其他配置。

开发人员中心配置

在以下type情况下devcenter可用：

platform:
  type: devcenter
  config:
    name: my-devcenter
    project: my-project
    catalog: my-catalog
    environmentDefinition: my-env-def
    environmentType: dev

workflows

（对象） 为工作流提供其他配置，例如重写 azd up 行为。

工作流步骤

工作流 up 接受 steps 数组（也可以直接指定为数组）。 每个步骤都运行一个 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: package
      - azd: deploy --all

cloud

（对象） 提供用于部署到主权云（例如 Azure 政府）的其他配置。 默认云为 AzureCloud.

cloud:
  name: AzureUSGovernment

请求帮助

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

后续步骤

• 使用命令和事件挂钩自定义工作流
• Azure 开发人员 CLI 模板概述
• 将 Terraform 用作 IaC 提供程序
• 管理环境变量