Distributed applications sometimes need a dependable way to coordinate actions, discover shared state or choose a leader. Apache ZooKeeper provides coordination services around a small shared data tree, with notifications and session behavior that applications can build on. Several servers form an ensemble whose membership and quorum govern availability. Running those servers on Kubernetes still requires stable identities, durable storage and coordinated membership changes; increasing a StatefulSet’s replica count alone is not a complete scaling procedure.
Current guidance
The original body closely matches the Kubernetes contrib K8SZK example, including Ubuntu 16.04, Java 8 and ZooKeeper 3.4.10. Its stated lack of scaling and observer support describes that old package. Current Apache ZooKeeper documentation supports dynamic ensemble reconfiguration, with the feature disabled by default unless explicitly enabled; the old limitation is not a universal statement about the application today.
Choose a supported ZooKeeper distribution and packaging that coordinates ensemble membership, stable server identities and persistent data. Maintain quorum across failure domains, protect client and peer communication, and understand snapshot and transaction-log recovery. Kubernetes scheduling and a PodDisruptionBudget help operations but do not replace ZooKeeper’s membership protocol or application-aware maintenance.
For migration, inventory client compatibility, ACLs, chroots, sessions and the application’s dependence on ZooKeeper. Rehearse the documented version sequence, a member failure and restoration from backups. If the consuming application offers another coordination mode, follow that application’s migration procedure rather than treating it as a generic database swap. Preserve data and server identities before removing the old StatefulSet or volumes, and validate client reconnect behavior during the transition.
Historical upstream link check · 2026-10-09
The recorded upstream address redirects to https://github.com/kubernetes-retired/contrib/blob/master/statefulsets/zookeeper/README.md and returned HTTP 200 on 2026-10-09. GitHub marks kubernetes-retired/contrib as archived. This confirms the repository's read-only archive state; any successor or supported distribution needs separate evidence. GitHub resolves the old repository identity to kubernetes-retired/contrib. Link availability does not certify the historical installation instructions or current security support.
Website availability is separate from project, chart and image support. Use the current guidance and primary sources on this page to assess the distribution.
Historical Kubedex content
Preserved for context. Commands, versions, prices and results below reflect the original research.
This project contains a Docker image meant to facilitate the deployment of Apache ZooKeeper on Kubernetes using StatefulSets.
Limitations
Scaling is not currently supported. An ensemble’s membership cannot be updated in a safe way in ZooKeeper 3.4.10 (The current stable release).
Observers are currently not supported. Contributions are welcome.
Persistent Volumes must be used. emptyDirs will likely result in a loss of data.
Docker Image
The docker image contained in this repository is comprised of a base Ubuntu 16.04 image using the latest release of the OpenJDK JRE based on the 1.8 JVM (JDK 8u111) and the latest stable release of ZooKeeper, 3.4.10. Ubuntu is a much larger image than BusyBox or Alpine, but these images contain mucl or ulibc. This requires a custom version of OpenJDK to be built against a libc runtime other than glibc. No vendor of the ZooKeeper software supplies or verifies the software against such a JVM, and, while Alpine or BusyBox would provide smaller images, we have prioritized a well-known environment.
The image is built such that the ZooKeeper process is designated to run as a non-root user. By default, this user is zookeeper. The ZooKeeper package is installed into the /opt/zookeeper directory, all configuration is symlinked into the /usr/etc/zookeeper/, and all executables are symlinked into /usr/bin. The ZooKeeper data directories are contained in /var/lib/zookeeper. This is identical to the RPM distribution that users should be familiar with.
Logging
The Log Level configuration may be modified via the ZK_LOG_LEVEL environment variable as described above. However, the location of the log output is not modifiable. The ZooKeeper process must be run in the foreground, and the log information will be shipped to the stdout. This is considered to be a best practice for containerized applications, and it allows users to make use of the log rotation and retention infrastructure that already exists for K8s.
Metrics
The zkMetrics script can be used to retrieve metrics from the ZooKeeper process and print them to stdout. A recurring Kubernetes job can be used to collect these metrics and provide them to a collector.
Sources & further reading
Spotted something that needs another look?
Help improve this page →