Skip to content

zot Clustering

Revised: 2022-10-17

High availability of the zot registry is supported by the following features:

  • Stateless zot instances to simplify scale out
  • Bare-metal and Kubernetes deployments

To ensure high-availability of the registry,zot supports a clustering scheme with stateless zot instances/replicas fronted by a loadbalancer and a shared remote backend storage. This scheme allows the registry service to remain available even if a few replicas fail or become unavailable. Loadbalancing across many zot replicas can also increase aggregate network throughput.


Clustering is supported in both bare-metal and Kubernetes environments.

Note: The remote backend storage must be S3 API-compatible.

Bare-metal deployment


  • A highly-available loadbalancer such as HAProxy configured to direct traffic to zot replicas.

  • Multiple zot replicas as systemd services hosted on mutiple hosts or VMs.

  • AWS S3 API-compatible remote backend storage.

Kubernetes deployment


  • A zot Kubernetes Deployment with required number of replicas.

  • AWS S3 API-compatible remote backend storage.

  • A zot Kubernetes Service.

  • A zot Kubernetes Ingress Gateway if the service needs to be exposed outside.

Implementing stateless zot

zot maintains two types of durable state:

  • the actual image data itself

  • the image metadata in the registry‚Äôs cache

In a stateless clustering scheme, the image data is stored in the remote storage backend and the registry cache is disabled by turning off both deduplication and garbage collection.

Ecosystem tools

The OCI Distribution Specification imposes certain rules about the HTTP URI paths to which various ecosystem tools must conform. Consider these rules when setting the HTTP prefixes during loadbalancing and ingress gateway configuration.