Mise à niveau et migration de Kafka avec des exemples pratiques

Introduction

La mise à niveau d'Apache Kafka est une tâche courante pour les équipes de plateforme, mais même une tâche courante peut interrompre un pipeline de production si une étape est manquée. Ce guide est destiné aux développeurs, consultants DevOps et équipes techniques de startups qui doivent faire passer Kafka d'une ancienne version à une version plus récente, ou migrer un cluster vers une nouvelle infrastructure, sans perte de données ni indisponibilité.

Nous nous concentrons sur des procédures pratiques et basées sur des exemples. Chaque section comprend des commandes réelles, les résultats attendus et ce qu'il faut faire si le résultat ne correspond pas. Vous apprendrez à inventorier votre déploiement actuel, planifier un chemin de mise à niveau sûr, vérifier le résultat et récupérer en cas de problème. Nous couvrons les mises à niveau de Kafka 2.x vers 3.x et les scénarios de migration courants, mais les principes s'appliquent également à d'autres versions.

La sécurité opérationnelle est le thème central : observez avant de changer, gardez les changements petits, utilisez des valeurs fictives au lieu de secrets réels et sachez toujours comment revenir à un état fonctionnel.

Inventaire de la version et de l'environnement

Avant de toucher quoi que ce soit, vous devez avoir une image précise de ce qui est en cours d'exécution. Cela signifie enregistrer la version de Kafka, la méthode de déploiement, la configuration des brokers et les versions des bibliothèques clientes qui se connectent à votre cluster. Une erreur ici peut entraîner des mises à niveau incompatibles ou une migration échouée.

Observation en lecture seule

Commencez par des commandes en lecture seule. N'exécutez jamais une commande de modification avant d'avoir capturé l'état actuel et de l'avoir sauvegardé dans un endroit sûr. Pour un broker Kafka, la version est généralement disponible à partir du script kafka-broker-api-versions.sh ou en vérifiant le processus du broker en cours d'exécution.

Exécutez ceci sur un hôte broker :

./bin/kafka-broker-api-versions.sh --bootstrap-server broker1:9092 | grep -A 5 "broker1"

Sortie attendue (exemple pour Kafka 2.8.1) :

broker1:9092 (id: 0 rack: null) -> (
  Produce(0): 0 to 8 [usable: 8],
  Fetch(1): 0 to 11 [usable: 11],
  ListOffsets(2): 0 to 5 [usable: 5],
  ...
)

Les versions d'API exactes sont moins importantes que le fait que le broker soit joignable et réponde. Si vous voyez un délai d'attente ou une connexion refusée, arrêtez-vous et corrigez la connectivité avant de continuer.

Pour obtenir la version exacte du broker à partir de l'hôte, vérifiez le fichier libs/kafka_2.13-<version>.jar ou exécutez :

ls /opt/kafka/libs/ | grep kafka_2.13

Exemple de sortie :

kafka_2.13-2.8.1.jar

Cela vous indique la version Scala (2.13) et la version Kafka (2.8.1). Notez que Kafka 3.x utilise uniquement Scala 2.13 ; 2.x peut utiliser 2.12 ou 2.13.

Détails de la topologie et de l'environnement

Enregistrez les informations suivantes dans un tableur ou un runbook :

• Nombre de brokers, leurs noms d'hôte et leurs ID de broker.
• Configuration du contrôleur : qui est le contrôleur actif ? (ZooKeeper pour Kafka 2.x, KRaft pour 3.x+).
• Applications clientes et leurs versions de bibliothèque (par exemple, clients Java utilisant kafka-clients 2.8.0, Python utilisant confluent-kafka-python 1.8.2).
• Configuration de sécurité : SSL/TLS, SASL, ACL.
• Facteurs de réplication des topics et nombre de partitions pour les topics critiques.

Exemple : utilisez kafka-topics.sh pour lister les topics et décrire un topic critique :

./bin/kafka-topics.sh --bootstrap-server broker1:9092 --list
./bin/kafka-topics.sh --bootstrap-server broker1:9092 --describe --topic commandes

Sortie attendue pour --describe :

Topic: commandes	PartitionCount: 6	ReplicationFactor: 3	Configs: min.insync.replicas=2
	Topic: commandes	Partition: 0	Leader: 2	Replicas: 2,1,3	Isr: 2,1,3

