Scenario 02.2.2 · Add a consumer: rebalance
Kafka consumer group rebalance when a consumer joins
One member owns every partition; a second consumer joins and a rebalance redistributes the partitions across both.
Run this scenario in the playgroundOne member owns every partition. t+0.000s
The group g1 starts with a single member, c1. With nobody to share with, the assignor gives c1 all four partitions (p0-p3). A one-member group is just a single consumer reading the whole topic.
Open at this step: step 1, One member owns every partitionc1 consuming all four partitions. t+1.700s
One record was produced to each partition. c1 polls and drains all four on its own - positions advance to 1 across p0-p3 and lag is 0. This is the throughput ceiling of a single member: it must keep up with every partition by itself.
Open at this step: step 2, c1 consuming all four partitionsc2 joins - eager rebalance (stop-the-world). t+2.050s
A second consumer joins the group. The classic range assignor uses an EAGER rebalance: every member first REVOKES all of its partitions (the group is marked rebalancing and no one owns anything), so consumption pauses for the rebalance window before the new assignment is computed.
Open at this step: step 3, c2 joins - eager rebalance (stop-the-world)Rebalanced - partitions split 2 + 2. t+2.600s
The rebalance completes: the assignor redistributes the four partitions across the two members - c1 keeps p0-p1 and c2 takes p2-p3. Read work is now shared, and both members resume polling their own partitions. Adding (or removing) a consumer is exactly how a group scales with its membership.
Open at this step: step 4, Rebalanced - partitions split 2 + 2What you start with
When group membership changes, the coordinator runs a rebalance to redistribute partitions. This scenario starts with one member owning every partition, then a second consumer joins and the classic eager (range) protocol revokes everything before re-assigning the work across both.
Step by step
- One member owns every partition t+0.000s The group g1 starts with a single member, c1. With nobody to share with, the assignor gives c1 all four partitions (p0-p3). A one-member group is just a single consumer reading the whole topic. Open at this step: step 1, One member owns every partition
- c1 consuming all four partitions t+1.700s One record was produced to each partition. c1 polls and drains all four on its own - positions advance to 1 across p0-p3 and lag is 0. This is the throughput ceiling of a single member: it must keep up with every partition by itself. Open at this step: step 2, c1 consuming all four partitions
- c2 joins - eager rebalance (stop-the-world) t+2.050s A second consumer joins the group. The classic range assignor uses an EAGER rebalance: every member first REVOKES all of its partitions (the group is marked rebalancing and no one owns anything), so consumption pauses for the rebalance window before the new assignment is computed. Open at this step: step 3, c2 joins - eager rebalance (stop-the-world)
- Rebalanced - partitions split 2 + 2 t+2.600s The rebalance completes: the assignor redistributes the four partitions across the two members - c1 keeps p0-p1 and c2 takes p2-p3. Read work is now shared, and both members resume polling their own partitions. Adding (or removing) a consumer is exactly how a group scales with its membership. Open at this step: step 4, Rebalanced - partitions split 2 + 2
The takeaway
Adding a consumer triggers a rebalance that spreads partitions across the new membership; the same mechanism runs in reverse when a member leaves, so a group scales reads up and down with its size.
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=02.2.2" title="Kafka Simulator: Add a consumer: rebalance" width="100%" height="520" style="border:1px solid #d0d0d0;border-radius:8px" loading="lazy"></iframe>
<p><a href="https://monedula.dev/kafka-simulator/scenarios/add-consumer-rebalance/">Kafka consumer group rebalance when a consumer joins</a></p>Further reading
More in Consumer groups
- Kafka consumer poll loop: subscribe, poll, fetch
- Kafka auto.offset.reset: earliest vs latest vs none
- Kafka committed offsets: enable.auto.commit and restart
- Replay a Kafka topic: consumed records stay in the log
- Kafka consumer group: how partitions split across members
- Kafka partition assignors: range vs round-robin vs sticky
- Kafka eager vs cooperative rebalancing (cooperative-sticky)
- Kafka consumer crash and session.timeout.ms
- Kafka max.poll.interval.ms: evicting a stuck consumer
- Kafka static membership: group.instance.id avoids rebalances
- Kafka consumer lag: why it grows and how it drains
- Evicted Kafka consumer: how a survivor takes its partition