Szybki start z Apache Kafka – instalacja Kafki 4.2 z CLI i lokalnymi przykładami

Apache Kafka 4.2.0 to obecnie wspierana linia wydań i stanowi najlepszą bazę do nowoczesnego szybkiego startu, ponieważ Kafka 4.x jest w pełni pozbawiona ZooKeepera i domyślnie opiera się na KRaft.

Ten przewodnik to praktyczny, oparty na linii poleceń przewodnik szybkiego startu: instalacja Kafki, uruchomienie lokalnego brokera, nauka podstawowych narzędzi CLI Kafki oraz zakończenie dwoma przykładami end-to-end, które możesz wkleić bezpośrednio do terminala.

Czym jest Apache Kafka i do czego służy

Apache Kafka to platforma do przesyłania zdarzeń (event streaming). W praktyce oznacza to przechwytywanie danych zdarzeń w czasie rzeczywistym ze źródeł (bazy danych, czujniki, aplikacje), trwałe przechowywanie powstałych strumieni oraz ich przetwarzanie lub przekierowywanie w czasie rzeczywistym (lub później).

Kafka łączy w jednej platformie trzy podstawowe możliwości: publikowanie i subskrypcję strumieni zdarzeń, trwałe przechowywanie strumieni przez dowolnie długi czas oraz przetwarzanie strumieni w momencie ich wystąpienia lub w trybie retrospektywnym. To połączenie sprawia, że Kafka jest wykorzystywana do rurociągów danych w czasie rzeczywistym, integracji, komunikacji międzyprocesowej oraz analizy strumieniowej.

W celu uzyskania kontekstu dotyczącego miejsca Kafki w szerszej infrastrukturze danych, zobacz filar Infrastruktura danych dla systemów AI: Magazynowanie obiektowe, bazy danych, wyszukiwanie i architektura danych AI, który obejmuje magazynowanie obiektowe kompatybilne z S3, architekturę PostgreSQL, optymalizację Elasticsearch oraz warstwy danych native dla AI.

Jeśli budujesz systemy w oparciu o AWS i potrzebujesz zarządzanej alternatywy, Budowanie mikroserwisów opartych na zdarzeniach z AWS Kinesis opisuje implementację mikroserwisów opartych na zdarzeniach z wykorzystaniem strumieni danych Kinesis.

W przypadku przetwarzania strumieni z zachowaniem stanu (stateful) z wykorzystaniem Kafki, zobacz Apache Flink na K8s i Kafka: PyFlink, Go, operacje i cennik zarządzany.

Pod względem operacyjnym Kafka to system rozproszony serwerów i klientów komunikujących się za pomocą wysokowydajnego protokołu TCP: brokerzy przechowują i udostępniają dane, a klienci (producenty i konsumenci) zapisują i odczytują zdarzenia, często w dużych skalach i z tolerancją błędów.

Oto kilka pojęć, które spotkasz wielokrotnie w CLI:

• Tematy (Topics) organizują zdarzenia. Temat obsługuje wielu producentów i wielu subskrybentów, a zdarzenia mogą być odczytywane wielokrotnie, ponieważ zasady retencji kontrolują, kiedy stare dane są usuwane.
• Podziały (Partitions) dzielą temat między brokerami dla skalowalności; kolejność jest gwarantowana w ramach każdego podziału.
• Współczynnik replikacji (Replication factor) kontroluje tolerancję błędów. Przykłady w dokumentacji często zalecają współczynniki replikacji 2 lub 3 w produkcji (jedno-węzłowy szybki start deweloperski zazwyczaj używa 1).

Instalacja Apache Kafka

Oficjalny przewodnik szybkiego startu Kafki wykorzystuje wydanie binarne (tarball) lub oficjalny obraz Docker. Oba są poprawne dla dewelopmentu lokalnego.

Wymagania wstępne, których nie należy pomijać

Kafka 4.x wymaga nowoczesnego Java: dla serwera i narzędzi Java 17+ jest bazą dla uruchomienia lokalnego, a Kafka 4.0 usunęła obsługę Java 8.

Jeśli instalujesz Kafkę w celu nauki, celuj w wspieraną JDK, taką jak Java 17 lub 21. Strona wsparcia Java dla Kafki wymienia Java 17, 21 i 25 jako w pełni wspierane, podczas gdy Java 11 jest wspierana tylko dla podzbioru modułów (klienci i strumienie).

Instalacja z oficjalnego wydania binarnego

Oficjalny szybki start dla Kafki 4.2.0 rozpoczyna się od pobrania i rozpakowania dystrybucji binarnej:

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

Uwagi dla zaawansowanych użytkowników:

• “2.13” w nazwie pliku odzwierciedla linię budowy Scala. Dla binariów Kafki 4.x, Scala 2.13 jest główną linią dystrybucji, a Kafka 4.0 usunęła obsługę Scala 2.12.
• Jeśli zależy Ci na integralności łańcucha dostaw, strona pobierania wyraźnie dokumentuje, że możesz zweryfikować pobrania korzystając z opublikowanych procedur Apache i kluczy KEYS.

Instalacja z Docker

Kafka udostępnia również oficjalne obrazy Docker na Docker Hub. Przewodnik szybkiego startu pokazuje, że możesz pobrać i uruchomić Kafkę 4.2.0 w następujący sposób:

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

Istnieje również linia obrazów “natywnych” (opartych na natywnych obrazach GraalVM). Dokumentacja Kafki i propozycja ulepszenia Kafki (KIP) dla tej linii obrazów opisują ją jako eksperymentalną i przeznaczoną dla dewelopmentu lokalnego oraz testów, nie zaś dla środowisk produkcyjnych.

Uwaga dotycząca platformy dla użytkowników Windows

Dystrybucje Kafki zawierają skrypty Windows (pliki wsadowe). Dokumentacja Kafki historycznie odnotowuje, że na Windowsie używasz bin\windows\ i skryptów .bat zamiast skryptów Unix bin/ .sh.

Uruchomienie Kafki lokalnie z KRaft

Jeśli pytasz “Czy potrzebuję ZooKeepera do uruchomienia Apache Kafka”, nowoczesna odpowiedź brzmi nie. Kafka 4.0 to pierwsze duże wydanie zaprojektowane do działania całkowicie bez ZooKeepera, działające domyślnie w trybie KRaft, co zmniejsza nakłady operacyjne dla użytku lokalnego i produkcyjnego.

Uruchomienie lokalnego brokera na jednym węźle z rozpakowanego tarballa

Szybki start Kafki 4.2 używa trzech poleceń:

1. Generowanie UUID klastra
2. Formatowanie katalogów dzienników
3. Uruchomienie serwera

# Generowanie UUID klastra
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Formatowanie katalogów dzienników (format standalone lokalny)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Uruchomienie brokera Kafki
bin/kafka-server-start.sh config/server.properties

Dlaczego krok “formatowania” ma znaczenie w KRaft: Dokumentacja operacji KRaft w Kafce wyjaśnia, że kafka-storage.sh random-uuid generuje ID klastra i że każdy serwer musi być sformatowany za pomocą kafka-storage.sh format. Jednym z podanych uzasadnień jest to, że automatyczne formatowanie może ukrywać błędy, szczególnie wokół dziennika metadanych, więc preferowane jest jawne formatowanie.

Co uruchamiasz w tym przewodniku szybkiego startu

Do celów deweloperskich lokalnych, Kafka może działać w uproszczonym ustawieniu “połączonym” (kontrolery i brokerzy razem). Dokumentacja KRaft w Kafce wskazuje serwery połączone jako prostsze dla dewelopmentu, ale nie zalecane dla krytycznych środowisk wdrożeniowych (gdzie chcesz, aby kontrolery były izolowane i skalowalne niezależnie).

Dla “prawdziwych” klastrów, kontrolery i brokerzy KRaft są oddzielnymi rolami (process.roles), a kontrolery są zazwyczaj wdrażane jako kworum 3 lub 5 węzłów (dostępność zależy od większości węzłów będących aktywnymi).

Podstawy CLI Kafki i główne parametry linii poleceń

Kafka dostarcza wiele narzędzi CLI w katalogu bin/. Oficjalna dokumentacja operacyjna podkreśla dwie użyteczne właściwości:

• Wspólne narzędzia znajdują się w katalogu bin/ dystrybucji.
• Każde narzędzie drukuje pełne użycie linii poleceń, gdy jest uruchomione bez argumentów.

Również ważne dla Kafki 4.x: Polecenia AdminClient nie akceptują już --zookeeper. Dokumentacja kompatybilności Kafki odnotowuje, że począwszy od Kafki 4.0, musisz użyć --bootstrap-server do interakcji z klastrem.

Flagi połączenia Kafką, których będziesz stale używać