Cela montre que le topic a 6 partitions, un facteur de réplication de 3, un min ISR de 2, et que toutes les répliques sont synchronisées. Si une partition montre un ISR plus petit que l'ensemble des répliques, résolvez ce problème avant la mise à niveau car un redémarrage du broker retirera temporairement plus de répliques.

Prérequis pour la mise à niveau

• Sauvegarde de la configuration : copiez server.properties, log4j.properties et tous les fichiers JAAS vers un emplacement sûr.
• Compatibilité des clients : vérifiez que vos bibliothèques clientes peuvent communiquer avec la version cible de Kafka. Kafka maintient généralement une compatibilité ascendante : les clients peuvent être plus récents ou plus anciens d'une version majeure, mais passer de clients Kafka 0.10 à des brokers Kafka 3.x ne fonctionnera pas. Consultez la documentation.
• Espace disque : assurez-vous d'avoir suffisamment de disque pour les redémarrages en rolling et la croissance possible des logs.
• Fenêtre de maintenance : coordonnez avec les consommateurs et les producteurs.

Le plus petit changement justifié

Ne mettez pas à niveau tous les brokers en même temps. Utilisez une mise à niveau en rolling : mettez à niveau un broker, attendez, testez, puis continuez. Il en va de même pour les changements de configuration : changez un paramètre à la fois et vérifiez.

Chemin de configuration sûr

La mise à niveau elle-même implique de changer la configuration du broker et de remplacer les binaires. Suivez une séquence qui minimise les risques et permet un rollback à chaque étape.

Plan de mise à niveau étape par étape

Supposons que vous mettiez à niveau de Kafka 2.8.1 à Kafka 3.1.0 sur trois brokers. La recommandation officielle est de mettre à niveau les brokers d'abord, puis les clients si nécessaire, et enfin d'activer les nouvelles fonctionnalités si vous le souhaitez.

1. Arrêtez un broker proprement.

Un arrêt propre garantit que le broker quitte les listes ISR proprement.

./bin/kafka-server-stop.sh

Attendez que le processus se termine, puis vérifiez qu'il n'est plus dans le cluster en consultant le log du contrôleur ou en exécutant :

./bin/kafka-broker-api-versions.sh --bootstrap-server broker1:9092 | grep broker1

(Devrait ne rien retourner ou afficher une connexion refusée.)

2. Remplacez la distribution Kafka sur ce broker.

Gardez l'ancienne installation dans un répertoire séparé, par exemple /opt/kafka-old. Installez la nouvelle version dans /opt/kafka. Copiez votre server.properties sauvegardé et les autres fichiers de configuration dans le nouveau répertoire config. Ne copiez pas les répertoires de logs.

3. Démarrez le broker mis à niveau.

./bin/kafka-server-start.sh -daemon config/server.properties

Vérifiez le fichier log logs/server.log pour le succès du démarrage. Cherchez une ligne comme :

[2025-03-01 14:30:00,123] INFO [KafkaServer id=1] started (kafka.server.KafkaServer)

4. Vérifiez que le broker a rejoint le cluster.

Exécutez à nouveau la commande des versions d'API :

./bin/kafka-broker-api-versions.sh --bootstrap-server broker1:9092 | grep broker1

Vous devriez maintenant voir les détails de version. Vérifiez également le statut de sous-réplication du topic :

./bin/kafka-topics.sh --bootstrap-server broker1:9092 --describe --under-replicated-partitions

Si cela ne retourne rien, toutes les répliques sont synchronisées.

5. Répétez pour les autres brokers un par un.

Ne passez pas au broker suivant tant que le broker actuel n'est pas sain et que toutes les répliques sont à jour.

Changements de configuration à éviter pendant la mise à niveau

Ne changez pas les paramètres de configuration du broker en même temps que la mise à niveau de version. Par exemple, ne changez pas num.partitions ou default.replication.factor pendant la mise à niveau en rolling. Si vous devez faire un changement de configuration, faites-le après que tous les brokers sont mis à niveau et stables, ou avant, mais pas simultanément.

Rayon d'impact et récupération

Si un broker ne démarre pas après la mise à niveau, vous pouvez revenir en arrière en l'arrêtant, en restaurant l'ancien répertoire Kafka (par exemple, renommez /opt/kafka en /opt/kafka-bad, et /opt/kafka-old en /opt/kafka), et en redémarrant avec l'ancienne version. Le broker rejoindra le cluster et répliquera les données manquées depuis les autres brokers, tant que le répertoire de logs est intact. Ne supprimez pas le répertoire de logs à moins d'être prêt à perdre des données ou à reconstruire à partir des répliques.

Vérification et diagnostics

Après que tous les brokers sont mis à niveau, vous devez vérifier que le cluster est sain et que les clients peuvent produire et consommer.

Vérifications de santé du cluster

1. Vérifiez le nombre de brokers et les versions.

./bin/zookeeper-shell.sh zookeeper1:2181 <<< "ls /brokers/ids"

(Pour le mode KRaft, utilisez kafka-metadata-shell.sh.)

Sortie attendue :

[0, 1, 2]

Tous les ID de broker doivent être présents.

2. Vérifiez le statut du contrôleur.

Dans les logs du broker ou via JMX, trouvez quel broker est le contrôleur. Assurez-vous qu'il n'y a qu'un seul contrôleur actif. Si vous voyez des boucles de basculement du contrôleur, vérifiez les problèmes de réseau ou de ZooKeeper.

3. Vérifiez les partitions sous-répliquées et hors ligne.

./bin/kafka-topics.sh --bootstrap-server broker1:9092 --describe --under-replicated-partitions
./bin/kafka-topics.sh --bootstrap-server broker1:9092 --describe --unavailable-partitions

Les deux ne devraient retourner aucune sortie. Si des partitions sont sous-répliquées, attendez ou examinez les logs du broker.

Test de fumée client

Utilisez le producteur et le consommateur console pour tester les fonctionnalités de base :

Produire :

echo "message de test $(date)" | ./bin/kafka-console-producer.sh --bootstrap-server broker1:9092 --topic test-topic --producer-property acks=all

Consommer :

./bin/kafka-console-consumer.sh --bootstrap-server broker1:9092 --topic test-topic --from-beginning --max-messages 1

Sortie attendue : la même chaîne de message que vous avez envoyée.

Métriques de surveillance

Métriques clés à surveiller pendant et après la mise à niveau :

• kafka.server:type=ReplicaManager,name=UnderReplicatedPartitions devrait être 0.
• kafka.controller:type=KafkaController,name=ActiveControllerCount devrait être 1.
• kafka.network:type=RequestMetrics,name=RequestsPerSec,request=Produce ne devrait pas chuter significativement par rapport à la référence.
• Le lag des consommateurs pour les groupes de consommateurs critiques ne devrait pas augmenter au-delà de la normale.

Si une métrique est hors plage, diagnostiquez avant d'ouvrir le cluster au trafic complet.

Modes de défaillance et récupération

Même avec une planification minutieuse, les choses peuvent mal tourner. Voici les modes de défaillance courants et comment récupérer.

Le broker ne démarre pas après la mise à niveau

Symptômes : le processus du broker se termine immédiatement, server.log affiche ClassNotFoundException, NoSuchMethodError ou une configuration incompatible.

Pourquoi cela arrive :

• Versions Scala mélangées : utilisation d'un jar compilé en 2.12 avec un runtime 2.13 ou vice versa.
• Clé de configuration renommée ou supprimée dans la nouvelle version.
• Fichiers jar dépendants manquants si vous avez mal copié l'installation.

Récupération :

1. Vérifiez l'erreur dans logs/server.log.
2. Si c'est un problème de configuration, corrigez le fichier server.properties (par exemple, supprimez zookeeper.connect déprécié si vous utilisez KRaft).
3. Si c'est une incompatibilité binaire, assurez-vous d'utiliser la bonne distribution Kafka pour votre version Scala.
4. Si tout échoue, revenez à l'ancienne version en arrêtant le broker, en restaurant l'ancien répertoire et en redémarrant. Le broker rattrapera les répliques.

Les partitions sous-répliquées persistent

Symptômes : kafka-topics.sh --describe --under-replicated-partitions liste des partitions pendant longtemps après la mise à niveau.

Pourquoi cela arrive :

• Le broker a été arrêté trop longtemps et est sorti de l'ISR.
• Partition réseau ou problèmes d'E/S disque.
• Réaffectation des répliques en cours.

Récupération :

