KIP-848 migration guide says never use assign()/unassign() with group.protocol='consumer'; it's only rejected after subscribe

Abierto Apto para principiantes
#2,405 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 3 días

@hidingmyname ya está trabajando en esto.

Desde el 29/10/2026.

  • #2407 de @hidingmyname — abierto

Evaluación

Dificultad
1/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
88/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
kafka, python

Línea de trabajo

Empieza por la sección «Rebalance Callback Changes» de docs/kip-848-migration-guide.md y la sección correspondiente de docs/kip-848-migration-guide.rst. Compara la redacción con el comportamiento descrito en el issue y con la sección «Manual partition assignment» de la guía de .NET. El objetivo se cumple cuando ambas guías de Python aclaran que manual assign() está admitido antes de suscribirse y describen la restricción después de suscribirse.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Description

docs/kip-848-migration-guide.md, section "Rebalance Callback Changes":

- **Do not** use `consumer.assign()` or `consumer.unassign()` when using `group.protocol='consumer'` (KIP-848).

docs/kip-848-migration-guide.rst has the same text:

-  **Do not** use ``consumer.assign()`` or ``consumer.unassign()`` when
   using ``group.protocol='consumer'`` (KIP-848).

This is broader than what the client actually enforces. In librdkafka, the
check that rejects a non-incremental assign ("Changes to the current
assignment must be made using incremental_assign() or incremental_unassign()
when rebalance protocol type is COOPERATIVE") only applies once the rebalance
protocol is COOPERATIVE. With the consumer protocol, that only happens
after the consumer has subscribed. Before that, rd_kafka_cgrp_rebalance_protocol()
returns NONE:

if (rkcg->rkcg_group_protocol == RD_KAFKA_GROUP_PROTOCOL_CONSUMER) {
        if (!(rkcg->rkcg_consumer_flags &
              RD_KAFKA_CGRP_CONSUMER_F_SUBSCRIBED_ONCE))
                return RD_KAFKA_REBALANCE_PROTOCOL_NONE;

        return RD_KAFKA_REBALANCE_PROTOCOL_COOPERATIVE;
}

So consumer.assign() for manual partition assignment, without calling
subscribe(), still works with group.protocol='consumer'.

Why it matters

Applications that use manual assignment, often with a group.id set only for
committing offsets, read this guide to decide whether they can switch
group.protocol. As written, the guide tells them they can't use assign()
at all, which isn't true. The restriction that actually matters, using only
incremental_assign()/incremental_unassign() once subscribed, gets lost
in the over-broad wording.

Suggested fix
-- **Do not** use `consumer.assign()` or `consumer.unassign()` when using `group.protocol='consumer'` (KIP-848).
+- **Do not** use `consumer.assign()` or `consumer.unassign()` after subscribing with `group.protocol='consumer'` (KIP-848).
+  `consumer.assign()` can still be used for manual partition assignment without subscribing.

and the same change in docs/kip-848-migration-guide.rst:

--  **Do not** use ``consumer.assign()`` or ``consumer.unassign()`` when
-   using ``group.protocol='consumer'`` (KIP-848).
+-  **Do not** use ``consumer.assign()`` or ``consumer.unassign()`` after
+   subscribing with ``group.protocol='consumer'`` (KIP-848).
+   ``consumer.assign()`` can still be used for manual partition assignment
+   without subscribing.
Upstream reference

confluent-kafka-go fixed the same sentence in its copy of this guide in
confluentinc/confluent-kafka-go@cc3d3f7 ("Few minor nits", 2025-10-10):

--- a/kafka/kip-848-migration-guide.md
+++ b/kafka/kip-848-migration-guide.md
@@ -51,15 +51,15 @@
 - In the **rebalance callbacks**, you **must only use** (optional - if not used, client will handle it internally):
   - `consumer.IncrementalAssign(e.Partitions)` to assign new partitions
   - `consumer.IncrementalUnassign(e.Partitions)` to revoke partitions
-- **Do not** use `consumer.Assign()` or `consumer.Unassign()` when using `group.protocol='consumer'` (KIP-848).
+- **Do not** use `consumer.Assign()` or `consumer.Unassign()` after subscribing with `group.protocol='consumer'` (KIP-848).

The .NET guide (doc/kip-848-migration-guide.md) already describes it
correctly in its "Manual partition assignment" section: "You can still use
Assign() before being subscribed but after subscribing you can only use
IncrementalAssign() and IncrementalUnassign()." All three clients use
the same librdkafka check, so the Python guide can use the same wording.

I can submit a PR for this.

Lenguaje dominante
Python
Estrellas
528
Forks
977
Merge medio
2 d 19 h
PR fusionados (30 d)
19

Preparar el entorno

  • Sin Dockerfile ni archivo de Docker Compose
  • Tiene una plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de confluentinc/confluent-kafka-python

Todos los issues de confluentinc/confluent-kafka-python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.