Using ZooKeeper

The Vespa container supports ZooKeeper, which allows distributed synchronization across nodes in a container cluster.

Once enabled all nodes in a container cluster will automatically form a ZooKeeper ensemble, and participate as servers. Vespa takes care of reconfiguring ZooKeeper members when nodes are added or removed from the container cluster.

Note that Vespa enforces an optimal node limit for clusters with ZooKeeper. Application packages that violate this node count will be rejected. The valid number of nodes is 3, 5 or 7. See #15762 for other node counts.


  1. ZooKeeper must be explicitly enabled in the container cluster configuration.

  2. The application must specify an dependency on zkfacade. Example for pom.xml:


Code example

ZooKeeper features are exposed through VespaCurator. Inject VespaCurator to use it. Handler example:

public class MyRequestHandler extends LoggingRequestHandler {

    private final VespaCurator curator;

    public CuratorHandler(Executor executor, AccessLog accessLog, VespaCurator curator) {
        super(executor, accessLog);
        this.curator = curator;

    public HttpResponse handle(HttpRequest httpRequest) {
        Path lockPath = Path.fromString("/locks/mylock");
        Duration timeout = Duration.ofSeconds(1);
        try (var lock = curator.lock(lockPath, timeout)) {
            // Do something while holding lock
        } catch (Exception e) {
            throw new RuntimeException("Failed to acquire lock " + lockPath, e);