Azure Deployment Preflight Validation

このスキルは実行前に 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 またはユーザーに確認
場所	Sub/MG/Tenant スコープ	ユーザーに確認するか設定からデフォルトを使用
環境	azd プロジェクト	azd env list またはユーザーに確認

必要な情報が不足している場合、続行する前にユーザーに確認してください。

エラー処理

詳細なエラー処理ガイダンスについては references/ERROR-HANDLING.md を参照してください。

重要原則: エラーが発生した場合でも検証を続行してください。すべての問題を最終レポートに記載します。

エラー タイプ	アクション
ログインしていない	レポートに記載、az login または azd auth login を提案
権限が拒否された	ProviderNoRbac にフォールバック、レポートに記載
Bicep 構文エラー	すべてのエラーを記載、他のファイルの検証を続行
ツールがインストールされていない	レポートに記載、その検証ステップをスキップ
リソース グループが見つからない	レポートに記載、作成を提案

ツール要件

このスキルは以下のツールを使用します:

• Azure CLI (az) - --validation-level の場合はバージョン 2.76.0 以上を推奨
• Azure Developer CLI (azd) - azure.yaml を含むプロジェクト用
• Bicep CLI (bicep) - 構文検証用
• Azure MCP Tools - ドキュメント検索とベストプラクティス用

開始前にツールの利用可能性を確認します:

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. エージェントが調査結果をユーザーに要約

参考ドキュメント

• 検証コマンド リファレンス
• レポート テンプレート
• エラー処理ガイド