Cluster

Configuration for clustering multiple Virtual Registry nodes together.

For more information on the internals of clustering: https://docs.varnish-software.com/varnish-enterprise/features/cluster

Peers can be defined statically via peers, or discovered dynamically via peer_group. To enable clustering for a specific virtual registry, set enable_cluster on the registry.

Example:

cluster:
  token: secret
  peers:
  - url: http://orca-node-1:8080
  - url: http://orca-node-2:8080
  - url: http://orca-node-3:8080

token

cluster:
  token: secret

Type: String

Shared secret used to authenticate cluster peers. All nodes in the cluster must be configured with the same token.

extra_tokens

cluster:
  token: new-secret
  extra_tokens:
  - secret

Type: List

Additional shared secrets accepted from peers, alongside token. Lets a cluster token be rotated with a rolling redeploy instead of a coordinated restart of every node at once: stage the new token here on every node first, promote it to token once every node accepts it, then remove the old value.

storage_replicas

cluster:
  token: secret
  storage_replicas: 1

Type: Integer

Default: unset, which replicates in full

How many nodes keep an on-disk copy of each cacheable object.

A clustered node caches every object it serves in memory and persists it to disk as well, so a cluster of N nodes holds N copies on disk and its usable persistent cache is no larger than one node’s. Setting storage_replicas: 1 persists an object only on the node that owns it, pooling the whole cluster’s disk into a single cache. A higher count keeps that many copies, on the nodes nearest in the hash ring, trading capacity back for redundancy. Left unset, an object is persisted on every node it passes through.

A node that does not persist an object still caches it in memory, so this decides what survives a restart rather than what a hit costs.

Requires persistent storage to shard, meaning configured varnish.storage.stores and the sup-persistence addon. Without them every object is memory-only already and the setting has no effect, which the Supervisor warns about at startup.

peer_group

Dynamic cluster peer group configuration. Uses the same fields as remotes to point to a service that exposes the list of cluster peers.

cluster:
  token: secret
  peer_group:
    url: http://peer-discovery-service:8080

peers

cluster:
  token: secret
  peers:
  - url: http://orca-node-1:8080
  - url: http://orca-node-2:8080
  - url: http://orca-node-3:8080

Type: List

List of individual peer nodes for a static cluster. Each entry uses the same fields as remotes, including name, which replaces the peer’s position in the generated <registry>_cluster_dir_<label> identifier.

All nodes in the cluster should be listed, including the node itself. Each node must be able to send HTTP requests to all other nodes, including itself. All inter-node communication happens over the regular HTTP(S) port.