Registry Architecture

In one sentence: A registry is a content-addressed blob server behind a small HTTP API — two object kinds (manifests and blobs), four verbs, and token-based auth in front.

A tiny API surface

The entire distribution protocol fits on an index card. Manifests: GET /v2/{repo}/manifests/{tag-or-digest} — the only endpoint that understands names. Blobs: GET /v2/{repo}/blobs/{digest} — dumb byte service. Existence checks use HEAD on the same paths, and uploads use POST/PUT (Lesson 16). Internally the registry mirrors this split: a metadata service for manifests and tags, and a blob store — usually delegating actual bytes to object storage (S3-style), often behind a CDN, because verified-by-digest bytes can be served from anywhere.

flowchart LR
  C["client (engine)"]
  AUTH["auth service
issues scoped tokens"]
  API["HTTP API frontend
/v2/…"]
  MS["manifest + tag service
(understands names)"]
  BS["blob service
(digests → bytes)"]
  OS[("object storage / CDN")]
  C -- "1· get token (repo:pull)" --> AUTH
  C -- "2· requests + token" --> API
  API --> MS
  API --> BS
  BS --> OS
  MS -. "manifests reference blobs" .-> BS
    

The token dance

Registries decouple auth from serving. An unauthenticated request gets 401 plus a header saying where to get a token and for what scope; the client fetches a short-lived token scoped to one repository and one action (pull or push), then retries. The registry only ever validates tokens — it never sees your password:

sequenceDiagram
  participant E as Engine
  participant R as Registry API
  participant A as Auth service
  E->>R: GET /v2/acme/api/manifests/2.1
  R-->>E: 401 + "get token at A, scope: repository:acme/api:pull"
  E->>A: credentials + requested scope
  A-->>E: signed token (expires in minutes)
  E->>R: same GET + Authorization: Bearer token
  R-->>E: 200 manifest JSON