DOCSEARCHbyAlgolia
Submit Docs

zookeeperdesign

repository·master·Indexed 19 days ago

https://github.com/qiurunze123/zookeeperdesign

An educational repository focused on the design, architecture, and internal implementation of Apache ZooKeeper. It covers distributed coordination, the ZAB (ZooKeeper Atomic Broadcast) protocol, cluster deployment, and practical distributed patterns such as locks, service registries, and jobs. The documentation includes guides on ZNode management, watch mechanisms, ACL configuration, and Java client usage including the ZkClient wrapper.

Tokens
9.1K
Snippets
17
Records
42
Agent score
71%

What's inside zookeeperdesign

  1. Overview of ZooKeeper Design

    master
    The zookeeperdesign project is an educational resource designed to explain the architecture, deployment, and internal mechanisms of Apache ZooKeeper. It focuses on how ZooKeeper provides consistency services for distributed applications, such as configuration management, naming services, distributed synchronization, and group services. The project covers everything from basic commands and cluster deployment to deep-dive source code analysis of the ZAB (ZooKeeper Atomic Broadcast) protocol.

  2. Understand the ZooKeeper Project Structure

    master

    The ZooKeeper project (based on Apache ZooKeeper branch 3.5.5) is organized into several key modules:

    • zookeeper-server: The core server implementation.
    • zookeeper-client: The C language client implementation.
    • zookeeper-recipes: Example source code and patterns.

    To run the system, use ZooKeeperServerMain for the server and ZooKeeperMain for the client.

  3. What is ZkClient and when to use it

    master

    ZkClient is a third-party wrapper around the standard ZooKeeper client designed to be more user-friendly. Use ZkClient if you need:

    • Persistent Watches: The ability to set watches that don't expire after one trigger, or manually remove them.
    • Object Serialization: Automatic serialization and deserialization of Java objects when storing data.
    • Simplified CRUD: A more intuitive API for basic Create, Read, Update, and Delete operations.

  4. What is the ZAB Protocol

    master

    The ZAB (ZooKeeper Atomic Broadcast) protocol is used by ZooKeeper to maintain data consistency across a cluster. It ensures a global sequence of changes by assigning a globally incrementing transaction ID (zxid) to every transaction.

    Key behaviors:

    • Read Requests: Handled directly by the node the client is connected to.
    • Write Requests: If the node is not the Leader, it forwards the request to the Leader. The Leader broadcasts the write operation as a Proposal. Once a quorum (more than half) of nodes acknowledge the proposal, the write is committed and the Leader notifies all Learners to synchronize the data.

  5. Core Principles of ZAB Protocol

    master

    The ZAB protocol defines how transaction requests are coordinated:

    1. Single Coordinator: All transaction requests must be coordinated by a single, globally unique server called the Leader. All other servers are Followers.
    2. Proposal Distribution: The Leader converts a client transaction request into a Proposal and distributes it to all Followers via data broadcast/replication.
    3. Quorum-based Commitment: After distribution, the Leader waits for feedback (Ack requests). Once a majority (quorum) of Followers have sent correct Ack requests, the Leader sends a Commit message to all Followers, instructing them to commit the transaction.

  6. Implement Distributed Locks (Shared and Exclusive)

    master

    Distributed locks manage resource ownership across multiple processes. This implementation uses ephemeral sequential nodes to prevent the 'Herd Effect'.

    Shared Lock (Read Lock)

    Allows multiple readers but blocks writers.

    1. Create an ephemeral sequential node: /lock/{resourceID}.R0000000001.
    2. Get all children of /lock.
    3. If your node has the smallest sequence number, you hold the lock.
    4. If not, set a Watch on the node immediately preceding yours in the sequence and wait.

    Exclusive Lock (Write Lock)

    Allows only one holder for both reading and writing.

    1. Create an ephemeral sequential node: /lock/{resourceID}.W0000000002.
    2. Get all children of /lock.
    3. If your node has the smallest sequence number, you hold the lock.
    4. If not, set a Watch on the node immediately preceding yours in the sequence and wait.

    Releasing the Lock

    • Manually delete the ephemeral node.
    • If the process crashes, ZooKeeper automatically deletes the node when the session expires.

    Avoiding the Herd Effect

    Instead of having all waiting nodes watch the root /lock node (which causes a massive traffic spike when the lock is released), implement a Watch Chain. Each waiting node should only watch the node immediately preceding it in the sequence. This ensures that when a lock is released, only one waiting node is notified.

  7. ZAB Data Structures: zxid, epoch, and xid

    master

    ZAB uses a 64-bit Long type called zxid to manage transaction ordering. It is composed of two parts:

    • epoch (High 32 bits): Represents the current 'era' or 'dynasty' of the Leader. Every time a new Leader is elected, the epoch is incremented.
    • xid (Low 32 bits): A monotonically increasing transaction ID (sequence number) that resets to 0 at the start of every new epoch.

    Epoch Increment Logic: When a new Leader is elected, it takes the highest zxid from its local transaction logs, extracts the epoch, increments it by 1, and sets the low 32 bits to 0 to start a new sequence of zxids.

  8. ZAB Protocol Modes: Recovery vs. Broadcast

    master

    ZAB operates in two fundamental modes depending on the cluster state:

    1. Crash Recovery Mode

    Triggered during cluster startup or when the Leader crashes/restarts/loses connection. In this mode, the cluster performs a Leader election to establish a new Leader.

    2. Broadcast Mode

    Triggered once a new Leader is elected and a quorum of nodes has completed state synchronization (data sync) with that Leader. In this mode, the cluster processes transaction requests.

    Note on New Nodes: If a new server joins the cluster while it is in Broadcast mode, the new server automatically enters Recovery Mode to find the Leader and synchronize data before participating in the Broadcast process as a Follower.

  9. ZAB Node States

    master

    Every host in a ZooKeeper cluster exists in one of four states:

    • LOOKING: The node is in the election phase.
    • FOLLOWING: The node is a Follower in normal operation, synchronizing data from the Leader.
    • OBSERVING: The node is an Observer in normal operation, synchronizing data from the Leader.
    • LEADING: The node is the Leader in normal operation, broadcasting data updates.

  10. Configure Access Control Lists (ACL)

    master

    ZooKeeper uses ACLs to control access to ZNodes using the format scheme:id:permission.

    Schemes (Authentication Models)

    • world: Open access. The ID anyone is used for all users.
    • ip: Limits access to specific IP addresses or ranges.
    • auth: Requires authentication within the session.
    • digest: Uses a SHA-1 + Base64 encoded username/password (most common).

    Permissions

    • c: CREATE (create subnodes)
    • d: DELETE (delete immediate subnodes)
    • r: READ (read data and list children)
    • w: WRITE (set node data)
    • a: ADMIN (set ACL permissions)

    Digest Authentication Workflow

    1. Generate Key: Use OpenSSL to create a SHA-1 + Base64 string from username:password. echo -n "user:pass" | openssl dgst -binary -sha1 | openssl base64
    2. Set ACL: setAcl <path> digest:<user>:<key>:<permissions>
    3. Authenticate: Before accessing the node, the client must run addauth digest <user>:<pass>.
    # 1. Generate digest key
