Operational Runbook Essentials

Overview

Rolling restart: the upgrade documentation says to upgrade the brokers one at a time, shutting each down, updating the code and restarting it. Checking that UnderReplicatedPartitions is back to its normal value of 0 before moving on is operational practice, not a documented requirement. Preferred leader election: automatic by default (auto.leader.rebalance.enable=true); run kafka-leader-election.sh yourself only if you turned that off. Partition reassignment: kafka-reassign-partitions.sh, optionally with a replication throttle that you remove afterwards. Retention tuning: change retention.ms or retention.bytes with kafka-configs.sh. Offset management: kafka-consumer-groups.sh --reset-offsets is a dry run unless you add --execute, and the consumer instances must be inactive. Shutdown: kafka-server-stop.sh sends SIGTERM; the broker syncs its logs to disk and, with controlled.shutdown.enable=true (the default), migrates the partitions it leads to other replicas before it exits. Controlled shutdown only succeeds if every partition on the broker has a replica, meaning a replication factor above 1 with at least one of the replicas alive.

Key configuration

controlled.shutdown.enable=true   # default
# controlled.shutdown.max.retries is not a setting in Kafka 4.2

Production tip

Sources

• Upgrading (4.2 documentation) (opens in a new tab)
• Basic Kafka operations (4.2 documentation) (opens in a new tab)
• Broker configs (4.2 documentation) (opens in a new tab)
• ServerConfigs.java (4.2 source) (opens in a new tab)
• kafka-server-stop.sh (4.2 source) (opens in a new tab)
• Monitoring (4.2 documentation) (opens in a new tab)

Checked against Kafka 4.2 documentation on Oct 2026. Draft: not yet reviewed by a Kafka specialist. Releases move on, so confirm against the current documentation before you act on a number.