• Vérifiez les logs du broker pour les erreurs de réplication.
• Vérifiez l'utilisation du disque : si le disque d'un broker est plein, la réplication stagnera. Libérez de l'espace.
• Assurez-vous que tous les brokers fonctionnent et peuvent communiquer sur le port de réplication (par défaut 9092 pour l'inter-broker, ou 9093 si différent).
• Si nécessaire, forcez la réaffectation ou redémarrez le broker pour déclencher la réplication.

Problèmes de compatibilité des clients

Symptômes : les clients lèvent UnsupportedVersionException ou similaire après la mise à niveau.

Pourquoi cela arrive :

• Les clients sont trop anciens par rapport au broker.
• Les clients utilisent une API supprimée (par exemple, les groupes de consommateurs basés sur ZooKeeper).

Récupération :

• Mettez à niveau la bibliothèque cliente vers une version compatible avec le broker. Consultez la matrice de compatibilité Kafka.
• Pour les anciens groupes de consommateurs utilisant ZooKeeper, migrez vers le nouveau protocole de groupe de consommateurs avant de mettre à niveau les brokers au-delà de 3.x, ou gardez un broker de compatibilité.

Perte de données ou corruption

Symptômes : certains messages manquent après la mise à niveau, ou le broker ne peut pas charger les segments de log.

Pourquoi cela arrive :

• Problèmes de disque pendant la mise à niveau.
• Élection de leader non propre activée (unclean.leader.election.enable=true) combinée à des défaillances de broker.
• Suppression manuelle des répertoires de logs.

Récupération :

• Si les segments de log sont corrompus, vous devrez peut-être restaurer à partir d'une sauvegarde ou utiliser kafka-reassign-partitions.sh pour déplacer les partitions affectées vers un broker sain.
• Pour éviter cela, définissez toujours unclean.leader.election.enable=false (par défaut) et assurez-vous que min.insync.replicas est défini de manière appropriée pour les topics critiques.
• Gardez toujours une sauvegarde des répertoires de logs avant les actions destructrices.

Scénarios de migration

Mettre à niveau sur place est une chose ; migrer vers un nouveau matériel ou un nouveau cluster en est une autre. Nous couvrons ici deux approches de migration courantes.

MirrorMaker 2 pour la réplication inter-cluster

Si vous déménagez vers un nouveau cluster (par exemple, un nouveau centre de données ou un service Kafka géré), MirrorMaker 2 peut répliquer les topics et les offsets des consommateurs.

Exemple de configuration :

Définissez les clusters source et cible dans mm2.properties :

clusters = source, cible
source.bootstrap.servers = source-broker1:9092
cible.bootstrap.servers = cible-broker1:9092
source->cible.enabled = true
source->cible.topics = commandes, paiements
cible->source.enabled = false

Exécutez MirrorMaker 2 :

./bin/connect-mirror-maker.sh mm2.properties

Surveillez la réplication en utilisant les offsets des groupes de consommateurs ou les métriques de MirrorMaker 2. Une fois les données répliquées et les consommateurs basculés vers le cluster cible, vous pouvez mettre hors service la source.

Expansion du cluster et réaffectation

Si vous ajoutez des brokers à un cluster existant et souhaitez y déplacer des topics, utilisez kafka-reassign-partitions.sh.

1. Générez un plan de réaffectation.

Créez un fichier JSON avec les topics à déplacer :

{"topics": [{"topic": "commandes"}], "version":1}

./bin/kafka-reassign-partitions.sh --bootstrap-server broker1:9092 --topics-to-move-json-file topics.json --broker-list "3,4,5" --generate

2. Examinez et exécutez le plan.

Copiez le plan généré dans reassign.json et exécutez :

./bin/kafka-reassign-partitions.sh --bootstrap-server broker1:9092 --reassignment-json-file reassign.json --execute

3. Vérifiez l'achèvement.

./bin/kafka-reassign-partitions.sh --bootstrap-server broker1:9092 --reassignment-json-file reassign.json --verify

Sortie attendue : Reassignment of partition commandes-0 completed successfully etc.

Pièges courants et comment les éviter

De nombreux problèmes de mise à niveau et de migration sont causés par des erreurs évitables. Voici les pièges les plus courants, pourquoi ils surviennent et comment les prévenir ou les récupérer.

1. Ne pas vérifier la compatibilité des clients avant de mettre à niveau les brokers

Pourquoi cela arrive : les équipes se concentrent sur la version du broker et oublient que les producteurs et les consommateurs ont leurs propres dépendances de version.

Comment éviter : avant de mettre à niveau les brokers, listez toutes les applications clientes et leurs versions de bibliothèque. Consultez la matrice de compatibilité Kafka pour vous assurer qu'elles peuvent communiquer avec la nouvelle version du broker. Sinon, prévoyez de mettre à niveau les clients d'abord ou simultanément.

Récupération : si les clients cassent après la mise à niveau du broker, vous devrez peut-être revenir en arrière sur les brokers jusqu'à ce que les clients soient mis à niveau, ou mettre à niveau les clients rapidement.

2. Changer plusieurs variables à la fois

Pourquoi cela arrive : pour gagner du temps, les équipes mettent à niveau la version et modifient également les paramètres de configuration ou le matériel en même temps.

Comment éviter : séparez strictement les mises à niveau de version des changements de configuration. Faites un type de changement, testez complètement, puis faites l'autre.

Récupération : si un changement combiné cause des problèmes, vous aurez plus de mal à identifier la cause. Revenez en arrière sur une variable à la fois pour isoler.

3. Ignorer le contrôleur et le quorum de métadonnées

Pourquoi cela arrive : dans Kafka 2.x avec ZooKeeper, les équipes peuvent oublier de vérifier la santé de ZooKeeper. Dans Kafka 3.x avec KRaft, elles peuvent ne pas comprendre le nouveau quorum de contrôleurs.

Comment éviter : vérifiez toujours la santé du contrôleur et de ZooKeeper (ou KRaft) avant et après la mise à niveau. Si vous utilisez ZooKeeper, assurez-vous que l'ensemble ZooKeeper est sain et a un leader. Si vous utilisez KRaft, assurez-vous qu'un quorum de contrôleurs fonctionne.

Récupération : si ZooKeeper est en mauvaise santé, corrigez-le avant de toucher aux brokers. Si KRaft perd le quorum, restaurez les contrôleurs manquants.

4. Ne pas avoir de plan de rollback testé

Pourquoi cela arrive : les équipes supposent que la mise à niveau se passera bien et ne préparent pas de procédure de rollback.

Comment éviter : écrivez un plan de rollback avant de commencer. Incluez les commandes pour arrêter la nouvelle version, restaurer les anciens binaires et la configuration, et redémarrer. Testez le rollback dans un environnement de staging si possible.

Récupération : si vous n'avez pas préparé et que quelque chose échoue, votre solution de repli est de restaurer à partir des sauvegardes ou de reconstruire à partir des répliques, ce qui peut être plus lent.

5. Oublier de surveiller le lag des consommateurs

Pourquoi cela arrive : après une mise à niveau du broker, les groupes de consommateurs peuvent se rééquilibrer, provoquant un lag temporaire. Les équipes oublient de surveiller le lag et supposent que le système va bien.

Comment éviter : configurez des alertes sur le lag des consommateurs pour les groupes critiques. Après la mise à niveau, surveillez le lag pendant au moins 24 heures pour détecter les problèmes retardés.

Récupération : si le lag est élevé, vérifiez les logs de rééquilibrage des consommateurs, les E/S du broker et le réseau. Vous devrez peut-être redémarrer les consommateurs ou augmenter la capacité.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour chaque mise à niveau ou migration Kafka. Elle est conçue pour qu'un seul responsable rende des comptes à chaque étape et en vérifie l'achèvement.

Chaque responsable est une personne unique et redevable, pas un groupe. La fréquence de révision indique quand ils doivent réévaluer le résultat si nécessaire.

Conclusion

La mise à niveau ou la migration d'Apache Kafka ne doit pas être un événement à haut risque. La clé est de l'aborder méthodiquement : inventorier votre environnement, planifier une mise à niveau en rolling sûre, vérifier chaque étape et avoir un chemin de rollback testé. Les exemples de ce guide fournissent un point de départ, mais adaptez toujours les commandes et les vérifications à votre version et déploiement Kafka spécifiques.

La plupart des échecs proviennent de l'omission des bases : ne pas vérifier la compatibilité des clients, changer trop de choses à la fois ou manquer d'un plan de rollback. En suivant les pratiques décrites ici, vous pouvez minimiser les interruptions, éviter les pertes de données et garder votre plateforme de streaming en bonne santé.

Ensuite, choisissez une tâche de vérification à faible risque dans la liste de contrôle, comme exécuter la commande de version en lecture seule et enregistrer la sortie. Ensuite, planifiez une fenêtre de maintenance pour une mise à niveau en rolling d'un broker dans un cluster de staging, pratiquez le rollback et affinez votre runbook. À mesure que vous gagnez en confiance, étendez à la production.

Un flux de travail de mise à niveau fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision.