The artifact registry fleet — the artifact layer

The registry fleet is the artefact identity layer: the component that turns “an image built by some CI run” into “an image signed by this key, available at this digest, in this region”. This lesson names the four primitives a production registry fleet depends on and the relationship between the registry and the manifest repository Argo CD reads from. Treating the registry as a fleet rather than a stash is what makes the B4 boundary verifiable.

The four primitives

A production registry fleet depends on four primitives. Forgetting any one of them turns the artefact plane into a place where images exist but cannot be authenticated.

flowchart LR
    IMG["OCI image"] -->|"cosign sign"| REG["Registry by digest"]
    PRV["Provenance (SLSA)"] --> REG
    SBOM["SBOM (in-toto)"] --> REG
    SIG["Cosign signature"] --> REG
    REG -->|"replicate"| REG2["Regional mirror"]
    REG -->|"replicate"| REG3["DR region mirror"]
    ACD["Argo CD"] -->|"pull by digest"| REG2
    ACD -->|"verify cosign"| REG2
    ACD -->|"stamp"| RCPT["Deployment receipt"]
    RET["Retention policy"] --> REG

• OCI by digest. Every artefact in the registry is addressed by its content hash (sha256). The tag is a human handle; the digest is the identity. The latest tag is a contract that resolves to whatever someone pushed most recently; the digest is a pointer to exactly one immutable artefact.
• Cosign signatures. Every artefact has a cosign signature attached as an OCI artefact in the same repository. The signature’s subject is the digest; the signature’s predicate carries the issuer and the transparency-log entry.
• Retention and immutability. Tags are mutable; the artefact behind a digest is not. A repository’s retention policy drops the tags that no manifest references, while keeping the digests manifests reference, so audits can keep walking back through old digests for as long as the policy allows.
• Replication topology. Multi-region replication so that a region outage does not stop the deploy plane from pulling. Push-based replication for control over the timing; pull-based replication for the case where the registry chooses. The topology decision is a fleet decision, not a registry-internal one.

The registry is separate from the manifest repository

The registry holds the artefacts the deploy plane runs; the manifest repository holds the declarative description of which artefacts each cluster should run. The two are siblings, not the same.

• The registry is append-only by digest. A digest that exists at time T cannot be unmade at time T+1; only retention policies eventually drop the digest.
• The manifest repository is mutable. A manifest’s image: field can change from one digest to another across commits; that change is the thing Argo CD reconciles to.

The two together produce the B4 boundary: Argo CD reads the manifest, learns the desired digest, pulls the digest from the registry, verifies the cosign signature, and only then applies. Replacing the registry is a fleet decision; changing the manifest is a deploy. The registry cannot be a deploy’s source of truth because the registry is the artefact catalogue, not the policy.

Operating the fleet

A production registry fleet is operated as a product with three recurring concerns:

• Retention policy. A policy that drops tags no manifest references is the mechanism that bounds the registry’s storage growth. The policy must keep the digests manifests reference - including historical manifests - for the audit retention window. A policy that drops “everything older than 30 days” will eventually drop digests still referenced by an audit pull; that is the failure mode the audit team experiences as “the image we deployed a year ago is unresolvable”.
• Replication topology. Multi-region with explicit ownership of who pushes and who pulls. The deploy plane pulls from a regional mirror; the build plane pushes to the central registry, which propagates to the mirrors. A topology that has the build plane pushing to every region independently has no single source of truth for the artefact and makes audit reconstruction harder.
• Signing discipline. The signing key is held by the CI fleet; the verifier key is held by the deploy plane. Rotation is regular; the old key continues to verify old signatures for the duration of the audit window. A fleet that rotates keys without backfilling has produced signatures that no current key can verify.

echo "Verify a cosign signature against a digest:"
cosign verify \
  --certificate-identity "${WORKFLOW_IDENTITY}" \
  --certificate-oidc-issuer "${OIDC_ISSUER}" \
  "${IMAGE_REF}@${IMAGE_DIGEST}"

The command above is what Argo CD runs at pull time. The certificate identity and the OIDC issuer are the values the CI fleet’s OIDC token carried; the verifier checks that the signature was produced by a workflow the cert chain names.

Production discipline

1. Pull by digest, never by tag. Tags are for humans; digests are for the deploy plane.
2. Cosign signatures are mandatory. Unsigned artefacts cannot cross B4.
3. Provenance and SBOM as OCI artefacts. Not in a side database.
4. Multi-region replication with explicit ownership. No region is the source of truth for every cluster.

Cross-course references

• This course, Part LXIX (cosign) - the signing primitive this lesson assumes.
• This course, Part LXX (SLSA provenance) - the attestation shape the registry carries.
• Containers for Production Sysadmins - Parts XXII-XXV cover the retention patterns the fleet inherits.

Quiz