Streams Rebalance Protocol

Kafka Streams rebalance protocol behavior, migration paths, and limitations.
Tags:

The Streams Rebalance Protocol is a broker-driven rebalancing system designed specifically for Kafka Streams applications. Following the pattern of KIP-848, which moved rebalance coordination of plain consumers from clients to brokers, KIP-1071 extends this model to Kafka Streams workloads.

Overview

Instead of clients computing new assignments on the client during rebalance events involving all members of the group, assignments are computed continuously on the broker. Instead of using a consumer group, the streams application registers as a streams group with the broker, which manages and exposes all metadata required for coordination of the streams application instances.

This approach brings Kafka Streams coordination in line with the modern broker-driven rebalance model introduced for consumers in KIP-848, providing a dedicated group type with streams-specific semantics and metadata management.

What’s Supported in This Version

The following features are available in the current release:

  • Core Streams Group Rebalance Protocol: The group.protocol=streams configuration enables the dedicated streams rebalance protocol. This separates streams groups from consumer groups and provides a streams-specific group membership lifecycle and metadata management on the broker.

  • Sticky Task Assignor: A basic task assignment strategy that minimizes task movement during rebalances is included. It is registered under the name sticky and is the default assignor.

  • Custom Task Assignors: Brokers can be configured with custom task assignors via group.streams.assignors, which takes a list of built-in assignor names and fully qualified class names of custom TaskAssignor implementations. The first entry is the default assignor. An individual group selects one of the registered assignors by name with the group configuration streams.assignor.name; when unset, the group uses the first entry of group.streams.assignors. Custom implementations must be thread-safe, since a single instance is shared across all groups on a broker.

  • Interactive Query Support: IQ operations are compatible with the new streams protocol.

  • New Admin RPC: The StreamsGroupDescribe RPC provides streams-specific metadata separate from consumer group information, with corresponding access via the Admin interface.

  • CLI Integration: You can list, describe, and delete streams groups via the bin/kafka-streams-groups.sh script.

  • Topology Description Plugin: Brokers can record a human-readable description of each streams group’s processing topology via a pluggable backend, configured with group.streams.topology.description.plugin.class. The recorded topology can be inspected via the Admin interface or kafka-streams-groups.sh --describe --topology. See the Topology Description Plugin documentation for details.

  • Offline Migration: After shutting down all members and waiting for their session.timeout.ms to expire (or forcing an explicit group leave), a classic group can be converted to a streams group and a streams group can be converted to a classic group. The only broker-side group data that will be preserved are the committed offsets. Internal topics (changelog and repartition topics) will continue to exist as regular Kafka topics.

  • Static Membership: Streams applications can configure group.instance.id when using group.protocol=streams. This requires clients and brokers running Kafka 4.4 or newer: brokers on older versions reject group.instance.id on the streams group heartbeat with INVALID_REQUEST, which is a fatal error that shuts down the Kafka Streams client. Before downgrading brokers below 4.4, or if brokers have already been downgraded, remove group.instance.id from all Streams applications using group.protocol=streams and restart them. Also note that for topologies without persistent state stores, Kafka Streams generates a new process ID on each restart, causing the broker to recompute the group assignment and effectively negating the benefits of static membership across restarts.

What’s Not Supported in This Version

The following features are not yet available and should be avoided when using the new protocol:

  • Topology Updates: If a topology is changed significantly (e.g., by adding new source topics or changing the number of subtopologies), a new streams group must be created.

  • High Availability Assignor: The sticky assignor is the only built-in assignor and it does not support rack aware assignment, but a custom assignor registered via group.streams.assignors can implement it.

  • Warmup Tasks: In contrast to the “classic” rebalance protocol, warmup tasks are not an assignor feature, but the group coordinator would inject warmup tasks into an assignment. The benefit is, that warmup tasks can be used independent of the configured assignor. However, warmup task support is not implemented yet.

  • Regular Expressions: Pattern-based topic subscription is not supported.

  • Online Migration: Group migration while the application is running is not available between the classic and new streams protocol.

  • Custom Client Supplier: Using a custom KafkaClientSupplier will only allow so provide restore/global consumer, producer, and admin client. It’s not possible to provide the “main” consumer when “streams” groups are enabled.

