Avvio rapido di Apache Kafka: installazione di Kafka 4.2 con CLI ed esempi locali

Apache Kafka 4.2.0 è la versione attualmente supportata e rappresenta la migliore base di partenza per una rapida introduzione moderna, poiché Kafka 4.x è completamente privo di ZooKeeper e si basa di default su KRaft.

Questa guida è una rapida introduzione pratica incentrata sulla 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 incollare nel tuo terminale.

Cos’è Apache Kafka e a cosa serve

Apache Kafka è una piattaforma di streaming di eventi. In termini pratici, lo streaming di eventi significa acquisire dati degli eventi in tempo reale da varie fonti (database, sensori, applicazioni), memorizzare in modo durevole i flussi risultanti ed elaborarli o instradarli in tempo reale (o in un secondo momento).

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

Per un contesto su come Kafka si inserisce in un’infrastruttura dati più ampia, consulta il pilastro Data Infrastructure for AI Systems: Object Storage, Databases, Search & AI Data Architecture, che copre l’archiviazione di oggetti compatibile con S3, l’architettura PostgreSQL, l’ottimizzazione di Elasticsearch e i livelli 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 come implementare microservizi basati su eventi con Kinesis Data Streams.

Operativamente, 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 (produttori e consumatori) scrivono e leggono eventi, spesso su larga scala e con tolleranza ai guasti.

Ecco alcuni concetti che incontrerai ripetutamente nella CLI:

• Argomenti (Topics) organizzano gli eventi. Un argomento è multi-produttore e multi-sottoscrittore, e gli eventi possono essere letti più volte perché le impostazioni di ritenzione controllano quando i dati obsoleti vengono scartati.
• Partizioni (Partitions) frammentano un argomento tra i broker per la scalabilità; l’ordinamento è garantito per partizione.
• Fattore di replicazione controlla la tolleranza ai guasti. Gli esempi nella documentazione consigliano comunemente fattori di replicazione di 2 o 3 in produzione (un Quickstart di sviluppo a nodo singolo utilizza tipicamente 1).

Installazione di Apache Kafka

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

Prerequisiti da non saltare

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

Se stai installando Kafka per impararlo, punta a una JDK supportata come Java 17 o 21. La pagina del 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 stream).

Installazione dal rilascio binario ufficiale

Il Quickstart ufficiale per Kafka 4.2.0 inizia scaricando ed estraendo la distribuzione binaria:

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

Note per i lettori avanzati:

• Il “2.13” nel nome del file riflette la linea di build di Scala. Per i binari 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 approvvigionamento, la pagina dei download documenta esplicitamente che puoi verificare i download utilizzando le procedure e i KEYS pubblicati da Apache.

Installazione con Docker

Kafka fornisce anche immagini Docker ufficiali su Docker Hub. Il Quickstart mostra come prelevare 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 GraalVM native image). La documentazione di Kafka e la Kafka Improvement Proposal per questa linea di immagini la descrivono come sperimentale e destinata allo sviluppo e ai test locali, non alla produzione.

Nota sulla piattaforma per gli utenti Windows

Le distribuzioni di Kafka includono script per Windows (file batch). La documentazione di Kafka nota storicamente che su Windows si utilizzano bin\windows\ e gli script .bat invece degli script .sh Unix in bin/.

Avvio locale di Kafka 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 funzionare interamente senza ZooKeeper, eseguendo in modalità KRaft di default, il che riduce il sovraccarico operativo per l’uso locale e in produzione.

Avvio di un broker locale a nodo singolo dal tarball estratto

Il Quickstart 4.2 di Kafka utilizza tre comandi:

1. Generare un UUID del cluster
2. Formattare i directory dei log
3. Avviare il server

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

# Formatta le directory dei log (formato standalone locale)
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 “format” è importante in KRaft: la documentazione delle operazioni KRaft di Kafka 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 ragioni fornite è che la formattazione automatica può nascondere errori, specialmente intorno al log dei metadati, quindi è preferibile una formattazione esplicita.

Cosa stai eseguendo in questo Quickstart

Per lo sviluppo locale, Kafka può eseguire una configurazione semplificata “combinata” (controller e broker insieme). La documentazione KRaft di Kafka evidenzia che i server combinati sono più semplici per lo sviluppo ma non consigliati per ambienti di deployment critici (dove desideri controller isolati e scalabili indipendentemente).

Per i cluster “veri”, i controller KRaft e i broker sono ruoli separati (process.roles) e i controller sono tipicamente distribuiti come un quorum di 3 o 5 nodi (la disponibilità dipende dalla maggioranza dei nodi attivi).

Elementi essenziali della CLI Kafka e parametri principali della riga di comando

Kafka viene fornito con molti strumenti CLI sotto bin/. La documentazione ufficiale sulle operazioni enfatizza due proprietà utili:

• Gli strumenti comuni risiedono nel 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 utilizzerai costantemente

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

• --bootstrap-server host:port
  Usa questo per le operazioni sugli argomenti, i gruppi di consumatori e la maggior parte dei comandi rivolti ai broker. È la sostituzione canonica per i flussi di lavoro amministrativi basati su ZooKeeper in Kafka 4.x.

KRaft introduce endpoint per broker e controller per alcuni strumenti. Ad esempio, kafka-features.sh e parti degli strumenti di metadati possono utilizzare endpoint del controller, mentre molte operazioni amministrative utilizzano endpoint del broker. La pagina delle operazioni KRaft mostra entrambi gli stili negli esempi.

