Guía · Kafka

Guía de migración de Kafka: de ZooKeeper a KRaft paso a paso, 2026

Las migraciones de Kafka fracasan en el cutover, no en la copia. Replicar topics entre clústeres es un terreno muy trillado; mover los consumidores sin reprocesar ni saltarse mensajes es donde los planes se desmoronan. Esta guía recorre las tres migraciones que los equipos realizan de verdad y ordena las decisiones de cada una.

Tyler Eastridge

Por Tyler Eastridge, Director de Operaciones

LinkedIn · Actualizado el · 13 min de lectura · 7 secciones

En esta página

La migración de Kafka en un párrafo

La migración de Kafka en un párrafo

Para migrar Kafka de ZooKeeper a KRaft, lleve los brokers a 3.9.1 o posterior, arranque un quórum de controladores KRaft con el ID de clúster existente y la migración activada, reinicie los brokers en modo migración y después como brokers KRaft, y finalice tras un periodo de observación. Puede hacer rollback hasta que finalice. La sección 1 contiene el runbook completo.

Hay tres cosas distintas que se llaman migración de Kafka y apenas tienen nada en común. Pasar de ZooKeeper a KRaft es un cambio en la capa de metadatos del mismo clúster; es un requisito previo para la línea 4.x, porque la 4.0 eliminó ZooKeeper por completo, y se realiza mediante un modo puente que exige que los brokers estén antes en una versión 3.x suficientemente reciente. Cambiar de plataforma, ya sea de un clúster autogestionado a MSK, de Confluent a código abierto o de cualquier cosa a Redpanda, es una migración de datos en la que MirrorMaker 2 copia los topics y traduce los offsets de los consumidores, y en la que la secuencia del cutover decide si pierde mensajes. Abandonar Kafka por completo, normalmente hacia RabbitMQ, es una decisión de arquitectura que debe tomarse en función del patrón de mensajería y no de la frustración operativa. Cada una tiene un riesgo distinto, y solo la primera tiene una fecha límite marcada por el proyecto.

Migración de ZooKeeper a KRaft, paso a paso

Para migrar Kafka de ZooKeeper a KRaft: lleve los brokers a Apache Kafka 3.9.1 o posterior con inter.broker.protocol.version=3.9, arranque un quórum de controladores KRaft que tenga el ID de clúster existente y la migración activada, reinicie los brokers en modo migración, vuelva a reinicarlos como brokers KRaft, espere y, por último, finalice sacando los controladores del modo migración. Puede hacer rollback en cualquier momento hasta que finalice, pero no después. Kafka 4.0 eliminó ZooKeeper por completo, así que esta migración es un requisito previo para cualquier versión 4.x; por eso va antes de la actualización y no en su lugar.

El runbook siguiente se basa en la documentación de operaciones de KRaft de Apache Kafka 3.9, modificada por última vez el 23 de octubre de 2026 y consultada el 28 de octubre de 2026. Revise la página de su versión de parche exacta antes de una ventana de migración y ensaye primero en una copia del clúster.

Paso 0: conozca qué bloquea la migración

Hay tres condiciones que la impiden o la atascan. Las funcionalidades que KRaft no implementa por completo la impiden. Un broker con varios directorios de log, uno de ellos averiado, no puede migrar hasta que se repare el directorio (KAFKA-16431). Y si se ejecutó antes la ZooKeeper Security Migration Tool, la migración puede atascarse en un nodo /migration mal formado (KAFKA-19480), que se elimina con delete /migration en zookeeper-shell.sh. Localice las tres en el clúster antiguo antes de reservar la ventana. No cambie la versión de metadatos (inter.broker.protocol.version) mientras haya una migración en curso.

Paso 1: lleve todos los brokers a la versión puente

