Skip to content
CommonLayer
Documentation menu
On this page

ADR-0009: CNCF Distribution as registry engine; the platform issues its tokens

Status: Accepted (plan decision D9). Implemented in crates/commonlayer-registry; verified against a local registry:3.1.2.

Context

CommonLayer must distribute images and charts that it has verified, and nothing else. Writing an OCI registry is unnecessary; the question is how to make "only verified content is published" structural rather than a convention.

Decision

  • Run CNCF Distribution v3 (registry:3) with S3-compatible storage, configured for Docker token authentication with the platform API as the token realm (GET /registry/token).
  • Anonymous callers receive pull on repositories that exist in artifacts and belong to a public project; anything else yields an empty access list.
  • push and delete are granted only to the promoter identity, whose credentials only the worker holds. No user, maintainer or CI token can push.
  • Tokens are ES256 JWTs valid for 5 minutes; the header kid is the RFC 7638 thumbprint. A previous key can stay valid during rotation; GET /registry/jwks.json publishes the active public keys.

Consequences

  • A compromised maintainer account or CI token cannot place content in the trusted registry; content gets there only through the verification pipeline.
  • WP-11 verified empirically that Distribution 3.1.2 accepts the minted tokens (kid and x5c, not jwk) and refuses anonymous push and tampered tokens.
  • During key rotation the registry's rootcertbundle must contain both certificates.
  • Distribution 3.1.2 does not implement the OCI referrers API; see ADR-0027.
  • Retention deletes manifests through the registry API only; blob space is reclaimed by Distribution's offline garbage collector (an operations task).