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 に進みます（what-if 中に Azure が構文を検証します）

手順 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) - --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. エージェントが検出結果をユーザーに要約

参考ドキュメント

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