Apache exige brokers en 3.9.1 con inter.broker.protocol.version=3.9. La versión 3.9.2, publicada el 21 de febrero de 2026, es la última 3.x y añade un flag de compatibilidad para una diferencia conocida en lo que recibe una AlterConfigPolicy entre los modos ZooKeeper y KRaft (KIP-1252), así que úsela si tiene una política de este tipo. Si usa ACL, migre en 3.6.2 o posterior: la CVE-2024-27309 podía hacer que Kafka ignorara las reglas DENY durante una migración en las versiones 3.5.0 a 3.6.1 (consulte el registro de CVE de Kafka). Active el logging TRACE de la migración en cada controlador con log4j.logger.org.apache.kafka.metadata.migration=TRACE.

Paso 2: lea el ID del clúster y aprovisione los controladores

bin/zookeeper-shell.sh localhost:2181 get /cluster/id

Los controladores KRaft deben llevar ese ID de clúster. Asigne a cada controlador un node.id que no coincida con ningún broker.id, porque brokers y controladores comparten el mismo espacio de ID. Use tres o cinco controladores: debe haber una mayoría activa, así que tres toleran un fallo y cinco toleran dos. Un controlador listo para migrar tiene este aspecto (ejemplo de Apache):

process.roles=controller
node.id=3000
controller.quorum.bootstrap.servers=localhost:9093
controller.listener.names=CONTROLLER
listeners=CONTROLLER://:9093
# Enable the migration
zookeeper.metadata.migration.enable=true
# ZooKeeper client configuration
zookeeper.connect=localhost:2181
# Brokers' inter-broker listener, so the controller can send RPCs to them
inter.broker.listener.name=PLAINTEXT
bin/kafka-storage.sh format --standalone --cluster-id=<zk-cluster-id> -c config/kraft/controller.properties
bin/kafka-server-start.sh config/kraft/controller.properties

El ejemplo de Apache arranca un único controlador standalone. Para un quórum de tres o cinco nodos, aprovisione los demás como indica la documentación de KRaft para su versión de Kafka, todos con el mismo ID de clúster y el flag de migración activado.

Paso 3: reinicie los brokers en modo migración (la fase híbrida)

Añada a cada broker la configuración del quórum de controladores y el flag de migración, mantenga broker.id con un entero no negativo y reinicie los brokers de uno en uno. Los brokers siguen funcionando en modo ZooKeeper, y el controlador KRaft les envía las RPC de controlador.

broker.id=0
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
inter.broker.protocol.version=3.9
# Enable the migration
zookeeper.metadata.migration.enable=true
zookeeper.connect=localhost:2181
controller.quorum.bootstrap.servers=localhost:9093
controller.listener.names=CONTROLLER

La migración arranca sola en cuanto se reinicia el último broker. El controlador activo registra Completed migration of metadata from Zookeeper to KRaft cuando termina la copia de metadatos.

Paso 4: convierta los brokers a KRaft (la fase de doble escritura)

Reconfigure cada broker como broker KRaft y reinícielo, de uno en uno: sustituya broker.id por node.id manteniendo el mismo número, añada process.roles=broker, elimine la configuración de ZooKeeper y zookeeper.metadata.migration.enable, elimine control.plane.listener.name si lo había configurado y quite inter.broker.protocol.version, porque KRaft usa en su lugar la feature metadata.version. Si el broker usa kafka.security.authorizer.AclAuthorizer, cambie authorizer.class.name a org.apache.kafka.metadata.authorizer.StandardAuthorizer en este reinicio. Mientras tanto, los controladores siguen escribiendo metadatos en ZooKeeper.

process.roles=broker
node.id=0
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
controller.quorum.bootstrap.servers=localhost:9093
controller.listener.names=CONTROLLER

Paso 5: periodo de observación y, después, finalización

