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：產生報告

在專案根目錄建立名為 preflight-report.md 的 Markdown 報告檔案。

使用 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 向使用者摘要說明結果

參考文件

• 驗證命令參考
• 報告範本
• 錯誤處理指南