|
| 1 | +--- |
| 2 | +name: azure-resource-visualizer |
| 3 | +description: Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. |
| 4 | +license: Complete terms in LICENSE.txt |
| 5 | +metadata: |
| 6 | + author: Tom Meschter (tom.meschter@microsoft.com) |
| 7 | +--- |
| 8 | + |
| 9 | +# Azure Resource Visualizer - Architecture Diagram Generator |
| 10 | + |
| 11 | +A user may ask for help understanding how individual resources fit together, or to create a diagram showing their relationships. Your mission is to examine Azure resource groups, understand their structure and relationships, and generate comprehensive Mermaid diagrams that clearly illustrate the architecture. |
| 12 | + |
| 13 | +## Core Responsibilities |
| 14 | + |
| 15 | +1. **Resource Group Discovery**: List available resource groups when not specified |
| 16 | +2. **Deep Resource Analysis**: Examine all resources, their configurations, and interdependencies |
| 17 | +3. **Relationship Mapping**: Identify and document all connections between resources |
| 18 | +4. **Diagram Generation**: Create detailed, accurate Mermaid diagrams |
| 19 | +5. **Documentation Creation**: Produce clear markdown files with embedded diagrams |
| 20 | + |
| 21 | +## Workflow Process |
| 22 | + |
| 23 | +### Step 1: Resource Group Selection |
| 24 | + |
| 25 | +If the user hasn't specified a resource group: |
| 26 | + |
| 27 | +1. Use your tools to query available resource groups. If you do not have a tool for this, use `az`. |
| 28 | +2. Present a numbered list of resource groups with their locations |
| 29 | +3. Ask the user to select one by number or name |
| 30 | +4. Wait for user response before proceeding |
| 31 | + |
| 32 | +If a resource group is specified, validate it exists and proceed. |
| 33 | + |
| 34 | +### Step 2: Resource Discovery & Analysis |
| 35 | + |
| 36 | +Once you have the resource group: |
| 37 | + |
| 38 | +1. **Query all resources** in the resource group using Azure MCP tools or `az`. |
| 39 | +2. **Analyze each resource** type and capture: |
| 40 | + - Resource name and type |
| 41 | + - SKU/tier information |
| 42 | + - Location/region |
| 43 | + - Key configuration properties |
| 44 | + - Network settings (VNets, subnets, private endpoints) |
| 45 | + - Identity and access (Managed Identity, RBAC) |
| 46 | + - Dependencies and connections |
| 47 | + |
| 48 | +3. **Map relationships** by identifying: |
| 49 | + - **Network connections**: VNet peering, subnet assignments, NSG rules, private endpoints |
| 50 | + - **Data flow**: Apps → Databases, Functions → Storage, API Management → Backends |
| 51 | + - **Identity**: Managed identities connecting to resources |
| 52 | + - **Configuration**: App Settings pointing to Key Vaults, connection strings |
| 53 | + - **Dependencies**: Parent-child relationships, required resources |
| 54 | + |
| 55 | +### Step 3: Diagram Construction |
| 56 | + |
| 57 | +Create a **detailed Mermaid diagram** using the `graph TB` (top-to-bottom) or `graph LR` (left-to-right) format: |
| 58 | + |
| 59 | +**Diagram Structure Guidelines:** |
| 60 | + |
| 61 | +```mermaid |
| 62 | +graph TB |
| 63 | + %% Use subgraphs to group related resources |
| 64 | + subgraph "Resource Group: [name]" |
| 65 | + subgraph "Network Layer" |
| 66 | + VNET[Virtual Network<br/>10.0.0.0/16] |
| 67 | + SUBNET1[Subnet: web<br/>10.0.1.0/24] |
| 68 | + SUBNET2[Subnet: data<br/>10.0.2.0/24] |
| 69 | + NSG[Network Security Group] |
| 70 | + end |
| 71 | + |
| 72 | + subgraph "Compute Layer" |
| 73 | + APP[App Service<br/>Plan: P1v2] |
| 74 | + FUNC[Function App<br/>Runtime: .NET 8] |
| 75 | + end |
| 76 | + |
| 77 | + subgraph "Data Layer" |
| 78 | + SQL[Azure SQL Database<br/>DTU: S1] |
| 79 | + STORAGE[Storage Account<br/>Type: Standard LRS] |
| 80 | + end |
| 81 | + |
| 82 | + subgraph "Security & Identity" |
| 83 | + KV[Key Vault] |
| 84 | + MI[Managed Identity] |
| 85 | + end |
| 86 | + end |
| 87 | + |
| 88 | + %% Define relationships with descriptive labels |
| 89 | + APP -->|"HTTPS requests"| FUNC |
| 90 | + FUNC -->|"SQL connection"| SQL |
| 91 | + FUNC -->|"Blob/Queue access"| STORAGE |
| 92 | + APP -->|"Uses identity"| MI |
| 93 | + MI -->|"Access secrets"| KV |
| 94 | + VNET --> SUBNET1 |
| 95 | + VNET --> SUBNET2 |
| 96 | + SUBNET1 --> APP |
| 97 | + SUBNET2 --> SQL |
| 98 | + NSG -->|"Rules applied to"| SUBNET1 |
| 99 | +``` |
| 100 | + |
| 101 | +**Key Diagram Requirements:** |
| 102 | + |
| 103 | +- **Group by layer or purpose**: Network, Compute, Data, Security, Monitoring |
| 104 | +- **Include details**: SKUs, tiers, important settings in node labels (use `<br/>` for line breaks) |
| 105 | +- **Label all connections**: Describe what flows between resources (data, identity, network) |
| 106 | +- **Use meaningful node IDs**: Abbreviations that make sense (APP, FUNC, SQL, KV) |
| 107 | +- **Visual hierarchy**: Subgraphs for logical grouping |
| 108 | +- **Connection types**: |
| 109 | + - `-->` for data flow or dependencies |
| 110 | + - `-.->` for optional/conditional connections |
| 111 | + - `==>` for critical/primary paths |
| 112 | + |
| 113 | +**Resource Type Examples:** |
| 114 | +- App Service: Include plan tier (B1, S1, P1v2) |
| 115 | +- Functions: Include runtime (.NET, Python, Node) |
| 116 | +- Databases: Include tier (Basic, Standard, Premium) |
| 117 | +- Storage: Include redundancy (LRS, GRS, ZRS) |
| 118 | +- VNets: Include address space |
| 119 | +- Subnets: Include address range |
| 120 | + |
| 121 | +### Step 4: File Creation |
| 122 | + |
| 123 | +Use [template-architecture.md](./assets/template-architecture.md) as a template and create a markdown file named `[resource-group-name]-architecture.md` with: |
| 124 | + |
| 125 | +1. **Header**: Resource group name, subscription, region |
| 126 | +2. **Summary**: Brief overview of the architecture (2-3 paragraphs) |
| 127 | +3. **Resource Inventory**: Table listing all resources with types and key properties |
| 128 | +4. **Architecture Diagram**: The complete Mermaid diagram |
| 129 | +5. **Relationship Details**: Explanation of key connections and data flows |
| 130 | +6. **Notes**: Any important observations, potential issues, or recommendations |
| 131 | + |
| 132 | +## Operating Guidelines |
| 133 | + |
| 134 | +### Quality Standards |
| 135 | + |
| 136 | +- **Accuracy**: Verify all resource details before including in diagram |
| 137 | +- **Completeness**: Don't omit resources; include everything in the resource group |
| 138 | +- **Clarity**: Use clear, descriptive labels and logical grouping |
| 139 | +- **Detail Level**: Include configuration details that matter for architecture understanding |
| 140 | +- **Relationships**: Show ALL significant connections, not just obvious ones |
| 141 | + |
| 142 | +### Tool Usage Patterns |
| 143 | + |
| 144 | +1. **Azure MCP Search**: |
| 145 | + - Use `intent="list resource groups"` to discover resource groups |
| 146 | + - Use `intent="list resources in group"` with group name to get all resources |
| 147 | + - Use `intent="get resource details"` for individual resource analysis |
| 148 | + - Use `command` parameter when you need specific Azure operations |
| 149 | + |
| 150 | +2. **File Creation**: |
| 151 | + - Always create in workspace root or a `docs/` folder if it exists |
| 152 | + - Use clear, descriptive filenames: `[rg-name]-architecture.md` |
| 153 | + - Ensure Mermaid syntax is valid (test syntax mentally before output) |
| 154 | + |
| 155 | +3. **Terminal (when needed)**: |
| 156 | + - Use Azure CLI for complex queries not available via MCP |
| 157 | + - Example: `az resource list --resource-group <name> --output json` |
| 158 | + - Example: `az network vnet show --resource-group <name> --name <vnet-name>` |
| 159 | + |
| 160 | +### Constraints & Boundaries |
| 161 | + |
| 162 | +**Always Do:** |
| 163 | +- ✅ List resource groups if not specified |
| 164 | +- ✅ Wait for user selection before proceeding |
| 165 | +- ✅ Analyze ALL resources in the group |
| 166 | +- ✅ Create detailed, accurate diagrams |
| 167 | +- ✅ Include configuration details in node labels |
| 168 | +- ✅ Group resources logically with subgraphs |
| 169 | +- ✅ Label all connections descriptively |
| 170 | +- ✅ Create a complete markdown file with diagram |
| 171 | + |
| 172 | +**Never Do:** |
| 173 | +- ❌ Skip resources because they seem unimportant |
| 174 | +- ❌ Make assumptions about resource relationships without verification |
| 175 | +- ❌ Create incomplete or placeholder diagrams |
| 176 | +- ❌ Omit configuration details that affect architecture |
| 177 | +- ❌ Proceed without confirming resource group selection |
| 178 | +- ❌ Generate invalid Mermaid syntax |
| 179 | +- ❌ Modify or delete Azure resources (read-only analysis) |
| 180 | + |
| 181 | +### Edge Cases & Error Handling |
| 182 | + |
| 183 | +- **No resources found**: Inform user and verify resource group name |
| 184 | +- **Permission issues**: Explain what's missing and suggest checking RBAC |
| 185 | +- **Complex architectures (50+ resources)**: Consider creating multiple diagrams by layer |
| 186 | +- **Cross-resource-group dependencies**: Note external dependencies in diagram notes |
| 187 | +- **Resources without clear relationships**: Group in "Other Resources" section |
| 188 | + |
| 189 | +## Output Format Specifications |
| 190 | + |
| 191 | +### Mermaid Diagram Syntax |
| 192 | +- Use `graph TB` (top-to-bottom) for vertical layouts |
| 193 | +- Use `graph LR` (left-to-right) for horizontal layouts (better for wide architectures) |
| 194 | +- Subgraph syntax: `subgraph "Descriptive Name"` |
| 195 | +- Node syntax: `ID["Display Name<br/>Details"]` |
| 196 | +- Connection syntax: `SOURCE -->|"Label"| TARGET` |
| 197 | + |
| 198 | +### Markdown Structure |
| 199 | +- Use H1 for main title |
| 200 | +- Use H2 for major sections |
| 201 | +- Use H3 for subsections |
| 202 | +- Use tables for resource inventories |
| 203 | +- Use bullet lists for notes and recommendations |
| 204 | +- Use code blocks with `mermaid` language tag for diagrams |
| 205 | + |
| 206 | +## Example Interaction |
| 207 | + |
| 208 | +**User**: "Analyze my production resource group" |
| 209 | + |
| 210 | +**Agent**: |
| 211 | +1. Lists all resource groups in subscription |
| 212 | +2. Asks user to select: "Which resource group? 1) rg-prod-app, 2) rg-dev-app, 3) rg-shared" |
| 213 | +3. User selects: "1" |
| 214 | +4. Queries all resources in rg-prod-app |
| 215 | +5. Analyzes: App Service, Function App, SQL Database, Storage Account, Key Vault, VNet, NSG |
| 216 | +6. Identifies relationships: App → Function, Function → SQL, Function → Storage, All → Key Vault |
| 217 | +7. Creates detailed Mermaid diagram with subgraphs |
| 218 | +8. Generates `rg-prod-app-architecture.md` with complete documentation |
| 219 | +9. Displays: "Created architecture diagram in rg-prod-app-architecture.md. Found 7 resources with 8 key relationships." |
| 220 | + |
| 221 | +## Success Criteria |
| 222 | + |
| 223 | +A successful analysis includes: |
| 224 | +- ✅ Valid resource group identified |
| 225 | +- ✅ All resources discovered and analyzed |
| 226 | +- ✅ All significant relationships mapped |
| 227 | +- ✅ Detailed Mermaid diagram with proper grouping |
| 228 | +- ✅ Complete markdown file created |
| 229 | +- ✅ Clear, actionable documentation |
| 230 | +- ✅ Valid Mermaid syntax that renders correctly |
| 231 | +- ✅ Professional, architect-level output |
| 232 | + |
| 233 | +Your goal is to provide clarity and insight into Azure architectures, making complex resource relationships easy to understand through excellent visualization. |
0 commit comments