Apache señala que algunos usuarios esperan una o dos semanas antes de finalizar, lo que implica mantener ZooKeeper en marcha durante ese tiempo, para validar el modo KRaft con la carga real. Durante ese periodo, revise bin/kafka-metadata-quorum.sh --bootstrap-server host:9092 describe --status, confirme que las particiones con replicación insuficiente y las particiones offline están a 0 y ejecute los simulacros de fallo que haría en cualquier clúster nuevo. Para finalizar, elimine zookeeper.metadata.migration.enable y la configuración de cliente de ZooKeeper de cada controlador y reinicie los controladores de uno en uno. A partir de ahí, ZooKeeper puede darse de baja y la migración ya no se puede revertir.

Paso 6: después, actualice a Kafka 4.x

Los brokers pueden actualizarse a 4.0 o posterior desde cualquier clúster KRaft con versiones de software y de metadatos de al menos 3.3.x. Antes de la ventana de actualización, pase los hosts de los brokers a Java 17 (Apache admite 17, 21 y 25 para brokers y recomienda la LTS más reciente) y corrija todos los scripts, llamadas de administración y configuraciones que aún apunten a una cadena de conexión de ZooKeeper, como --zookeeper o zookeeper.connect, porque 4.x no tiene modo ZooKeeper: use --bootstrap-server. A 28 de octubre de 2026, Apache mantiene las versiones 4.4, 4.3 y 4.2.

Rollback

Los pasos para revertir dependen de hasta dónde haya llegado, y todos exigen comprobar primero la epoch del controlador de ZooKeeper: Apache añadió esa comprobación a su documentación el 23 de octubre de 2026 (KAFKA-20488), porque un controlador de ZooKeeper elegido con una epoch inferior a la de KRaft no puede cambiar el estado de las particiones.

Último paso completadoCómo revertir
Controladores aprovisionados, brokers aún no en modo migración (pasos 1 y 2)Dé de baja el quórum de controladores KRaft. No ha cambiado nada más.
Brokers en modo migración (paso 3)Dé de baja el quórum. En zookeeper-shell.sh, compare get /controller_epoch con el campo kraft_controller_epoch de get /migration y, si la epoch de KRaft es mayor, haga set /controller_epoch por encima de ella. Ejecute delete /controller y después get /migration y delete /migration. En cada broker elimine la configuración de migración, controller.listener.names y controller.quorum.bootstrap.servers, asegúrese de que cada broker usa broker.id y no node.id, y reinicie los brokers progresivamente.
Brokers convertidos a KRaft (paso 4)Dos reinicios progresivos. Primero, elimine process.roles, restaure broker.id y zookeeper.connect, mantenga zookeeper.metadata.migration.enable=true y reinicie. Después, dé de baja el quórum, haga la comprobación de epoch, elimine /controller y /migration, quite la configuración de migración y reinicie por segunda vez.
Finalizada (paso 5)No se puede revertir.

Fuentes: Apache Kafka KRaft operations (3.9), las notas de actualización de 4.4, las notas de actualización de 4.0, la página de versiones de Java y la lista de CVE de Apache Kafka.

¿No sabe qué bloqueos tiene su clúster? Un health check de Kafka los detecta antes de que reserve la ventana. Si todavía no puede migrar y necesita que los brokers 3.x y ZooKeeper sigan recibiendo parches mientras tanto, eso es el soporte extendido de Kafka y ZooKeeper de OSSeva, un servicio independiente de AceMQ.

Elegir la plataforma de destino

Apache Kafka autogestionado, Amazon MSK, Confluent Platform, Confluent Cloud y Redpanda se diferencian menos en el protocolo que en aquello de lo que usted es responsable y en lo que puede cubrir un contrato de soporte. La decisión que importa a nivel operativo es qué capa conserva: MSK le proporciona los brokers y le deja los topics, los consumidores y los conectores, mientras que un servicio totalmente gestionado asume más y también impone más restricciones. Valore el coste del destino frente al coste operativo total, incluido el tiempo de los ingenieros, y no solo frente a la partida de infraestructura.

Copiar los datos: MirrorMaker 2 y la traducción de offsets

