Usare Apache Kafka con Docker

Questa guida mostra passo per passo come eseguire Apache Kafka in ambienti di sviluppo usando Docker e Docker Compose.

Vedremo come:

  • capire il ruolo di Kafka e i vantaggi dell'uso con Docker;
  • avviare rapidamente un cluster minimo con Docker Compose;
  • configurare topic, producer e consumer da linea di comando;
  • organizzare una struttura di progetto riutilizzabile per i tuoi servizi.

Perché usare Kafka con Docker

Apache Kafka è una piattaforma di streaming distribuita pensata per gestire flussi di eventi ad alta velocità. Docker semplifica moltissimo l'esecuzione di Kafka in locale:

  • non devi installare manualmente Java, Kafka e Zookeeper;
  • tutto il cluster è descritto in file di configurazione versionabili (Dockerfile, docker-compose.yml);
  • puoi distruggere e ricreare l'ambiente in pochi secondi;
  • puoi condividere la stessa configurazione con il team.

Prerequisiti

  • Docker installato e in esecuzione;
  • Docker Compose (versione stand-alone o integrata in Docker Desktop);
  • conoscenza di base della riga di comando.

Creare un progetto Kafka con Docker

Crea una cartella per il progetto, ad esempio:

mkdir kafka-docker-demo
cd kafka-docker-demo

All'interno di questa cartella creeremo un file docker-compose.yml che definisce i container necessari.

Docker Compose: esempio di cluster minimo

Di seguito un esempio di configurazione con un broker Kafka e Zookeeper, basato sulle immagini di Bitnami. Crea il file docker-compose.yml con il contenuto seguente: 

version: "3.8"

services:
  zookeeper:
    image: bitnami/zookeeper:latest
    container_name: zookeeper
    environment:
      - ALLOW_ANONYMOUS_LOGIN=yes
    ports:
      - "2181:2181"

  kafka:
    image: bitnami/kafka:latest
    container_name: kafka
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      - KAFKA_BROKER_ID=1
      - KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181
      - KAFKA_LISTENERS=PLAINTEXT://:9092
      - KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092
      - ALLOW_PLAINTEXT_LISTENER=yes

Spiegazione rapida della configurazione

  • zookeeper esegue un server Zookeeper accessibile sulla porta 2181.
  • kafka esegue un singolo broker Kafka.
  • KAFKA_ADVERTISED_LISTENERS indica come il broker si presenta ai client (in questo caso, la tua macchina locale).
  • ALLOW_PLAINTEXT_LISTENER abilita l'uso di connessioni non cifrate, adatte a sviluppo e test.

Avviare Kafka con Docker Compose

Per avviare il cluster, esegui:

docker compose up -d

L'opzione -d manda i container in background. Puoi verificare che tutto sia in esecuzione con: 

docker compose ps

Accedere alla shell del container Kafka

Molti comandi di gestione di Kafka (creazione di topic, producer, consumer) vengono eseguiti all'interno del container. Per aprire una shell: 

docker exec -it kafka /bin/bash

Da qui puoi usare gli script forniti da Kafka, tipicamente sotto /opt/bitnami/kafka/bin nelle immagini Bitnami. Per semplicità, potresti esportare una variabile: 

export KAFKA_BIN=/opt/bitnami/kafka/bin

Creare un topic

Esempio di creazione di un topic chiamato test-topic:

$KAFKA_BIN/kafka-topics.sh \
  --create \
  --topic test-topic \
  --bootstrap-server localhost:9092 \
  --partitions 3 \
  --replication-factor 1

Per verificare che il topic esista:

$KAFKA_BIN/kafka-topics.sh \
  --describe \
  --topic test-topic \
  --bootstrap-server localhost:9092

Inviare messaggi (producer)

Per aprire un producer interattivo sulla riga di comando:

$KAFKA_BIN/kafka-console-producer.sh \
  --topic test-topic \
  --bootstrap-server localhost:9092

Dopo aver eseguito il comando, ogni riga che digiti verrà inviata come messaggio a Kafka sul topic test-topic.

Leggere messaggi (consumer)

In una seconda shell (sempre nel container Kafka), esegui:

$KAFKA_BIN/kafka-console-consumer.sh \
  --topic test-topic \
  --bootstrap-server localhost:9092 \
  --from-beginning

L'opzione --from-beginning indica al consumer di leggere tutti i messaggi presenti sul topic a partire dall'inizio.

Esempio di producer e consumer in un'applicazione

In uno scenario reale, vorrai collegare i tuoi servizi applicativi al broker Kafka in esecuzione nel container. I client si connettono all'indirizzo pubblicato da KAFKA_ADVERTISED_LISTENERS, quindi per uno sviluppo locale sarà tipicamente localhost:9092.

Di seguito un semplice esempio (pseudocodice) di configurazione client in un file JSON di impostazioni: 

{
  "kafka": {
    "bootstrapServers": "localhost:9092",
    "clientId": "example-app",
    "acks": "all",
    "retries": 3
  }
}

Arrestare e ripulire il cluster

Per fermare i container ma mantenere i dati:

docker compose down

Se vuoi eliminare anche i volumi (e quindi i dati persistenti di Kafka e Zookeeper), esegui: 

docker compose down -v

Consigli pratici

  • Mantieni il file docker-compose.yml nel controllo di versione del progetto, insieme alla documentazione su come avviare il cluster.
  • Usa nomi di topic significativi, coerenti tra ambienti (sviluppo, staging, produzione) e documentali chiaramente.
  • Per scenari più avanzati (più broker, sicurezza, monitoraggio), estendi il file Docker Compose aggiungendo nuovi servizi e configurazioni, mantenendo però una variante minimale per lo sviluppo.

Conclusione

Usare Kafka con Docker ti permette di avere un ambiente di messaggistica potente e realistico direttamente sulla tua macchina di sviluppo, senza installazioni complesse. Con pochi comandi puoi creare, distruggere e ricreare un cluster, testare producer e consumer e condividere l'intera configurazione con il resto del team.

A partire dall'esempio mostrato in questa guida puoi costruire configurazioni sempre più complete, aggiungendo più broker, tool di monitoraggio e servizi applicativi che consumano e producono eventi su Kafka.

Torna su