Mermaid.js Kubernetes Architecture Diagrams: Complete Guide with Examples

# Mermaid.js Kubernetes Architecture Diagrams: Complete Guide with Examples

Kubernetes architectures are notoriously hard to document. YAML files describe individual resources, but no single file shows you the whole picture — how pods connect to services, which ingresses route to which deployments, or how namespaces carve up your cluster.

Mermaid.js fixes this. Because diagrams are plain text, they live in your repo alongside your manifests, get reviewed in pull requests, and stay current when your architecture changes.

This guide shows you how to diagram real Kubernetes architectures using Mermaid — from single-cluster deployments to multi-namespace service meshes.

Why Mermaid for Kubernetes Diagrams?

Before diving into syntax, here's why text-based diagrams beat GUI tools for K8s documentation:

• Lives in the repo. Your diagram is a .md file next to your Helm chart. Change the chart, update the diagram in the same PR.
• Diffs like code. When you add a sidecar or change an ingress rule, the diff shows exactly what changed — not a blob binary.
• Renders everywhere. GitHub, GitLab, Confluence, and Notion all render Mermaid natively. Your architecture docs look great without a separate tool.
• Fast to write. Once you know the syntax, you can sketch a 20-node cluster diagram in under 5 minutes.

Basic Kubernetes Cluster Diagram

Let's start with the most common diagram: showing what's running inside a cluster.

flowchart TD
    subgraph Cluster["Kubernetes Cluster"]
        subgraph NS1["Namespace: production"]
            ING["Ingress nginx"]
            SVC1["Service frontend"]
            SVC2["Service backend"]
            DEP1["Deployment: frontend 3 replicas"]
            DEP2["Deployment: backend 2 replicas"]
        end
        subgraph NS2["Namespace: data"]
            SVC3["Service postgres"]
            SS1["StatefulSet: postgres"]
        end
    end
    Internet(["Internet"]) --> ING
    ING --> SVC1
    ING --> SVC2
    SVC1 --> DEP1
    SVC2 --> DEP2
    DEP2 --> SVC3
    SVC3 --> SS1

This single diagram answers the question most engineers ask first: *what's in this cluster and how does traffic flow through it?*

Pod-to-Pod Communication

For deeper architectural diagrams, show pod topology and how services route between pods:

flowchart LR
    subgraph Node1["Node: worker-1"]
        P1["Pod: frontend-abc 10.0.0.1"]
        P2["Pod: backend-def 10.0.0.2"]
    end
    subgraph Node2["Node: worker-2"]
        P3["Pod: backend-ghi 10.0.0.3"]
        P4["Pod: redis-jkl 10.0.0.4"]
    end

    SVC_FE["Service: frontend ClusterIP"]
    SVC_BE["Service: backend ClusterIP"]
    SVC_CACHE["Service: redis ClusterIP"]
    ING["Ingress nginx"]

    ING --> SVC_FE
    SVC_FE --> P1
    P1 --> SVC_BE
    SVC_BE --> P2
    SVC_BE --> P3
    P2 --> SVC_CACHE
    P3 --> SVC_CACHE
    SVC_CACHE --> P4

Showing node assignments makes capacity planning much clearer — you can see at a glance that worker-2 carries both backend replicas and the cache.

Kubernetes Deployment Rollout Flow

Use a sequence diagram to document how a deployment rollout happens step by step:

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub Actions
    participant REG as Container Registry
    participant K8S as Kubernetes API
    participant DEP as Deployment Controller

    Dev->>GH: git push / PR merge
    GH->>GH: Build and test
    GH->>REG: Push image tag v1.2.3
    GH->>K8S: kubectl apply new image tag
    K8S->>DEP: Update Deployment spec
    DEP->>DEP: Create new ReplicaSet
    loop Rolling Update
        DEP->>DEP: Scale up new RS by 1
        DEP->>DEP: Scale down old RS by 1
        DEP->>DEP: Wait for readiness probe
    end
    DEP->>K8S: Deployment complete
    K8S->>GH: Webhook: rollout success
    GH->>Dev: Notify: deployed to production

This is exactly the kind of diagram to put in your runbook — new team members understand the full CI/CD pipeline without reading three separate docs.

Ingress and Service Mesh Architecture

For setups with Istio or Linkerd, a layered diagram captures the mesh clearly:

flowchart TD
    subgraph Edge["Edge Layer"]
        CF["CloudFront CDN"]
        NLB["Network Load Balancer"]
    end

    subgraph Mesh["Istio Service Mesh"]
        GW["Istio Gateway"]
        subgraph VS["Virtual Services"]
            VS1["VirtualService /api to backend"]
            VS2["VirtualService / to frontend"]
        end
        subgraph Workloads["Workloads and Sidecars"]
            direction LR
            FE["frontend pod + envoy proxy"]
            BE["backend pod + envoy proxy"]
            AUTH["auth-service + envoy proxy"]
        end
    end

    subgraph Infra["Infrastructure"]
        DB[("PostgreSQL RDS")]
        CACHE[("Redis ElastiCache")]
    end

    CF --> NLB --> GW
    GW --> VS1 --> BE
    GW --> VS2 --> FE
    BE --> AUTH
    BE --> DB
    BE --> CACHE
    FE --> BE

Multi-Environment Deployment Strategy

Document how code moves from dev to staging to production:

flowchart LR
    subgraph Dev["Cluster: dev"]
        D_APP["app: latest"]
        D_DB[("postgres dev-db")]
    end

    subgraph Staging["Cluster: staging"]
        S_APP["app: v1.2.3-rc"]
        S_DB[("postgres staging-db")]
    end

    subgraph Prod["Cluster: production"]
        P_APP["app: v1.2.2 to v1.2.3"]
        P_DB[("postgres prod-db RDS")]
    end

    CI["CI/CD Pipeline GitHub Actions"]
    CI -->|"auto-deploy on PR merge"| Dev
    Dev -->|"promote on tag"| Staging
    Staging -->|"manual approval + canary"| Prod

