{"id":18708096,"url":"https://github.com/threecommaio/k8s-zookeeper","last_synced_at":"2025-11-09T09:30:35.337Z","repository":{"id":98210112,"uuid":"166276598","full_name":"threecommaio/k8s-zookeeper","owner":"threecommaio","description":"Fork of kubernetes contrib repo for zookeeper stateful set","archived":false,"fork":false,"pushed_at":"2019-01-17T19:04:46.000Z","size":9,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-28T07:26:35.229Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/threecommaio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-17T18:37:24.000Z","updated_at":"2019-01-17T19:04:48.000Z","dependencies_parsed_at":"2023-03-29T04:03:04.752Z","dependency_job_id":null,"html_url":"https://github.com/threecommaio/k8s-zookeeper","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threecommaio%2Fk8s-zookeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threecommaio%2Fk8s-zookeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threecommaio%2Fk8s-zookeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threecommaio%2Fk8s-zookeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/threecommaio","download_url":"https://codeload.github.com/threecommaio/k8s-zookeeper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239571586,"owners_count":19661165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T12:21:35.750Z","updated_at":"2025-11-09T09:30:35.287Z","avatar_url":"https://github.com/threecommaio.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kubernetes ZooKeeper K8SZK\nThis project contains a Docker image meant to facilitate the deployment of \n[Apache ZooKeeper](https://zookeeper.apache.org/) on [Kubernetes](http://kubernetes.io/) using \n[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/). \n## Limitations\n1. Scaling is not currently supported. An ensemble's membership can not be updated in a safe way \nin ZooKeeper 3.4.10 (The current stable release).\n2. Observers are currently not supported. Contributions are welcome.\n3. Persistent Volumes must be used. emptyDirs will likely result in a loss of data.\n\n## Docker Image\nThe docker image contained in this repository is comprised of a base Ubuntu 16.04 image using the latest\nrelease of the OpenJDK JRE based on the 1.8 JVM (JDK 8u111) and the latest stable release of \nZooKeeper, 3.4.10. Ubuntu is a much larger image than BusyBox or Alpine, but these images contain\nmucl or ulibc. This requires a custom version of OpenJDK to be built against a libc runtime other \nthan glibc. No vendor of the ZooKeeper software supplies or verifies the software against such a \nJVM, and, while Alpine or BusyBox would provide smaller images, we have prioritized a well known \nenvironment.\n\nThe image is built such that the ZooKeeper process is designated to run as a non-root user. By default, \nthis user is zookeeper. The ZooKeeper package is installed into the /opt/zookeeper directory, all \nconfiguration is sym linked into the /usr/etc/zookeeper/, and all executables are sym linked into \n/usr/bin. The ZooKeeper data directories are contained in /var/lib/zookeeper. This is identical to \nthe RPM distribution that users should be familiar with.\n\n## Configuration\n\n### Headless Service\nThe ZooKeeper Stateful Set requires a Headless Service to control the network domain for the \nZooKeeper processes. An example configuration is provided below.\n\n```yaml\napiVersion: v1\nkind: Service\nmetadata:\n  name: zk-svc\n  labels:\n    app: zk-svc\nspec:\n  ports:\n  - port: 2888\n    name: server\n  - port: 3888\n    name: leader-election\n  clusterIP: None\n  selector:\n    app: zk-svc\n```\nNote that the Service contains two ports. The server port is used for followers to tail the leaders\neven log, and the leader-election port is used by the ensemble to perform leader election.\n### Stateful Set\nThe Stateful Set configuration must match the Headless Service, and it must provide the number of \nreplicas. In the example below we request a ZooKeeper ensemble of size 3. \n**As weighted quorums are not supported, it is imperative that an odd number of replicas be chosen.\nMoreover, the number of replicas should be either 1, 3, 5, or 7. Ensembles may be scaled to larger \nmembership for read fan out, but, as this will adversely impact write performance, careful thought\nshould be given to selecting a larger value.**\n```yaml\napiVersion: apps/v1beta1\nkind: StatefulSet\nmetadata:\n  name: zk\nspec:\n  serviceName: zk-svc\n  replicas: 3\n```\n### Container Configuration\nThe zkGenConfig.sh script will generate the ZooKeeper configuration (zoo.cfg), Log4J configuration\n(log4j.properties), and JVM configuration (jvm.env). These will be written to the \n/opt/zookeeper/conf directory with correct read permissions for the zookeeper user. These files are \ngenerated from environment variables that are injected into the container as in the example, minimal \nconfiguration below.\n```yaml\ncontainers:\n      - name: k8szk\n        imagePullPolicy: Always\n        image: gcr.io/google_samples/k8szk:v3\n        ports:\n        - containerPort: 2181\n          name: client\n        - containerPort: 2888\n          name: server\n        - containerPort: 3888\n          name: leader-election\n        env:\n        - name : ZK_ENSEMBLE\n          value: \"zk-0;zk-1;zk-2\"\n        - name: ZK_CLIENT_PORT\n          value: \"2181\"\n        - name: ZK_SERVER_PORT\n          value: \"2888\"\n        - name: ZK_ELECTION_PORT\n          value: \"3888\"\n```\n#### Membership Configuration\n|Variable|Type|Default|Description|\n|:------:|:---:|:-----:|:---------|\n|ZK_ENSEMBLE|string|N/A|A colon separated list of servers in the ensemble.|\nThis is a mandatory configuration variable that is used to configure the membership of the \nZooKeeper ensemble. It is also used to prevent data loss during accidental scale operations. The \nset can be computed as follows. For all integers in the range [0,replicas), prepend the name of \nservice followed by a dash to the integer. So for the Stateful Set above, the name is zk and we have\n3 replicas. for the set {0,1,2} we prepend zk- giving us zk-0;zk-1;zk-2.\n\n#### Network Configuration\n|Variable|Type|Default|Description|\n|:------:|:---:|:-----:|:--------|\n|ZK_CLIENT_PORT|integer|2181|The port on which the server will accept client requests.|\n|ZK_SERVER_PORT|integer|2888|The port on which the leader will send events to followers.|\n|ZK_ELECTION_PORT|integer|3888|The port on which the ensemble performs leader election.|\n|ZK_MAX_CLIENT_CNXNS|integer|60|The maximum number of concurrent client connections that a server in the ensemble will accept.|\n\nThe ZK_CLIENT_PORT, ZK_ELECTION_PORT, and ZK_SERVERS_PORT must be set to the containerPorts \nspecified in the container configuration, and the ZK_SERVER_PORT and ZK_ELECTION_PORT \nmust match the Headless Service configuration. However, if the default values of \nthe environment variables are used for both the containerPorts and the Headless Service, the \nenvironment variables may be omitted from the configuration.\n\n#### ZooKeeper Time Configuration\n|Variable|Type|Default|Description|\n|:------:|:---:|:-----:|:--------|\n|ZK_TICK_TIME|integer|2000|The number of wall clock ms that corresponds to a Tick for the ensembles internal time.|\n|ZK_INIT_LIMIT|integer|5|The number of Ticks that an ensemble member is allowed to perform leader election.|\n|ZK_SYNC_LIMIT|integer|10|The number of Tick by which a follower may lag behind the ensembles leader.|\n\n#### ZooKeeper Session Configuration\n|Variable|Type|Default|Description|\n|:------:|:---:|:-----:|:--------|\n|ZK_MIN_SESSION_TIMEOUT|integer|2 * ZK_TICK_TIME|The minimum session timeout that the ensemble will allow a client to request.|\n|ZK_MAX_SESSION_TIMEOUT|integer|20 * ZK_TICK_TIME|The maximum session timeout that the ensemble will allow a client to request.|\n\n#### Data Retention Configuration\n**ZooKeeper does not, by default, purge old transactions logs or snapshots. This can cause \nthe disk to become full.** If you have backup procedures and retention policies that rely on \nexternal systems, the snapshots can be retrieved manually from the /var/lib/zookeeper/data directory,\nand the logs can be retrieved manually from the /var/lib/zookeeper/log directory.\nThese will be stored on the persistent volume. The zkCleanup.sh script can be used to manually purge\noutdated logs and snapshots.\n\nIf you do not have an existing retention policy and backup procedure, and if you are comfortable with \nan automatic procedure, you can use the environment variables below to enable and configure \nautomatic data purge policies.\n\n|Variable|Type|Default|Description|\n|:------:|:---:|:-----:|:---------|\n|ZK_SNAP_RETAIN_COUNT|integer|3|The number of snapshots that the ZooKeeper process will retain if ZK_PURGE_INTERVAL is set to a value greater than 0.|\n|ZK_PURGE_INTERVAL|integer|0|The delay, in hours, between ZooKeeper log and snapshot cleanups.|\n\n#### JVM Configuration\nCurrently the only supported JVM configuration is the JVM heap size. Be sure that the heap size you\nrequest does not cause the process to swap out.\n\n|Variable|Type|Default|Description|\n|:------:|:---:|:-----:|:--------|\n|ZK_HEAP_SIZE|integer|2|The JVM heap size in Gibibytes.|\n\n#### Log Level Configuration\n|Variable|Type|Default|Description|\n|:------:|:---:|:-----:|:--------|\n|ZK_LOG_LEVEL|enum(TRACE,DEBUG,INFO,WARN,ERROR,FATAL)|INFO|The Log Level that for the ZooKeeper processes logger.|\n\n#### Liveness and Readiness\nThe zkOk.sh script can be used to check the liveness and readiness of ZooKeeper process. The example \nbelow demonstrates how to configure liveness and readiness probes for the Pods in the Stateful Set.\n```yaml\n  readinessProbe:\n    exec:\n      command:\n      - sh\n      - -c\n      - \"zkOk.sh\"\n    initialDelaySeconds: 15 \n    timeoutSeconds: 5\n  livenessProbe:\n    exec:\n      command:\n      - sh\n      - -c\n      - \"zkOk.sh\"\n    initialDelaySeconds: 15\n    timeoutSeconds: 5\n```\n#### Volume Mounts\nvolumeMounts for the container should be defined as below.\n```yaml\n  volumeMounts:\n  - name: datadir\n    mountPath: /var/lib/zookeeper\n```\n### Storage Configuration\nCurrently, the use of Persistent Volumes to provide durable, network attached storage is mandatory.\n**If you use the provided image with emptyDirs, you will likely suffer a data loss.** The example \nbelow demonstrates how to request a dynamically provisioned persistent volume of 20 GiB.\n```yaml\n  volumeClaimTemplates:\n  - metadata:\n      name: datadir\n      annotations:\n        volume.alpha.kubernetes.io/storage-class: anything\n    spec:\n      accessModes: [ \"ReadWriteOnce\" ]\n      resources:\n        requests:\n          storage: 20Gi\n```\n\n### Logging \nThe Log Level configuration may be modified via the ZK_LOG_LEVEL environment variable as described \nabove. However, the location of the log output is not modifiable. The ZooKeeper process must be \nrun in the foreground, and the log information will be shipped to the stdout. This is considered \nto be a best practice for containerized applications, and it allows users to make use of the \nlog rotation and retention infrastructure that already exists for K8s.\n\n### Metrics \nThe zkMetrics script can be used to retrieve metrics from the ZooKeeper process and print them to \nstdout. A recurring Kubernetes job can be used to collect these metrics and provide them to a \ncollector.\n```bash\nbash$ kubectl exec zk-0 zkMetrics.sh\nzk_version\t3.4.9-1757313, built on 08/23/2016 06:50 GMT\nzk_avg_latency\t0\nzk_max_latency\t0\nzk_min_latency\t0\nzk_packets_received\t21\nzk_packets_sent\t20\nzk_num_alive_connections\t1\nzk_outstanding_requests\t0\nzk_server_state\tfollower\nzk_znode_count\t4\nzk_watch_count\t0\nzk_ephemerals_count\t0\nzk_approximate_data_size\t27\nzk_open_file_descriptor_count\t39\nzk_max_file_descriptor_count\t1048576\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreecommaio%2Fk8s-zookeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreecommaio%2Fk8s-zookeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreecommaio%2Fk8s-zookeeper/lists"}