Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0013: zot as the managed registry cache implementation

Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden

Context and Problem Statement

ADR-0007 settles that a host-side pull-through cache exists and that Xianyun can run one. It leaves open which program the managed mode runs. The cache has to proxy several upstream registries from one process, and it has to be something Xianyun can start from a configuration file it writes.

Decision Drivers

  • Several upstream registries behind one listener
  • On-demand pull-through, so nothing has to be pre-seeded
  • One binary with no daemon dependencies, so it’s easy to install and supervise
  • Blob deduplication and garbage collection without extra work

Considered Options

  1. zot, using its sync extension
  2. Docker’s registry:2
  3. crane
  4. A custom HTTP proxy
  5. Spegel

Decision Outcome

Chosen option: “zot”, because it’s a single statically linked binary whose sync extension supports multiple upstream proxies with on-demand pull-through, deduplicates blobs, and has built-in garbage collection. The alternatives fall short in specific ways: registry:2 has no multi-upstream sync, so it would need one instance per upstream; crane is a client tool and can’t proxy pulls; Spegel is peer-to-peer inside one cluster and keeps nothing across a destroy; a custom proxy would mean writing what zot already provides.

Xianyun writes zot’s configuration (crates/xianyun-deploy/src/registrycache/config.rs) and starts the binary found on PATH.

Consequences

Good:

  • One process and one port serve every upstream
  • The data directory persists across cluster destroy and recreate

Bad:

  • zot has to be installed separately, and it’s resolved through PATH (TM-EXEC-005)
  • The generated configuration binds 0.0.0.0:5555 and has no access control (TM-REG-001)

Neutral:

  • Bring-your-own mode isn’t tied to zot; it accepts any cache that speaks the registry protocol

Implementation Location

  • crates/xianyun-deploy/src/registrycache/config.rs
  • crates/xianyun-deploy/src/registrycache/process.rs

More Information