Kubernetes RBAC Model

Role-Based Access Control is notoriously hard to explain in prose. A diagram makes it click instantly:

flowchart TD
    subgraph Subjects
        U1["User: alice"]
        U2["ServiceAccount: ci-runner"]
        G1["Group: platform-eng"]
    end

    subgraph RoleBindings
        RB1["ClusterRoleBinding: cluster-admin"]
        RB2["RoleBinding ns:production deploy-role"]
        RB3["RoleBinding ns:production view-only"]
    end

    subgraph Roles
        CR1["ClusterRole: cluster-admin"]
        R1["Role: deploy-role deploys and rollouts"]
        R2["Role: view-only read all resources"]
    end

    G1 --> RB1 --> CR1
    U2 --> RB2 --> R1
    U1 --> RB3 --> R2

    classDef subject fill:#3b82f6,color:#fff,stroke:#1d4ed8
    classDef binding fill:#f59e0b,color:#fff,stroke:#b45309
    classDef role fill:#10b981,color:#fff,stroke:#047857
    class U1,U2,G1 subject
    class RB1,RB2,RB3 binding
    class CR1,R1,R2 role

The color coding (blue = subjects, amber = bindings, green = roles) maps directly to the three-part RBAC model and makes onboarding new engineers dramatically faster.

StatefulSet and Persistent Volume Architecture

For databases and stateful workloads, showing how PVCs bind to PVs clarifies the storage layer:

flowchart TD
    subgraph StatefulSet["StatefulSet: postgres"]
        P0["Pod: postgres-0 10.0.0.10"]
        P1["Pod: postgres-1 10.0.0.11"]
        P2["Pod: postgres-2 10.0.0.12"]
    end

    subgraph PVCs["PersistentVolumeClaims"]
        PVC0["PVC: data-postgres-0"]
        PVC1["PVC: data-postgres-1"]
        PVC2["PVC: data-postgres-2"]
    end

    subgraph Storage["Storage: AWS EBS"]
        PV0["PV: vol-abc123 100Gi gp3"]
        PV1["PV: vol-def456 100Gi gp3"]
        PV2["PV: vol-ghi789 100Gi gp3"]
    end

    P0 --> PVC0 --> PV0
    P1 --> PVC1 --> PV1
    P2 --> PVC2 --> PV2

    SVC_HEAD["Headless Service postgres"]
    SVC_READ["Service postgres-read replicas only"]
    SVC_HEAD --> P0 & P1 & P2
    SVC_READ --> P1 & P2

This is extremely valuable in incident postmortems — you can see exactly which pod owns which volume when a storage issue hits.

Kubernetes HPA Autoscaling Logic

Document autoscaling behavior with a state diagram:

stateDiagram-v2
    [*] --> Stable: Deployment healthy
    Stable --> ScalingUp: CPU over 70pct for 3m
    ScalingUp --> Stable: Replicas added and CPU normalized
    Stable --> ScalingDown: CPU under 30pct for 5m
    ScalingDown --> Stable: Replicas removed min floor hit
    ScalingUp --> MaxCapacity: maxReplicas=10 reached
    MaxCapacity --> Alerting: CPU still over 90pct
    Alerting --> [*]: PagerDuty alert sent

Where to Put Each Diagram in Your Repo

All of these render natively in GitHub and GitLab. If you are on Confluence, use the Mermaid for Confluence plugin — or paste into the Mermaid Editor and export as PNG.

Tips for Clean Kubernetes Diagrams

1. Use subgraphs for every namespace. Namespaces are the primary unit of isolation in K8s. They should always be visually distinct in your diagrams.

2. Show services, not just pods. Pods are ephemeral — services are how components find each other. Route your arrows through services, not pod names.

3. Label your arrows. An unlabeled arrow tells you nothing. Add a short label to every connection that carries meaningful context. Spend the extra two seconds — reviewers will thank you.

4. Keep secrets and ConfigMaps implicit. Showing every ConfigMap mount clutters the diagram. Unless the secret itself is architecturally significant (like a Vault integration), leave it out.

5. Color-code by layer. In complex diagrams, consistent color coding (ingress = blue, services = green, databases = purple) makes scanning much faster and helps new engineers orient themselves instantly.

6. Update diagrams with manifests. When you add a service or change an ingress rule, update the diagram in the same commit. Reviewers can check the diagram diff alongside the YAML diff — dramatically reducing review time.

Common Pitfalls

• Too many nodes in one diagram. If your cluster diagram has 40+ nodes, split it by namespace or concern. One diagram per namespace often works well.
• Showing pod names instead of deployment names. Pod names are generated and change on every restart. Show the Deployment or StatefulSet name instead.
• Mixing abstraction levels. Don't put AWS account topology and individual pod routing in the same diagram. Pick one level of abstraction and stick to it.
• Forgetting to update diagrams. Stale diagrams are worse than no diagrams. Set a team convention: if you change a manifest, you update the relevant diagram in the same PR.

Conclusion

Mermaid.js is one of the best tools for documenting Kubernetes architectures. The text-based approach fits perfectly with the Infrastructure-as-Code mindset: your architecture diagram *is* code, lives in your repo, and evolves with your cluster.

Start with a simple cluster overview in your README, then expand to rollout runbooks, RBAC models, and per-namespace topology docs as your cluster grows.

Try building your Kubernetes architecture diagram in the free editor →