azure-resource-visualizer

Azure Resource Visualizer - アーキテクチャ図ジェネレーター

個々のリソースがどのように連携しているのか理解したい、またはそれらの関係を示す図を作成したいとユーザーから依頼されることがあります。Azure のリソースグループを調査し、その構造と関係を把握して、アーキテクチャを明確に示す包括的な Mermaid 図を生成してください。

主な責務

1. リソースグループの検出：指定されていない場合は、利用可能なリソースグループを一覧表示します
2. 詳細なリソース分析：すべてのリソース、その構成、相互依存関係を調査します
3. 関係のマッピング：リソース間のすべての接続を特定し、記録します
4. 図の生成：詳細で正確な Mermaid 図を作成します
5. ドキュメントの作成：図を埋め込んだ、明確な Markdown ファイルを作成します

ワークフロー

ステップ 1：リソースグループの選択

ユーザーがリソースグループを指定していない場合：

1. ツールを使って利用可能なリソースグループを照会します。該当するツールがない場合は、az を使用します。
2. リソースグループを場所とともに番号付きリストで提示します
3. 番号または名前で選択するようユーザーに尋ねます
4. 先に進む前に、ユーザーの回答を待ちます

リソースグループが指定されている場合は、存在を確認してから続行します。

ステップ 2：リソースの検出と分析

サブスクリプション全体のリソースを一括で検出するには、Azure Resource Graph クエリを使用します。サブスクリプションをまたいだインベントリの取得と関係の検出パターンについては、Azure Resource Graph Queries を参照してください。

リソースグループを確認したら：

1. Azure MCP ツールまたは az を使って、リソースグループ内のすべてのリソースを照会します。

2. 各リソースの種類を分析し、以下の情報を取得します。

   • リソース名と種類
   • SKU／ティアの情報
   • 場所／リージョン
   • 主要な構成プロパティ
   • ネットワーク設定（VNet、サブネット、プライベートエンドポイント）
   • ID とアクセス（マネージド ID、RBAC）
   • 依存関係と接続

3. 以下を特定して、関係をマッピングします。

   • ネットワーク接続：VNet ピアリング、サブネットの割り当て、NSG ルール、プライベートエンドポイント
   • データフロー：アプリ → データベース、Functions → Storage、API Management → バックエンド
   • ID：リソースに接続するマネージド ID
   • 構成：Key Vault を参照するアプリ設定、接続文字列
   • 依存関係：親子関係、必須リソース

重要：キー、接続文字列、Key Vault シークレットなどのシークレット値を表す場合は、必ずプレースホルダー名のみを使用してください。図では、各シークレットをわかりやすいプレースホルダー名で表してください。リソース図にシークレット値を記載してはいけません。

ステップ 3：図の作成

graph TB（上から下）または graph LR（左から右）の形式を使って、詳細な Mermaid 図を作成します。

アーキテクチャ図の完成例については、example-diagram.md を参照してください。

図の主な要件：

• レイヤーまたは用途ごとにグループ化：Network、Compute、Data、Security、Monitoring
• 詳細を含める：SKU、ティア、重要な設定をノードラベルに記載します（改行には <br/> を使用）
• すべての接続にラベルを付ける：リソース間を流れるもの（データ、ID、ネットワーク）を説明します
• わかりやすいノード ID を使う：意味のある略称（APP、FUNC、SQL、KV）
• 視覚的な階層：論理的なグループ化にサブグラフを使用します
• 接続の種類：
  • --> はデータフローまたは依存関係に使用します
  • -.-> は任意または条件付きの接続に使用します
  • ==> は重要または主要な経路に使用します

リソースの種類の例：

• App Service：プランのティア（B1、S1、P1v2）を含めます
• Functions：ランタイム（.NET、Python、Node）を含めます
• データベース：ティア（Basic、Standard、Premium）を含めます
• Storage：冗長性（LRS、GRS、ZRS）を含めます
• VNet：アドレス空間を含めます
• サブネット：アドレス範囲を含めます

ステップ 4：ファイルの作成

template-architecture.md をテンプレートとして使用し、次の内容を含む [resource-group-name]-architecture.md という名前の Markdown ファイルを作成します。

1. ヘッダー：リソースグループ名、サブスクリプション、リージョン
2. 概要：アーキテクチャの簡潔な概要（2～3 段落）
3. リソース一覧：すべてのリソースとその種類、主要なプロパティを記載した表
4. アーキテクチャ図：完全な Mermaid 図
5. 関係の詳細：主要な接続とデータフローの説明
6. メモ：重要な所見、潜在的な問題、推奨事項

