(kafka) branch 4.2 updated: KAFKA-20254: Add upgrade guide warning about classic to streams group migration in 4.2.0 (#21638)

[lu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lucasbru pushed a commit to branch 4.2
in repository https://gitbox.apache.org/repos/asf/kafka.git


The following commit(s) were added to refs/heads/4.2 by this push:
     new c9da3ada1e7 KAFKA-20254: Add upgrade guide warning about classic to streams group migration in 4.2.0 (#21638)
c9da3ada1e7 is described below

commit c9da3ada1e728d567ac915926c8ff9330c5363e7
Author: Lucas Brutschy <lb...@confluent.io>
AuthorDate: Fri Mar 6 23:33:59 2026 +0100

    KAFKA-20254: Add upgrade guide warning about classic to streams group migration in 4.2.0 (#21638)
    
    Due to a critical bug in the offline migration code (KAFKA-20254), we
    recommend against doing migrations from classic to streams groups in
    4.2.0. This adds a note to both the main upgrade guide and the Kafka
    Streams upgrade guide, advising users to upgrade to a later release that
    includes the fix before attempting the migration.
    
    Reviewers: Matthias J. Sax <ma...@confluent.io>, Christo Lolov
     <lo...@amazon.com>
---
 docs/getting-started/upgrade.md                            | 2 +-
 docs/streams/developer-guide/streams-rebalance-protocol.md | 2 ++
 docs/streams/upgrade-guide.md                              | 2 ++
 3 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/getting-started/upgrade.md b/docs/getting-started/upgrade.md
index 6cccbb361ad..e9a088018ad 100644
--- a/docs/getting-started/upgrade.md
+++ b/docs/getting-started/upgrade.md
@@ -36,7 +36,7 @@ type: docs
 
   * The `--max-partition-memory-bytes` option in `kafka-console-producer` is deprecated and will be removed in Kafka 5.0. Please use `--batch-size` instead. 
   * Queues for Kafka ([KIP-932](https://cwiki.apache.org/confluence/x/4hA0Dw)) is production-ready in Apache Kafka 4.2. This feature introduces a new kind of group called share groups, as an alternative to consumer groups. Consumers in a share group cooperatively consume records from topics, without assigning each partition to just one consumer. Share groups also introduce per-record acknowledgement and counting of delivery attempts. Use share groups in cases where records are processed  [...]
-  * The Streams Rebalance Protocol ([KIP-1071](https://cwiki.apache.org/confluence/display/KAFKA/KIP-1071%3A+Streams+Rebalance+Protocol)) is now production-ready for its core feature set. This broker-driven rebalancing system designed specifically for Kafka Streams applications provides faster, more stable rebalances and better observability. For more information about the supported feature set, usage, and migration, please refer to the [Streams developer guide](/{version}/documentation/ [...]
+  * The Streams Rebalance Protocol ([KIP-1071](https://cwiki.apache.org/confluence/display/KAFKA/KIP-1071%3A+Streams+Rebalance+Protocol)) is now production-ready for its core feature set. This broker-driven rebalancing system designed specifically for Kafka Streams applications provides faster, more stable rebalances and better observability. For more information about the supported feature set, usage, and migration, please refer to the [Streams developer guide](/{version}/documentation/ [...]
   * The `org.apache.kafka.common.header.internals.RecordHeader` class has been updated to be read thread-safe. See [KIP-1205](https://cwiki.apache.org/confluence/x/nYmhFg) for details. In other words, each individual `Header` object within a `ConsumerRecord`'s `headers` can now be safely read from multiple threads concurrently. 
   * The `org.apache.kafka.disallowed.login.modules` config was deprecated. Please use the `org.apache.kafka.allowed.login.modules` instead. 
   * The `remote.log.manager.thread.pool.size` config was deprecated. Please use the `remote.log.manager.follower.thread.pool.size` instead. 
diff --git a/docs/streams/developer-guide/streams-rebalance-protocol.md b/docs/streams/developer-guide/streams-rebalance-protocol.md
index 0b56d411342..33800ebc17d 100644
--- a/docs/streams/developer-guide/streams-rebalance-protocol.md
+++ b/docs/streams/developer-guide/streams-rebalance-protocol.md
@@ -253,3 +253,5 @@ The only broker-side group data that will be preserved are the committed offsets
 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](https://issues.apache.org/jira/browse/KAFKA-20254)), we recommend against doing migrations from classic to streams groups in 4.2.0. Newly created streams groups are not impacted. Users planning to migrate should upgrade their brokers to a later release that includes the fix.
diff --git a/docs/streams/upgrade-guide.md b/docs/streams/upgrade-guide.md
index 2f948c6324a..d701cd33fd4 100644
--- a/docs/streams/upgrade-guide.md
+++ b/docs/streams/upgrade-guide.md
@@ -65,6 +65,8 @@ Since 2.6.0 release, Kafka Streams depends on a RocksDB version that requires Ma
 
 ## Streams API changes in 4.2.0
 
+**Note:** Due to a critical broker-side bug in the offline migration code ([KAFKA-20254](https://issues.apache.org/jira/browse/KAFKA-20254)), we recommend against doing migrations from classic to streams groups in 4.2.0. Newly created streams groups are not impacted. Users planning to migrate should upgrade their brokers to a later release that includes the fix.
+
 ### General Availability for a core feature set of the Streams Rebalance Protocol (KIP-1071)
 
 The Streams Rebalance Protocol is a broker-driven rebalancing system designed specifically for Kafka Streams applications.