Większość narzędzi wymaga punktu wejścia do klastra:

• --bootstrap-server host:port
  Użyj tego do operacji tematów, grup konsumentów i większości poleceń skierowanych do brokera. To kanoniczne zastąpienie dla przepływów pracy administracyjnych opartych na ZooKeeper w Kafce 4.x.

KRaft wprowadza punkty końcowe brokera i kontrolera dla niektórych narzędzi. Na przykład kafka-features.sh i część narzędzi metadanych mogą używać punktów końcowych kontrolera, podczas gdy wiele operacji administracyjnych używa punktów końcowych brokera. Strona operacji KRaft pokazuje oba style w przykładach.

Zarządzanie tematami z kafka-topics.sh

Będziesz używać kafka-topics.sh do podstawowego cyklu życia:

• Tworzenie, opisywanie i listowanie tematów (Szybki start pokazuje --create, --describe, --topic).
• Określanie skali i trwałości poprzez podziały i współczynnik replikacji. Przewodnik operacyjny pokazuje --partitions i --replication-factor oraz wyjaśnia, jak wpływają one na skalowalność i tolerancję błędów.
• Dodawanie nadpisań dla pojedynczych tematów w momencie tworzenia z --config key=value (dokumentacja konfiguracji tematów pokazuje konkretne przykłady).

Dobre, “produkcyjne” polecenie tworzenia wygląda tak (ten dokładny kształt jest używany w oficjalnej dokumentacji operacyjnej):

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

Produkowanie i konsumowanie z klientami konsolowymi

Szybki start używa konsolowego producenta i konsumenta, ponieważ są szybkie do walidacji i testów dymowych:

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

Kafka 4.2 obejmuje również ulepszenia spójności CLI. W notatkach o aktualizacjach:

• kafka-console-producer deprecjonuje --max-partition-memory-bytes i zaleca zamiast tego --batch-size.
• kafka-console-consumer deprecjonuje --property (właściwości formatownika) na rzecz --formatter-property.
• kafka-console-producer deprecjonuje --property (właściwości czytnika wiadomości) na rzecz --reader-property.

Jeśli utrzymujesz wewnętrzne instrukcje (runbooks), te notatki warto zaktualizować teraz, zanim Kafka 5.0 usunie deprecjonowane flagi.

Inspekcja opóźnienia konsumenta z kafka-consumer-groups.sh

Dla systemów w produkcji, “Czy mój konsument nadąża” to codzienne pytanie. Przewodnik operacyjny demonstruje:

• Listowanie grup: --list
• Opis grupy z przesunięciami i opóźnieniem: --describe --group ...
• Opis członków i przypisań: --members i --verbose
• Usuwanie grup: --delete
• Bezpieczne resetowanie przesunięć: --reset-offsets

Przykład:

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

Jedna uwaga dotycząca konfiguracji dla lokalnego Docker i zdalnych klientów

Jeśli uruchamiasz Kafkę w kontenerach lub za balanserami obciążenia, ostatecznie napotkasz potrzebę poprawnego ustawienia nasłuchujących (listeners). Dokumentacja konfiguracji brokera Kafki wyjaśnia advertised.listeners jako adresy, które brokerzy ogłaszają klientom i innym brokerom, szczególnie gdy adres wiązania (bind address) nie jest adresem, którego klienci powinni użyć.

Przykłady szybkiego startu, które możesz uruchomić teraz

Poniższe przykłady są celowo oparte na CLI, abyś mógł zwalidować lokalną konfigurację Kafki przed napisaniem jakiegokolwiek kodu aplikacji.

Przykład: uruchomienie tematu i przesyłanie wiadomości end-to-end

To jest kanoniczny przepływ “stworz, wyprodukuj, skonsumuj” z przewodnika szybkiego startu Kafki 4.2.

Otwórz terminal A i stwórz temat:

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

Teraz opisz go (opcjonalnie, ale użyteczne, gdy uczysz się podziałów i współczynnika replikacji):

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

Otwórz terminal B i uruchom producenta:

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

Wpisz parę linii (każda linia staje się zdarzeniem), a następnie zostaw producenta uruchomionego:

To jest moje pierwsze zdarzenie
To jest moje drugie zdarzenie

Otwórz terminal C i uruchom konsumenta od początku:

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

Powinieneś zobaczyć wydrukowane te same linie.

