Démarrage rapide d'Apache Kafka - Installation de Kafka 4.2 avec l'interface en ligne de commande et des exemples locaux

Apache Kafka 4.2.0 est la version actuellement prise en charge, et c’est la meilleure base pour un démarrage rapide moderne, car Kafka 4.x est entièrement dépourvu 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, démarrage d’un broker local, prise en main des outils CLI essentiels de Kafka, et conclusion avec deux exemples de bout en bout que vous pouvez copier-coller dans votre terminal.

Ce qu’est Apache Kafka et à quoi il sert

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 regroupe trois capacités principales en une seule plateforme : publier et s’abonner à des flux d’événements, stocker les flux durablement aussi longtemps que nécessaire, et traiter les flux au fur et à 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’analytique de flux.

Pour comprendre où Kafka s’insère dans une infrastructure de données plus large, consultez le pilier Infrastructure de données pour les systèmes IA : stockage d’objets, bases de données, recherche et architecture de données IA, qui couvre le stockage d’objets compatible S3, l’architecture PostgreSQL, l’optimisation Elasticsearch et les couches de données natives à l’IA.

Si vous construisez sur AWS et avez besoin d’une alternative gérée, Construction de microservices événementiels avec AWS Kinesis couvre la mise en œuvre de microservices événementiels avec Kinesis Data Streams.

Pour le traitement de flux avec état avec Kafka, consultez Apache Flink sur K8s et Kafka : PyFlink, Go, opérations et tarification gérée.

Pour les services qui écrivent dans une base de données avant de publier sur Kafka, le motif de boîte de sortie transactionnelle garantit que les événements ne sont jamais perdus entre le commit de la base de données et l’appel de production Kafka.

Sur le plan opérationnel, Kafka est un système distribué de serveurs et de clients communiquant via un protocole TCP haute performance : les 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.

Quelques concepts que vous verrez régulièrement 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 la rétention contrôle quand les anciennes données sont supprimées.
• Les Partitions segmentent un topic entre les brokers pour l’évolutivité ; 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 sur un nœud unique utilise typiquement 1).

Installer Apache Kafka

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

Prérequis à ne pas sauter

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 un JDK pris en charge tel que Java 17 ou 21. La page de support Java de Kafka liste Java 17, 21 et 25 comme entièrement pris en charge, tandis que Java 11 est pris en charge 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 construction 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 tirer 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 Kafka et la proposition d’amélioration Kafka (KIP) pour cette ligne d’images la décrivent comme expérimentale et destinée au développement et aux tests locaux, 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 de bin/.

Démarrer 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 mode KRaft par défaut, ce qui réduit la surcharge opérationnelle pour l’utilisation locale et en production.

Démarrer un broker local à nœud unique depuis l’archive tar extraite

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 broker Kafka
bin/kafka-server-start.sh config/server.properties

Pourquoi l’étape de “formatage” est importante 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. Une raison donnée est que le formatage automatique peut masquer des erreurs, en particulier autour du journal de métadonnées, donc le formatage explicite est préféré.

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

Pour le développement local, Kafka peut fonctionner dans une configuration “combinée” simplifiée (contrôleurs et brokers ensemble). La documentation KRaft de Kafka souligne que les serveurs combinés sont plus simples pour le développement mais non recommandés pour les environnements de déploiement critiques (où vous souhaitez que les contrôleurs soient isolés et évolutifs indépendamment).

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

L’essentiel de la CLI Kafka et principaux paramètres de ligne de commande

Kafka est livré avec beaucoup d’outils CLI sous bin/. Les docs opérationnels officiels mettent l’accent sur deux propriétés utiles :

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

Également important pour Kafka 4.x : les commandes AdminClient n’acceptent plus --zookeeper. La documentation de compatibilité de Kafka note que, depuis 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 host:port
  Utilisez ceci pour les opérations de topic, les groupes de consommateurs et la plupart des commandes orientées broker. C’est le remplacement canonique des flux de travail d’administration basés sur ZooKeeper dans Kafka 4.x.

KRaft introduit des points de terminaison broker vs contrôleur pour certains outils. Par exemple, kafka-features.sh et certaines parties des outils de métadonnées peuvent utiliser des points de terminaison de contrôleur, tandis que de nombreuses opérations d’administration utilisent des points de terminaison de broker. 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 les 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 l’évolutivité et la tolérance aux pannes.
• Ajouter des remplacements par topic au moment de la création avec --config key=value (la documentation de configuration des topics montre des exemples concrets).

Une commande de création “orientée production” ressemble à ceci (cette forme exacte est utilisée dans les docs opérationnels officiels) :

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 du formatteur) au profit de --formatter-property.
• kafka-console-producer déprécie --property (propriétés du lecteur de messages) au profit de --reader-property.

Si vous maintenez des runbooks internes, ces notes méritent d’être mises à jour maintenant, avant que Kafka 5.0 ne supprime les drapeaux dépréciés.

Inspection du retard des consommateurs 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 les offsets et le retard : --describe --group ...
• Décrire les membres et les assignments : --members et --verbose
• Supprimer les groupes : --delete
• Réinitialiser les offsets en toute sécurité : --reset-offsets

Exemple :

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

Une mise en garde de configuration pour Docker local et clients distants

Si vous exécutez Kafka dans des conteneurs ou derrière des chargeurs de charge, vous finirez par avoir besoin de configurer les listeners correctement. Les docs de configuration du broker Kafka expliquent advertised.listeners comme les adresses que les brokers annoncent aux clients et aux autres brokers, 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 pour que vous puissiez valider une configuration Kafka locale avant d’écrire du code d’application.

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

Décrivez-le maintenant (optionnel mais utile quand 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 tourner :

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 brokers 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 la raison pour laquelle ce modèle 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 minimale et locale utilisant les connecteurs source et sink de fichier.

Depuis votre répertoire Kafka, définissez d’abord le chemin du plugin worker pour inclure le jar du connecteur de 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 standalone 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 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 enseigne également où se trouve 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 de “Kafka Quickstart ne démarre pas” se résument à un petit ensemble de causes racines.

Le broker ne démarre pas

Commencez par les exigences officielles :

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

Si vous avez expérimenté et voulez maintenant une page 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 broker tourne

Dans Kafka 4.x, validez que vous utilisez --bootstrap-server (pas --zookeeper). La documentation de compatibilité de Kafka souligne 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 pouvez avoir besoin d’une annonce de listener correcte. Les docs de configuration du broker expliquent que advertised.listeners est utilisé lorsque les adresses à lesquelles 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 initiales les plus courantes :

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

D’ici là, 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).