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 prise en charge et constitue la meilleure base pour une prise en main rapide moderne, car Kafka 4.x est entièrement indépendant de ZooKeeper et est construit autour de KRaft par défaut.

Ce guide est une prise en main rapide pratique, axée sur la ligne de commande : installation de Kafka, démarrage d’un broker 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 la capture de données d’événements en temps réel depuis des sources (bases de données, capteurs, applications), le stockage durable des flux résultants, et leur traitement ou leur routage en temps réel (ou ultérieurement).

Kafka réunit trois capacités fondamentales dans une seule plateforme : publier et s’abonner à des flux d’événements, stocker durablement ces flux 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 par streaming.

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 d’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 pour l’IA.

Si vous construisez sur AWS et avez besoin d’une alternative gérée, Construction de microservices pilotés par les événements avec AWS Kinesis explique comment implémenter des microservices pilotés par les événements avec Kinesis Data Streams.

Sur le plan opérationnel, Kafka est un système distribué de serveurs et 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.

Voici quelques concepts que vous rencontrerez régulièrement dans la CLI :

• Les Topics 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 supprimées.
• Les Partitions fragmentent un topic sur plusieurs 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 (une prise en main rapide de développement à nœud unique utilise généralement 1).

Installation d’Apache Kafka

La prise en main rapide officielle 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 une exécution locale, et Kafka 4.0 a retiré la prise en charge 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 à partir de la version binaire officielle

La prise en main rapide officielle 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 retiré 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 et clés publiées par Apache.

Installation avec Docker

Kafka fournit également des images Docker officielles sur Docker Hub. La prise en main 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 les images natives GraalVM). La documentation de Kafka et la proposition d’amélioration de 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). La documentation de Kafka note historiquement que sur Windows, vous utilisez bin\windows\ et les scripts .bat plutôt que les scripts Unix bin/ .sh.

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 exécutant le mode KRaft par défaut, ce qui réduit la surcharge opérationnelle pour une utilisation locale et en production.

Démarrage d’un broker local à nœud unique à partir du tarball extrait

La prise en main 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 standalone)
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 dans 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. Un des arguments avancés est que le formatage automatique peut masquer des erreurs, en particulier autour du journal des métadonnées, donc un formatage explicite est préférable.

Ce que vous exécutez dans cette prise en main rapide

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

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 d’une majorité de nœuds vivants).

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

Kafka est livré avec beaucoup d’outils CLI sous bin/. La documentation opérationnelle officielle met en avant deux propriétés utiles :

• Les outils courants résident sous le répertoire bin/ de la distribution.
• Chaque outil affiche son utilisation complète de 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, dès 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 tournées vers le broker. C’est le remplacement canonique des workflows 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 de l’outillage de métadonnées peuvent utiliser des points de terminaison contrôleur, tandis que de nombreuses opérations d’administration utilisent des points de terminaison broker. La page des opérations KRaft montre les deux styles dans des exemples.

Gestion de topics avec kafka-topics.sh

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

• Créer, décrire, lister des topics (la prise en main rapide montre --create, --describe, --topic).
• Spécifier l’échelle et la durabilité via les partitions et le facteur de réplication. Le guide opérationnel montre --partitions et --replication-factor et explique comment ils affectent l’évolutivité et la tolérance aux pannes.
• Ajouter des reconfigurations par topic lors de la création avec --config key=value (la doc de configuration de topic montre des exemples concrets).

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

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

La prise en main 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 messages) en faveur 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 décalage de consommation avec kafka-consumer-groups.sh

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

• Lister les groupes : --list
• Décrire un groupe avec des offsets et un décalage : --describe --group ...
• Décrire les membres et les attributions : --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 équilibres de charge, vous finirez par devoir définir correctement les listeners. La documentation de configuration des brokers Kafka explique advertised.listeners comme les adresses que les brokers annoncent aux clients et autres brokers, en particulier lorsque l’adresse de liaison n’est pas l’adresse que les clients devraient utiliser.

Exemples de prise en main 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 d’application.

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

C’est le flux canonique “créer, produire, consommer” de la prise en main 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 :

Ceci est mon premier événement
Ceci est mon deuxième événement

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” : la prise en main 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 pourquoi ce schéma de prise en main 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 vers topic vers fichier

Kafka Connect répond à la question récurrente “Comment puis-je déplacer des données vers et depuis Kafka sans écrire des producteurs et consommateurs personnalisés pour tout”. L’aperçu de Kafka Connect le décrit comme un outil pour un streaming scalable et fiable entre Kafka et d’autres systèmes, via des connecteurs.

La prise en main rapide Kafka 4.2 inclut une démo Connect locale minimale utilisant les connecteurs de source et de 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 fichier d’entrée minuscule :

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 produire (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 enseigne également où se situe la configuration Connect (config worker + configs connecteurs) et montre une boucle minimale “ingestion, stockage, exportation”.

Dépannage et prochaines étapes

La plupart des problèmes “Kafka Quickstart ne démarre pas” tombent dans un petit ensemble de causes racines.

Le broker échoue au démarrage

Commencez par les exigences officielles :

• La prise en main rapide Kafka 4.2 requiert 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 verrez probablement des échecs de démarrage ou des erreurs de métadonnées.

Si vous avez expérimenté et voulez maintenant une page blanche, la prise en main 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 est en cours d’exécution

Dans Kafka 4.x, vérifiez que vous utilisez --bootstrap-server (et non --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 pouvez avoir besoin d’une annonce de listener correcte. La documentation de configuration du broker explique 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 la prise en main rapide

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

• à quoi sert Kafka (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 en 4.x
• quels outils CLI comptent au quotidien (topics, producteur, consommateur, groupes)

D’ici là, les prochaines étapes les plus utiles sont généralement :

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