Environment:Apache Shardingsphere ZooKeeper Cluster Coordination

Knowledge Sources	Apache ShardingSphere Apache ZooKeeper Apache Curator
Domains	Infrastructure, Cluster_Coordination
Last Updated	2026-02-10 02:00 GMT

Overview

Apache ZooKeeper 3.9.4 cluster coordination environment with Curator 5.7.0 client for ShardingSphere cluster mode operation.

Description

This environment provides the distributed coordination service required for ShardingSphere's cluster mode. ZooKeeper serves as the persist repository for configuration data, metadata, and cluster state. The Curator framework provides high-level client abstractions including retry policies, leader election, and distributed locks. ShardingSphere uses ephemeral nodes for worker ID reservation and persistent nodes for configuration storage.

Usage

Use this environment when deploying ShardingSphere in Cluster Mode with ZooKeeper as the persist repository type. This is one of two supported cluster repository backends (the other being etcd). It is the mandatory prerequisite for running the ClusterContextManagerBuilder and ClusterPersistRepository implementations with ZooKeeper.

System Requirements

Category	Requirement	Notes
ZooKeeper Server	Apache ZooKeeper 3.9.4+	Must be running and accessible
Network	TCP connectivity to ZooKeeper cluster	Default port 2181
Java	JDK 8+	Required by Curator client libraries

Dependencies

System Packages

`zookeeper` = 3.9.4 (server-side)

Java Libraries (Client-side)

`org.apache.curator:curator-framework` = 5.7.0
`org.apache.curator:curator-client` = 5.7.0
`org.apache.curator:curator-recipes` = 5.7.0
`org.apache.zookeeper:zookeeper` = 3.9.4

Credentials

No authentication credentials are required by default. ZooKeeper ACL-based authentication is supported but not mandatory.

The following configuration properties must be set in `server.yaml`:

`server-lists`: Comma-separated ZooKeeper connection string (e.g., `localhost:2181`)
`namespace`: ZooKeeper namespace for ShardingSphere data isolation

Quick Install

# Install ZooKeeper (Ubuntu/Debian)
apt-get install zookeeper

# Or download official release
wget https://dlcdn.apache.org/zookeeper/zookeeper-3.9.4/apache-zookeeper-3.9.4-bin.tar.gz
tar xzf apache-zookeeper-3.9.4-bin.tar.gz

# Start ZooKeeper standalone (development)
./bin/zkServer.sh start

# Configure ShardingSphere cluster mode (in server.yaml)
# mode:
#   type: Cluster
#   repository:
#     type: ZooKeeper
#     props:
#       namespace: governance_ds
#       server-lists: localhost:2181
#       retryIntervalMilliseconds: 500
#       maxRetries: 3
#       timeToLiveSeconds: 60
#       operationTimeoutMilliseconds: 500

Code Evidence

ZooKeeper client initialization from `ZookeeperRepository.java:73-78`:

@Override
public void init(final ClusterPersistRepositoryConfiguration config) {
    ZookeeperProperties zookeeperProps = new ZookeeperProperties(config.getProps());
    client = buildCuratorClient(config, zookeeperProps);
    initCuratorClient(zookeeperProps);
}

Curator client construction with retry policy from `ZookeeperRepository.java:87-93`:

CuratorFrameworkFactory.builder()
    .connectString(config.getServerLists())
    .retryPolicy(new ExponentialBackoffRetry(retryIntervalMilliseconds, maxRetries, retryIntervalMilliseconds * maxRetries))
    .namespace(config.getNamespace())
    .sessionTimeoutMs(timeToLiveSeconds * 1000)
    .connectionTimeoutMs(operationTimeoutMilliseconds)
    .build();

Default configuration properties from `ZookeeperPropertyKey.java:34-49`:

RETRY_INTERVAL_MILLISECONDS("retryIntervalMilliseconds", "500", long.class),
MAX_RETRIES("maxRetries", "3", int.class),
TIME_TO_LIVE_SECONDS("timeToLiveSeconds", "60", int.class),
OPERATION_TIMEOUT_MILLISECONDS("operationTimeoutMilliseconds", "500", int.class)

Common Errors

Error Message	Cause	Solution
`KeeperException$ConnectionLossException`	Cannot connect to ZooKeeper server	Verify ZooKeeper is running and accessible at configured `server-lists`
`KeeperException$SessionExpiredException`	Session timeout exceeded	Increase `timeToLiveSeconds` (default 60s) in configuration
`WorkerIdAssignedException`	All 1024 worker IDs are taken	Deregister stale compute nodes or restart ZooKeeper to clear ephemeral nodes

Compatibility Notes

ZooKeeper 3.8.x: Should work but 3.9.4 is the tested version bundled with Curator 5.7.0.
Curator 5.x: Required; older Curator 4.x is not compatible with the current client API.
Namespace isolation: Multiple ShardingSphere clusters can share a single ZooKeeper ensemble using different `namespace` values.
Ephemeral nodes: Worker ID reservations and compute node registrations use ephemeral nodes that auto-expire when the session ends.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment