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 rapida introduzione moderna, poiché Kafka 4.x è completamente privo di ZooKeeper e basato su KRaft di default.

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 potete incollare direttamente nel terminale.

Cos’è Apache Kafka e a cosa serve

Apache Kafka è una piattaforma di streaming di eventi. In termini pratici, lo streaming di eventi significa catturare dati di eventi in tempo reale da varie fonti (database, sensori, applicazioni), memorizzare in modo durevole i flussi risultanti e 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 retrospettiva. 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 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 l’archiviazione di oggetti compatibile con S3, l’architettura PostgreSQL, l’ottimizzazione di Elasticsearch e gli strati di dati nativi per l’IA.

Se state sviluppando su AWS e avete bisogno di un’alternativa gestita, Building Event-Driven Microservices with AWS Kinesis descrive come implementare microservizi guidati dagli eventi con Kinesis Data Streams.

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

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

Ecco alcuni concetti che incontrerai ripetutamente nella CLI:

• Topic organizzano gli eventi. Un topic è multiprodotto e multisottoscrittore, e gli eventi possono essere letti più volte perché i controlli di retention determinano quando i dati vecchi vengono scartati.
• Partizioni frammentano un topic su più broker per la scalabilità; l’ordinamento è garantito per partizione.
• Fattore di replica controlla la tolleranza ai guasti. Gli esempi nella documentazione raccomandano comunemente fattori di replica di 2 o 3 in produzione (una rapida introduzione di sviluppo con un singolo nodo utilizza tipicamente 1).

Installazione di Apache Kafka

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

Prerequisiti da non saltare

Kafka 4.x richiede Java moderno: 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 state installando Kafka specificamente per impararlo, puntate a un JDK supportato come Java 17 o 21. La pagina di supporto Java di Kafka elenca Java 17, 21 e 25 come pienamente supportati, mentre Java 11 è supportato solo per un sottoinsieme di moduli (client e stream).

Installazione dal rilascio binario ufficiale

La rapida introduzione 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 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 vi interessa l’integrità della catena di fornitura, la pagina dei download documenta esplicitamente che potete 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 rapida introduzione mostra come scaricare 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 proposta di miglioramento di 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 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 Unix bin/ .sh.

Avvio di Kafka localmente con KRaft

Se vi chiedete “Ho bisogno di ZooKeeper per eseguire Apache Kafka”, la risposta moderna è no. Kafka 4.0 è il primo rilascio maggiore progettato per funzionare completamente senza ZooKeeper, operando in modalità KRaft di default, il che riduce il sovraccarico operativo per l’uso locale e in produzione.

Avvio di un broker locale a singolo nodo dall’archivio estratto

La rapida introduzione 4.2 di Kafka utilizza tre comandi:

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

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

# Formatta Log Directories (standalone local format)
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 sulle 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 è che la formattazione automatica può nascondere errori, specialmente intorno al log dei metadati, quindi è preferibile una formattazione esplicita.

Cosa state eseguendo in questa rapida introduzione

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

Per i cluster “veri”, i controllori KRaft e i broker sono ruoli separati (process.roles) e i controllori 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 da riga di comando

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

• Gli strumenti comuni si trovano nella directory bin/ della distribuzione.
• Ogni strumento stampa il suo uso completo da 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, è necessario utilizzare --bootstrap-server per interagire con il cluster.

Flag di connessione Kafka che userete costantemente

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

• --bootstrap-server host:port
  Usate questo per le operazioni sui topic, i gruppi di consumatori e la maggior parte dei comandi rivolti al 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 sulle operazioni KRaft mostra entrambi gli stili negli esempi.

Gestione dei topic con kafka-topics.sh

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

• Creare, descrivere e elencare topic (la rapida introduzione mostra --create, --describe, --topic).
• Specificare scala e durabilità 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.
• Aggiungere override per topic al momento della creazione con --config key=value (la documentazione sulla configurazione dei topic mostra esempi concreti).

Un comando di creazione “orientato alla produzione” assomiglia 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

La rapida introduzione utilizza il produttore e il consumatore console perché sono veloci per la convalida e i test “smoke”:

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

Kafka 4.2 include anche miglioramenti di coerenza della 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 mantenete runbook interni, è il momento di aggiornare queste note prima che Kafka 5.0 rimuova i flag deprecati.

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

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

• Elenco gruppi: --list
• Descrivere un gruppo con offset e lag: --describe --group ...
• Descrivere membri e assegnazioni: --members e --verbose
• Eliminare gruppi: --delete
• Reimpostare offset in sicurezza: --reset-offsets

Esempio:

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

Una nota di configurazione per Docker locale e client remoti

Se eseguite Kafka in contenitori o dietro bilanciatori di carico, alla fine incontrerete la necessità di impostare correttamente gli listeners. 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 rapida introduzione che potete eseguire ora

Gli esempi qui sotto sono deliberatamente basati sulla CLI in modo che possiate convalidare una configurazione locale di Kafka prima di scrivere qualsiasi codice dell’applicazione.

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

Questo è il flusso canonico “crea, produci, consuma” dalla rapida introduzione di 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 state 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 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:

This is my first event
This is my second event

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

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

Dovreste vedere le stesse righe stampate.

Perché questo convalida più di “funziona”: la rapida introduzione 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 durabilità è il motivo per cui questo schema di rapida introduzione è la prima cosa che dovreste fare dopo qualsiasi installazione o aggiornamento.

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

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

La rapida introduzione di Kafka 4.2 include una demo minima e locale di Connect utilizzando i connector di fonte e sink per file.

Dalla directory di Kafka, impostate prima il percorso del plug-in del worker per includere il jar del connector di 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 di Connect in modalità standalone con una configurazione di connector sia di fonte 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 connector di fonte legge le righe da test.txt e le produce al topic connect-test.
• Il connector di sink legge da connect-test e scrive in test.sink.txt.

Verifica il file di sink:

more test.sink.txt

Dovreste vedere:

foo
bar

Potete anche verificare il topic 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 del connector) e mostra un ciclo minimo 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

Iniziate con i requisiti ufficiali:

• La rapida introduzione di Kafka 4.2 richiede esplicitamente Java 17+. Se state utilizzando un JDK più vecchio, correggete prima quello.
• In modalità KRaft, la formattazione dello storage è un passaggio esplicito richiesto. Se saltate kafka-storage.sh format, è probabile che vediate errori di avvio o errori di metadati.

Se avete sperimentato e ora volete un punto di partenza pulito, la rapida introduzione di Kafka mostra come eliminare le directory dei dati locali utilizzate 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, convalidate che state 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 nella rete Docker

Se Kafka è in Docker e il vostro strumento client è fuori da Docker (o su un’altra macchina), potrebbe essere necessario un annuncio corretto degli listeners. La documentazione sulla configurazione del broker spiega che advertised.listeners viene utilizzato quando gli indirizzi a cui i client si devono connettere differiscono dagli indirizzi di binding (listeners).

Dove andare dopo la rapida introduzione

Se avete completato gli esempi in questo post, avete già risposto alle ricerche più comuni per i principianti:

• 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 (topic, produttore, consumatore, gruppi)

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

• Leggere l’“Introduzione” di Kafka per modelli mentali più approfonditi su topic, partizioni e replica.
• Esplorare la rapida introduzione di Kafka Streams se volete una prima applicazione di elaborazione (la rapida introduzione di Streams dimostra come eseguire la demo WordCount e ispezionare i risultati con il consumatore console).