azure-deployment-preflight

Azure 部署预检验证

此技能在执行前验证 Bicep 部署，支持 Azure CLI (az) 和 Azure Developer CLI (azd) 工作流。

何时使用此技能

• 在部署基础设施到 Azure 之前
• 准备或审查 Bicep 文件时
• 预览部署将进行的更改
• 验证权限是否足以进行部署
• 在运行 azd up、azd provision 或 az deployment 命令之前

验证流程

按顺序执行以下步骤。即使上一步失败也继续下一步——在最终报告中捕获所有问题。

步骤 1：检测项目类型

通过检查项目指示器确定部署工作流：

1. 检查是否为 azd 项目：在项目根目录中查找 azure.yaml

   • 如果找到 → 使用 azd 工作流
   • 如果未找到 → 使用 az CLI 工作流

2. 定位 Bicep 文件：查找所有要验证的 .bicep 文件

   • 对于 azd 项目：首先检查 infra/ 目录，然后检查项目根目录
   • 对于独立项目：使用用户指定的文件或搜索常见位置（infra/、deploy/、项目根目录）

3. 自动检测参数文件：对于每个 Bicep 文件，查找匹配的参数文件：

   • <filename>.bicepparam（Bicep 参数 - 首选）
   • <filename>.parameters.json（JSON 参数）
   • 同一目录中的 parameters.json 或 parameters/<env>.json

步骤 2：验证 Bicep 语法

在尝试部署验证之前，运行 Bicep CLI 检查模板语法：

bicep build <bicep-file> --stdout

需要捕获的内容：

• 带有行/列号的语法错误
• 警告消息
• 构建成功/失败状态

如果未安装 Bicep CLI：

• 在报告中记录问题
• 继续执行步骤 3（Azure 将在 what-if 期间验证语法）

步骤 3：运行预检验证

根据步骤 1 中检测到的项目类型选择适当的验证。

对于 azd 项目（存在 azure.yaml）

使用 azd provision --preview 验证部署：

azd provision --preview

如果指定了环境或存在多个环境：

azd provision --preview --environment <env-name>

对于独立 Bicep（无 azure.yaml）

根据 Bicep 文件的 targetScope 声明确定部署范围：

目标范围	命令
resourceGroup（默认）	az deployment group what-if
subscription	az deployment sub what-if
managementGroup	az deployment mg what-if
tenant	az deployment tenant what-if

首先使用 Provider 验证级别运行：

# 资源组范围（最常见）
az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# 订阅范围
az deployment sub what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# 管理组范围
az deployment mg what-if \
  --location <location> \
  --management-group-id <mg-id> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# 租户范围
az deployment tenant what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

回退策略：

如果 --validation-level Provider 因权限错误（RBAC）失败，则使用 ProviderNoRbac 重试：

az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --validation-level ProviderNoRbac

在报告中记录回退——用户可能缺少完整的部署权限。

步骤 4：捕获 What-If 结果

解析 what-if 输出以对资源更改进行分类：

更改类型	符号	含义
创建	+	将创建新资源
删除	-	资源将被删除
修改	~	资源属性将更改
无更改	=	资源未更改
忽略	*	资源未分析（达到限制）
部署	!	资源将被部署（更改未知）

对于修改的资源，捕获具体的属性更改。

步骤 5：生成报告

在项目根目录中创建一个 Markdown 报告文件，命名为：

• preflight-report.md

使用 references/REPORT-TEMPLATE.md 中的模板结构。

报告部分：

1. 摘要 - 总体状态、时间戳、已验证的文件、目标范围
2. 执行的工具 - 运行的命令、版本、使用的验证级别
3. 问题 - 所有错误和警告，带有严重性和补救措施
4. What-If 结果 - 要创建/修改/删除/未更改的资源
5. 建议 - 可操作的下一个步骤

所需信息

在运行验证之前，收集：

信息	所需对象	如何获取
资源组	az deployment group	询问用户或检查现有的 .azure/ 配置
订阅	所有部署	az account show 或询问用户
位置	订阅/管理组/租户范围	询问用户或使用配置中的默认值
环境	azd 项目	azd env list 或询问用户

如果缺少所需信息，请在继续之前提示用户。

错误处理

有关详细的错误处理指南，请参阅 references/ERROR-HANDLING.md。

关键原则： 即使发生错误也继续验证。在最终报告中捕获所有问题。

错误类型	操作
未登录	在报告中记录，建议 az login 或 azd auth login
权限被拒绝	回退到 ProviderNoRbac，在报告中记录
Bicep 语法错误	包含所有错误，继续处理其他文件
未安装工具	在报告中记录，跳过该验证步骤
未找到资源组	在报告中记录，建议创建它

工具要求

此技能使用以下工具：

• Azure CLI (az) - 建议版本 2.76.0+ 以支持 --validation-level
• Azure Developer CLI (azd) - 用于包含 azure.yaml 的项目
• Bicep CLI (bicep) - 用于语法验证
• Azure MCP 工具 - 用于文档查找和最佳实践

在开始之前检查工具可用性：

az --version
azd version
bicep --version

示例工作流

1. 用户：“在我运行之前验证我的 Bicep 部署”
2. 代理检测到 azure.yaml → azd 项目
3. 代理找到 infra/main.bicep 和 infra/main.bicepparam
4. 代理运行 bicep build infra/main.bicep --stdout
5. 代理运行 azd provision --preview
6. 代理在项目根目录生成 preflight-report.md
7. 代理向用户总结发现

参考文档

• 验证命令参考
• 报告模板
• 错误处理指南