Guida rapida ad Apache Kafka: installazione di Kafka 4.2 con CLI ed esempi locali

Apache Kafka 4.2.0 è la versione supportata attuale e rappresenta la base ideale per una moderna guida introduttiva, poiché Kafka 4.x è completamente privo di ZooKeeper e si basa su KRaft per impostazione predefinita.

Questa guida è un’introduzione pratica orientata alla riga di comando: installazione di Kafka, avvio di un broker locale, apprendimento degli strumenti CLI essenziali di Kafka e conclusione con due esempi end-to-end che puoi copiare direttamente nel tuo terminale.

Cos’è Apache Kafka e a cosa serve

Apache Kafka è una piattaforma di event streaming. In termini pratici, l’event streaming significa catturare dati di eventi in tempo reale da varie sorgenti (database, sensori, applicazioni), memorizzare le stream risultanti in modo duraturo ed elaborarle o instradarle in tempo reale (o in un secondo momento).

Kafka unisce tre capacità fondamentali in un’unica piattaforma: pubblicare e sottoscrivere stream di eventi, memorizzare gli stream in modo duraturo per tutto il tempo necessario ed elaborare gli stream mentre si verificano o in modo retrospettivo. Questa combinazione è il motivo per cui Kafka viene utilizzato per pipeline di dati in tempo reale, integrazione, messaggistica e analisi in streaming.

Per un contesto su dove Kafka si inserisce all’interno di un’infrastruttura dati più ampia, consulta il pilastro Data Infrastructure for AI Systems: Object Storage, Databases, Search & AI Data Architecture, che copre lo storage di oggetti compatibile con S3, l’architettura PostgreSQL, l’ottimizzazione di Elasticsearch e i layer di dati nativi per l’IA.

Se stai sviluppando su AWS e hai bisogno di un’alternativa gestita, Building Event-Driven Microservices with AWS Kinesis illustra l’implementazione di microservizi guidati dagli eventi con Kinesis Data Streams.

Per l’elaborazione di stream con stato (stateful stream processing) con Kafka, consulta Apache Flink on K8s and Kafka: PyFlink, Go, ops, and managed pricing.

Per i servizi che scrivono su un database prima di pubblicare su Kafka, il pattern dell’outbox transazionale garantisce che gli eventi non vengano mai persi tra il commit del database e la chiamata di produzione su Kafka.

Dal punto di vista operativo, Kafka è un sistema distribuito di server e client che comunicano tramite un protocollo TCP ad alte prestazioni: i broker memorizzano e servono i dati; i client (producer e consumer) scrivono e leggono eventi, spesso su larga scala e con tolleranza ai guasti.

Alcuni concetti che incontrerai frequentemente nella CLI:

• I Topic organizzano gli eventi. Un topic è multi-produttore e multi-sottoscrittore, e gli eventi possono essere letti più volte perché la ritenzione controlla quando i dati vecchi vengono scartati.
• Le Partizioni frammentano un topic tra i broker per scalabilità; l’ordinamento è garantito per partizione.
• Il fattore di replica controlla la tolleranza ai guasti. Gli esempi nella documentazione raccomandano comunemente fattori di replica di 2 o 3 in produzione (una guida introduttiva di sviluppo su un singolo nodo utilizza tipicamente 1).

Installa Apache Kafka

La guida introduttiva ufficiale di Kafka utilizza il rilascio binario (tarball) o l’immagine Docker ufficiale. Entrambi sono validi per lo sviluppo locale.

Prerequisiti che non puoi saltare

Kafka 4.x richiede Java moderno: per il server e gli strumenti, Java 17+ è la base minima per l’esecuzione locale, e Kafka 4.0 ha rimosso il supporto per Java 8.

Se stai installando Kafka specificamente per impararlo, punta a un JDK supportato come Java 17 o 21. La pagina di supporto Java di Kafka elenca Java 17, 21 e 25 come completamente supportati, mentre Java 11 è supportato solo per un sottoinsieme di moduli (client e streams).