Why Use the Streams Rebalance Protocol?

The Streams Rebalance Protocol offers several key advantages over the classic client-driven protocol:

  • Broker-Driven Coordination: Centralizes task assignment logic on brokers instead of the client. This provides consistent, authoritative task assignment decisions from a single coordination point, and reduces the potential for split-brain scenarios.

  • Faster, More Stable Rebalances: Reduces rebalance duration and impact by removing the global synchronization point. This minimizes application downtime during membership changes or failures.

  • Better Observability: Provides dedicated metrics and admin interfaces that separate streams from consumer groups, leading to clearer troubleshooting with broker-side observability. See the streams groups metrics documentation for details.

Enabling the Protocol

The Streams Rebalance Protocol is enabled by default on new clusters starting with Apache Kafka 4.2. Both brokers and clients must be running Apache Kafka 4.2 or later to use this protocol.

Broker Configuration

The protocol is enabled by default on new Apache Kafka 4.2 clusters. To enable the feature on existing clusters (after upgrading to 4.2) or to explicitly control it:

Enable the feature:

bin/kafka-features.sh --bootstrap-server localhost:9092 upgrade --feature streams.version=1

Disable the feature:

bin/kafka-features.sh --bootstrap-server localhost:9092 downgrade --feature streams.version=0

Client Configuration

In your Kafka Streams application configuration, set:

group.protocol=streams

Configuration

Broker Configuration

The following broker configurations control the behavior of streams groups. For complete details, see the broker configuration documentation.

Group Configuration

Configurations for the resource type GROUP are available in DescribeConfigs and IncrementalAlterConfigs to override the default broker configurations dynamically for specific groups. These can be set using the Admin Java interface or the bin/kafka-configs.sh utility.

For complete details, see the group configuration documentation.

The following group-level configurations are available for streams groups:

Example: Setting Group-Level Configuration

bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --alter --entity-type groups --entity-name wordcount \
  --add-config streams.num.standby.replicas=1

Note: In the streams rebalance protocol, session.timeout.ms, heartbeat.interval.ms and num.standby.replicas are group-level configurations, which are ignored when they are set on the client side. Use the bin/kafka-configs.sh tool to set these configurations as shown above.

Streams Configuration

For complete details on all Kafka Streams configurations, see the streams configuration documentation.

The following client configuration enables the streams rebalance protocol:

  • group.protocol: A flag which indicates if the streams rebalance protocol should be used. Set to streams to enable (default is classic).

Ignored Configurations

The following configurations are ignored when the streams rebalance protocol is enabled:

Administration

Admin API

Use the “streams groups” methods of the Admin interface to manage streams groups programmatically. These APIs are mostly backed by the same implementations as the consumer group API.

The main differences from consumer group APIs are:

  • The describeStreamsGroups uses the DescribeStreamsGroup RPC and contains different information than consumer groups.
  • A streams group has an extra state - NOT_READY - and no legacy states from the classic protocol.
  • removeMembersFromConsumerGroup will not have a corresponding API in this version, as it uses the LeaveGroup RPC for classic consumer groups, which is not available for KIP-848-style groups.

kafka-streams-groups.sh

A new tool called bin/kafka-streams-groups.sh is added for working with streams groups. It replaces bin/kafka-streams-application-reset.sh for streams groups and can be used to list, describe, and delete streams groups. See the kafka-streams-groups.sh documentation for detailed usage information.

Topology Description

When a topology description plugin is configured on the brokers via group.streams.topology.description.plugin.class, the group coordinator records a human-readable description of each streams group’s processing topology, pushed automatically by the Kafka Streams clients. The description can be retrieved via Admin#describeStreamsGroups or kafka-streams-groups.sh --describe --topology. See the Topology Description Plugin documentation for the push/describe workflow, plugin implementation guidelines, and troubleshooting.

Architecture and How It Works

Streams Groups

The protocol introduces the concept of a streams group in parallel to a consumer group. Streams clients use a dedicated heartbeat RPC, StreamsGroupHeartbeat, to join a group, leave a group, and update the group coordinator about its currently owned tasks and its client-specific metadata.

