The reference architecture — the integrated view of every fleet

The reference architecture is the picture an engineer draws when asked “how does code reach production in this team?”. Parts CVII and CVIII already introduced the components and the planes. This part, CXVIII, treats the same picture as an integrated system: five fleets of components, four planes of delivery, and signed edges between them. The master lesson in this part is this one; the next five lessons inspect each fleet on its own.

The integrated picture

The same picture drawn before, but with every fleet labelled and every signed edge named. A diagram that fits on a single screen is the production test of the architecture: if the audit chain cannot be drawn in seven minutes, the chain is too long to operate.

flowchart TB
    subgraph SP["Source plane"]
        ENG["Engineer + SSH + signing key"] -->|"B1: SSH+GPG"| REPO["Source repository"]
    end
    subgraph BP["Build plane — GitHub Actions fleet"]
        REPO -->|"B2: webhook + OIDC"| WF["Workflow run"]
        WF -->|"pin revision"| RUN["Ephemeral runner"]
        RUN -->|"emit"| OCI["OCI artefact + SBOM + provenance"]
    end
    subgraph AP["Artifact plane — Registry fleet"]
        OCI -->|"cosign sign"| REG["Registry by digest"]
        REG -->|"replicate"| REG2["Regional mirror"]
    end
    subgraph DP["Deploy plane — Argo CD fleet"]
        MAN["Manifest repository"] -->|"B4: digest + sig verify"| ACD["Argo CD controller"]
        REG -->|"B4: pull by digest"| ACD
        ACD -->|"B5: mTLS + RBAC"| CLUS["Cluster"]
        ACD -->|"stamp"| RCPT["Deployment receipt"]
    end
    subgraph OP["Observability plane — Audit fleet"]
        RUN --> MET["Metrics — Prometheus"]
        ACD --> MET
        CLUS --> MET
        CLUS --> LOG["Logs — Loki"]
        CLUS --> TRC["Traces — Tempo"]
        RCPT --> AUD["Audit trail — derived"]
        MAN --> AUD
        REPO --> AUD
    end

Five fleets, one per purpose: Actions for build, runner for execution, Argo CD for deploy, registry for artefact identity, observability for the audit trail. Each fleet is operated by a different team in a mature organisation, but the signed edges between fleets are what hold the system together.

Fleet versus plane

A plane is a stage of delivery: source, build, artefact, deploy, observability. A fleet is a group of components owned for a purpose. The two are orthogonal: each fleet spans one or more planes, and each plane contains parts of several fleets.

• The Actions fleet lives mostly in the build plane but also touches the artefact plane when it pushes a signed image and the observability plane when it emits build metrics.
• The Argo CD fleet lives mostly in the deploy plane but touches the artefact plane when it pulls by digest and the observability plane when it stamps a receipt.
• The runner fleet lives in the build plane as execution capacity, but every request the runner serves is observable, so the runner identity is a first-class citizen in the audit fleet too.
• The registry fleet is one plane (artefact) but is reached by every other fleet; it is the pivot that turns a build into a deploy.
• The observability fleet sits across every plane; it is the only fleet whose absence does not stop delivery but whose degradation does stop trust.

The signed edges

The diagram above labels seven edges. Every edge has three properties - distinct identity on each side, a signed handoff, and re-signing by the receiver. The edges most often violated in incident reconstruction are:

• B2 (source to Actions). Long-lived cloud credentials in the runner secrets, instead of OIDC, break the signed handoff.
• B4 (registry to Argo CD). Pull by tag, not digest, breaks the artefact identity.
• B5 (Argo CD to cluster). A controller with cluster-admin breaks the receiver’s re-signing property: the cluster cannot tell whether a change came through the controller or from some other party with the same privileges.

Production discipline

Three rules that recur through every fleet in the next five lessons:

1. The diagram is the contract. A change to the architecture is a change to the diagram first and to the code second. If the diagram does not change, the change is local, not architectural.
2. One identity per fleet. Each fleet has its own OIDC audience, its own IAM role, and its own service account. Sharing identities collapses fleet boundaries.
3. Every fleet has an owner. A fleet without a named owner is a fleet whose signed edge is the next thing to fail.

Cross-course references

• This course, Part CVII (ProductionArch) - the components and planes the fleets map onto.
• This course, Part LXX (SLSA) - the build-plane provenance every fleet must carry.
• Kubernetes for Production Sysadmins - Parts XX-XXII cover the runtime side of the Argo CD fleet.

Quiz