Gestione degli argomenti con kafka-topics.sh

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

• Creare, descrivere, elencare argomenti (il Quickstart mostra --create, --describe, --topic).
• Specificare scala e durata tramite partizioni e fattore di replicazione. La guida alle operazioni mostra --partitions e --replication-factor e spiega come influenzano scalabilità e tolleranza ai guasti.
• Aggiungere override per argomento al momento della creazione con --config key=value (la documentazione sulla configurazione degli argomenti mostra esempi concreti).

Un buon comando di creazione “orientato alla produzione” è simile a questo (questa forma esatta è utilizzata nella documentazione ufficiale sulle operazioni):

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

Il Quickstart utilizza il produttore e il consumatore console perché sono rapidi per la convalida e i test di fumosità:

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

Kafka 4.2 include anche miglioramenti di consistenza della CLI. Nelle note sull’aggiornamento:

• kafka-console-producer depreca --max-partition-memory-bytes e consiglia --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 un aggiornamento ora, prima che Kafka 5.0 rimuova i flag obsoleti.

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

Per i sistemi reali, “Il mio consumatore sta tenendo il passo?” è una domanda quotidiana. La guida alle operazioni dimostra:

• Elenca i gruppi: --list
• Descrivi un gruppo con offset e lag: --describe --group ...
• Descrivi membri e assegnazioni: --members e --verbose
• Elimina i gruppi: --delete
• Resetta gli offset in sicurezza: --reset-offsets

Esempio:

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

Una nota sulla configurazione per Docker locale e client remoti

Se esegui Kafka in contenitori o dietro load balancer, alla fine dovrai configurare correttamente gli listener. La documentazione sulla configurazione del broker di Kafka spiega advertised.listeners come gli indirizzi che i broker pubblicizzano ai client e agli altri broker, in particolare quando l’indirizzo di binding non è l’indirizzo che i client dovrebbero utilizzare.

Esempi di Quickstart che puoi eseguire ora

Gli esempi sottostanti sono deliberatamente basati sulla CLI in modo da poter convalidare una configurazione locale di Kafka prima di scrivere qualsiasi codice applicativo.

Esempio: esegui un argomento e trasmetti messaggi end to end

Questo è il flusso canonico “crea, produci, consuma” dal Quickstart Kafka 4.2.

Apri il terminale A e crea un argomento:

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

Ora descrivilo (opzionale ma utile quando stai imparando partizioni e fattore di replicazione):

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

Apri il terminale B e avvia un produttore:

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 produttore in esecuzione:

Questo è il mio primo evento
Questo è il mio secondo evento

Apri il terminale C e avvia un consumatore 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”: il Quickstart di Kafka spiega che i broker memorizzano gli eventi in modo durevole e che gli eventi possono essere letti più volte e da più consumatori. Questa durata è il motivo per cui questo modello Quickstart è la prima cosa che dovresti fare dopo qualsiasi installazione o aggiornamento.

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

Kafka Connect risponde alla domanda ricorrente “Come sposto i dati in e fuori da Kafka senza scrivere produttori e consumatori personalizzati per tutto”. L’overview di Kafka Connect lo descrive come uno strumento per lo streaming scalabile e affidabile tra Kafka e altri sistemi, tramite connettori.

Il Quickstart Kafka 4.2 include una demo minimale locale di Connect utilizzando i connettori di origine e destinazione file.

Dal tuo directory di Kafka, imposta prima 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 file di input minuscolo:

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

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

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 nell’argomento connect-test.
• Il connettore di destinazione legge da connect-test e scrive in test.sink.txt.

Verifica il file di destinazione:

more test.sink.txt

Dovresti vedere:

foo
bar

Puoi anche verificare l’argomento direttamente:

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

Questo secondo esempio è un ottimo costruttore di memoria muscolare perché insegna anche dove risiede la configurazione di Connect (configurazione del worker più configurazioni dei connettori) e mostra un loop minimale di “ingestione, memorizzazione, esportazione”.

Risoluzione dei problemi e prossimi passi

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

Il broker non riesce ad avviarsi

Inizia con i requisiti ufficiali:

• Il Quickstart Kafka 4.2 richiede esplicitamente Java 17+. Se stai utilizzando una JDK più vecchia, correggi 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 un punto di partenza pulito, il Quickstart di Kafka mostra come eliminare i directory dei dati locali utilizzati 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, convalida che stai utilizzando --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 Docker

Se Kafka è in Docker e il tuo strumento client è fuori da Docker (o su un’altra macchina), potresti aver bisogno di una corretta pubblicità degli listener. La documentazione sulla configurazione del broker spiega che advertised.listeners viene utilizzato quando gli indirizzi a cui i client dovrebbero connettersi differiscono dagli indirizzi di binding (listeners).

Dove andare dopo il Quickstart

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

• a cosa serve Kafka (streaming di eventi end to end)
• come installare Kafka localmente (tarball o Docker)
• perché ZooKeeper è sparito e KRaft è il default in 4.x
• quali strumenti CLI sono importanti giorno per giorno (argomenti, produttore, consumatore, gruppi)

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

• Leggi l’“Introduzione” di Kafka per modelli mentali più approfonditi su argomenti, partizioni e replicazione.
• Esplora il Quick Start di Kafka Streams se desideri una prima applicazione di elaborazione (il Quickstart di Streams dimostra l’esecuzione della demo WordCount e l’ispezione dei risultati con il consumatore console).