Azv Diagram Azure Sync

Compare a Draw.io Azure architecture diagram against a live Azure environment and resolve drift. Supports two modes: quick (existence-level) and deep (existence + property-level comparison against all tracked configuration properties).

Input: A Draw.io diagram file (.drawio or .drawio.xml) and an Azure scope — a resource group name or subscription ID. The user can specify both, or the skill will prompt for missing inputs.

Tools required: File system tools (read/write files), Azure MCP server tools (mcp_azure_group_resource_list, mcp_azure_compute, mcp_azure_storage, mcp_azure_subscription_list, etc.), Draw.io MCP (mcp_drawio_create_diagram or mcp_draw_io_create_diagram)

Reference files:

• .github/skills/shared/azure-resource-model.md — Shared resource metadata model definition
• .github/skills/shared/azure-stencil-mapping.json — Azure resource type to Draw.io stencil mapping (used for reverse-lookup and diagram generation)
• .github/skills/shared/azure-deployment-verification.md — Pre-deployment verification rules (MUST run before generating Azure update scripts)
• .github/skills/shared/azure-resource-configs.md — Per-resource-type configuration schemas with defaults and auto-detection rules
• .github/skills/shared/data/azure-property-paths.json — Azure Property Retrieval Mapping (MCP tools, CLI fallbacks, ARM JSON paths, severity classifications)

Shared procedures (MUST follow):

• .github/skills/shared/procedures/azure-authentication.md — Azure session check procedure
• .github/skills/shared/procedures/diagram-parsing.md — Diagram-to-resource-model parsing procedure
• .github/skills/shared/procedures/resource-matching.md — Resource matching algorithm
• .github/skills/shared/procedures/resource-filtering.md — Resource exclusion lists (use "Exclude for Diagrams" column)

---

Steps

1. Check Azure Authentication

Follow the procedure in .github/skills/shared/procedures/azure-authentication.md. HARD GATE — stop if not authenticated.

2. Accept Inputs

Identify the Draw.io diagram, the Azure scope, and the comparison depth.

2a. Identify Comparison Depth

Determine the depth mode from the user's request:

• Quick (default): Existence-level comparison only — are the right resources deployed?
• Deep: Existence + property-level comparison — checks every tracked configuration property (SKU, tier, size, security settings) against expected values from azure-property-paths.json

If the user says "deep", "detailed", "full", "property", or "configuration" → use deep mode. Otherwise default to quick.

2b. Identify the Draw.io Diagram

If the user specifies a file path:

• Verify the file exists and is a .drawio or .drawio.xml file
• Read the file contents

If no file is specified:

• Search the workspace for .drawio files
• If exactly one is found, use it (announce which file)
• If multiple are found, present the list and ask the user to select one
• If none are found, ask the user to provide a diagram file

2c. Identify the Azure Scope

If the user specifies a resource group:

• Use that resource group as the comparison scope
• Verify the resource group exists using Azure MCP tools

If the user specifies a subscription:

• Use that subscription as the comparison scope
• Note: subscription-level comparison can be noisy — warn the user

If no scope is specified:

• Check if the diagram contains resource group containers — if so, use those resource group names as the scope
• If the resource group name(s) can be inferred from the diagram, confirm with the user: "The diagram shows resources in resource group <name>. Should I compare against that resource group?"
• If the scope cannot be inferred, ask the user: "Which Azure resource group or subscription should I compare this diagram against?"

3. Parse Diagram into Resource Model

Follow the procedure in .github/skills/shared/procedures/diagram-parsing.md to parse the Draw.io XML into a structured resource model.

Display the parsed resource model as a table with columns: #, Resource, Type, Container.

4. Discover Azure Environment

Query the Azure scope to build a resource model of what is actually deployed.

Discovery process:

1. List all resources in scope:

   • For resource group scope: Use mcp_azure_group_resource_list to get all resources in the specified resource group
   • For subscription scope: Use mcp_azure_subscription_list to get subscriptions, then list resources across the target subscription

2. Build the Azure resource model: For each discovered resource, create a resource model entry:

   {
     "id": "<resource-name-slug>",
     "type": "<Microsoft.Provider/resourceType>",
     "name": "<resource-name>",
     "resourceGroup": "<resource-group-name>",
     "location": "<region>",
     "properties": {},
     "relationships": []
   }

3. Enrich with resource-type-specific details where available:

   • Use mcp_azure_compute for VM details (size, OS, status)
   • Use mcp_azure_storage for Storage Account details (SKU, kind, access tier)
   • Use Azure MCP networking tools for VNet, subnet, NSG details
   • Use Azure MCP database tools for SQL, Cosmos DB details
   • Use Azure MCP web/app tools for App Service, Function App details

4. Discover relationships:

   • VNets → Subnets (containment from resource hierarchy)
   • Resources → Resource Groups (containment)
   • NICs → VMs (connection via NIC's virtualMachine property)
   • Private Endpoints → target resources (connection via privateLinkServiceConnections)
   • App Services → App Service Plans (dependency)
   • Subnets → NSGs (security association)

5. Exclude infrastructure-only resources: Apply the "Exclude for Diagrams" column from .github/skills/shared/procedures/resource-filtering.md.

6. Output the Azure resource model as a table with columns: #, Resource, Type, Location.

5. Compare Models and Identify Drift

Follow the matching algorithm in .github/skills/shared/procedures/resource-matching.md to compare diagram resources (Step 3) against Azure resources (Step 4). Use label "Diagram Only" for Model A and "Azure Only" for Model B.

5b. Deep Mode Only: Retrieve and Compare Properties

Skip this step in quick mode.

For each resource matched in both models (In Sync or In Sync with name difference):

1. Retrieve full properties from Azure using the Azure Property Retrieval Mapping in .github/skills/shared/data/azure-property-paths.json. Use the listed MCP tool (primary) or az CLI command (fallback) for each resource type. Extract all tracked properties using the ARM JSON paths specified in the mapping.

2. Determine expected values: Use diagram-specified values if available; otherwise use defaults from azure-property-paths.json.

3. Normalize before comparing: Case-insensitive for enum values (SKUs, tiers, regions). Boolean normalization (true/"true"/"True" → true). Empty collection equivalence ([]/null/absent → equal). Numeric strings ("30" = 30). Region normalization ("West Europe" → "westeurope").

4. Record property drifts where normalized expected ≠ normalized actual, including property name, expected value (source: diagram/default), actual Azure value, and severity level from azure-property-paths.json.

5. Refine classification: Matched resources get sub-status: "all properties match" or "properties drifted" (with count per severity level).

6. Present Drift Report

Display a categorized drift report.

Quick mode: Summary table (In Sync / Diagram Only / Azure Only counts), details table (Resource, Type, Status, Notes). If fully in sync, show "✅ Fully in sync!" and stop.

Deep mode: Add property drift information:

• Summary table adds columns: Critical, Warning, Info (counts of property drifts per resource)
• For each resource with property drifts, show per-property diff table (Property, Expected, Actual, Severity, Source)
• Only show properties where expected ≠ actual — matching properties go in a separate "Confirmed In Sync" table

If drift is detected, proceed to Step 7.

7. Offer Resolution Options

When drift is detected, present resolution options to the user.

Quick mode options: Update Diagram (1), Update Azure (2), Selective (3), No action (4).

Deep mode options (vary by drift type):

Wait for the user's choice before proceeding.