Infrastructure as Code to Diagram

Infrastructure as Code to Diagram

Generate architecture diagrams directly from your Bicep, Terraform, ARM templates, or Azure Pipeline definitions.

⚠️ Critical Guidelines

1. Always Use Full Resource Names

The whole point of generating from IaC is accuracy. Use the actual resource names from the code:

# ✅ CORRECT - Full names from Bicep/Terraform
aks = AKS("aks-ecommerce-prod\n3-10 nodes, D4s_v3")
cosmos = CosmosDb("cosmos-ecommerce-prod\ncatalog, inventory")
kv = KeyVaults("kv-ecommerce-prod")

# ❌ WRONG - Generic abbreviations
aks = AKS("AKS")
cosmos = CosmosDb("Cosmos")
kv = KeyVaults("KV")

2. Use labelloc='t' for Labels Inside Clusters

The diagrams library places labels below icons by default, causing them to overflow cluster boundaries. Fix: put labels ABOVE icons:

node_attr = {
    "fontname": "Arial Bold",
    "fontsize": "11",
    "labelloc": "t",  # Labels at TOP - stays inside clusters!
}

with Diagram("My Architecture", node_attr=node_attr, ...):
    with Cluster("Data Tier"):
        sql = SQLDatabases("sql-ecommerce-prod\nS3 tier")  # Label stays inside!

Additional settings for professional output:

graph_attr = {
    "dpi": "200",              # High resolution
    "fontname": "Arial Bold",  # Bold titles
}

cluster_style = {"margin": "30"}  # Extra padding inside clusters

3. ALWAYS Review the Output (Mandatory!)

After generating, you MUST view the image and check for:

If ANY issues exist, regenerate with fixes. Never deliver without confirming all resource names are fully readable.

How It Works

When you have access to your codebase (via GitHub Copilot in your repo, or Claude Code with file access), the AI can:

1. Read your IaC files (Bicep, Terraform, ARM, YAML pipelines)
2. Parse the resource definitions and relationships
3. Map resources to official Azure diagram components
4. Generate accurate architecture diagrams

This creates diagrams that are the source of truth - directly derived from your actual infrastructure code.

Example Prompts

From Bicep Files

Basic diagram generation:

Read the Bicep files in /infra and generate an architecture diagram showing all Azure resources
and their relationships

With module resolution:

Analyze main.bicep and its module references, then create a diagram of the complete
infrastructure. Follow the module references in the modules/ folder.

Network-focused:

Generate a network topology diagram from the Bicep files, focusing on VNets, subnets,
and private endpoints. Show which resources are in which subnet.

With resource details:

Read the Bicep in /infra and create a diagram that includes:
- Resource names as defined in the Bicep
- SKU/tier information where specified
- Subnet CIDR ranges
- Show private endpoints with dashed lines

Grouped by function:

Parse the Bicep files and generate a diagram grouped by logical function
(networking, compute, data, security) rather than by resource group

From Terraform

Read the Terraform files in /terraform and generate an Azure architecture diagram

Parse main.tf and the module definitions, then create a visual representation of the infrastructure

Create a diagram showing the resources defined in our Terraform, grouped by resource group

From ARM Templates

Analyze the ARM template in azuredeploy.json and generate an architecture diagram

Read all ARM templates in /arm-templates and create a consolidated infrastructure diagram

From Azure Pipelines

Basic pipeline diagram:

Read our azure-pipelines.yml and create a CI/CD pipeline diagram showing the stages and deployments

With environments:

Analyze the pipeline YAML files and generate a deployment flow diagram showing which
resources are deployed to which environments (dev, test, prod)

Including artifacts:

Create a pipeline diagram from azure-pipelines.yml that shows:
- Build stage with artifact creation
- Each deployment stage
- Artifact flows (dashed lines)
- Environment gates/approvals
- Stage dependencies and conditions

Combined infrastructure + pipeline:

Read our Bicep infrastructure code AND the azure-pipelines.yml to create:
1. An architecture diagram of the deployed resources
2. A deployment pipeline diagram showing how code flows to each environment

Combined Analysis

Full repo analysis:

Read our Bicep infrastructure code AND the azure-pipelines.yml to create:
1. An architecture diagram of the deployed resources
2. A deployment pipeline diagram showing how code flows to each environment

Multi-environment comparison:

We have Bicep parameter files for dev, test, and prod. Create three architecture diagrams
showing the differences between environments (e.g., different SKUs, node counts,
redundancy settings)

Security-focused from IaC:

Analyze our Bicep/Terraform and create a security architecture diagram highlighting:
- Identity and access (Entra ID, Managed Identities)
- Network security (NSGs, Firewall, Private Endpoints)
- Secrets management (Key Vault connections)
- Which resources have public endpoints vs private only

Cost visualization:

Read the Bicep files and create a diagram that visually indicates cost tiers:
- Group expensive resources (Premium SKUs) with a highlighted border
- Show which resources are consumption-based vs reserved
- Annotate with SKU names

Bicep Parsing Guide

Resource Mapping

Module References

When Bicep uses modules, the AI should:

1. Follow module references to understand the full resource graph
2. Include resources from all referenced modules
3. Show module boundaries as clusters if helpful