The group coordinator manages a streams group similarly to a consumer group, continuously updating the group member metadata via heartbeat responses and running assignment logic when changes are detected. A new group type called streams is introduced to the group coordinator, with new record key and value types for group metadata, topology metadata, and group member metadata. These records are persisted in the __consumer_offsets topic.

A group can either be a streams group, a share group, or a consumer group, defined by the first heartbeat request using the corresponding GroupId.

Topology Configuration and Validation

To assign tasks among streams clients, the group coordinator uses topology metadata that is initialized when a member joins the group and persisted in the consumer offsets topic.

Whenever a member joins the streams group, the first heartbeat request contains metadata of the topology. The metadata describes the topology as a set of subtopologies, each identified by a unique string identifier and containing metadata relevant for creation of internal topics and assignment.

Topology Validation and NOT_READY State

During the handling of the streams group heartbeat, the group coordinator may detect that source/sink or internal topics required by the topology do not exist or differ in their configuration from what is required for the topology to execute successfully. This triggers a “topology configuration” process, in which the group coordinator performs the following steps:

  • Check that all configured source topics exist.
  • Check that “copartition groups” are satisfied - that is, all source topics that are supposed to be copartitioned are indeed copartitioned.
  • Derive the required number of partitions for all internal topics from the source topic configuration.
  • Check that all internal topics exist with the right configuration.

If any source topics or internal topics are missing, the group enters a state NOT_READY. In NOT_READY, all heartbeats will be handled as usual (so they typically should not fail), but in the heartbeat response, the status will indicate which kind of problem exists. All members will get an empty assignment when the group is in NOT_READY state.

Centralized Assignment Configuration

Core assignment options are configured centrally on the broker, without relying on each client’s configuration. This allows tuning a streams group without redeploying the streams application. The core assignment option introduced on the broker-side is num.standby.replicas. This can be configured both globally on the broker and dynamically for specific streams groups through the IncrementalAlterConfigs and DescribeConfigs RPCs.

The last used assignment configuration is stored in the group metadata on the broker. This way, if an assignment configuration is dynamically changed, reassignment can be triggered immediately.

Monitoring and Metrics

The existing group metrics are extended to differentiate between streams groups and consumer groups and account for streams group states. For complete details, see the streams groups metrics documentation.

Group Count by Protocol

Number of groups based on type of protocol, where the list of protocols is extended by the protocol=streams variation:

kafka.server:type=group-coordinator-metrics,name=group-count,protocol={consumer|classic|streams}

Streams Group Count by State

Number of streams groups based on state:

kafka.server:type=group-coordinator-metrics,name=streams-group-count,state={empty|not_ready|assigning|reconciling|stable|dead}

Streams Group Rebalances

Streams group rebalances sensor:

kafka.server:type=group-coordinator-metrics,name=streams-group-rebalance-rate

kafka.server:type=group-coordinator-metrics,name=streams-group-rebalance-count

Migration from Classic Protocol

Currently, only offline migration is supported. To migrate a Kafka Streams application from the classic protocol to the streams rebalance protocol:

  1. Shut down all application instances.
  2. Wait for the session.timeout.ms to expire so the group becomes empty (or force an explicit group leave).
  3. Update the application configuration to set group.protocol=streams.
  4. Restart the application instances.

The only broker-side group data that will be preserved are the committed offsets. All other group metadata will be recreated when the application starts with the new protocol. Internal topics (changelog and repartition topics) will continue to exist as regular Kafka topics.

Similarly, you can convert a streams group back to a classic group by following the same process but setting group.protocol=classic.

Warning: Online migration (migrating while the application is running) is not available in this version. Plan for a maintenance window when migrating between protocols.

Warning: Due to a critical broker-side bug in the offline migration code (KAFKA-20254), we recommend against doing migrations from classic to streams groups in 4.2.0. Newly created streams groups are not impacted. The fix is available in 4.2.1.

Last modified October 22, 2026: MINOR: Add 4.4 release (#925) (b70dc484a2)