Installazione dal rilascio binario ufficiale

La guida introduttiva ufficiale per Kafka 4.2.0 inizia con il download e l’estrazione della distribuzione binaria:

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

Note per lettori avanzati:

• Il “2.13” nel nome del file riflette la linea di build Scala. Per i binari di Kafka 4.x, Scala 2.13 è la linea di distribuzione principale, e Kafka 4.0 ha rimosso il supporto per Scala 2.12.
• Se ti interessa l’integrità della catena di fornitura, la pagina dei download documenta esplicitamente che puoi verificare i download utilizzando le procedure e le KEYS pubblicate da Apache.

Installazione con Docker

Kafka fornisce anche immagini Docker ufficiali su Docker Hub. La guida introduttiva mostra come puoi estrarre ed eseguire Kafka 4.2.0 in questo modo:

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

Esiste anche una linea di immagini “native” (basate su immagini native GraalVM). La documentazione di Kafka e la proposta di miglioramento Kafka (KIP) per questa linea di immagini la descrivono come sperimentale e destinata allo sviluppo e al test locale, non alla produzione.

Nota sulla piattaforma per utenti Windows

Le distribuzioni di Kafka includono script Windows (file batch). I documenti di Kafka notano storicamente che su Windows si utilizzano bin\windows\ e script .bat invece degli script Unix bin/ .sh.

Avvia Kafka localmente con KRaft

Se ti stai chiedendo “Ho bisogno di ZooKeeper per eseguire Apache Kafka”, la risposta moderna è no. Kafka 4.0 è il primo rilascio principale progettato per operare completamente senza ZooKeeper, esecuzione in modalità KRaft per impostazione predefinita, il che riduce il sovraccarico operativo per l’uso locale e di produzione.

Avvia un broker locale a nodo singolo dal tarball estratto

La guida introduttiva 4.2 di Kafka utilizza tre comandi:

1. Genera un UUID del cluster
2. Formatta le directory dei log
3. Avvia il server

# Genera un UUID del Cluster
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Formatta le Directory dei Log (formato locale standalone)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Avvia il broker Kafka
bin/kafka-server-start.sh config/server.properties

Perché il passaggio di “formattazione” è importante in KRaft: la documentazione operativa di Kafka KRaft spiega che kafka-storage.sh random-uuid genera l’ID del cluster e che ogni server deve essere formattato con kafka-storage.sh format. Una delle motivazioni fornite è che la formattazione automatica può nascondere errori, specialmente intorno al log dei metadati, quindi la formattazione esplicita è preferita.

Cosa stai eseguendo in questa guida introduttiva

Per lo sviluppo locale, Kafka può essere eseguito in una configurazione semplificata “combinata” (controllori e broker insieme). La documentazione KRaft di Kafka evidenzia i server combinati come più semplici per lo sviluppo ma non raccomandati per ambienti di distribuzione critici (dove si desidera che i controllatori siano isolati e scalabili in modo indipendente).

Per i cluster “reali”, i controllatori KRaft e i broker sono ruoli separati (process.roles), e i controllatori sono tipicamente distribuiti come un quorum di 3 o 5 nodi (la disponibilità dipende dal fatto che la maggioranza sia attiva).

Essenziali della CLI Kafka e principali parametri della riga di comando

Kafka viene fornito con molti strumenti CLI sotto bin/. I documenti operativi ufficiali enfatizzano due proprietà utili:

• Gli strumenti comuni risiedono nella directory bin/ della distribuzione.
• Ogni strumento stampa il suo utilizzo completo della riga di comando quando viene eseguito senza argomenti.

Importante anche per Kafka 4.x: i comandi AdminClient non accettano più --zookeeper. La documentazione sulla compatibilità di Kafka nota che, a partire da Kafka 4.0, devi usare --bootstrap-server per interagire con il cluster.

Flag di connessione Kafka che userai costantemente

La maggior parte degli strumenti ha bisogno di un punto di ingresso al cluster:

• --bootstrap-server host:port
  Usalo per le operazioni sui topic, i gruppi di consumer e la maggior parte dei comandi rivolti ai broker. È il sostituto canonico per i flussi di lavoro amministrativi basati su ZooKeeper in Kafka 4.x.

KRaft introduce endpoint per broker vs controller per alcuni strumenti. Ad esempio, kafka-features.sh e parti degli strumenti per i metadati possono usare endpoint dei controller, mentre molte operazioni amministrative usano endpoint dei broker. La pagina operativa KRaft mostra entrambi gli stili negli esempi.

Gestione dei topic con kafka-topics.sh

Userai kafka-topics.sh per il ciclo di vita principale:

• Crea, descrivi, elenca i topic (la guida introduttiva mostra --create, --describe, --topic).
• Specifica scala e durata tramite partizioni e fattore di replica. La guida operativa mostra --partitions e --replication-factor e spiega come influenzano la scalabilità e la tolleranza ai guasti.
• Aggiungi override per topic al momento della creazione con --config key=value (la documentazione sulla configurazione del topic mostra esempi concreti).

Un buon comando di creazione “orientato alla produzione” è simile a questo (questa forma esatta è usata nei documenti operativi ufficiali):

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

Produzione e consumo con client console

La guida introduttiva usa il producer e il consumer console perché sono veloci per la validazione e i test preliminari (smoke test):

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

Kafka 4.2 include anche miglioramenti di coerenza CLI. Nelle note di aggiornamento:

• kafka-console-producer depreca --max-partition-memory-bytes e raccomanda --batch-size invece.
• kafka-console-consumer depreca --property (proprietà del formatter) a favore di --formatter-property.
• kafka-console-producer depreca --property (proprietà del lettore di messaggi) a favore di --reader-property.

Se mantieni runbook interni, queste note meritano di essere aggiornate ora, prima che Kafka 5.0 rimuova i flag deprecati.

Ispezione del lag dei consumer con kafka-consumer-groups.sh

Per i sistemi reali, “Il mio consumer sta seguendo il ritmo?” è una domanda quotidiana. La guida operativa dimostra:

• Elenco gruppi: --list
• Descrivi un gruppo con offset e lag: --describe --group ...
• Descrivi membri e assegnazioni: --members e --verbose
• Elimina gruppi: --delete
• Resetta offset in modo sicuro: --reset-offsets

Esempio:

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

Una caveat sulla configurazione per Docker locale e client remoti

Se esegui Kafka in contenitori o dietro load balancer, alla fine dovrai impostare correttamente gli listener. I documenti di configurazione del broker di Kafka spiegano che advertised.listeners sono gli indirizzi che i broker annunciano ai client e agli altri broker, particolarmente quando l’indirizzo di binding non è l’indirizzo che i client dovrebbero usare.

Esempi della guida introduttiva che puoi eseguire ora

Gli esempi qui sotto sono deliberatamente basati sulla CLI in modo che tu possa validare un setup Kafka locale prima di scrivere qualsiasi codice applicativo.

Esempio: esegui un topic e trasmetti messaggi end-to-end

Questo è il flusso canonico “crea, produci, consuma” dalla guida introduttiva Kafka 4.2.

Apri il terminale A e crea un topic:

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

Ora descrivilo (opzionale ma utile quando stai imparando le partizioni e il fattore di replica):

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

Apri il terminale B e avvia un producer:

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

Digita un paio di righe (ogni riga diventa un evento), poi lascia il producer in esecuzione:

This is my first event
This is my second event

Apri il terminale C e avvia un consumer dall’inizio:

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

Dovresti vedere le stesse righe stampate.

