ADR-0015: The registry cache is opt-in and fails soft
Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden
Context and Problem Statement
The cache is a performance feature. Turning it on adds a network listener, a host process, and a dependency on a zot binary. Two defaults need deciding: whether it’s on unless you say otherwise, and what up does when the cache can’t start.
Decision Drivers
- Existing projects shouldn’t change behaviour when they upgrade
- A missing binary or a port conflict shouldn’t block a developer from getting a cluster
- A failure still has to be diagnosable
Considered Options
- Off unless
cluster.registry_mirrorlists upstreams; on a failure to start, warn and bring the cluster up without the cache - On by default, with a flag to turn it off
- Off by default, and a failure to start the cache fails
up
Decision Outcome
Chosen option: “opt-in, and fail soft”. The cache is off when registry_mirror is absent or upstreams is empty. When it’s on and can’t start, up logs a warning (“registry cache could not be started; continuing without it”) and carries on, so pulls go to the upstream registries directly. The cache only affects speed, never correctness, so blocking bring-up on it would be the wrong trade. Turning it on by default would add a service to everyone’s up, with new ways to fail (a port conflict, a missing binary).
Consequences
Good:
- No change for projects that don’t configure it
- A broken cache never blocks
up
Bad:
- A project that relies on the cache for speed can lose it without noticing if nobody reads the warning
- In CI, a silent fall-back to the upstream registries can hit rate limits that the cache was meant to avoid
Neutral:
xianyun registry statusand thezot.logfile are how you diagnose a cache that didn’t start
Implementation Location
crates/xianyun-cli/src/commands/up.rscrates/xianyun-core/src/config/types.rs
More Information
- Recorded on 2026-10-13 from decisions 5 and 6 in the Go project’s registry-cache design.
- Related: ADR-0007, Registry cache.