The reference architecture in one diagram — the cluster's complete story

The complete reference architecture is the cluster’s complete story. The diagram is the canonical view; the discipline is the same scale-free: every component is justified.

The complete reference architecture

The complete reference architecture is the cluster’s single diagram. The diagram is the canonical view of the cluster.

flowchart TB
    subgraph USER["Users"]
        CLI["kubectl / Helm"]
        WEB["Web UI"]
    end

    subgraph LB["Load Balancer"]
        LB_NODE["HAProxy / cloud LB"]
    end

    subgraph CP["Control Plane (3 nodes, multi-AZ)"]
        ETCD["etcd (3x)"]
        API["kube-apiserver (3x)"]
        CM["kube-controller-manager (2x)"]
        SCH["kube-scheduler (2x)"]
    end

    subgraph W["Worker Pools (3 nodes each, multi-AZ)"]
        W1["General"]
        W2["Memory-optimized"]
        W3["Compute-optimized"]
    end

    subgraph N["Networking"]
        CNI["CNI (Cilium)"]
        DNS["CoreDNS (2x)"]
        NLP["NetworkPolicy: default-deny"]
    end

    subgraph ING["Ingress"]
        INGC["Ingress / Gateway API"]
        TLS["cert-manager"]
    end

    subgraph S["Storage"]
        CSI["CSI driver"]
        SC["StorageClass: fast-ssd, backup"]
    end

    subgraph SEC["Security"]
        PSS["Pod Security Standards"]
        RBAC["RBAC: ClusterRole, Role"]
        SA["ServiceAccount"]
    end

    subgraph OBS["Observability"]
        PROM["Prometheus"]
        GRAF["Grafana"]
        LOG["Loki"]
        TRC["Tempo"]
    end

    subgraph BACK["Backup"]
        VEL["Velero"]
        ETCD_SNAP["etcd snapshot (CronJob)"]
    end

    subgraph OPS["Ops"]
        ARG["ArgoCD (GitOps)"]
        POL["Polaris (anti-pattern)"]
        KLT["KLT (kubectl)"]
    end

    subgraph WS["Workloads"]
        STAT["Stateless Deployment"]
        STFL["StatefulSet"]
        CM["ConfigMaps"]
        SEC2["Secrets (External Secrets)"]
    end

    CLI --> LB_NODE
    WEB --> LB_NODE
    LB_NODE --> API
    API --> ETCD
    API --> CM
    API --> SCH
    W1 --> STAT
    W2 --> STFL
    W3 --> STAT
    API --> W1
    API --> W2
    API --> W3
    W1 --> CNI
    W2 --> CNI
    W3 --> CNI
    W1 --> DNS
    W2 --> DNS
    W3 --> DNS
    INGC --> STAT
    INGC --> STFL
    INGC --> TLS
    STAT --> CM
    STAT --> SEC2
    STAT --> CSI
    STFL --> CSI
    PROM --> W1
    PROM --> W2
    PROM --> W3
    VEL --> ETCD
    VEL --> CSI
    ARG --> STAT
    ARG --> STFL
    POL --> STAT
    POL --> STFL
    KLT --> API
    PSS --> W1
    PSS --> W2
    PSS --> W3
    RBAC --> SA
    SA --> STAT
    SA --> STFL
    NLP --> W1
    NLP --> W2
    NLP --> W3
    SC --> CSI

The complete reference architecture is the cluster’s complete story.

The cluster-wide components

The cluster-wide components are the ones that span the cluster:

• HA control plane. The cluster’s brain.
• Multi-worker pools. The cluster’s compute.
• Networking. The cluster’s connectivity.
• Ingress. The cluster’s external reachability.
• Storage. The cluster’s data.
• Security. The cluster’s protection.
• Observability. The cluster’s insight.
• Backup. The cluster’s safety net.
• Ops. The cluster’s automation.

flowchart LR
    A[Cluster-wide] --> B[HA cp]
    A --> C[Multi-worker]
    A --> D[Networking]
    A --> E[Ingress]
    A --> F[Storage]
    A --> G[Security]
    A --> H[Observability]
    A --> I[Backup]
    A --> J[Ops]

The cluster-wide components are the cluster’s foundation.

The workload-specific components

The workload-specific components are the ones that apply to each workload:

• Stateless Deployment. The standard workloads.
• StatefulSet. The stateful workloads.
• ConfigMaps. The configuration.
• Secrets. The sensitive data (via External Secrets).
• Requests/limits. The CPU/memory.
• Probes. The readiness/liveness.
• Affinity/spread. The topology distribution.
• PDB. The disruption budget.
• Services. The cluster’s routing.
• ServiceAccount. The workload’s identity.

flowchart LR
    A[Workload-specific] --> B[Deployment]
    A --> C[StatefulSet]
    A --> D[ConfigMaps]
    A --> E[Secrets]
    A --> F[Resources]
    A --> G[Probes]
    A --> H[Affinity]
    A --> I[PDB]
    A --> J[Services]
    A --> K[ServiceAccount]

The workload-specific components are the workload’s contract.

The operational procedures

The operational procedures are the ones that keep the cluster running:

• Rolling deployment. The cluster’s continuous delivery.
• Worker maintenance. The cluster’s node repairs.
• Kubernetes upgrade. The cluster’s upgrades.
• Failure recovery. The cluster’s recovery.

flowchart LR
    A[Operational procedures] --> B[Rolling deployment]
    A --> C[Worker maintenance]
    A --> D[Kubernetes upgrade]
    A --> E[Failure recovery]

The operational procedures are the cluster’s runbook.

The verification

The canonical verification:

# 1. Verify the HA control plane
kubectl get nodes -o wide

# 2. Verify the multi-worker pools
kubectl get nodes -l workload=general
kubectl get nodes -l workload=memory
kubectl get nodes -l workload=compute

# 3. Verify the networking
kubectl get networkpolicy -A
kubectl get pods -n kube-system -l k8s-app=kube-dns

# 4. Verify the ingress
kubectl get ingress -A

# 5. Verify the storage
kubectl get storageclass

# 6. Verify the workloads
kubectl get deployments -A
kubectl get statefulset -A

# 7. Verify the observability
kubectl get pods -n monitoring

# 8. Verify the backup
kubectl get cronjob -A
kubectl get pods -n velero

The verification is the cluster’s evidence.

The production discipline

The complete reference architecture is the cluster’s hypothesis. The discipline is the same scale-free: every component is justified. The cluster’s discipline is the same for every workload.

Quiz

Production discipline

• Walk the 11-step methodology. The methodology is the diagnostic.
• Identify the gaps. The gaps are the cluster’s missing components.
• Deploy the missing components. The deployment is the cluster’s recovery.
• Verify the deployment. The verification is the cluster’s evidence.
• Document the reference architecture. The runbook is the cluster’s reference.
• Run the cluster upgrade. The upgrade is the cluster’s evolution.
• Document the incident. The PIR is the artefact that pays down the lesson.