Operate a cluster

Start with the procedure for your task. Each imported guide names its source branch, commit, and commit date above the instructions.

Index reviewed: October 4, 2026. The procedures follow the broker source branch; this index does not certify them for every release.

From 1.0.0, every 1.x broker reads every on-disk artifact an earlier 1.x broker wrote, and a new format stays off until you finalize its feature level, so you can roll back until then. Persisted formats lists every artifact and the gaps that remain. A data directory that a 0.x broker wrote is not covered: reformat it with krabka-format before you start 1.0.0 on it. Review the source guide and changelog for the exact build you deploy. Test recovery and any upgrade or rollback on a disposable cluster before using them on retained data.

Choose a task

Deploy and configure Choose an image, format storage, configure listeners, and connect health probes. Backup and restore Capture recovery inputs, verify their integrity, and set a recovery rehearsal schedule. Restore from the archive Rebuild after data loss, restore group positions, and expand the restored single-node cluster. Rolling upgrade Check cluster health, replace one broker at a time, and wait for readiness and replication. Metrics and alerts Find metric names, labels, health conditions, and the linked alert runbooks. Scale a cluster Add capacity, move replicas, and drain a broker with the required replication checks. Alert runbooks The full broker operations guide, with a runbook for every alert the broker ships. Configure operator resources Find CRD fields, defaults, allowed values, and validation rules. Rebalance partitions Configure the rebalancer and review a proposal before execution. Configure a gateway Connect gRPC clients and set up webhook ingestion and delivery.

Prepare and rehearse backup recovery

Read Backup and restore before the cluster loses data, then follow Restore from the archive for the full recovery sequence.

Prerequisites: a readable tiered-storage archive, a verified capture with the RLMM snapshot, controller metadata checkpoint, and committed group offsets, archive credentials, and enough space in an empty target directory. Record the cluster id outside the source cluster. For signed captures, retain the verification key and trusted chain head independently of the archive.
Run the capture integrity check and the restore dry run first. Capture verification exits 0 when all artifacts match and 5 on an integrity mismatch. Confirm that the dry-run plan contains the expected topics, partitions, and record counts before writing data.
After restoration, confirm topic settings and record contents. Restore group offsets while the consumer groups are stopped, then start consumers and check lag against the restored end offsets.
Recovery limits: a restore produces a single-node cluster with one replica per partition. Expand it through reassignment afterward. In-flight transactions and data beyond the reported capture boundary do not return. Without the metadata checkpoint, topic configuration, ACLs, quotas, credentials, and feature levels do not return.

The upstream guide names the per-change dr_roundtrip.rs test and a digest-pinned qualification drill. Check their evidence for your candidate build. No independent operator rehearsal or tested release pair is recorded by this index.

Plan an upgrade and a rollback

Follow Rolling upgrade only after reviewing both builds' changelogs and storage format compatibility.

Capture and verify recovery inputs. Record the running image digest, configuration, feature levels, and the proposed target digest. Rehearse the change and the recovery path on a disposable cluster.
Start with zero under-replicated and offline partitions. Stop one broker with SIGTERM, allow controlled shutdown to finish, and replace its build using the same data directory only when formats are compatible.
Wait for /readyz to return 200 and under-replicated partitions to return to zero before moving to the next broker. Roll the controller leader last, then run the preferred leader election described in the guide.
If checks fail, stop the rollout. Return to the previous build only after testing that it can read the changed persisted state and feature levels. If compatibility is unverified or the format changed, use the rehearsed backup restoration path; do not assume an image-tag change reverses the upgrade.

Within 1.x, a build that introduces a new persisted format keeps writing the old one until you finalize its feature level, so the rolling upgrade above keeps the data directory. Moving from 0.x to 1.x, or between builds outside that contract, requires a fresh format and restoration of topic data according to the upstream guide. Kubernetes readiness and a PodDisruptionBudget do not check the under-replicated-partition gauge; the operator must check replication health.

Check the release and deployment scope

Release status distinguishes version tracks from operational qualification. Use broker qualification gates to find candidate evidence, operator guidance for operator-managed clusters, and the configuration reference for your source branch.

Guide ownership and review

Broker maintainers own the imported operational procedures. The website maintainer owns this index, navigation, imported source labels, and recurring link checks. Review the index and source links monthly and whenever broker commands, storage formats, recovery contracts, or release requirements change. Review imported guides against the candidate release before adopting them.

Record operator rehearsals with exact source and target digests, configuration, capture boundary, expected checks, observed output, and failures in the broker issue tracker. A second engineer's recovery and upgrade rehearsal remains required before this plan's operational acceptance criteria are complete.