Dlaczego to waliduje więcej niż “działa”: Szybki start Kafki wyjaśnia, że brokerzy przechowują zdarzenia trwale i że zdarzenia mogą być odczytywane wielokrotnie i przez wielu konsumentów. Ta trwałość jest powodem, dla którego ten wzór szybkiego startu jest pierwszą rzeczą, którą powinieneś zrobić po każdej instalacji lub aktualizacji.

Przykład: uruchomienie prostego rurociągu Kafka Connect od pliku do tematu do pliku

Kafka Connect odpowiada na powtarzające się pytanie “Jak przenosić dane do i z Kafki bez pisania niestandardowych producentów i konsumentów dla wszystkiego”. Przegląd Kafki Connect opisuje go jako narzędzie do skalowalnego, niezawodnego przesyłania strumieni między Kafką a innymi systemami, poprzez łączniki (connectors).

Szybki start Kafki 4.2 zawiera minimalną, lokalną demonstrację Connect z wykorzystaniem łączników źródłowego i docelowego pliku.

Z katalogu Kafki, najpierw ustaw ścieżkę wtyczki pracownika (worker plugin path), aby zawierała dostarczony plik jar łącznika:

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

Stwórz mały plik wejściowy:

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

Uruchom pracownika Connect w trybie standalone z konfiguracją łącznika źródłowego i docelowego:

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

Co powinno się stać (i dlaczego to jest użyteczne):

• Łącznik źródłowy czyta linie z test.txt i produkuje je do tematu connect-test.
• Łącznik docelowy czyta z connect-test i zapisuje do test.sink.txt.

Zweryfikuj plik docelowy:

more test.sink.txt

Powinieneś zobaczyć:

foo
bar

Możesz również zweryfikować temat bezpośrednio:

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

Ten drugi przykład to świetny budowniczew pamięci mięśniowej, ponieważ uczy też, gdzie znajduje się konfiguracja Connect (konfiguracja pracownika plus konfiguracje łączników) i pokazuje minimalną pętlę “pobierz, przechowaj, eksportuj”.

Rozwiązywanie problemów i kolejne kroki

Większość problemów “Szybki start Kafki nie uruchamia się” sprowadza się do małego zestawu przyczyn źródłowych.

Broker nie może się uruchomić

Zacznij od oficjalnych wymagań:

• Szybki start Kafki 4.2 wymaga jawnie Java 17+. Jeśli używasz starszej JDK, napraw to najpierw.
• W trybie KRaft, formatowanie magazynu jest wymaganym, jawnym krokiem. Jeśli pominiesz kafka-storage.sh format, prawdopodobnie zobaczysz błędy startu lub błędy metadanych.

Jeśli eksperymentowałeś i teraz chcesz czystą kartę, Szybki start Kafki pokazuje, jak usunąć lokalne katalogi danych używane w demo:

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

Polecenia CLI zawodzą, mimo że broker działa

W Kafce 4.x, zweryfikuj, że używasz --bootstrap-server (nie --zookeeper). Dokumentacja kompatybilności Kafki jawnie wskazuje usunięcie --zookeeper z poleceń AdminClient począwszy od Kafki 4.0.

Zaskoczenia sieciowe w Docker

Jeśli Kafka jest w Dockerze, a narzędzie klienta jest poza Dockerem (lub na innym komputerze), możesz potrzebować poprawnej reklamy nasłuchujących (listener advertisement). Dokumentacja konfiguracji brokera wyjaśnia, że advertised.listeners jest używane, gdy adresy, do których klienci powinni się łączyć, różnią się od adresów wiązania (listeners).

Gdzie podać po zakończeniu szybkiego startu

Jeśli ukończyłeś przykłady w tym poście, już odpowiedziałeś na najczęstsze pierwsze wyszukiwania:

• do czego służy Kafka (przesyłanie zdarzeń end-to-end)
• jak zainstalować Kafkę lokalnie (tarball lub Docker)
• dlaczego ZooKeeper zniknął i KRaft jest domyślny w 4.x
• które narzędzia CLI są ważne na co dzień (tematy, producent, konsument, grupy)

Stąd, najbardziej wartościowymi kolejnymi krokami są zazwyczaj:

• Przeczytaj “Wstęp” do Kafki dla głębszych modeli mentalnych tematów, podziałów i replikacji.
• Przeglądaj Szybki start Kafka Streams, jeśli chcesz pierwszą aplikację przetwarzającą (Szybki start Streams demonstruje uruchomienie demo WordCount i inspekcję wyników z konsolowym konsumentem).