Managing Diagrams

Diagrams — Architecture as Code

Generate cloud architecture diagrams programmatically using Python. Supports 15+ providers including AWS, Azure, GCP, Kubernetes, and on-premises infrastructure.

Repository: github.com/mingrammer/diagrams

Prerequisites

# Check installation
python3 -c "import diagrams; print(f'diagrams {diagrams.__version__}')" 2>/dev/null || echo "NOT INSTALLED"
dot -V 2>/dev/null || echo "Graphviz NOT INSTALLED"

# Install if needed
pip install diagrams
# macOS: brew install graphviz
# Ubuntu: apt-get install graphviz

Decision Matrix

Phase 1 — Discovery

Identify what architecture to diagram:

#!/usr/bin/env python3
"""List all available node providers and categories."""
import diagrams
from diagrams import aws, azure, gcp, k8s, onprem, saas, generic, programming, c4

# List available providers
providers = {
    "aws": dir(aws),
    "azure": dir(azure),
    "gcp": dir(gcp),
    "k8s": dir(k8s),
    "onprem": dir(onprem),
    "saas": dir(saas),
    "generic": dir(generic),
    "programming": dir(programming),
    "c4": dir(c4),
}

for provider, modules in providers.items():
    categories = [m for m in modules if not m.startswith("_")]
    print(f"{provider}: {', '.join(categories[:10])}...")

Phase 2 — Generate Diagram

AWS Architecture Example

#!/usr/bin/env python3
from diagrams import Diagram, Cluster, Edge
from diagrams.aws.compute import ECS, Lambda
from diagrams.aws.database import RDS, ElastiCache
from diagrams.aws.network import ELB, CloudFront, Route53
from diagrams.aws.storage import S3
from diagrams.aws.integration import SQS, SNS
from diagrams.aws.security import WAF

with Diagram("Production Architecture", show=False, direction="LR"):
    dns = Route53("DNS")
    cdn = CloudFront("CDN")
    waf = WAF("WAF")

    with Cluster("VPC"):
        lb = ELB("ALB")

        with Cluster("Application Tier"):
            svc = [ECS("service-1"), ECS("service-2"), ECS("service-3")]

        with Cluster("Data Tier"):
            db = RDS("PostgreSQL")
            cache = ElastiCache("Redis")

        with Cluster("Async Processing"):
            queue = SQS("task-queue")
            worker = Lambda("processor")
            events = SNS("notifications")

    storage = S3("assets")

    dns >> cdn >> waf >> lb >> svc
    svc >> cache >> db
    svc >> queue >> worker >> events
    cdn >> storage

Kubernetes Architecture Example

#!/usr/bin/env python3
from diagrams import Diagram, Cluster
from diagrams.k8s.compute import Pod, Deploy, RS
from diagrams.k8s.network import Ingress, Service
from diagrams.k8s.storage import PV, PVC
from diagrams.k8s.podconfig import ConfigMap, Secret

with Diagram("K8s Deployment", show=False):
    ingress = Ingress("ingress")

    with Cluster("Namespace: production"):
        svc = Service("api-svc")

        with Cluster("Deployment"):
            pods = [Pod("pod-1"), Pod("pod-2"), Pod("pod-3")]

        config = ConfigMap("config")
        secret = Secret("credentials")
        pvc = PVC("data-vol")

    pv = PV("persistent-volume")

    ingress >> svc >> pods
    [config, secret] >> pods
    pvc >> pv

Multi-Cloud / Hybrid Example

#!/usr/bin/env python3
from diagrams import Diagram, Cluster, Edge
from diagrams.aws.compute import ECS
from diagrams.gcp.compute import GKE
from diagrams.azure.compute import AKS
from diagrams.onprem.network import Nginx
from diagrams.onprem.monitoring import Prometheus, Grafana
from diagrams.generic.network import Firewall

with Diagram("Multi-Cloud Architecture", show=False, direction="TB"):
    with Cluster("On-Premises"):
        lb = Nginx("Load Balancer")
        fw = Firewall("Firewall")
        monitoring = [Prometheus("metrics"), Grafana("dashboards")]

    with Cluster("AWS"):
        aws_app = ECS("api-service")

    with Cluster("GCP"):
        gcp_app = GKE("ml-pipeline")

    with Cluster("Azure"):
        az_app = AKS("data-service")

    fw >> lb >> [aws_app, gcp_app, az_app]
    [aws_app, gcp_app, az_app] >> Edge(style="dashed") >> monitoring[0]

Available Providers

Diagram Parameters

Anti-Hallucination Rules

• NEVER import a node class without verifying it exists — use dir(diagrams.aws.compute) to check
• NEVER assume provider category names — they differ across providers (e.g., aws.integration vs gcp.api)
• ALWAYS set show=False in scripts/automation to prevent auto-opening
• ALWAYS verify Graphviz is installed before generating — diagrams silently fails without it

Output Format

Diagrams Report
═══════════════
Generated: [filename].png
Provider: [aws/gcp/azure/k8s/multi-cloud]
Components: [count] nodes, [count] clusters
Layout: [direction]

File: [absolute path to generated image]

Common Pitfalls

• Missing Graphviz: pip install diagrams does NOT install Graphviz — install separately
• show=True in CI: Will fail in headless environments — always use show=False
• Large diagrams: Use direction="LR" and clusters to keep readable
• Node naming: Node labels appear in diagram — keep short and descriptive
• Edge direction: >> means left-to-right flow; << means reverse; order matters