Kafka Partition Reassignment Generator
The reassignment JSON, and the three commands including the throttle. The throttle is the one whose absence turns a routine rebalance into an incident.
reassignment.json
updates as you typeCommon mistakes
These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.
Running a reassignment without a throttle
Replication of the moving partitions saturates the network and starves normal traffic, which turns a maintenance task into an outage.
Instead:Set a throttle, and remove it afterwards. A forgotten throttle silently slows all replication.
Reassigning too many partitions at once
The plan runs them concurrently, so a large batch moves an enormous amount of data simultaneously.
Instead:Split into waves and verify between them.
Forgetting to verify
The command returns as soon as the plan is submitted, not when it completes. Assuming completion leaves partially moved partitions.
Instead:Run with --verify until it reports complete, then remove the throttle.
A reassignment moves every byte, while the cluster serves traffic
The JSON is the easy part. What matters is the throttle, the leadership spread and remembering the third command.
Without a throttle it starves normal replication
A reassignment moves data as fast as the network allows, which competes with ordinary replica fetching. Followers fall behind, partitions drop out of the in-sync set, and a cluster with min.insync.replicas=2 starts rejecting acks=all writes. This is the most common way a planned rebalance becomes an incident, and the fix is one flag.
The verify command removes the throttle
It is not only a progress check. A throttle left in place after a completed reassignment limits normal replication indefinitely, and the symptom is replicas that fall behind for no visible reason weeks later, long after anyone connects it to the migration. Run it until it reports completion.
Leadership is the first replica in each list
An assignment can distribute replicas perfectly evenly and still put every leader on one broker, which sends every write to that broker while every count looks balanced. The generator offsets each partition's round robin so leadership spreads, and the diagram shows leaders and replicas separately for exactly this reason.
This is the only way to change a replication factor
There is no --alter for it. You write a reassignment with the replica list you want and execute it, which is why the JSON has an explicit replicas array rather than a count. It is also why increasing a replication factor is a data movement operation rather than a metadata change.
Rack awareness is what makes a zone failure survivable
Without it, replicas are placed by broker id, so some partition ends up with two or three replicas in one availability zone. A zone failure then takes that partition below its minimum in-sync replicas however high the replication factor is. With fewer distinct racks than the replication factor, this is unavoidable and the report says so.