Environment:Apache Shardingsphere Etcd Cluster Coordination
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Cluster_Coordination |
| Last Updated | 2026-02-10 02:00 GMT |
Overview
etcd 3.x cluster coordination environment with jetcd 0.7.7 client for ShardingSphere cluster mode operation.
Description
This environment provides an alternative distributed coordination service for ShardingSphere's cluster mode using etcd. The jetcd client library communicates with etcd via gRPC. ShardingSphere uses etcd's lease mechanism for ephemeral node behavior and key-value store for configuration persistence. The etcd repository supports the same operations as ZooKeeper but with a different wire protocol and consistency model.
Usage
Use this environment when deploying ShardingSphere in Cluster Mode with etcd as the persist repository type. This is one of two supported cluster repository backends (the other being ZooKeeper). It is the mandatory prerequisite for running the ClusterPersistRepository implementation with etcd.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| etcd Server | etcd 3.x+ | Must be running and accessible via gRPC |
| Network | TCP connectivity to etcd cluster | Default port 2379 |
| Java | JDK 8+ | Required by jetcd client libraries |
Dependencies
System Packages
- `etcd` >= 3.0 (server-side)
Java Libraries (Client-side)
- `io.etcd:jetcd-core` = 0.7.7
- `io.grpc:grpc-core` = 1.75.0
- `com.google.protobuf:protobuf-java` = 3.25.8
Credentials
No authentication credentials are required by default. etcd TLS and authentication are supported but not mandatory.
The following configuration properties must be set in `server.yaml`:
- `server-lists`: Comma-separated etcd endpoint list (e.g., `http://localhost:2379`)
- `namespace`: Namespace prefix for key isolation
Quick Install
# Install etcd (Ubuntu/Debian)
apt-get install etcd
# Or download official release
ETCD_VER=v3.5.12
curl -L https://github.com/etcd-io/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz -o etcd.tar.gz
tar xzf etcd.tar.gz
# Start etcd standalone (development)
./etcd
# Configure ShardingSphere cluster mode (in server.yaml)
# mode:
# type: Cluster
# repository:
# type: etcd
# props:
# namespace: governance_ds
# server-lists: http://localhost:2379
# timeToLiveSeconds: 30
# connectionTimeout: 30
Code Evidence
etcd client initialization from `EtcdRepository.java:70-76`:
@Override
public void init(final ClusterPersistRepositoryConfiguration config) {
EtcdProperties etcdProps = new EtcdProperties(config.getProps());
client = Client.builder().endpoints(Util.toURIs(Splitter.on(",").trimResults().splitToList(config.getServerLists())))
.namespace(ByteSequence.from(config.getNamespace(), StandardCharsets.UTF_8))
.maxInboundMessageSize((int) 32e9).build();
etcdInternalLockHolder = new EtcdInternalLockHolder(client);
}
Maximum inbound message size from `EtcdRepository.java:74`:
.maxInboundMessageSize((int) 32e9) // ~32GB maximum gRPC message size
Default configuration properties from `EtcdPropertyKey.java:34-39`:
TIME_TO_LIVE_SECONDS("timeToLiveSeconds", "30", long.class),
CONNECTION_TIMEOUT("connectionTimeout", "30", long.class)
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `io.grpc.StatusRuntimeException: UNAVAILABLE` | Cannot connect to etcd server | Verify etcd is running at configured endpoints |
| `LeaseNotFoundException` | Lease expired before renewal | Increase `timeToLiveSeconds` (default 30s) or check network stability |
| `RESOURCE_EXHAUSTED: Received message larger than max` | gRPC message size exceeded | Default is 32GB; check for abnormally large metadata |
Compatibility Notes
- etcd 3.4.x: Supported via jetcd 0.7.7 client.
- etcd 3.5.x: Recommended version for production deployments.
- gRPC transport: Uses gRPC protocol unlike ZooKeeper's custom TCP protocol; may require different firewall rules.
- Lease mechanism: Ephemeral keys use etcd leases with configurable TTL (default 30s), shorter than ZooKeeper's default 60s session timeout.