Apache ZooKeeper

This is an Ansible role designed to install and set up Apache ZooKeeper.

You can use this role to install and cluster several ZooKeeper nodes. By default, it uses all hosts listed under the "zookeeper-nodes" group in your inventory file. All servers will be included in the zoo.cfg file, which also includes the leader and election ports. If you want to open firewall ports, set the zookeeper_firewalld variable to true.

Supported Platforms

• Debian 10.x
• RedHat 7
• RedHat 8
• Ubuntu 18.04.x
• Ubuntu 20.04.x

Requirements

You need Java 8 or 11.

You must have Ansible version 2.9.16 or 2.10.4 at a minimum to fix an issue with some kernels that disrupt the systemd status check. If you see the message "Service is in unknown state" when trying to start the service using this Ansible role, the task will fail, but you can start the service directly on the host using systemctl. More information is available at https://github.com/ansible/ansible/issues/71528.

Role Variables

Variable	Default	Comment
zookeeper_mirror	https://dlcdn.apache.org/zookeeper
zookeeper_version	3.9.1
zookeeper_package	apache-zookeeper-{{ zookeeper_version }}-bin.tar.gz
zookeeper_group	zookeeper
zookeeper_user	zookeeper
zookeeper_root_dir	/usr/share
zookeeper_install_dir	'{{ zookeeper_root_dir}}/apache-zookeeper-{{zookeeper_version}}'
zookeeper_dir	'{{ zookeeper_root_dir }}/zookeeper'
zookeeper_log_dir	/var/log/zookeeper
zookeeper_data_dir	/var/lib/zookeeper
zookeeper_data_log_dir	/var/lib/zookeeper
zookeeper_client_port	2181
zookeeper_id	1	Unique per server; declare in the inventory file
zookeeper_leader_port	2888
zookeeper_election_port	3888
zookeeper_servers	zookeeper-nodes	See below
zookeeper_servers_use_inventory_hostname	false	See below
zookeeper_environment	"JVMFLAGS": "-javaagent:/opt/jolokia/jolokia-jvm-1.6.0-agent.jar"
zookeeper_config_params		Key-value pairs for zoo.cfg configuration
zookeeper_firewalld	false

Inventory and zookeeper_servers Variable

The zookeeper_servers variable accepts a list of inventory hostnames. These hostnames are used in the zoo.cfg to create a multi-server cluster, allowing them to find each other. By default, the hostname in the zoo.cfg will match the output from the hostname command. Here’s an example of how that looks.

Given this inventory file:

[zookeeper-nodes]
zoo1.foo.com zookeeper_id=1       # hostname command returns "zoo1"
zoo2.foo.com zookeeper_id=2       # hostname command returns "zoo2"
zoo3.foo.com zookeeper_id=3       # hostname command returns "zoo3"

And the following role variables:

---
- role: sleighzy.zookeeper
  zookeeper_servers:
    - zoo1.foo.com
    - zoo2.foo.com
    - zoo3.foo.com

The generated zoo.cfg file will show:

server.1=zoo1:2888:3888
server.2=zoo2:2888:3888
server.3=zoo3:2888:3888

If you want the zoo.cfg to use the inventory_hostname, set zookeeper_servers_use_inventory_hostname to true.

Default Ports

Port	Description
2181	Client connection port
2888	Quorum port for clustering
3888	Leader election port for clustering

Default Directories and Files

Description	Directory / File
Installation directory	/usr/share/apache-zookeeper-<version>
Symlink to install directory	/usr/share/zookeeper
Symlink to configuration	/etc/zookeeper/zoo.cfg
Log files	/var/log/zookeeper
Data directory for snapshots and myid file	/var/lib/zookeeper
Data directory for transaction log files	/var/lib/zookeeper
Systemd service	/usr/lib/systemd/system/zookeeper.service
System Defaults	/etc/default/zookeeper

Starting and Stopping ZooKeeper Services

• To start the ZooKeeper service: systemctl start zookeeper
• To stop the ZooKeeper service: systemctl stop zookeeper

Four Letter Word Commands

ZooKeeper offers commands known as four-letter words. For more details, refer to https://zookeeper.apache.org/doc/current/zookeeperAdmin.html#sc_4lw.

For example, use the stat command to find out which instance is the leader:

for i in 1 2 3 ; do
  echo "zookeeper0$i is a "$(echo stat | nc zookeeper0$i 2181 | grep ^Mode | awk '{print $2}');
done

Dependencies

There are no required dependencies for this role.

Example Playbook

- hosts: zookeeper-nodes
  roles:
    - sleighzy.zookeeper

Linting

Use ansible-lint for linting your code.

pip3 install ansible-lint --user

ansible-lint -c ./.ansible-lint .

Testing

This role uses the Ansible Molecule testing framework, which creates a ZooKeeper cluster of three nodes running in Docker containers, each with a different OS to verify compatibility.

Follow the [Molecule Installation guide] and use a virtual environment. The following commands set up a Python virtual environment and install Molecule with the Docker driver:

$ python3 -m venv molecule-venv
$ source molecule-venv/bin/activate
(molecule-venv) $ pip3 install ansible docker "molecule-plugins[docker]"

Run the playbook and tests. Fix any linting issues before running tests with Molecule. This process will execute all tests and then clean up the Docker containers.

molecule test

To run the playbook without running tests, which can be repeated when changes are made, use:

molecule converge

For running tests without cleaning everything up, use:

molecule create
molecule converge
molecule verify

To tear down Molecule tests and Docker containers:

molecule destroy

License