Sur cette page
La migration Kafka en un paragraphe
La migration Kafka en un paragraphe
Pour migrer Kafka de ZooKeeper vers KRaft, passez les brokers en 3.9.1 ou version ultérieure, démarrez un quorum de contrôleurs KRaft avec l'ID de cluster existant et la migration activée, redémarrez les brokers en mode migration puis en tant que brokers KRaft, et finalisez après une période d'observation. Le retour arrière reste possible jusqu'à la finalisation. La section 1 présente le runbook complet.
Trois opérations différentes portent le nom de migration Kafka, et elles n'ont presque rien en commun. Passer de ZooKeeper à KRaft est un changement de la couche de métadonnées sur le même cluster ; c'est un prérequis pour la branche 4.x, puisque la 4.0 a entièrement supprimé ZooKeeper, et cela passe par un mode passerelle qui exige que les brokers soient d'abord sur une version 3.x suffisamment récente. Changer de plateforme, qu'il s'agisse de passer d'un cluster autogéré à MSK, de Confluent à l'open source, ou de n'importe quoi vers Redpanda, est une migration de données : MirrorMaker 2 copie les topics et traduit les offsets des consommateurs, et c'est l'ordre de la bascule qui détermine si vous perdez des messages. Quitter complètement Kafka, généralement pour RabbitMQ, est une décision d'architecture qui doit se fonder sur le pattern de messagerie plutôt que sur la frustration opérationnelle. Chacune comporte un risque différent, et seule la première a une échéance fixée par le projet.
Migration de ZooKeeper vers KRaft, étape par étape
Pour migrer Kafka de ZooKeeper vers KRaft : passez les brokers en Apache Kafka 3.9.1 ou version ultérieure avec inter.broker.protocol.version=3.9, démarrez un quorum de contrôleurs KRaft qui porte l'ID de cluster existant et dont la migration est activée, redémarrez les brokers en mode migration, redémarrez-les à nouveau en tant que brokers KRaft, patientez, puis finalisez en sortant les contrôleurs du mode migration. Le retour arrière est possible à tout moment jusqu'à la finalisation, et plus après. Kafka 4.0 a entièrement supprimé ZooKeeper : cette migration est donc un prérequis pour toute version 4.x, et c'est pourquoi elle précède la mise à niveau au lieu de la remplacer.
Le runbook ci-dessous suit la documentation d'exploitation KRaft d'Apache Kafka 3.9, modifiée pour la dernière fois le 23 octobre 2026 et consultée le 28 octobre 2026. Vérifiez la page correspondant à votre version de correctif exacte avant une fenêtre de migration, et répétez d'abord l'opération sur une copie du cluster.
Étape 0 : identifier ce qui bloque la migration
Trois conditions l'arrêtent ou la bloquent. Les fonctionnalités que KRaft n'implémente pas entièrement l'arrêtent. Un broker qui utilise plusieurs répertoires de logs dont l'un est défaillant ne peut pas migrer tant que le répertoire n'est pas réparé (KAFKA-16431). Enfin, si le ZooKeeper Security Migration Tool a déjà été exécuté, la migration peut se bloquer sur un nœud /migration mal formé (KAFKA-19480), que vous supprimez avec delete /migration dans zookeeper-shell.sh. Repérez ces trois points sur l'ancien cluster avant de réserver la fenêtre. Ne modifiez pas la version des métadonnées (inter.broker.protocol.version) pendant une migration.
Étape 1 : passer tous les brokers sur la version passerelle
Apache exige des brokers en 3.9.1 avec inter.broker.protocol.version=3.9. La version 3.9.2, publiée le 21 février 2026, est la dernière version 3.x ; elle ajoute un indicateur de compatibilité pour une différence connue dans ce que reçoit une AlterConfigPolicy entre les modes ZooKeeper et KRaft (KIP-1252) : utilisez-la si vous appliquez une telle politique. Si vous utilisez des ACL, migrez en 3.6.2 ou version ultérieure : la CVE-2024-27309 pouvait amener Kafka à ignorer les règles DENY pendant une migration en 3.5.0 à 3.6.1 (voir le registre des CVE Kafka). Activez la journalisation TRACE de la migration sur chaque contrôleur avec log4j.logger.org.apache.kafka.metadata.migration=TRACE.
Étape 2 : lire l'ID de cluster et provisionner les contrôleurs
bin/zookeeper-shell.sh localhost:2181 get /cluster/idLes contrôleurs KRaft doivent porter cet ID de cluster. Attribuez à chaque contrôleur un node.id qui n'entre en collision avec aucun broker.id, car brokers et contrôleurs partagent le même espace d'identifiants. Utilisez trois ou cinq contrôleurs : une majorité doit rester active, donc trois tolèrent une panne et cinq en tolèrent deux. Un contrôleur prêt à migrer ressemble à ceci (exemple d'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=PLAINTEXTbin/kafka-storage.sh format --standalone --cluster-id=<zk-cluster-id> -c config/kraft/controller.properties
bin/kafka-server-start.sh config/kraft/controller.propertiesL'exemple d'Apache démarre un seul contrôleur autonome. Pour un quorum de trois ou cinq nœuds, provisionnez les autres comme le décrit la documentation KRaft de votre version de Kafka, tous avec le même ID de cluster et l'indicateur de migration activé.
Étape 3 : redémarrer les brokers en mode migration (phase hybride)
Ajoutez les paramètres du quorum de contrôleurs et l'indicateur de migration à chaque broker, conservez broker.id défini sur un entier positif ou nul, et redémarrez les brokers un par un. Les brokers fonctionnent toujours en mode ZooKeeper, le contrôleur KRaft leur envoyant les RPC de contrôleur.
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=CONTROLLERLa migration démarre d'elle-même dès que le dernier broker a redémarré. Le contrôleur actif journalise Completed migration of metadata from Zookeeper to KRaft une fois la copie des métadonnées terminée.
Étape 4 : convertir les brokers en KRaft (phase de double écriture)
Reconfigurez chaque broker en broker KRaft et redémarrez-le, un par un : remplacez broker.id par node.id en conservant le même numéro, ajoutez process.roles=broker, supprimez les paramètres ZooKeeper et zookeeper.metadata.migration.enable, supprimez control.plane.listener.name si vous l'aviez défini, et retirez inter.broker.protocol.version, car KRaft utilise à la place la fonctionnalité metadata.version. Si le broker utilise kafka.security.authorizer.AclAuthorizer, changez authorizer.class.name en org.apache.kafka.metadata.authorizer.StandardAuthorizer lors de ce redémarrage. Les contrôleurs continuent d'écrire les métadonnées dans ZooKeeper pendant ce temps.
process.roles=broker
node.id=0
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
controller.quorum.bootstrap.servers=localhost:9093
controller.listener.names=CONTROLLERÉtape 5 : observer, puis finaliser
Apache indique que certains utilisateurs attendent une ou deux semaines avant de finaliser, ce qui implique de laisser ZooKeeper tourner aussi longtemps, afin de valider le mode KRaft sur la charge réelle. Pendant cette période d'observation, vérifiez bin/kafka-metadata-quorum.sh --bootstrap-server host:9092 describe --status, confirmez que les partitions sous-répliquées et hors ligne sont à 0, et menez les exercices de panne que vous feriez sur n'importe quel nouveau cluster. Pour finaliser, supprimez zookeeper.metadata.migration.enable et les paramètres client ZooKeeper de chaque contrôleur, puis redémarrez les contrôleurs un par un. Ensuite, ZooKeeper peut être décommissionné, et la migration ne peut plus être annulée.
Étape 6 : puis mettre à niveau vers Kafka 4.x
Les brokers peuvent passer en 4.0 et au-delà depuis tout cluster KRaft dont les versions logicielle et de métadonnées sont au moins en 3.3.x. Avant la fenêtre de mise à niveau, passez les hôtes des brokers sous Java 17 (Apache prend en charge 17, 21 et 25 pour les brokers et recommande la dernière LTS), et corrigez chaque script, appel d'administration et configuration qui pointe encore vers une chaîne de connexion ZooKeeper, comme --zookeeper ou zookeeper.connect, car la 4.x n'a plus de mode ZooKeeper : utilisez --bootstrap-server. Au 28 octobre 2026, Apache maintient les versions 4.4, 4.3 et 4.2.
Retour arrière
Les étapes de retour arrière dépendent de votre avancement, et chacune exige de vérifier d'abord l'epoch du contrôleur ZooKeeper : Apache a ajouté cette vérification à sa documentation le 23 octobre 2026 (KAFKA-20488), car un contrôleur ZooKeeper élu avec un epoch inférieur à celui de KRaft ne peut pas modifier l'état des partitions.
| Dernière étape terminée | Comment revenir en arrière |
|---|---|
| Contrôleurs provisionnés, brokers pas encore en mode migration (étapes 1 et 2) | Décommissionnez le quorum de contrôleurs KRaft. Rien d'autre n'a changé. |
| Brokers en mode migration (étape 3) | Décommissionnez le quorum. Dans zookeeper-shell.sh, comparez get /controller_epoch au champ kraft_controller_epoch de get /migration et, si l'epoch KRaft est supérieur, définissez set /controller_epoch au-dessus. Exécutez delete /controller, puis get /migration et delete /migration. Sur chaque broker, supprimez les paramètres de migration, controller.listener.names et controller.quorum.bootstrap.servers, assurez-vous que chaque broker utilise broker.id et non node.id, puis redémarrez progressivement les brokers. |
| Brokers convertis en KRaft (étape 4) | Deux redémarrages progressifs. D'abord, supprimez process.roles, rétablissez broker.id et zookeeper.connect, conservez zookeeper.metadata.migration.enable=true et redémarrez. Ensuite, décommissionnez le quorum, effectuez la vérification de l'epoch, supprimez /controller et /migration, retirez les paramètres de migration et redémarrez une seconde fois. |
| Finalisée (étape 5) | Le retour arrière est impossible. |
Sources : Apache Kafka exploitation KRaft (3.9), les notes de mise à niveau 4.4, les notes de mise à niveau 4.0, la page des versions Java et la liste des CVE Apache Kafka.
Vous ne savez pas quels blocages concernent votre cluster ? Un bilan de santé Kafka les identifie avant que vous réserviez la fenêtre. Si vous ne pouvez pas encore migrer et que vos brokers 3.x et ZooKeeper doivent rester corrigés d'ici là, c'est le support étendu Kafka et ZooKeeper d'OSSeva, un service distinct d'AceMQ.
Choisir la plateforme de destination
Apache Kafka autogéré, Amazon MSK, Confluent Platform, Confluent Cloud et Redpanda diffèrent moins par le protocole que par ce dont vous êtes responsable et par ce qu'un contrat de support peut couvrir. La décision qui compte sur le plan opérationnel est la couche que vous conservez : MSK vous fournit les brokers et vous laisse les topics, les consommateurs et les connecteurs, tandis qu'un service entièrement managé en prend davantage en charge et impose davantage de contraintes. Évaluez le coût de la destination au regard de l'ensemble des coûts d'exploitation, temps d'ingénierie compris, plutôt que de la seule ligne d'infrastructure.
Copier les données : MirrorMaker 2 et la traduction des offsets
MirrorMaker 2 réplique les topics entre clusters et, surtout, traduit les offsets des groupes de consommateurs, car un offset sur le cluster source n'a pas la même signification sur le cluster cible. Il tourne sous forme de cluster Connect et nécessite sa propre planification de capacité : un déploiement MirrorMaker dimensionné pour le régime de croisière prendra du retard pendant le rattrapage initial. Décidez tôt si les noms de topics sont réécrits avec un préfixe de cluster ou conservés, car ce choix se répercute sur la configuration de chaque client et il est pénible de revenir dessus en pleine migration.
La bascule : là où les migrations échouent vraiment
L'ordre sûr consiste à répliquer jusqu'à ce que la cible ait rattrapé son retard, arrêter les producteurs, laisser les consommateurs vider la source jusqu'à un lag nul, vérifier que les offsets ont été correctement traduits, puis rediriger producteurs et consommateurs ensemble. Les équipes se mettent en difficulté en déplaçant les consommateurs avant les producteurs, ce qui provoque des rejeux ou des sauts selon le sens de la traduction des offsets, ou en pratiquant la double écriture sans plan pour réconcilier ensuite les deux clusters. Mettez-vous d'accord sur le déclencheur de retour arrière avant l'ouverture de la fenêtre, et assurez-vous que le cluster source reste en service, sans modification, suffisamment longtemps pour pouvoir y revenir.
Si la destination est Kubernetes
Exécuter Kafka sur Kubernetes change les modes de défaillance plutôt qu'il ne les supprime : la storage class et le comportement des volumes déterminent ce que coûte le redémarrage d'un broker, l'anti-affinité des pods détermine si la perte d'un nœud emporte tout un jeu de réplicas, et les mises à jour progressives doivent respecter le leadership des partitions et pas seulement l'état de préparation des pods. C'est une destination viable, mais un mauvais endroit pour découvrir l'exploitation de Kafka en pleine migration.
Quitter Kafka, et quand c'est le bon choix
Certains parcs utilisent Kafka pour des tâches qui relèvent de la file d'attente plutôt que du journal : distribution de tâches, requête-réponse, routage message par message, consommation sélective. Ce sont des patterns RabbitMQ, et les imposer à Kafka entraîne les contorsions de partitions et de groupes de consommateurs qui font dire aux équipes que Kafka est compliqué. Tranchez en fonction du pattern de messagerie, pas de la frustration opérationnelle : passer à un broker que vous n'exploitez pas mieux ne résout rien.
Retour de nos missions. American National Insurance avait besoin de CDC (capture des changements de données) pour SQL Server et a évalué Kafka à cette fin. Kafka a été jugé trop complexe à exploiter pour ce besoin ; AceMQ a donc conçu un Debezium autonome publiant directement vers RabbitMQ. Cela a évité d'exploiter un cluster Kafka et Kafka Connect, dont l'exploitation aurait été disproportionnée par rapport au volume de données, tout en assurant une capture complète des changements avec un routage plus flexible (l'étude de cas).
Prouver la reprise sur le nouveau cluster avant de lui faire confiance
Un cluster migré n'hérite d'aucune de la confiance qu'avait gagnée l'ancien. Avant de décommissionner la source, exécutez sur la cible la reprise dont vous auriez besoin lors d'un incident : restaurez ou rejouez jusqu'à un point connu, vérifiez que les paramètres de rétention correspondent à ce que les systèmes en aval pensent pouvoir rejouer, et consignez le RPO obtenu. Les migrations sont le moment où un plan de reprise après sinistre cesse le plus souvent, discrètement, d'être valable.
Questions fréquentes
Faut-il obligatoirement migrer de ZooKeeper vers KRaft ?
Oui, si vous comptez utiliser Kafka 4.0 ou une version ultérieure. La version 4.0 a entièrement supprimé ZooKeeper au lieu de le déprécier : KRaft est donc un prérequis pour toute mise à niveau ultérieure. La migration passe par un mode passerelle qui exige que les brokers soient d'abord sur une version 3.x suffisamment récente.
Que faut-il vérifier avant de migrer Kafka de ZooKeeper vers KRaft ?
Passez sur Kafka 3.9.1, la dernière version passerelle, avec inter.broker.protocol.version défini à 3.9. Recherchez les fonctionnalités que KRaft ne prend pas entièrement en charge et les répertoires de logs en échec, qui bloquent la migration. Provisionnez au moins trois contrôleurs avec l'ID du cluster existant et des node IDs qui n'entrent pas en conflit avec les broker IDs, et fixez d'emblée la règle de retour arrière : le retour à ZooKeeper n'est possible que jusqu'à la finalisation. Auditez ensuite l'outillage qui utilise encore --zookeeper avant de passer en 4.x.
Quelle version de Java faut-il pour Kafka 4.0 ?
Java 17 pour les brokers, Kafka Connect et les outils, et Java 11 ou supérieur pour les clients et les applications Kafka Streams, selon les notes de mise à niveau d'Apache Kafka 4.0. Prévoyez le changement de JDK sur les hôtes des brokers dans toute mise à niveau de Kafka vers la 4.0, en plus de la migration KRaft qui doit intervenir en premier.
Comment les offsets des consommateurs sont-ils gérés lors d'une migration de cluster Kafka ?
MirrorMaker 2 traduit les offsets des consumer groups d'un cluster à l'autre, car un même numéro d'offset ne désigne pas le même message sur la cible. Vérifier cette traduction avant de rediriger les consommateurs est l'étape qui distingue une bascule propre d'une bascule qui rejoue ou saute des messages.
Quel est l'ordre sûr pour la bascule ?
Répliquez jusqu'à ce que la cible soit à jour, arrêtez les producteurs, laissez les consommateurs vider la source jusqu'à un consumer lag nul, vérifiez les offsets traduits, puis déplacez producteurs et consommateurs ensemble. Déplacer les consommateurs avant les producteurs est la cause la plus fréquente de perte ou de duplication de messages.
Faut-il quitter Kafka pour RabbitMQ ?
Uniquement si la charge de travail relève de la file d'attente plutôt que du journal : distribution de tâches, requête-réponse, routage par message et consommation sélective sont des patterns RabbitMQ. Décidez en fonction du pattern de messagerie plutôt que de la difficulté opérationnelle, qui tient généralement davantage à l'équipe qu'au broker.
Comment migrer de ZooKeeper vers KRaft étape par étape ?
Passez chaque broker en Apache Kafka 3.9.1 ou version ultérieure avec inter.broker.protocol.version=3.9. Lisez l'ID de cluster dans ZooKeeper et démarrez des contrôleurs KRaft qui le portent, avec zookeeper.metadata.migration.enable=true. Redémarrez les brokers en mode migration, puis redémarrez chacun d'eux en tant que broker KRaft avec process.roles=broker et un node.id égal à son ancien broker.id. Après une période d'observation, retirez l'indicateur de migration des contrôleurs et redémarrez-les un par un pour finaliser. Passez ensuite à la 4.x.
Peut-on faire un retour arrière sur une migration de ZooKeeper vers KRaft ?
Oui, jusqu'à la finalisation. Les étapes dépendent de votre avancement, et chacune exige de comparer l'epoch du contrôleur ZooKeeper à celui de KRaft, afin que le contrôleur ZooKeeper qui reprend la main démarre avec un epoch supérieur. Après la finalisation, revenir à ZooKeeper est impossible, c'est pourquoi Apache indique que certains utilisateurs attendent une ou deux semaines avant de finaliser.
La migration de ZooKeeper vers KRaft nécessite-t-elle une interruption de service ?
La procédure d'Apache redémarre les brokers de manière progressive pour ne pas affecter la disponibilité du cluster, et la migration elle-même démarre automatiquement dès que le dernier broker a redémarré en mode migration. Répétez l'opération sur une copie du cluster, car les clients et outils qui supposent encore la présence de ZooKeeper sont la source habituelle de mauvaises surprises.