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 验证级别运行：

# Resource Group scope (most common)
az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Subscription scope
az deployment sub what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Management Group scope
az deployment mg what-if \
  --location <location> \
  --management-group-id <mg-id> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Tenant scope
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 输出，对资源更改进行分类：

更改类型	符号	含义
Create	+	将创建新资源
Delete	-	将删除资源
Modify	~	资源属性将更改
NoChange	=	资源未更改
Ignore	*	资源未分析（已达到限制）
Deploy	!	将部署资源（更改未知）

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

步骤 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 Tools - 用于文档查询和最佳实践

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

az --version
azd version
bicep --version

示例工作流

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

参考文档

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