azure-deployment-preflight

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Deployment Preflight Validation

Azure部署预检验证

This skill validates Bicep deployments before execution, supporting both Azure CLI (

az

) and Azure Developer CLI (

azd

) workflows.

此技能在执行前验证Bicep部署，支持Azure CLI (

az

) 和Azure Developer CLI (

azd

) 工作流。

When to Use This Skill

何时使用此技能

Before deploying infrastructure to Azure
When preparing or reviewing Bicep files
To preview what changes a deployment will make
To verify permissions are sufficient for deployment
Before running
```
azd up
```
,
```
azd provision
```
, or
```
az deployment
```
commands

向Azure部署基础架构之前
准备或审核Bicep文件时
预览部署将做出哪些变更时
验证部署权限是否足够时
运行
```
azd up
```
、
```
azd provision
```
或
```
az deployment
```
命令之前

Validation Process

验证流程

Follow these steps in order. Continue to the next step even if a previous step fails—capture all issues in the final report.

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

Step 1: Detect Project Type

步骤1：检测项目类型

Determine the deployment workflow by checking for project indicators:

Check for azd project: Look for
```
azure.yaml
```
in the project root
- If found → Use azd workflow
- If not found → Use az CLI workflow
Locate Bicep files: Find all
```
.bicep
```
files to validate
- For azd projects: Check
```
infra/
```
  directory first, then project root
- For standalone: Use the file specified by the user or search common locations (
```
infra/
```
  ,
```
deploy/
```
  , project root)
Auto-detect parameter files: For each Bicep file, look for matching parameter files:
- ```
<filename>.bicepparam
```
  (Bicep parameters - preferred)
- ```
<filename>.parameters.json
```
  (JSON parameters)
- ```
parameters.json
```
  or
```
parameters/<env>.json
```
  in same directory

通过检查项目标识来确定部署工作流：

检查azd项目：在项目根目录中查找
```
azure.yaml
```
- 如果找到 → 使用azd工作流
- 如果未找到 → 使用Azure CLI工作流
定位Bicep文件：找到所有需要验证的
```
.bicep
```
文件
- 对于azd项目：首先检查
```
infra/
```
  目录，然后检查项目根目录
- 对于独立项目：使用用户指定的文件或搜索常见位置（
```
infra/
```
  、
```
deploy/
```
  、项目根目录）
自动检测参数文件：对于每个Bicep文件，查找匹配的参数文件：
- ```
<filename>.bicepparam
```
  （Bicep参数 - 首选）
- ```
<filename>.parameters.json
```
  （JSON参数）
- 同一目录中的
```
parameters.json
```
  或
```
parameters/<env>.json
```

Step 2: Validate Bicep Syntax

步骤2：验证Bicep语法

Run Bicep CLI to check template syntax before attempting deployment validation:

bash

bicep build <bicep-file> --stdout

What to capture:

Syntax errors with line/column numbers
Warning messages
Build success/failure status

If Bicep CLI is not installed:

Note the issue in the report
Continue to Step 3 (Azure will validate syntax during what-if)

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

bash

bicep build <bicep-file> --stdout

需要捕获的内容：

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

如果未安装Bicep CLI：

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

Step 3: Run Preflight Validation

步骤3：运行预检验证

Choose the appropriate validation based on project type detected in Step 1.

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

For azd Projects (azure.yaml exists)

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

Use

azd provision --preview

to validate the deployment:

bash

azd provision --preview

If an environment is specified or multiple environments exist:

bash

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

使用

azd provision --preview

验证部署：

bash

azd provision --preview

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

bash

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

For Standalone Bicep (no azure.yaml)

对于独立Bicep（无azure.yaml）

Determine the deployment scope from the Bicep file's

targetScope

declaration:

Target Scope	Command
`resourceGroup` (default)	`az deployment group what-if`
`subscription`	`az deployment sub what-if`
`managementGroup`	`az deployment mg what-if`
`tenant`	`az deployment tenant what-if`

Run with Provider validation level first:

bash

undefined

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

bash

undefined

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


**Fallback Strategy:**

