The reference architecture — the diagram and the components

A reference architecture is the single picture drawn when an engineer is asked “how does code reach production in this organisation?”. For an auditable team, the picture has the same shape regardless of tools: seven components across four planes, each connected by a signed edge. If a system matches, the audit chain is intact. If it deviates, the deviation is a named failure mode in the next five lessons.

The diagram

flowchart TB
    subgraph SP["Source plane"]
        ENG["Engineer + SSH key"] --> REPO["Git repo\n(default branch)"]
    end
    subgraph BP["Build plane"]
        REPO -->|"webhook + OIDC"| WF["CI workflow\n(signed revision)"]
        WF --> IMG["OCI image\n(by digest)"]
        WF --> PROV["Provenance\n(SLSA)"]
        WF --> SBOM["SBOM"]
    end
    subgraph AP["Artifact plane"]
        IMG -->|"cosign sign"| REG["Registry"]
        PROV --> REG
        SBOM --> REG
    end
    subgraph DP["Deploy / Runtime plane"]
        REG -->|"pull by digest"| CTRL["GitOps controller"]
        CTRL -->|"reconcile"| CLUS["Cluster"]
        CTRL -->|"stamp"| RCPT["Deployment receipt"]
    end
    subgraph OP["Observability plane"]
        CLUS --> MET["Metrics"]
        CLUS --> LOG["Logs"]
        CLUS --> TRC["Traces"]
        RCPT --> AUD["Audit trail"]
    end

Edges are signed: a webhook carries an OIDC token, a push carries a cosign signature, a reconcile carries a receipt. An unsigned edge is an edge where any party can impersonate any other.

The seven components

• Engineer. SSH key and signing key. The terminal is not a component.
• Source repo. Branch protection, signed commits, required reviewers.
• CI workflow. Pinned revision on an ephemeral runner that signs outputs, writes provenance, and emits an SBOM. Identity is an OIDC token.
• Registry. OCI by digest. Tags are for humans.
• GitOps controller. Reconciles the cluster to the manifest and stamps the receipt.
• Cluster. Runtime. Holds resources and annotations.
• Observability. Metrics, logs, traces, and the audit trail derived from receipts.

What this architecture is not

Not a vendor diagram (Argo CD diagrams end at the cluster; Actions diagrams end at the registry). Not a tool inventory (swapping Argo CD for Flux does not change the architecture). Not a single pipeline (the pipeline is one edge; the architecture is the graph). Not a single repository (source, manifests, workflows, postmortems live in separate repos).

Production discipline

1. The diagram is the contract. A change to the architecture is a change to the diagram first.
2. One identity per component. Sharing identities collapses boundaries.
3. Every edge is signed. Unsigned edges are impersonation paths.

Cross-course references

• This course, Part LXIV (Auditability) - the six links the architecture encodes.
• This course, Part LXX (SLSA) - the build-plane provenance the architecture requires.
• Kubernetes for Production Sysadmins - Parts XX-XXII cover the runtime plane.

Quiz