azure-resource-visualizer

概觀

什麼是 azure-resource-visualizer？

azure-resource-visualizer 是一個專注於 Azure 的可視化技能，用來分析你的 Azure resource groups，並將其轉換成清楚、易讀的架構文件。它會檢查資源本身、其設定與彼此之間的關係，接著產生詳細的 Mermaid 圖表與描述雲端拓撲的 markdown 檔案。

不用再手動拼湊虛擬網路、子網路、App Services、資料庫與安全性元件如何彼此搭配；azure-resource-visualizer 會自動完成資源探索與繪圖，讓你隨時掌握環境的最新全貌。

核心功能

• Resource group 探索 – 當沒有指定時，列出並協助你選擇 Azure resource groups。
• 深入資源分析 – 在指定的 resource group 中檢視資源、其設定與彼此之間的相依關係。
• 關聯關係對映 – 辨識並記錄運算、網路、資料與安全性資源之間的連結。
• Mermaid 圖表產生 – 輸出完整且語法正確的 Mermaid 圖表，可直接用於 markdown、文件網站或 wiki。
• 架構文件產生 – 產生 markdown 頁面，可包含資源清單、高階摘要與內嵌圖表。

適用對象

如果你符合以下情境，建議使用 azure-resource-visualizer：

• 雲端架構師：需要快速產出視覺化架構圖，用於審查與設計文件。
• 開發者或 DevOps 工程師：想了解 resource group 內各服務是如何串接在一起。
• 平台／基礎架構工程師：希望在多個訂用帳戶與團隊之間標準化文件格式。
• 資安或營運工程師：需要清楚掌握網路流向與相依關係。

它最適合用在已經部署好 Azure 資源、需要洞察、文件或新人上手資料的場景；若你目前只是在紙上規劃設計，則較不適合。

可以解決的問題

• 花好幾個小時在繪圖工具裡手動畫 Azure 架構圖。
• 難以理解大型 resource group 中各資源之間的關聯性。
• 架構文件長期未更新，與實際部署狀態不符。
• 缺乏每個 resource group 的一致、可檢閱的 markdown 文件。

什麼情況適合（或不適合）使用 azure-resource-visualizer

適合的情況：

• 你希望對現有 Azure 基礎架構進行 資料視覺化與報告。
• 你需要將 Mermaid 圖表 整合進 markdown、程式庫或內部文件入口。
• 你正在使用 Azure Resource Graph 或 az 來查詢資源中繼資料。

不那麼適合的情況：

• 你需要的是可以 佈建或變更 Azure 資源的工具（此技能專注於分析與視覺化，非部署工具）。
• 你想做 成本分析、效能監控或安全掃描——這些都不在範圍內。
• 你無法存取 Azure 訂用帳戶的中繼資料，或無法執行 az／Azure Resource Graph 查詢。

使用方式

先決條件

在使用 azure-resource-visualizer 之前，請先確認你具備：

• 啟用中的 Azure 訂用帳戶（subscription），且內含一個或多個 resource groups。
• 有權限在這些訂用帳戶中查詢資源。
• 已安裝並登入 Azure CLI (az)，若你的架構依賴 CLI 進行探索則必備。
• 若打算使用 Azure Resource Graph 查詢，需安裝 Resource Graph CLI extension：
  • az extension add --name resource-graph

這些先決條件能讓此技能（或使用它的代理／agent）列出 resource groups，並檢視資源與其關聯性。

安裝 azure-resource-visualizer 技能

若要從 microsoft/azure-skills repository 新增 azure-resource-visualizer，請使用 skills CLI：

npx skills add https://github.com/microsoft/azure-skills --skill azure-resource-visualizer

這會將技能定義與相關資產（範例、模板與參考文件）拉到你的本地 skills 設定中，方便你的 agent 或工作流程呼叫。

認識安裝後的檔案

安裝完成後，請查看 skills/azure-resource-visualizer 底下的重要檔案與資料夾：

• SKILL.md – 技能的核心定義、職責說明與工作流程指引。
• assets/example-diagram.md – 完整的 Mermaid 圖表示例，展示一般 Azure 資源與層級的呈現方式。
• assets/template-architecture.md – 完整架構報告的 markdown 模板，包含資源清單與圖表區塊的占位標記。
• references/azure-resource-graph.md – 使用 Azure Resource Graph 進行大規模資源探索的說明與 KQL 範例。

這些檔案示範了「理想輸出」應該長什麼樣子，以及如何組織你自己的架構文件。

典型流程：從 resource group 到架構圖

步驟 1：選擇或探索 resource group

若使用者尚未指定 resource group 名稱，此技能的流程會：

1. 使用可用工具（通常是 az 或 Azure Resource Graph）來 列出 resource groups。
2. 提供包含名稱與位置的 編號清單。
3. 詢問使用者要分析哪一個 resource group。

若一開始就已知 resource group，技能便可略過探索階段，直接進入分析。

步驟 2：探索資源與關係

一旦選定 resource group，azure-resource-visualizer 會專注於：

• 列出該群組內所有資源（類型、名稱、位置，以及像 SKU 這類相關設定）。
• 辨識資源如何彼此連結——例如哪些 App Services 使用哪些子網路、哪些 Function Apps 會存取哪些資料庫，或身分識別如何存取 Key Vault。

這可以透過以下工具完成：

• 加上 --resource-group 篩選條件的 az 指令。
• 使用 az graph query 搭配與 references/azure-resource-graph.md 類似的 KQL 模式。