If `--validation-level Provider` fails with permission errors (RBAC), retry with `ProviderNoRbac`:

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

Note the fallback in the report—the user may lack full deployment permissions.

az deployment tenant what-if
--location <location>
--template-file <bicep-file>
--parameters <param-file>
--validation-level Provider


**回退策略：**

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

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

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

Step 4: Capture What-If Results

步骤4：捕获what-if结果

Parse the what-if output to categorize resource changes:

Change Type	Symbol	Meaning
Create	`+`	New resource will be created
Delete	`-`	Resource will be deleted
Modify	`~`	Resource properties will change
NoChange	`=`	Resource unchanged
Ignore	`*`	Resource not analyzed (limits reached)
Deploy	`!`	Resource will be deployed (changes unknown)

For modified resources, capture the specific property changes.

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

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

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

Step 5: Generate Report

步骤5：生成报告

Create a Markdown report file in the project root named:

```
preflight-report.md
```

Use the template structure from references/REPORT-TEMPLATE.md.

Report sections:

Summary - Overall status, timestamp, files validated, target scope
Tools Executed - Commands run, versions, validation levels used
Issues - All errors and warnings with severity and remediation
What-If Results - Resources to create/modify/delete/unchanged
Recommendations - Actionable next steps

在项目根目录中创建一个名为以下名称的Markdown报告文件：

```
preflight-report.md
```

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

报告章节：

摘要 - 整体状态、时间戳、已验证文件、目标范围
已执行工具 - 运行的命令、版本、使用的验证级别
问题 - 所有错误和警告，包含严重性和修复建议
what-if结果 - 将创建/修改/删除/未变更的资源
建议 - 可执行的后续步骤

Required Information

所需信息

Before running validation, gather:

Information	Required For	How to Obtain
Resource Group	`az deployment group`	Ask user or check existing `.azure/` config
Subscription	All deployments	`az account show` or ask user
Location	Sub/MG/Tenant scope	Ask user or use default from config
Environment	azd projects	`azd env list` or ask user

If required information is missing, prompt the user before proceeding.

运行验证之前，收集以下信息：

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

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

Error Handling

错误处理

See references/ERROR-HANDLING.md for detailed error handling guidance.

Key principle: Continue validation even when errors occur. Capture all issues in the final report.

Error Type	Action
Not logged in	Note in report, suggest `az login` or `azd auth login`
Permission denied	Fall back to `ProviderNoRbac` , note in report
Bicep syntax error	Include all errors, continue to other files
Tool not installed	Note in report, skip that validation step
Resource group not found	Note in report, suggest creating it

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

**核心原则：**即使发生错误，也要继续执行验证。在最终报告中捕获所有问题。

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

Tool Requirements

工具要求

This skill uses the following tools:

Azure CLI (
```
az
```
) - Version 2.76.0+ recommended for
```
--validation-level
```
Azure Developer CLI (
```
azd
```
) - For projects with
```
azure.yaml
```
Bicep CLI (
```
bicep
```
) - For syntax validation
Azure MCP Tools - For documentation lookups and best practices

Check tool availability before starting:

bash

az --version
azd version
bicep --version

此技能使用以下工具：

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

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

bash

az --version
azd version
bicep --version

Example Workflow

示例工作流

User: "Validate my Bicep deployment before I run it"
Agent detects
```
azure.yaml
```
→ azd project
Agent finds
```
infra/main.bicep
```
and
```
infra/main.bicepparam
```
Agent runs
```
bicep build infra/main.bicep --stdout
```
Agent runs
```
azd provision --preview
```
Agent generates
```
preflight-report.md
```
in project root
Agent summarizes findings to user

用户："在我运行之前验证我的Bicep部署"
Agent检测到
```
azure.yaml
```
→ azd项目
Agent找到
```
infra/main.bicep
```
和
```
infra/main.bicepparam
```
Agent运行
```
bicep build infra/main.bicep --stdout
```
Agent运行
```
azd provision --preview
```
Agent在项目根目录生成
```
preflight-report.md
```
Agent向用户总结发现的问题

Reference Documentation

参考文档

Validation Commands Reference
Report Template
Error Handling Guide

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