Démarrage rapide d'Apache Kafka - Installation de Kafka 4.2 avec CLI et exemples locaux

Apache Kafka 4.2.0 est la ligne de version actuellement supportée, et elle constitue la meilleure base pour un démarrage rapide moderne, car Kafka 4.x est totalement libre de ZooKeeper et construit autour de KRaft par défaut.

Ce guide est un démarrage rapide pratique axé sur la ligne de commande : installation de Kafka, lancement d’un courtier local, apprentissage des outils CLI essentiels de Kafka, et finalisation avec deux exemples complets que vous pouvez coller directement dans votre terminal.

Qu’est-ce qu’Apache Kafka et à quoi sert-il

Apache Kafka est une plateforme de streaming d’événements. En termes pratiques, le streaming d’événements signifie capturer des données d’événements en temps réel depuis des sources (bases de données, capteurs, applications), stocker les flux résultants de manière durable, et les traiter ou les acheminer en temps réel (ou ultérieurement).

Kafka rassemble trois capacités principales au sein d’une seule plateforme : publier et s’abonner à des flux d’événements, stocker ces flux de manière durable aussi longtemps que nécessaire, et traiter les flux à mesure qu’ils se produisent ou de manière rétrospective. C’est ce mélange qui fait que Kafka est utilisé pour les pipelines de données en temps réel, l’intégration, la messagerie et l’analyse de flux.

Pour comprendre où Kafka s’insère dans une infrastructure de données plus large, consultez le pilier Data Infrastructure for AI Systems: Object Storage, Databases, Search & AI Data Architecture, qui couvre le stockage d’objets compatible S3, l’architecture PostgreSQL, l’optimisation Elasticsearch et les couches de données natives pour l’IA.

Si vous construisez sur AWS et avez besoin d’une alternative gérée, Building Event-Driven Microservices with AWS Kinesis couvre l’implémentation de microservices événementiels avec Kinesis Data Streams.

Pour le traitement de flux avec état avec Kafka, consultez Apache Flink on K8s and Kafka: PyFlink, Go, ops, and managed pricing.

Opérationnellement, Kafka est un système distribué de serveurs et clients communiquant via un protocole TCP haute performance : les courtiers (brokers) stockent et servent les données ; les clients (producteurs et consommateurs) écrivent et lisent des événements, souvent à grande échelle et avec une tolérance aux pannes.

Voici quelques concepts que vous verrez à plusieurs reprises dans la CLI :

• Les Topics (sujets) organisent les événements. Un topic est multi-producteur et multi-abonné, et les événements peuvent être lus plusieurs fois car les contrôles de rétention déterminent quand les anciennes données sont éliminées.
• Les Partitions fragmentent un topic sur plusieurs courtiers pour la scalabilité ; l’ordre est garanti par partition.
• Le facteur de réplication contrôle la tolérance aux pannes. Les exemples de documentation recommandent couramment des facteurs de réplication de 2 ou 3 en production (un démarrage rapide de développement à nœud unique utilise généralement 1).

Installation d’Apache Kafka

Le démarrage rapide officiel de Kafka utilise la version binaire (tarball) ou l’image Docker officielle. Les deux sont valides pour le développement local.

Prérequis que vous ne devez pas ignorer

Kafka 4.x nécessite une version moderne de Java : pour le serveur et les outils, Java 17+ est la base pour l’exécution locale, et Kafka 4.0 a supprimé le support de Java 8.

Si vous installez Kafka spécifiquement pour l’apprendre, visez une JDK supportée telle que Java 17 ou 21. La page de support Java de Kafka liste Java 17, 21 et 25 comme entièrement supportés, tandis que Java 11 est supporté uniquement pour un sous-ensemble de modules (clients et streams).

Installation depuis la version binaire officielle

Le démarrage rapide officiel pour Kafka 4.2.0 commence par le téléchargement et l’extraction de la distribution binaire :

tar -xzf kafka_2.13-4.2.0.tgz
cd kafka_2.13-4.2.0

Notes pour les lecteurs avancés :

• Le “2.13” dans le nom de fichier reflète la ligne de build Scala. Pour les binaires Kafka 4.x, Scala 2.13 est la ligne de distribution principale, et Kafka 4.0 a supprimé le support de Scala 2.12.
• Si vous vous souciez de l’intégrité de la chaîne d’approvisionnement, la page de téléchargements documente explicitement que vous pouvez vérifier les téléchargements en utilisant les procédures publiées par Apache et les KEYS.

Installation avec Docker

Kafka fournit également des images Docker officielles sur Docker Hub. Le démarrage rapide montre que vous pouvez récupérer et exécuter Kafka 4.2.0 comme ceci :

docker pull apache/kafka:4.2.0
docker run -p 9092:9092 apache/kafka:4.2.0

Il existe également une ligne d’images “natives” (basée sur l’image native GraalVM). La documentation de Kafka et la proposition d’amélioration Kafka pour cette ligne d’images la décrivent comme expérimentale et destinée au développement local et aux tests, pas à la production.

Note de plateforme pour les utilisateurs Windows

Les distributions Kafka incluent des scripts Windows (fichiers batch). Les docs Kafka notent historiquement que sur Windows, vous utilisez bin\windows\ et les scripts .bat plutôt que les scripts .sh Unix bin/.

Démarrage de Kafka localement avec KRaft

Si vous vous demandez “Ai-je besoin de ZooKeeper pour exécuter Apache Kafka”, la réponse moderne est non. Kafka 4.0 est la première version majeure conçue pour fonctionner entièrement sans ZooKeeper, en s’exécutant en mode KRaft par défaut, ce qui réduit la surcharge opérationnelle pour une utilisation locale et en production.

Démarrer un courtier local à nœud unique à partir du tarball extrait

Le démarrage rapide 4.2 de Kafka utilise trois commandes :

1. Générer un UUID de cluster
2. Formater les répertoires de journaux
3. Démarrer le serveur

# Générer un UUID de Cluster
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Formater les répertoires de journaux (format local autonome)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Démarrer le courtier Kafka
bin/kafka-server-start.sh config/server.properties

Pourquoi l’étape de “format” compte en KRaft : la documentation des opérations KRaft de Kafka explique que kafka-storage.sh random-uuid génère l’ID du cluster et que chaque serveur doit être formaté avec kafka-storage.sh format. L’une des raisons avancées est que le formatage automatique peut masquer des erreurs, en particulier autour du journal de métadonnées, donc un formatage explicite est préférable.

Ce que vous exécutez dans ce démarrage rapide

Pour le développement local, Kafka peut s’exécuter dans une configuration “combinée” simplifiée (contrôleurs et courtiers ensemble). La documentation KRaft de Kafka qualifie les serveurs combinés de plus simples pour le développement, mais non recommandés pour les environnements de déploiement critiques (où vous voulez des contrôleurs isolés et scalables indépendamment).

Pour les clusters “réels”, les contrôleurs et courtiers KRaft sont des rôles séparés (process.roles), et les contrôleurs sont généralement déployés en tant que quorum de 3 ou 5 nœuds (la disponibilité dépend d’une majorité en vie).

Essentiels de la CLI Kafka et principaux paramètres de ligne de commande

Kafka est livré avec beaucoup d’outils CLI sous bin/. La documentation officielle des opérations met l’accent sur deux propriétés utiles :

• Les outils courants se trouvent sous le répertoire bin/ de la distribution.
• Chaque outil affiche son utilisation complète en ligne de commande lorsqu’il est exécuté sans arguments.

Aussi important pour Kafka 4.x : les commandes AdminClient n’acceptent plus --zookeeper. La documentation de compatibilité de Kafka note qu’à partir de Kafka 4.0, vous devez utiliser --bootstrap-server pour interagir avec le cluster.

Drapeaux de connexion Kafka que vous utiliserez constamment

La plupart des outils ont besoin d’un point d’entrée de cluster :

• --bootstrap-server hôte:port
  Utilisez ceci pour les opérations de topic, les groupes de consommateurs et la plupart des commandes orientées courtier. C’est le remplacement canonique des flux de travail administratifs basés sur ZooKeeper dans Kafka 4.x.

KRaft introduit des endpoints courtier vs contrôleur pour certains outils. Par exemple, kafka-features.sh et certaines parties de l’outillage de métadonnées peuvent utiliser des endpoints de contrôleur, tandis que de nombreuses opérations administratives utilisent des endpoints de courtier. La page des opérations KRaft montre les deux styles dans les exemples.

Gestion des topics avec kafka-topics.sh

Vous utiliserez kafka-topics.sh pour le cycle de vie principal :

• Créer, décrire, lister des topics (le démarrage rapide montre --create, --describe, --topic).
• Spécifier l’échelle et la durabilité via les partitions et le facteur de réplication. Le guide des opérations montre --partitions et --replication-factor et explique comment ils affectent la scalabilité et la tolérance aux pannes.
• Ajouter des overrides par topic au moment de la création avec --config clé=valeur (les docs de config de topic montrent des exemples concrets).

Une bonne commande de création “orientée production” ressemble à ceci (cette forme exacte est utilisée dans la documentation officielle des opérations) :

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic my_topic_name \
  --partitions 20 --replication-factor 3 \
  --config x=y

Production et consommation avec les clients console

Le démarrage rapide utilise le producteur et le consommateur console car ils sont rapides pour la validation et les tests de fumée :

• kafka-console-producer.sh --topic ... --bootstrap-server ...
• kafka-console-consumer.sh --topic ... --from-beginning --bootstrap-server ...

Kafka 4.2 inclut également des améliorations de cohérence CLI. Dans les notes de mise à niveau :

• kafka-console-producer déprécie --max-partition-memory-bytes et recommande --batch-size à la place.
• kafka-console-consumer déprécie --property (propriétés de formatteur) en faveur de --formatter-property.
• kafka-console-producer déprécie --property (propriétés de lecteur de message) en faveur de --reader-property.

Si vous maintenez des livres de procédures internes, ces notes valent la peine d’être mises à jour maintenant, avant que Kafka 5.0 ne supprime les drapeaux dépréciés.

Inspection du retard de consommation avec kafka-consumer-groups.sh

Pour les systèmes réels, “Mon consommateur est-il à jour” est une question quotidienne. Le guide des opérations démontre :

• Lister les groupes : --list
• Décrire un groupe avec des décalages (offsets) et le retard : --describe --group ...
• Décrire les membres et les affectations : --members et --verbose
• Supprimer les groupes : --delete
• Réinitialiser les décalages en toute sécurité : --reset-offsets

Exemple :

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

Une caveat de configuration pour Docker local et clients distants

Si vous exécutez Kafka dans des conteneurs ou derrière des équilibres de charge, vous finirez par avoir besoin de configurer correctement les listeners. Les docs de configuration de courtier de Kafka expliquent advertised.listeners comme les adresses que les courtiers annoncent aux clients et aux autres courtiers, en particulier lorsque l’adresse de liaison n’est pas l’adresse que les clients devraient utiliser.

Exemples de démarrage rapide que vous pouvez exécuter maintenant

Les exemples ci-dessous sont délibérément basés sur la CLI afin que vous puissiez valider une configuration Kafka locale avant d’écrire du code applicatif.

Exemple : exécuter un topic et streamer des messages de bout en bout

C’est le flux canonique “créer, produire, consommer” du démarrage rapide Kafka 4.2.

Ouvrez le terminal A et créez un topic :

bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

Maintenant, décrivez-le (optionnel mais utile lorsque vous apprenez les partitions et le facteur de réplication) :

bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

Ouvrez le terminal B et démarrez un producteur :

bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092

Tapez quelques lignes (chaque ligne devient un événement), puis laissez le producteur en cours d’exécution :

This is my first event
This is my second event

Ouvrez le terminal C et démarrez un consommateur depuis le début :

bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

Vous devriez voir les mêmes lignes imprimées.

