Build Status (master)

ZK is a high-level interface to the Apache ZooKeeper server. It is based on the zookeeper gem which is a multi-Ruby low-level driver. Currently MRI 1.8.7, 1.9.2, 1.9.3, and JRuby are supported, rubinius 2.0.testing is supported-ish (it's expected to work, but upstream is unstable, so YMMV).

ZK is licensed under the MIT license.

The key place to start in the documentation is with ZK::Client::Base (rubydoc.info, local).

This library is heavily used in a production deployment and is actively developed and maintained.

Development is sponsored by Snapfish and has been generously released to the Open Source community by HPDC, L.P.

Contacting the author

New in 1.1 !!

New in 1.0

zk.register('/path', :created) do |event|
  # event.node_created? will always be true

# or multiple kinds of events

zk.register('/path', [:created, :changed]) do |event|
  # (event.node_created? or event.node_changed?) will always be true

# this will, however, be changed in 1.1 to (backwards compatible, with a deprecation warning)

zk.register('/path', :only => :created) do |event|

zk.create('/path', '', :sequential => true)

# now also

zk.create('/path', :sequential => true)
ZK.new('localhost:2181/path', :chroot => :create) # the default, create the path before returning connection

ZK.new('localhost:2181/path', :chroot => :check)  # make sure the chroot exists, raise if not

ZK.new('localhost:2181/path', :chroot => :do_nothing) # old default behavior

# and, just for kicks

ZK.new('localhost:2181', :chroot => '/path') # equivalent to 'localhost:2181/path', :chroot => :create

What is ZooKeeper good for?

ZooKeeper is a multi-purpose tool that is designed to allow you to write code that coordinates many nodes in a cluster. It can be used as a directory service, a configuration database, and can provide cross-cluster locking, leader election, and group membership (to name a few). It presents to the user what looks like a distributed file system, with a few important differences: every node can have children and data, and there is a 1MB limit on data size for any given node. ZooKeeper provides atomic semantics and a simple API for manipulating data in the heirarchy.

One of the most useful aspects of ZooKeeper is the ability to set "watches" on nodes. This allows one to be notified when a node has been deleted, created, has had a child modified, or had its data modified. The asynchronous nature of these watches enables you to write code that can react to changes in your environment.

ZooKeeper is also (relatively) easy to deploy in a Highly Available configuration, and the clients natively understand the clustering and how to resume a session transparently when one of the cluster nodes goes away.

What does ZK do that the zookeeper gem doesn't?

The zookeeper gem provides a low-level, cross platform library for interfacing with ZooKeeper. While it is full featured, it only handles the basic operations that the driver provides. ZK implements the majority of the recipes in the ZooKeeper documentation, plus a number of other conveniences for a production environment. ZK aims to be to Zookeeper, as Sequel or ActiveRecord is to the MySQL or Postgres drivers (not that ZK is attempting to provide an object persistence system, but rather a higher level API that users can develop applications with).

ZK provides:

In addition to all of that, I would like to think that the public API the ZK::Client provides is more convenient to use for the common (synchronous) case. For use with EventMachine there is zk-eventmachine which provides a convenient API for writing evented code that uses the ZooKeeper server.


ZK strives to be a complete, correct, and convenient way of interacting with ZooKeeper. There are a few things to be aware of: