Configuration d’un laboratoire Kafka local avec exemples pratiques : guide pratique

Introduction

Mettre en place un laboratoire Kafka local est le moyen le plus rapide de passer d’un problème observé à un résultat vérifié sans risquer l’environnement de production. Que vous soyez développeur construisant un nouveau pipeline de streaming, consultant DevOps validant un changement de configuration ou équipe de start-up prototypant une architecture événementielle, un environnement local contrôlé vous permet de tester des hypothèses, reproduire des pannes et répéter les étapes de récupération en toute sécurité.

Ce guide pratique présente l’installation de Kafka en local, la création de topics, la production et la consommation de messages, ainsi que le diagnostic des problèmes courants. Chaque étape inclut des commandes précises, les résultats attendus et les signaux d’échec afin que vous puissiez vérifier chaque action avant de passer à la suivante. Les exemples utilisent Kafka 3.6.1, une version stable au moment de la rédaction, mais les principes s’appliquent à toute version récente de la branche 3.x. À la fin, vous disposerez d’une configuration de laboratoire reproductible et d’une liste de contrôle pour valider le comportement de Kafka dans vos propres projets.

Inventaire des versions et de l’environnement

Avant de modifier quoi que ce soit, sachez exactement avec quoi vous travaillez. Pour ce laboratoire, nous utilisons :

• Composant : Apache Kafka 3.6.1 (distribution binaire avec le mode KRaft ; ZooKeeper n’est plus nécessaire)
• Prérequis Java : Java 11 ou 17 (OpenJDK ou Oracle JDK). Kafka 3.6.1 prend en charge les deux.
• Système d’exploitation : Linux, macOS ou Windows avec WSL2. Les commandes ci-dessous supposent un interpréteur de type Unix.
• Topologie de déploiement : cluster KRaft à nœud unique avec un seul courtier et un seul processus de contrôleur combinés.

Commencez par capturer votre environnement actuel. Exécutez ces commandes en lecture seule pour confirmer votre version de Java et l’espace disque disponible :

java -version
# Exemple de sortie attendue :
# openjdk version "17.0.9" 2023-10-17
# OpenJDK Runtime Environment (build 17.0.9+8)
# OpenJDK 64-Bit Server VM (build 17.0.9+8, mixed mode, sharing)

df -h /tmp
# Sortie attendue : au moins 2 Go libres pour les journaux et les données Kafka

Si Java est absent ou trop ancien, installez un JDK pris en charge avant de continuer. N’essayez pas d’exécuter Kafka avec une version Java non prise en charge ; le courtier échouera avec une erreur claire comme UnsupportedClassVersionError.

Maintenant, téléchargez et extrayez Kafka. Remplacez la version si vous en utilisez une différente :

cd ~/labs
curl -O https://downloads.apache.org/kafka/3.6.1/kafka_2.13-3.6.1.tgz
tar -xzf kafka_2.13-3.6.1.tgz
cd kafka_2.13-3.6.1

Vérifiez l’extraction :

ls bin
# La sortie attendue doit inclure kafka-server-start.sh, kafka-topics.sh, kafka-console-producer.sh, kafka-console-consumer.sh

À ce stade, vous disposez d’un laboratoire local propre. Ne copiez aucune information d’identification réelle ni aucun fichier de configuration de production dans ce répertoire.

Chemin de configuration sécurisé

La configuration par défaut de Kafka fonctionne immédiatement pour un cluster KRaft à nœud unique, mais vous devez comprendre ce que fait chaque paramètre clé avant de le modifier. Le fichier de configuration principal est config/server.properties. Ouvrez-le et recherchez ces lignes :

# Paramètres du mode KRaft
process.roles=broker,controller
node.id=1
controller.quorum.voters=1@localhost:9093
listeners=PLAINTEXT://:9092,CONTROLLER://:9093
advertised.listeners=PLAINTEXT://localhost:9092
log.dirs=/tmp/kraft-combined-logs

Pour le développement local, les valeurs par défaut sont suffisantes. Si vous modifiez log.dirs, assurez-vous que le répertoire existe et est accessible en écriture par votre utilisateur. Une erreur courante consiste à pointer log.dirs vers un chemin inexistant ; Kafka ne démarrera pas avec java.io.FileNotFoundException.

Avant de démarrer Kafka, formatez le répertoire de stockage. Il s’agit d’une action unique pour le mode KRaft :

bin/kafka-storage.sh random-uuid
# Sortie attendue : une chaîne UUID, par exemple "8e0f0e1e-3b1d-4c9a-9b1e-7c3f3d1e0e1e"

Copiez cet UUID et exécutez :

bin/kafka-storage.sh format -t <VOTRE_UUID> -c config/server.properties
# Sortie attendue : Formatting /tmp/kraft-combined-logs with metadata.version 3.6-IV2.

Démarrez maintenant le courtier :

bin/kafka-server-start.sh config/server.properties
# Sortie attendue : un flux de lignes de journal se terminant par "Kafka Server started" et le courtier écoutant sur le port 9092.

Ouvrez un second terminal pour toutes les commandes suivantes ; le premier terminal exécute le courtier au premier plan. Pour arrêter le courtier, appuyez sur Ctrl+C dans le premier terminal.

Un chemin de configuration sécurisé signifie : effectuez une petite modification, redémarrez, observez et vérifiez. Ne modifiez jamais plusieurs paramètres inconnus à la fois, car le débogage devient beaucoup plus difficile.

Vérification et diagnostics

Une fois le courtier en cours d’exécution, vérifiez qu’il accepte les connexions. Créez un topic de test nommé orders avec une partition et une réplique :

bin/kafka-topics.sh --create --topic orders --partitions 1 --replication-factor 1 --bootstrap-server localhost:9092
# Sortie attendue : Created topic orders.

Listez les topics pour confirmer :

bin/kafka-topics.sh --list --bootstrap-server localhost:9092
# Sortie attendue : orders

Décrivez le topic pour voir sa configuration :

bin/kafka-topics.sh --describe --topic orders --bootstrap-server localhost:9092
# Sortie attendue :
# Topic: orders    TopicId: <un-id>    PartitionCount: 1    ReplicationFactor: 1    Configs:
#     Topic: orders    Partition: 0    Leader: 1    Replicas: 1    Isr: 1

Testez maintenant le flux de messages. Démarrez un producteur console et saisissez quelques messages. Chaque ligne devient un message :

bin/kafka-console-producer.sh --topic orders --bootstrap-server localhost:9092
> Commande 1 : 3 grandes pizzas
> Commande 2 : 2 salades
> Commande 3 : 1 tiramisu

Appuyez sur Ctrl+C pour fermer le producteur. Dans un autre terminal, démarrez un consommateur console pour lire tous les messages depuis le début :

bin/kafka-console-consumer.sh --topic orders --from-beginning --bootstrap-server localhost:9092
# Sortie attendue : les trois messages de commande imprimés dans l’ordre

Si le consommateur n’affiche pas les messages, vérifiez les journaux du courtier pour détecter des erreurs, assurez-vous que le producteur et le consommateur utilisent le même nom de topic et confirmez que le courtier est toujours en cours d’exécution.

Pour des diagnostics plus approfondis, examinez les journaux du courtier stockés dans logs/server.log (par rapport à votre répertoire Kafka). Recherchez les lignes contenant ERROR ou WARN. Un courtier sain enregistre périodiquement des messages de pulsation et de traitement des requêtes.

Modes de défaillance et récupération

Comprendre les défaillances courantes vous rend plus rapide dans la récupération. Voici trois modes de défaillance réalistes avec des commandes de récupération spécifiques.

Défaillance 1 : le courtier ne démarre pas en raison d’un stockage formaté manquant

Symptômes : Le courtier se termine immédiatement avec java.lang.IllegalArgumentException: No meta.properties file found in /tmp/kraft-combined-logs.

Récupération : Réexécutez la commande de formatage du stockage avec un nouvel UUID et redémarrez :

bin/kafka-storage.sh random-uuid
# Exemple d’UUID : a1b2c3d4-5678-90ab-cdef-1234567890ab
bin/kafka-storage.sh format -t a1b2c3d4-5678-90ab-cdef-1234567890ab -c config/server.properties
bin/kafka-server-start.sh config/server.properties
# Sortie attendue : le courtier démarre normalement

Défaillance 2 : port déjà utilisé

Symptômes : Le démarrage échoue avec java.net.BindException: Address already in use.

Récupération : Identifiez le processus utilisant le port 9092 et arrêtez-le, ou modifiez le port d’écoute dans server.properties. Pour trouver le processus sous Linux/macOS :

lsof -i :9092
# Sortie attendue : nom du processus et PID, par exemple java 12345 utilisateur
kill 12345  # remplacez par le PID réel

Redémarrez ensuite Kafka.

Défaillance 3 : la création du topic échoue avec « replication factor larger than available brokers »

Symptômes : Vous avez tenté de créer un topic avec --replication-factor 3 mais un seul courtier est en cours d’exécution.

Récupération : Réexécutez la commande de création avec --replication-factor 1 pour un laboratoire à nœud unique, ou démarrez des courtiers supplémentaires. Pour le laboratoire local, utilisez le facteur 1 :

bin/kafka-topics.sh --create --topic orders --partitions 1 --replication-factor 1 --bootstrap-server localhost:9092

Pour chaque défaillance, définissez le signal de succès attendu avant d’agir. Ainsi, vous savez immédiatement si la récupération a fonctionné.

Liste de contrôle des opérations

Utilisez cette liste de contrôle chaque fois que vous installez ou modifiez votre laboratoire Kafka local. Elle garantit que vous observez, modifiez et vérifiez dans un ordre contrôlé.

Exécutez ces étapes dans l’ordre. Si une étape échoue, arrêtez-vous et diagnostiquez avant de continuer. Ne sautez pas les étapes de vérification ; ce sont elles qui distinguent une supposition d’un état connu.

Conclusion

Un laboratoire Kafka local vous offre un terrain de jeu sûr pour apprendre, tester et résoudre les problèmes sans risque de production. En suivant les commandes spécifiques à la version, les principes de configuration sécurisée et les procédures de récupération décrites ici, vous pouvez gagner en confiance dans vos opérations Kafka. L’habitude clé est d’observer avant de modifier, de vérifier après chaque étape et de documenter à l’avance les signaux de défaillance.

Comme prochaine étape, étendez ce laboratoire : créez un topic multi-partitions, exécutez un producteur et un consommateur Java simples à l’aide du client Kafka officiel, ou expérimentez avec Kafka Connect et Schema Registry. Chaque nouveau composant doit être ajouté un par un, avec des contrôles de version et des commandes de vérification consignés dans votre propre runbook. La même discipline qui fonctionne en laboratoire protégera vos systèmes de production le moment venu.