Pourquoi cela valide plus que “ça marche” : le démarrage rapide de Kafka explique que les courtiers stockent les événements de manière durable et que les événements peuvent être lus plusieurs fois et par plusieurs consommateurs. Cette durabilité est pourquoi ce motif de démarrage rapide est la première chose que vous devriez faire après toute installation ou mise à niveau.

Exemple : exécuter un pipeline Kafka Connect simple de fichier à topic à fichier

Kafka Connect répond à la question récurrente “Comment déplacer des données dans et hors de Kafka sans écrire des producteurs et consommateurs personnalisés pour tout”. La vue d’ensemble de Kafka Connect le décrit comme un outil pour un streaming évolutif et fiable entre Kafka et d’autres systèmes, via des connecteurs.

Le démarrage rapide Kafka 4.2 inclut une démo Connect locale minimale utilisant les connecteurs source et sink fichier.

Depuis votre répertoire Kafka, définissez d’abord le chemin du plugin worker pour inclure le jar du connecteur fichier fourni :

echo "plugin.path=libs/connect-file-4.2.0.jar" >> config/connect-standalone.properties

Créez un petit fichier d’entrée :

echo -e "foo\nbar" > test.txt

Démarrez le worker Connect en mode autonome avec une configuration de connecteur source et sink :

bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/connect-file-source.properties \
  config/connect-file-sink.properties

Ce qui devrait se passer (et pourquoi c’est utile) :

• Le connecteur source lit les lignes de test.txt et les produit vers le topic connect-test.
• Le connecteur sink lit depuis connect-test et écrit dans test.sink.txt.

Vérifiez le fichier sink :

more test.sink.txt

Vous devriez voir :

foo
bar

Vous pouvez également vérifier le topic directement :

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning

Cet deuxième exemple est un excellent constructeur de mémoire musculaire car il vous apprend également où se situe la configuration Connect (config worker plus configs connecteurs) et montre une boucle minimale “ingérer, stocker, exporter”.

Dépannage et prochaines étapes

La plupart des problèmes “Kafka Quickstart ne démarre pas” se ramènent à un petit ensemble de causes racines.

Le courtier échoue à démarrer

Commencez par les exigences officielles :

• Le démarrage rapide Kafka 4.2 exige explicitement Java 17+. Si vous êtes sur une JDK plus ancienne, corrigez cela en premier.
• En mode KRaft, le formatage du stockage est une étape explicite requise. Si vous sautez kafka-storage.sh format, vous verrez probablement des échecs de démarrage ou des erreurs de métadonnées.

Si vous avez expérimenté et voulez maintenant une feuille blanche, le démarrage rapide de Kafka montre comment supprimer les répertoires de données locaux utilisés dans la démo :

rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs

Les commandes CLI échouent même si le courtier est en cours d’exécution

Dans Kafka 4.x, validez que vous utilisez --bootstrap-server (pas --zookeeper). La documentation de compatibilité de Kafka appelle explicitement à la suppression de --zookeeper des commandes AdminClient à partir de Kafka 4.0.

Surprises de réseau Docker

Si Kafka est dans Docker et que votre outil client est en dehors de Docker (ou sur une autre machine), vous aurez peut-être besoin d’une annonce de listener correcte. Les docs de config de courtier expliquent que advertised.listeners est utilisé lorsque les adresses auxquelles les clients doivent se connecter diffèrent des adresses de liaison (listeners).

Où aller après le démarrage rapide

Si vous avez terminé les exemples de cet article, vous avez déjà répondu aux recherches les plus courantes :

• à quoi Kafka sert (streaming d’événements de bout en bout)
• comment installer Kafka localement (tarball ou Docker)
• pourquoi ZooKeeper est parti et KRaft est le défaut dans 4.x
• quels outils CLI comptent au quotidien (topics, producteur, consommateur, groupes)

D’ici, les prochaines étapes les plus valables sont généralement :

• Lire l’“Introduction” de Kafka pour des modèles mentaux plus profonds des topics, partitions et réplication.
• Explorer le démarrage rapide Kafka Streams si vous voulez une première application de traitement (le démarrage rapide Streams démontre l’exécution de la démo WordCount et l’inspection des résultats avec le consommateur console).