Skip to main content
krabka
GitHub
Admin Tooling · Developer Preview

Cluster Administration & CLI

The operator command-line interface (krabka): log directory formatting, bootstrap record generation, and decoupled plugin delegation.

Developer Preview Notice: krabka-cli is under active development. The built-in commands cover log formatting, topic, config, ACL, consumer-group, feature and partition-reassignment administration, and the Gres tenant registry. Backup, barrier, guard, restore and the admin web UI run as separate plugin binaries.

The CLI is published as the krabka binary. It compiles in log formatting and administration commands, and runs other subcommands as plugin executables found on PATH.

Built-in: Cluster Formatting

The built-in krabka format command prepares a clean log directory before broker startup. It writes cluster UUID metadata to meta.properties.json, seeds the bootstrap VotersRecord for KRaft consensus, and optionally provisions bootstrap SCRAM credentials and feature levels.

Format Cluster Directory: 
# Format a fresh broker log directory as a standalone KRaft controller
krabka format --log-dir /var/lib/krabka --standalone --node-id 1 --controller-listener localhost:9093

# Format with pre-seeded SCRAM credentials and finalized feature levels (KIP-1022)
krabka format --log-dir /var/lib/krabka \
  --standalone \
  --node-id 1 \
  --controller-listener localhost:9093 \
  --add-scram 'SCRAM-SHA-256=[name=admin,password=secret]' \
  --feature 'transaction.version=2'

Built-in: Admin Commands

The other compiled-in subcommands are topics, configs, acls, consumer-groups, features, reassign-partitions and gres (the Gres tenant registry and range layout). They connect with --bootstrap-server or --bootstrap-controller (or KRABKA_BOOTSTRAP_SERVER), and accept --command-config as the JVM tools do. Run krabka <subcommand> --help for the flags of each.

Topic administration: 
# Built-in admin commands use the JVM tools' flag names
krabka topics --bootstrap-server localhost:9092 --create --topic orders \
  --partitions 3 --replication-factor 1
krabka topics --bootstrap-server localhost:9092 --list
krabka topics --bootstrap-server localhost:9092 --create --topic orders --dry-run

# Machine-readable output and a deadline for the whole command
krabka --output json topics --bootstrap-server localhost:9092 --list --timeout 10s

Plugin Architecture

Subcommands outside the core bootstrap flow are dispatched dynamically to standalone plugin executables following the convention established by git and cargo. When an unrecognised subcommand krabka <subcommand> is invoked, the CLI searches PATH for krabka-<subcommand>:

Plugin Subcommand Invocation: 
# Plugin subcommands are resolved from PATH as krabka-<name>

# Point-in-time restore from tiered-storage archive (resolved to the krabka-restore binary on PATH)
krabka restore \
  --archive-local /mnt/backups/s3-archive \
  --log-dir /var/lib/krabka-restored \
  --standalone --node-id 1 --controller-listener localhost:9093

# Validate an archive without writing the target
krabka restore --archive-local /mnt/backups/s3-archive --log-dir /tmp/check \
  --standalone --node-id 1 --controller-listener localhost:9093 --dry-run

# Any krabka-<name> binary on PATH, including tools from the broader Krabka ecosystem
krabka <name> --help
Subcommand Origin Repository Execution Model
krabka format krabka-cli (logic in the krabka-format crate of krabka-broker) Compiled-in built-in (always wins over PATH); also ships standalone as krabka-format
krabka admin-ui krabka-cli Dispatched to the krabka-admin-ui web UI, built as a separate binary in the same repository
krabka restore krabka-broker Dispatched to krabka-restore plugin
krabka backup, barrier, guard krabka-broker Dispatched to the krabka-backup, krabka-barrier and krabka-guard plugins

Because plugins are separate binaries, tools for one component, including ones from other krabka repositories, add nothing to the core CLI's dependency tree. A plugin that is not found on PATH exits with code 127; an unexecutable binary exits with 126.

Architectural Layering

krabka-cli sits atop four sibling repositories:

  • krabka-protocol: Provides wire types, record codecs, security credentials, and unit types.
  • krabka-client-rs: Supplies the admin and core clients.
  • krabka-broker: Supplies Raft and the bootstrap records that format writes.
  • gres: Supplies the Gres registry, range planning, and tenant provisioning behind krabka gres.

Related Resources

Quickstart Guide →

Deploy a local broker using Docker Compose or Helm.
Runtime Architecture →

Operational topology, internal broker components, and control plane reconcile loops.