Perché questo valida più del semplice “funziona”: la guida introduttiva di Kafka spiega che i broker memorizzano gli eventi in modo duraturo e che gli eventi possono essere letti più volte e da più consumer. Questa durabilità è il motivo per cui questo pattern della guida introduttiva è la prima cosa che dovresti fare dopo qualsiasi installazione o aggiornamento.

Esempio: esegui una pipeline Kafka Connect semplice da file a topic a file

Kafka Connect risponde alla domanda ricorrente “Come muovo dati dentro e fuori da Kafka senza scrivere producer e consumer personalizzati per tutto”. La panoramica di Kafka Connect lo descrive come uno strumento per streaming scalabile e affidabile tra Kafka e altri sistemi, tramite connettori.

La guida introduttiva Kafka 4.2 include una demo Connect minima e locale utilizzando i connettori di origine e sink file.

Dalla tua directory Kafka, prima imposta il percorso del plugin del worker per includere il jar del connettore file fornito:

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

Crea un piccolo file di input:

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

Avvia il worker Connect in modalità standalone con sia la configurazione del connettore di origine che di sink:

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

Cosa dovrebbe succedere (e perché è utile):

• Il connettore di origine legge le righe da test.txt e le produce nel topic connect-test.
• Il connettore di sink legge da connect-test e scrive su test.sink.txt.

Verifica il file di sink:

more test.sink.txt

Dovresti vedere:

foo
bar

Puoi anche verificare il topic direttamente:

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

Questo secondo esempio è un ottimo allenatore per la memoria muscolare perché ti insegna anche dove risiede la configurazione di Connect (configurazione del worker più configurazioni dei connettori) e mostra un ciclo minimo di “ingestione, archiviazione, export”.

Risoluzione dei problemi e prossimi passi

La maggior parte dei problemi “Kafka Quickstart non parte” rientra in un piccolo insieme di cause radice.

Il broker non si avvia

Inizia con i requisiti ufficiali:

• La guida introduttiva Kafka 4.2 richiede esplicitamente Java 17+. Se sei su un JDK più vecchio, risolvi prima quello.
• In modalità KRaft, la formattazione dello storage è un passaggio esplicito obbligatorio. Se salti kafka-storage.sh format, è probabile che tu veda fallimenti di avvio o errori di metadati.

Se hai sperimentato e ora vuoi una base pulita, la guida introduttiva di Kafka mostra come eliminare le directory dei dati locali usate nella demo:

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

I comandi CLI falliscono anche se il broker è in esecuzione

In Kafka 4.x, valida che stai usando --bootstrap-server (non --zookeeper). La documentazione sulla compatibilità di Kafka evidenzia esplicitamente la rimozione di --zookeeper dai comandi AdminClient a partire da Kafka 4.0.

Sorprese di rete con Docker

Se Kafka è in Docker e il tuo strumento client è fuori da Docker (o su un’altra macchina), potresti aver bisogno di un annuncio degli listener corretto. I documenti di configurazione del broker spiegano che advertised.listeners è usato quando gli indirizzi a cui i client dovrebbero connettersi differiscono dagli indirizzi di binding (listeners).

Dove andare dopo la guida introduttiva

Se hai completato gli esempi in questo post, hai già risposto alle ricerche iniziali più comuni:

• a cosa serve Kafka (event streaming end-to-end)
• come installare Kafka localmente (tarball o Docker)
• perché ZooKeeper è sparito e KRaft è il predefinito in 4.x
• quali strumenti CLI sono importanti giorno per giorno (topic, producer, consumer, gruppi)

Da qui, i prossimi passi più preziosi sono solitamente:

• Leggi l’“Introduzione” di Kafka per modelli mentali più profondi su topic, partizioni e replica.
• Esplora la guida introduttiva di Kafka Streams se vuoi una prima applicazione di elaborazione (la guida introduttiva di Streams dimostra l’esecuzione della demo WordCount e l’ispezione dei risultati con il consumer console).