fusedzoo

A FUSE filesystem that mounts an Apache ZooKeeper tree as a local directory, backed by kazoo.

The dual znode model

ZooKeeper znodes are simultaneously containers (they have children) and data holders (they carry a byte payload). fusedzoo exposes both facets at once:

• Every znode /a/b/c maps to a directory at the mountpoint.
• The znode's data payload is exposed through a virtual file named .zk-data inside that directory.

/mnt/zk/
  my/
    favorite/          <- znode /my/favorite (ls to see children)
      .zk-data         <- read/write the node's raw byte payload
      node/            <- child znode /my/favorite/node
        .zk-data

Node data is passed through as raw bytes with no encoding.

Installation

pip install fusedzoo            # default: fusepy (libfuse2) backend
pip install fusedzoo[pyfuse3]   # opt-in: pyfuse3 (libfuse3, async) backend

The host system needs libfuse installed (libfuse2 for the fusepy backend, libfuse3 for pyfuse3) and a usable /dev/fuse device.

Usage

fusedzoo mount localhost:2181 /mnt/zk   # mounts in the foreground
fusedzoo umount /mnt/zk

See fusedzoo mount --help for pool sizing, backend selection, read-only, and experimental poll options.

# Create a znode
mkdir /mnt/zk/services

# Write its payload
echo '{"host": "db1"}' > /mnt/zk/services/.zk-data

# Read it back
cat /mnt/zk/services/.zk-data

# Inspect ZooKeeper metadata as extended attributes
getfattr -d /mnt/zk/services

# Remove a childless znode
rmdir /mnt/zk/services

Note: df will not show fusedzoo in plain df -h because ZooKeeper has no filesystem capacity concept and the mount reports 0/0 blocks. Use df -h -a or df -h /mnt/zk to see it explicitly.

Development

hatch run release      # ruff + mypy + pytest --cov + hatch build (full gate)
hatch run dry_release  # same but non-blocking (continues on failure)
hatch run docs:build   # build Sphinx docs

License

Apache 2.0