步驟 3：產生 Mermaid 架構圖

接著，技能會將分析結果轉換成 Mermaid 圖表。assets/example-diagram.md 中的範例展示了整體風格：

• 使用 subgraph 區塊進行 分層分組，例如：
  • Network Layer（VNet、subnets、NSGs）
  • Compute Layer（App Service plans、App Services、Functions）
  • Data Layer（databases、storage）
  • Security & Identity（Key Vault、managed identities）
• 詳細節點標籤，呈現像位址範圍、SKU 或 runtime 版本等關鍵設定資料。
• 具描述性的邊線標籤，註記關係，例如 "HTTPS requests"、"SQL connection" 或 "Blob/Queue access"。

產生出的圖表符合標準 Mermaid 語法，因此可直接用於 GitHub markdown、文件產生工具與各種支援 Mermaid 的圖表預覽工具。

步驟 4：以 markdown 建立架構報告

使用 assets/template-architecture.md 作為起點，為每個 resource group 建立結構化報告：

• 在頁首填入 subscription、region、resource count 與 generation date。
• 撰寫簡短的 overview，說明解決方案的用途與關鍵元件。
• 在 Resource Inventory 表格中填入資源名稱、類型、SKU、位置與備註。
• 將產生的 Mermaid 圖表 貼到 Architecture Diagram 區段。
• 依據發現的關係，補充 Network Architecture、Data Flow、Identity & Access 與 Dependencies 的說明。
• 在 Notes & Recommendations 中記錄未來改進建議或風險。

如此可以建立一套可重複使用的報告格式，方便跨團隊或跨訂用帳戶採用。

使用情境範例

• 新成員入門 – 對核心 production resource groups 執行 azure-resource-visualizer，將產生的 markdown 分享給新同仁，協助他們快速理解系統架構。
• 變更前審查 – 在進行基礎架構變更前先繪製 resource group 架構圖，掌握相依關係與可能的影響範圍。
• 架構文件汰舊更新 – 定期重新執行此技能，更新圖表與資源清單，讓文件持續對應實際執行環境。

常見問題（FAQ）

azure-resource-visualizer 會部署或修改任何 Azure 資源嗎？

不會。azure-resource-visualizer 專注於 分析、視覺化與文件化。它會使用像 az 和 Azure Resource Graph 這類查詢工具來檢視現有的 Azure 資源，然後輸出 Mermaid 圖表與 markdown。它不會建立、更新或刪除任何資源。

azure-resource-visualizer 依賴哪些工具？

此技能的設計是與現有 Azure 工具搭配使用，而不是取代它們。在一般情況下，它主要依賴：

• Azure CLI (az) 列出 resource groups 與資源。
• 選用的 Azure Resource Graph（az graph query），用於快速進行跨訂用帳戶查詢，如 references/azure-resource-graph.md 中的示例。

實際環境可能會依你的 agent 或工作流程設定而有所不同，但你應預期需要安裝並完成 az 的驗證。

azure-resource-visualizer 可以跨多個訂用帳戶使用嗎？

可以，只要你的環境與查詢設計支援跨訂用帳戶探索。透過 Azure Resource Graph，你可以跨多個訂用帳戶查詢資源，再將分析範圍限制在特定的 resource group 或多個群組上。此技能的重點是你選定的 resource groups，而不受訂用帳戶本身限制。

azure-resource-visualizer 會產生哪種類型的圖表？

azure-resource-visualizer 會產生 基於 Mermaid 的架構圖。這些圖表具有以下特性：

• 使用分層的 subgraph 區段（Network、Compute、Data、Security & Identity）。
• 節點上會標示關鍵屬性（例如 VNet 位址空間、SKU、runtime 等）。
• 使用具方向性的邊線與文字描述元件間的互動方式。

輸出是標準的 Mermaid 程式碼，可直接嵌入到 markdown 檔案、GitHub README 或任何支援 Mermaid 的文件網站中。

我可以自訂產生的文件嗎？

可以。assets/template-architecture.md 本來就是當作模板來撰寫的，你可以：

• 調整各個區段（新增或移除表格、標題或備註區）。
• 依照組織內部標準統一用語與格式。
• 將此模板作為 agent 或腳本自動產生文件的基礎。

此技能的目標是提供一個 一致的結構，至於如何配合你的流程進一步調整，則完全由你決定。

azure-resource-visualizer 適合非常小的測試環境嗎？

它可以用在任何大小的 resource group，但當資源與關係多到手動繪圖變得耗時時，價值會特別高。若只有單一測試 VM 或極簡 demo，投入這些步驟可能不那麼必要；但對於多層應用程式、共用服務以及複雜網路拓撲，它會大幅提升理解與溝通效率。

我應該多久執行一次 azure-resource-visualizer？

每當你需要可信賴的環境視圖時都可以執行，例如：

• 在重要基礎架構變更之後。
• 在架構審查或稽核前。
• 以固定排程（例如每月或每季）執行，讓文件保持與實際環境同步。

由於此技能是唯讀，且透過查詢方式進行探索，因此可以放心地重複執行。

我在哪裡可以看到實際輸出的範例？

在技能目錄中：

• assets/example-diagram.md 包含一個完整的 Mermaid 架構圖範例，展示分層與註解關係的作法。
• assets/template-architecture.md 示範如何在該圖表之上，組成一份完整的架構報告。

閱讀這些檔案，是了解 azure-resource-visualizer 能為你的 Azure resource groups 產生哪些成果的最快途徑。