Registry cache

Recreating a cluster pulls every image again. A pull-through cache on your host keeps them across destroy and up, and cuts down on registry rate limits.

The cache is off unless cluster.registry_mirror lists upstreams.

Two ways to run it

Managed. Xianyun starts and supervises a zot process for you. It needs zot on your PATH.

cluster:
  registry_mirror:
    managed: true
    upstreams:
      - docker.io
      - quay.io

Bring your own. You run a cache (zot, distribution, Harbor) and Xianyun only writes the mirror settings the cluster needs. It never touches your cache process.

cluster:
  registry_mirror:
    endpoint: http://host.k3d.internal:5000
    upstreams:
      - docker.io

managed: true and endpoint are mutually exclusive. driver: external can’t use a mirror, because Xianyun can’t change an unmanaged cluster’s container runtime.

Lifecycle of the managed cache

• up starts zot if it isn’t running.
• destroy releases the project’s claim on it but leaves it running, so the next up is warm.
• Only xianyun registry stop stops it.
• One zot serves every profile, with reference counting.

$ xianyun registry status -o json
$ xianyun registry start
$ xianyun registry stop

registry status with -o json returns whether it’s running, its PID and port, the claims on it, its upstreams, the data size, and the paths of its config, data, and log. Over MCP, pass {"output": "json"}.

Security

The managed zot listens on 0.0.0.0:5555 and its generated config has no access control, and the k3d mirror config skips TLS verification. On a shared network, another host may be able to reach the cache. Whether anonymous writes are accepted hasn’t been measured. See TM-REG-001.

The reasoning for the design is in ADR-0007.