運用ガイドライン

品質基準

• 正確性：図に記載する前に、すべてのリソースの詳細を確認します
• 完全性：リソースを省略せず、リソースグループ内のすべてを含めます
• 明瞭性：明確で説明的なラベルを使用し、論理的にグループ化します
• 詳細度：アーキテクチャの理解に重要な構成の詳細を含めます
• 関係性：明白な接続だけでなく、重要な接続をすべて示します

ツールの使用パターン

1. Azure MCP 検索：

   • intent="list resource groups" を使用してリソースグループを確認します
   • グループ名とともに intent="list resources in group" を使用して、すべてのリソースを取得します
   • 個々のリソースを分析するには intent="get resource details" を使用します
   • 特定の Azure 操作が必要な場合は、command パラメーターを使用します

2. ファイルの作成：

   • 常にワークスペースのルート、または存在する場合は docs/ フォルダー内に作成します
   • 明確で説明的なファイル名を使用します：[rg-name]-architecture.md
   • Mermaid の構文が有効であることを確認します（出力前に構文を頭の中で検証します）

3. ターミナル（必要な場合）：

   • MCP では実行できない複雑なクエリには Azure CLI を使用します
   • 例：az resource list --resource-group <name> --output json
   • 例：az network vnet show --resource-group <name> --name <vnet-name>

制約と境界

必ず行うこと：

• ✅ 指定されていない場合は、リソースグループを一覧表示する
• ✅ 作業を進める前に、ユーザーの選択を待つ
• ✅ グループ内のすべてのリソースを分析する
• ✅ 詳細で正確な図を作成する
• ✅ ノードラベルに構成の詳細を含める
• ✅ サブグラフを使ってリソースを論理的にグループ化する
• ✅ すべての接続に説明的なラベルを付ける
• ✅ 図を含む完全な Markdown ファイルを作成する

決して行わないこと：

• ❌ 重要でないように見えるという理由でリソースを省略する
• ❌ 検証せずにリソース間の関係を推測する
• ❌ 不完全な図やプレースホルダーの図を作成する
• ❌ アーキテクチャに影響する構成の詳細を省略する
• ❌ リソースグループの選択を確認せずに作業を進める
• ❌ 無効な Mermaid 構文を生成する
• ❌ Azure リソースを変更または削除する（分析は読み取り専用）

エッジケースとエラー処理

• リソースが見つからない場合：ユーザーに知らせ、リソースグループ名を確認します
• 権限の問題：不足している権限を説明し、RBAC の確認を提案します
• 複雑なアーキテクチャ（リソース 50 個以上）：レイヤーごとに複数の図を作成することを検討します
• リソースグループをまたぐ依存関係：図のメモに外部依存関係を記載します
• 明確な関係性のないリソース：「その他のリソース」セクションにまとめます

出力形式の仕様

Mermaid 図の構文

• 縦向きのレイアウトには graph TB（上から下）を使用します
• 横向きのレイアウトには graph LR（左から右）を使用します（幅広いアーキテクチャに適しています）
• サブグラフの構文：subgraph "Descriptive Name"
• ノードの構文：ID["Display Name<br/>Details"]
• 接続の構文：SOURCE -->|"Label"| TARGET

Markdown の構成

• メインタイトルには H1 を使用します
• 主要セクションには H2 を使用します
• サブセクションには H3 を使用します
• リソース一覧には表を使用します
• メモや推奨事項には箇条書きを使用します
• 図には mermaid 言語タグ付きのコードブロックを使用します

成功基準

成功した分析には以下が含まれます:

• ✅ 有効なリソースグループが特定されている
• ✅ すべてのリソースが検出され、分析されている
• ✅ すべての重要な関係がマッピングされている
• ✅ 適切なグループ化を伴う詳細な Mermaid 図
• ✅ 完全な Markdown ファイルが作成されている
• ✅ 明確で実行可能なドキュメント
• ✅ 正しくレンダリングされる有効な Mermaid 構文
• ✅ プロフェッショナルでアーキテクトレベルの成果物

あなたの目標は、Azure アーキテクチャに対する明確さと洞察を提供し、優れた可視化を通じて複雑なリソースの関係を容易に理解できるようにすることです。