MirrorMaker 2 replica topics entre clústeres y, lo que es más importante, traduce los offsets de los consumer groups, porque un offset en el clúster de origen no significa lo mismo en el de destino. Se ejecuta como un clúster de Connect y necesita su propia planificación de capacidad; un despliegue de MirrorMaker dimensionado para el régimen estable se quedará atrás durante la carga inicial. Decida pronto si los nombres de los topics se reasignan con un prefijo de clúster o se conservan, porque esa decisión afecta a la configuración de todos los clientes y es muy difícil de revertir a mitad de la migración.

Objetivos de respuesta desde 15 minutos, según el plan. Ingenieros sénior asignados.

Contacto

El cutover: donde de verdad fracasan las migraciones

La secuencia segura consiste en replicar hasta que el destino esté al día, detener los productores, dejar que los consumidores vacíen el origen hasta un lag de cero, verificar que los offsets se han traducido correctamente y, después, redirigir productores y consumidores a la vez. Los equipos se meten en problemas cuando mueven los consumidores antes que los productores, lo que provoca que se reprocesen o se salten mensajes según en qué sentido se hayan traducido los offsets, o cuando hacen escritura dual sin un plan para conciliar después los dos clústeres. Acuerde el criterio de rollback antes de que se abra la ventana y asegúrese de que el clúster de origen sigue en marcha y sin tocar el tiempo suficiente para poder volver a él.

Si el destino es Kubernetes

Ejecutar Kafka en Kubernetes cambia los modos de fallo en lugar de eliminarlos: la storage class y el comportamiento de los volúmenes determinan lo que cuesta reiniciar un broker, la antiafinidad de los pods determina si la caída de un nodo se lleva por delante un conjunto completo de réplicas, y las actualizaciones progresivas deben respetar el liderazgo de las particiones y no solo el estado de readiness de los pods. Es un destino viable, y un mal lugar para aprender a operar Kafka por primera vez en plena migración.

Abandonar Kafka, y cuándo tiene sentido

Algunos entornos usan Kafka para trabajos que son de cola y no de log: distribución de tareas, request-reply, enrutamiento por mensaje, consumo selectivo. Son patrones de RabbitMQ, y forzarlos en Kafka genera las contorsiones de particiones y consumer groups que llevan a los equipos a describir Kafka como complicado. Tome la decisión en función del patrón de mensajería, no de la frustración operativa, porque pasar a un broker que tampoco opera bien no resuelve nada.

De nuestros proyectos. American National Insurance necesitaba CDC (captura de datos de cambios) para SQL Server y evaluó Kafka para ello. Se consideró que Kafka era demasiado complejo de operar para esa tarea, así que AceMQ diseñó Debezium en modo independiente publicando directamente en RabbitMQ. Así se evitó operar un clúster de Kafka y Kafka Connect, cuya operación habría sido desproporcionada para el volumen de datos, y se logró una captura de cambios completa con un enrutamiento más flexible (el caso).

Demuestre la recuperación en el nuevo clúster antes de confiar en él

Un clúster migrado no hereda nada de la confianza que se ganó el antiguo. Antes de dar de baja el origen, ejecute en el destino la recuperación que necesitaría durante un incidente: restaure o reprocese hasta un punto conocido, confirme que la configuración de retención coincide con lo que los sistemas aguas abajo dan por hecho que pueden reprocesar y documente el RPO resultante. Las migraciones son el momento más habitual en que un plan de recuperación ante desastres deja de ser cierto sin que nadie se dé cuenta.

Preguntas frecuentes

¿Es obligatorio migrar de ZooKeeper a KRaft?

Sí, si quiere usar Kafka 4.0 o posterior. La versión 4.0 eliminó ZooKeeper por completo en lugar de marcarlo como obsoleto, así que KRaft es un requisito previo para todas las actualizaciones posteriores. La migración se realiza mediante un modo puente que exige que los brokers estén antes en una versión 3.x suficientemente reciente.

