Scenario 07.1.3 · Partition reassignment by hand

kafka-reassign-partitions: change a replica set by hand

Operations · Intermediate · about 2 min · Apache Kafka 4.3

Rewrite a partition’s replica set with kafka-reassign-partitions so it drops the leader: leadership shifts to an in-sync survivor while the new replica fetches up to the high-watermark and joins the ISR (real Kafka moves leadership only once the new replica is in sync).

What you start with

kafka-reassign-partitions lets an operator name the exact replica set for a partition - the replica set is just a list of brokers, and rewriting it moves the data. We hand-reassign partition 0 from broker-1/2/3 to broker-2/4/3 in one move: broker-4 starts at offset 0, OUTSIDE the ISR, and must fetch up to the high-watermark before it joins; and because the move drops broker-1, the current leader, leadership shifts to broker-2, a surviving in-sync replica.

Step by step

1. Cluster ready t+0.000s Four brokers, one partition, RF 3, min.ISR 2. Replica set is broker-1/2/3; broker-1 leads, broker-4 is spare and holds nothing. Open at this step: step 1, Cluster ready
2. Records produced t+6.000s Three records committed to partition 0 (acks=all). High-watermark 3 across the ISR - the log a new replica must catch up on. Open at this step: step 2, Records produced
3. Reassign - leader dropped, new replica outside the ISR t+9.050s Hand-reassign to broker-2/4/3. The simulator drops leader broker-1 at once, so leadership shifts to in-sync broker-2 (leader epoch bumps) and broker-4 joins at offset 0 OUTSIDE the ISR. Real Kafka keeps broker-1 leading during the copy (replicas 2/4/3/1), so the partition is never under-replicated, and moves leadership only after broker-4 joins the ISR. Open at this step: step 3, Reassign - leader dropped, new replica outside the ISR
4. broker-4 in sync t+9.500s broker-4 reached the high-watermark and joined the ISR. The replica set is now broker-2/4/3 with broker-2 leading - data moved and leadership changed, entirely by hand, and the partition was never unavailable. Open at this step: step 4, broker-4 in sync

The takeaway

A partition’s replica set is operator-controlled: rewrite it to move data or change leadership - but a new replica joins the ISR only once it has fetched up to the high-watermark, and dropping the leader hands leadership to the first live in-sync replica of the new assignment once the move completes.

Configs in this scenario

• min.insync.replicas The fewest in-sync replicas, leader included, that must have a write for an acks=all produce to succeed (default 1); with fewer in the ISR the leader rejects the write with NOT_ENOUGH_REPLICAS. How min.insync.replicas works
• acks How many replicas must have a write before the producer counts it as sent: 0 (none), 1 (the leader only) or all (every in-sync replica, the default, and required for idempotence). How acks works

Embed this scenario

Paste this into a blog post, a course page or your team's docs. The scenario plays inside your page, and the link under it points readers to this walkthrough.

<iframe src="https://monedula.dev/kafka-simulator/embed/?scenario=07.1.3" title="Kafka Simulator: Partition reassignment by hand" width="100%" height="520" style="border:1px solid #d0d0d0;border-radius:8px" loading="lazy"></iframe>
<p><a href="https://monedula.dev/kafka-simulator/scenarios/partition-reassignment-by-hand/">kafka-reassign-partitions: change a replica set by hand</a></p>

Further reading

Apache Kafka documentation

More in Operations

• Add a Kafka broker and reassign partitions onto it
• Remove a Kafka broker safely: drain it first
• Kafka replication throttle during partition reassignment
• Change Kafka min.insync.replicas at runtime, no restart
• producer_byte_rate: how a Kafka client quota throttles

All scenarios