Azure 开发人员 CLI 模板概述

Azure开发人员 CLI （azd） 模板是遵循azd约定的代码存储库。 它结合了项目配置、基础结构即代码和可选应用程序源，以便可以创建可重复Azure环境和部署。

模板可以支持不同的项目类型，包括：

  • 包含一个或多个可部署服务的完整应用程序。
  • 不包含应用程序代码的纯基础设施解决方案。
  • 另一个开发人员可以初始化和扩展的可重用起点。
  • 为使用 azd 进行预配和部署而准备的现有项目。

本文介绍模板的结构以及命令如何使用 azd 其文件。

为何使用模板？

模板捕获在Azure上运行项目所需的决策。 根据项目，它可以定义：

  • Azure资源及其配置。
  • 可部署的应用程序服务和打包说明。
  • 应用程序服务和Azure资源之间的连接。
  • 特定于环境的参数和输出。
  • 本地开发、持续集成和持续交付配置。

由于配置与项目一起存储，团队可以查看源代码管理中的更改，并创建一致的开发、测试和生产环境。

如何使用 azd 模板

模板中的文件支持工作流的不同阶段 azd ：

  • azd init 初始化项目并创建环境 azd 。 它还可以使用GitHub Copilot生成初始模板或复制现有模板。
  • azd provision评估基础结构定义并创建或更新Azure资源。
  • azd package 根据 azure.yaml 准备可部署的应用服务。
  • azd deploy将每个服务与其Azure主机相关联，并部署应用程序包。
  • azd up 以组合工作流的形式运行预配、打包和部署阶段。

在整个过程中，模板文件将保持常规源文件。 您可以将它们与项目的其余部分一起审查、编辑并进行版本控制。

探索 Azure 开发人员 CLI 模板结构

azd 模板是具有额外配置和基础结构资产的标准代码存储库。 大多数模板使用以下结构：

  • azure.yaml文件 - 定义项目并将可部署的源目录映射到Azure资源。
  • infra folder - 包含用于创建 Azure 资源的 Bicep 或 Terraform 基础设施即代码文件。
  • src 文件夹 - 通常包含可部署的应用程序源代码。 仅基础结构模板可以省略应用程序源，应用程序模板可以使用其他源目录名称。
  • .azure folder - 包含由 azd 创建的本地环境和值。 此文件夹是本地项目状态，通常不会作为可重用模板的一部分共享。

例如，通用 azd 模板可能与以下文件夹结构匹配：

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

azd 模板还可以选择包含以下一个或多个文件夹：

  • .github 文件夹 - 用于存放 GitHub Actions 的 CI/CD 工作流文件。
  • .azdo 文件夹 - 如果决定将 Azure Pipelines 用于 CI/CD，请定义此文件夹中的工作流配置文件。
  • .devcontainer folder - 定义项目的 开发容器 环境。

下图显示了主模板资产如何协同工作：

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

必需和可选资产

确切的结构因项目而异，但大多数模板使用以下资产。

azure.yaml

该文件 azure.yaml 是主项目配置文件。 它定义项目名称，并可以定义可部署的服务、基础结构提供程序、挂钩、工作流和其他 azd 行为。

对于应用程序服务， azure.yaml 通常标识：

  • 应用程序源的路径。
  • 编程语言或打包策略。
  • 承载应用程序的Azure服务。
  • 构建、部署、容器或 Kubernetes 设置。

仅包含基础设施的模板可以省略应用服务。 有关完整的配置模型，请参阅 azure.yaml 架构。

以下示例定义两个应用程序服务。 服务名称、源路径、语言和托管目标会告知 azd 要打包的内容以及部署位置：

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

基础结构即代码

大多数模板都包含一个 infra 目录，其中包含 Bicep 或 Terraform 文件。 这些文件定义项目所需的Azure资源、角色分配、网络、应用程序设置和部署输出。

对于默认的 Bicep 提供程序，azd 通常使用 infra/main.bicep 作为部署入口点，并使用 infra/main.parameters.json 将 azd 环境值映射到 Bicep 参数。 Terraform 模板通常使用 infra/main.tf 和相关 Terraform 文件。

例如，Bicep参数文件可以将选定的azd值传递到基础结构部署中：

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

Bicep预配完成后，azd将入口点的输出存储为环境值。 应用程序服务和挂钩可以将这些值用于资源终结点、名称和其他运行时配置。

output API_ENDPOINT string = api.outputs.uri

应用程序源

应用程序源是可选的。 当模板包含可部署的服务时，每个服务定义都 azure.yaml 指向其源目录。 模板可以在 src 下组织服务，使用仓库中其他位置的目录，或将服务指向仓库根目录。

文件夹名称本身并不重要。 azure.yaml 中的 project 值决定了 azd 在何处找到每项服务。

环境配置

该 .azure 目录包含本地环境状态和由该目录 azd创建的值。 它可以包含多个环境的订阅、位置、资源名称、终结点和部署输出值。

将此目录视为本地状态，而不是可重用的模板资产。 不要提交包含机密或特定于环境的值的环境文件。

配套资源

模板还可以包含：

  • GitHub Actions 或 Azure Pipelines 的定义。
  • Dockerfiles 和容器配置。
  • 开发容器配置。
  • 命令和服务钩子。
  • 测试、脚本和项目文档。

这些资产是可选的，仅当它们支持预期的模板体验时，才应包含这些资产。

服务与资源的关联

若要部署应用程序服务，azd必须将其定义azure.yaml与预配Azure资源相关联。 默认情况下， azd 查找其 azd-service-name 标记与服务名称匹配的资源。

例如，名为 api 的服务映射到使用 azd-service-name: api标记的资源。 可以改用 resourceName 服务属性显式标识部署目标。

以下 Bicep 表达式将 discovery 标记添加到资源的现有标签中：

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

编辑模板时，保持服务名称、资源发现设置、基础结构输出和应用程序环境变量保持一致。

生成或调整模板

建议的创作方式是运行 azd init 并选择 使用 GitHub Copilot 设置（预览版）。 专用Copilot 智能体会话可以分析现有文件、帮助规划新项目、生成模板资产以及验证结果。 有关此工作流和其他创作方法，请参阅 “从新模板开始”。

生成的文件不绑定到Copilot。 可以在初始化后直接 浏览和编辑模板文件 。 还可以手动或使用另一个 AI 编码代理创建相同的文件。

如果来自Microsoft的模板、你的组织或开发人员社区已经提供了一个有用的体系结构，请从现有模板开始，并适应你的项目。 浏览 模板库中的可用模板。

模板使用指南

根据模板随附的协议，每个模板均由其所有者许可。 确定在使用或分发模板之前适用的许可证。

Microsoft不负责非Microsoft模板，并且不筛选它们以处理安全、隐私、兼容性或性能问题。 Microsoft支持计划或服务不支持模板（包括Microsoft提供的模板），并且按原样提供，不提供保修。

预配之前，请查看所有模板文件。 具体而言，评估角色分配、网络公开、身份验证方法、服务层级、资源位置和预期成本。

后续步骤

模板开发概述

  • Last updated on