¿Qué debo comprobar antes de migrar Kafka de ZooKeeper a KRaft?

Esté en Kafka 3.9.1, la última versión puente, con inter.broker.protocol.version configurado a 3.9. Compruebe si hay funcionalidades que KRaft no admite por completo y directorios de logs fallidos, que bloquean la migración. Aprovisione tres o más controladores con el ID del clúster existente y node IDs que no coincidan con los IDs de los brokers, y defina de antemano la regla de rollback: solo puede volver a ZooKeeper hasta que finalice. Después, audite las herramientas que aún usan --zookeeper antes de pasar a 4.x.

¿Qué versión de Java necesita Kafka 4.0?

Java 17 para los brokers, Kafka Connect y las herramientas, y Java 11 o posterior para los clientes y las aplicaciones de Kafka Streams, según las notas de actualización de Apache Kafka 4.0. Planifique el cambio de JDK en los hosts de los brokers como parte de cualquier actualización de Kafka a 4.0, junto con la migración a KRaft, que debe hacerse antes.

¿Cómo se gestionan los offsets de los consumidores en una migración de clúster de Kafka?

MirrorMaker 2 traduce los offsets de los grupos de consumidores (consumer groups) entre clústeres, porque el mismo número de offset no corresponde al mismo mensaje en el destino. Verificar esa traducción antes de redirigir los consumidores es el paso que distingue un cutover limpio de uno que reprocesa o se salta mensajes.

¿Cuál es la secuencia segura de cutover?

Replique hasta que el destino esté al día, detenga los productores, deje que los consumidores vacíen el origen hasta lag cero, verifique los offsets traducidos y, después, mueva productores y consumidores a la vez. Mover los consumidores antes que los productores es la forma más habitual de perder o duplicar mensajes.

¿Deberíamos abandonar Kafka y pasar a RabbitMQ?

Solo si la carga tiene forma de cola y no de log: la distribución de tareas, el request-reply, el enrutamiento por mensaje y el consumo selectivo son patrones de RabbitMQ. Tome la decisión en función del patrón de mensajería y no de la dificultad operativa, que suele depender del equipo más que del broker.

¿Cómo se migra de ZooKeeper a KRaft paso a paso?

Lleve todos los brokers a Apache Kafka 3.9.1 o posterior con inter.broker.protocol.version=3.9. Lea el ID del clúster en ZooKeeper y arranque controladores KRaft que lo lleven, con zookeeper.metadata.migration.enable=true. Reinicie los brokers en modo migración y, después, reinicie cada uno como broker KRaft con process.roles=broker y un node.id igual a su antiguo broker.id. Tras un periodo de observación, elimine el flag de migración de los controladores y reinícielos de uno en uno para finalizar. Después, actualice a 4.x.

¿Se puede hacer rollback de una migración de ZooKeeper a KRaft?

Sí, hasta que finalice. Los pasos dependen de hasta dónde haya llegado, y cada uno exige comparar la epoch del controlador de ZooKeeper con la de KRaft para que el controlador de ZooKeeper que toma el relevo arranque con una epoch mayor. Una vez finalizada, no es posible volver a ZooKeeper; por eso Apache señala que algunos usuarios esperan una o dos semanas antes de finalizar.

¿La migración de ZooKeeper a KRaft requiere tiempo de inactividad?

El procedimiento de Apache reinicia los brokers de forma progresiva para no afectar a la disponibilidad del clúster, y la migración arranca automáticamente en cuanto el último broker se ha reiniciado en modo migración. Ensaye en una copia del clúster, porque los clientes y las herramientas que todavía dan por hecho ZooKeeper son la fuente habitual de sorpresas.

Consulta gratuita

Que un experto revise su clúster de Kafka

Tanto si está resolviendo un incidente en producción como si planifica una migración o quiere una segunda opinión sobre su arquitectura, nuestro equipo está preparado. Sin discursos comerciales, solo respuestas.

Escríbanos