// Example: Follow this module reference
module aks 'modules/aks.bicep' = {
  name: 'aks-cluster'
  params: {
    // ...
  }
}

Extracting Relationships

Look for these patterns to determine connections:

// Subnet references indicate network placement
subnetId: vnet.outputs.subnets[0].id

// Private endpoint connections
privateEndpointSubnetId: vnet.outputs.subnets[2].id

// Resource references indicate dependencies
keyVaultName: keyVault.outputs.name
storageAccountName: storage.outputs.name

Terraform Parsing Guide

Resource Mapping

Following References

# Follow resource references
resource "azurerm_kubernetes_cluster" "aks" {
  default_node_pool {
    vnet_subnet_id = azurerm_subnet.aks.id  # <- Connection to subnet
  }
}

# Module references
module "database" {
  source = "./modules/database"
  # ...
}

Pipeline Diagram Generation

Azure Pipelines (YAML)

stages:
  - stage: Build
    jobs:
      - job: BuildJob
        steps:
          - task: Docker@2
            inputs:
              containerRegistry: "acr-connection"

  - stage: DeployDev
    dependsOn: Build
    jobs:
      - deployment: DeployToDev
        environment: "dev"

  - stage: DeployProd
    dependsOn: DeployDev
    jobs:
      - deployment: DeployToProd
        environment: "prod"

This generates a pipeline flow diagram showing: Build → DeployDev → DeployProd

GitHub Actions

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: azure/docker-login@v1

  deploy-dev:
    needs: build
    environment: development

  deploy-prod:
    needs: deploy-dev
    environment: production

Example: Full Workflow

Step 1: User Prompt

I have a Bicep-based infrastructure in /infra. Please:
1. Read all the Bicep files including modules
2. Generate an architecture diagram showing all resources
3. Group resources by subnet/network segment
4. Show private endpoint connections with dashed lines
5. Include resource names and SKUs as labels

Step 2: AI Reads Files

The AI reads:

• /infra/main.bicep
• /infra/modules/aks.bicep
• /infra/modules/sql.bicep
• /infra/modules/cosmos.bicep
• etc.

Step 3: AI Generates Diagram

from diagrams import Diagram, Cluster, Edge
from diagrams.azure.compute import AKS
from diagrams.azure.database import SQLDatabases, CosmosDb
# ... imports based on discovered resources

with Diagram("Infrastructure from Bicep", show=False):
    # Resources and connections based on parsed Bicep
    ...

Step 4: Output

A diagram that accurately reflects the actual infrastructure defined in code.

Tips for Best Results

Be Specific About Scope

# Good - specific scope
"Read the Bicep files in /infra/prod and generate a diagram"

# Less good - too vague
"Make a diagram of my infrastructure"

Request Grouping Strategy

"Group resources by:
- Resource group
- Subnet/network segment
- Logical tier (web/api/data)
- Environment (dev/prod)"

Ask for Specific Details

"Include in the diagram:
- Resource names from the Bicep
- SKU/tier information
- Private endpoint connections (dashed lines)
- VNet peering relationships"

Handle Multiple Environments

"We have /infra/dev and /infra/prod Bicep folders. Create:
1. A dev environment diagram
2. A prod environment diagram
3. A comparison showing what's different"

Scaling Diagram Size

Choose settings based on the number of resources:

Small (< 10 resources)

graph_attr = {
    "nodesep": "0.6",
    "ranksep": "0.8",
    "pad": "0.5",
}

Medium (10-25 resources)

graph_attr = {
    "nodesep": "0.8",
    "ranksep": "1.0",
    "pad": "0.6",
    "dpi": "150",
}

Large (25+ resources)

graph_attr = {
    "nodesep": "1.0",
    "ranksep": "1.2",
    "pad": "0.8",
    "dpi": "150",
    "fontsize": "11",  # Slightly smaller font
}

Very Large (50+ resources)

Consider splitting into multiple diagrams:

• Network topology diagram
• Application architecture diagram
• Data flow diagram
• Security architecture diagram

Limitations

1. Implicit connections: Some relationships aren't explicit in IaC (e.g., app code connecting to database). The AI infers these from common patterns.

2. Dynamic resources: Resources created via loops or conditions may need clarification.

3. External dependencies: Resources outside the IaC (existing VNets, shared services) should be mentioned in the prompt.

4. Cross-repo modules: If modules are in separate repos, provide that context.

Sample Prompt Templates

Basic Infrastructure Diagram

Read the [Bicep/Terraform] files in [path] and generate an architecture diagram
with official Azure icons. Group resources by [VNet/resource group/tier].

Detailed Network Diagram

Analyze the networking resources in our IaC code and create a network topology diagram
showing VNets, subnets, peerings, private endpoints, and NSG relationships.

Security-Focused Diagram

Generate a diagram from our Bicep that highlights the security architecture: identity
(Entra ID, managed identities), network security (NSGs, firewalls, private endpoints),
and secrets management (Key Vault).

Pipeline + Infrastructure

Read both the azure-pipelines.yml and the Bicep infrastructure code. Create two diagrams:
1. The deployed Azure architecture
2. The CI/CD pipeline that deploys it