echo -n "qiurunze:123456" | openssl dgst -binary -sha1 | openssl base64
# Output: 2Rz3ZtRZEs5RILjmwuXW/wT13Tk=

# 2. Set digest ACL
setAcl /qiurunze digest:qiurunze:2Rz3ZtRZEs5RILjmwuXW/wT13Tk=:cdrw

# 3. Authenticate session to access node
addauth digest qiurunze:123456
get /qiurunze

  11. The Four Phases of ZAB

    master

    The ZAB protocol progresses through four distinct stages to ensure consistency:

    1. Election Phase: Nodes start in the LOOKING state. A node becomes a 'prospective Leader' if it receives votes from a majority. This phase ends when a prospective Leader is identified.
    2. Discovery Phase: Followers communicate with the prospective Leader to synchronize recent transaction Proposals. The goal is for the prospective Leader to discover the latest proposals across the majority and generate a new epoch.
    3. Synchronization Phase: The Leader uses the history of the latest proposals to synchronize all replicas in the cluster. Once a quorum of nodes is synchronized, the prospective Leader becomes the official Leader.
    4. Broadcast Phase: The cluster is fully operational. The Leader broadcasts transactions to Followers/Observers. New nodes joining the cluster during this phase must undergo synchronization.

  12. How Zookeeper Leader Election Works

    master

    Leader election is triggered when nodes are initialized or when a majority of nodes cannot connect to the current Leader.

    Election Process

    Nodes enter a LOOKING state during election. The voting mechanism follows these rules:

    1. Round 1: Every node votes for itself.
    2. Round 2: Nodes vote for the adjacent node with a larger myid.
    3. Conclusion: The election ends when a node receives votes from a majority of the cluster.

    Node States

    • LOOKING: The node is actively participating in an election.
    • follower/observer: The node has successfully found a Leader and connected to it.