Изучаем Apache Kafka с нуля. Урок 1. Установка с Zookeeper

Версии: Apache Kafka 3.9.0, Apache ZooKeeper (встроен в дистрибутив)
Окружение: Ubuntu  24.04 LTS, Java 17
Сложность: начальный уровень

Кто мы и зачем этот курс

Мы — команда bigdataschool.ru. Уже несколько лет мы обучаем инженеров и аналитиков работе с большими данными: Kafka, Spark, Hadoop, Airflow и всем, что окружает современный дата-стек.

За это время через наши курсы прошло немало студентов, и мы заметили одну закономерность: многие начинают изучение Kafka с середины. Читают статьи про консюмеров и продюсеров, смотрят видео про партиции — и всё равно через месяц не могут самостоятельно поднять локальный кластер и объяснить, зачем нужен ZooKeeper.

Этот бесплатный курс — наш ответ на этот пробел. Мы идём с самого начала: от установки одиночного узла до разбора каждой утилиты из каталога bin/. Всё на практике, всё с примерами, всё с объяснением «зачем», а не только «как». Курс рассчитан на тех, кто уже умеет работать в терминале и знает базовые команды Linux.

Примечание: Если в процессе изучения материала у Вас возникнет какой либо вопрос или вы захотите высказать пожелание или комментарий ( вдруг найдете неточность или ошибку) сообщите нам в Телеграм Группу созданную для Изучения Кафки,  мы с удовольствием постараемся ответить на ваш вопрос в свободное время.

Хотите глубже — у нас есть платные продвинутые курсы

Бесплатный курс даёт прочную основу. Если вы хотите продвинуться дальше и работать с Kafka на профессиональном уровне, мы приглашаем на два специализированных курса.

KAFKA: Администрирование кластера Kafka — трёхдневный практический интенсив для администраторов, DevOps-инженеров и дата-инженеров. Вы научитесь разворачивать и настраивать распределённые кластеры Kafka 4.0 в KRaft-режиме, балансировать нагрузку, настраивать мониторинг через Prometheus + Grafana и управлять безопасностью кластера. 24 академических часа плюс 12 часов лабораторных работ.Подробности — на странице курса.

DEVKI: Apache Kafka для инженеров данных — пятидневный интенсив для разработчиков и дата-инженеров. Фокус на коде: Producer/Consumer API на Java и Python, Kafka Streams DSL, ksqlDB, Kafka Connect, Avro-сериализация и Schema Registry. 24 академических часа, реальные кейсы, которые можно применять сразу на работе. Подробности — на странице курса.

Зачем изучать ZooKeeper-режим, если он уже не актуален?

Если вы читаете это в 2026 году, наверняка возникнет вопрос, а зачем начинать с ZooKeeper, если в Kafka 4.0 его поддержка полностью убрана?

Причин несколько.

• Во-первых, огромное количество продуктивных кластеров до сих пор работает на связке Kafka + ZooKeeper.
• Во-вторых, понимание роли ZooKeeper помогает ощутить, какую именно проблему решает внешний координатор. Это делает KRaft-режим, который мы рассмотрим в уроке 2, гораздо понятнее — не как «просто новый способ», а как осознанный архитектурный выбор.

Kafka 3.9.0 — последняя версия ветки 3.x с официальной поддержкой ZooKeeper.

Архитектура за одну минуту

В ZooKeeper-режиме запущено два независимых процесса.

ZooKeeper — распределённый координатор. Он хранит метаданные кластера: список брокеров, конфигурации топиков, информацию о лидерах партиций. По сути это отдельная система с собственной базой данных (znodes), своими логами и конфигурацией.

Kafka-брокер — сам мессенджер. Принимает сообщения от продюсеров, хранит их в партиционированных логах и отдаёт консюмерам. При старте брокер регистрируется в ZooKeeper и с этого момента участвует в жизни кластера.

Для локальной установки оба процесса запускаются на одной машине. Для разработки и обучения этого достаточно.

Что понадобится

• Ubuntu 22.04 или 24.04
• Java 17 (рекомендуется; Java 11 тоже работает, Java 21 поддерживается с Kafka 3.7+)
• Минимум 2 ГБ RAM и 5 ГБ свободного места
• Права sudo

Шаг 1. Установка Java

Проверяем, есть ли уже Java в системе:

java -version

Если команда не найдена или версия ниже 11 — ставим:

sudo apt update
sudo apt install -y openjdk-17-jdk

Проверяем результат:

java -version
# openjdk version "17.x.x" ...

Шаг 2. Загрузка и распаковка Kafka 3.9.0

Скачиваем дистрибутив с официального зеркала Apache:

cd /opt
sudo wget https://downloads.apache.org/kafka/3.9.0/kafka_2.13-3.9.0.tgz

Часть 2.13 в имени файла — версия Scala, под которую собран дистрибутив. На поведение Kafka это не влияет, выбирайте 2.13 как актуальную.

Распаковываем и убираем архив:

sudo tar -xzf kafka_2.13-3.9.0.tgz
sudo mv kafka_2.13-3.9.0 kafka
sudo rm kafka_2.13-3.9.0.tgz

Смотрим структуру:

ls /opt/kafka
# bin/  config/  libs/  licenses/  logs/  site-docs/

Ключевые каталоги:

• bin/ — все утилиты командной строки. С ними мы будем работать начиная с урока 5.
• config/ — конфигурационные файлы брокера и ZooKeeper.
• libs/ — jar-файлы Kafka.
• logs/ — логи процессов, создаётся при первом запуске.

Шаг 3. Настройка ZooKeeper

ZooKeeper идёт вместе с дистрибутивом Kafka — отдельно ничего устанавливать не нужно. Конфиг лежит здесь:

cat /opt/kafka/config/zookeeper.properties

Для локального одиночного запуска дефолтная конфигурация подходит без изменений. Разберём ключевые параметры:

# Куда ZooKeeper пишет своё состояние (snapshot'ы и transaction log)
dataDir=/tmp/zookeeper

# Порт для подключения клиентов (в нашем случае — Kafka-брокера)
clientPort=2181

# Максимальное число подключений с одного IP (0 = без ограничений)
maxClientCnxns=0

# Базовая единица времени ZooKeeper в миллисекундах
tickTime=2000

# Количество тиков для синхронизации фолловеров с лидером при старте
initLimit=10

# Допустимое отставание фолловера от лидера в тиках
syncLimit=5

dataDir=/tmp/zookeeper — данные не переживут перезагрузку системы. Для учёбы нормально, для постоянной работы лучше заменить на /var/lib/zookeeper.

Шаг 4. Настройка Kafka-брокера

nano /opt/kafka/config/server.properties

Основные параметры:

# Уникальный ID брокера в кластере. При одном брокере — всегда 0
broker.id=0

# Адрес и порт, на котором брокер принимает подключения
listeners=PLAINTEXT://:9092

# Адрес, который брокер анонсирует клиентам
# Если оставить закомментированным — берётся из listeners
# advertised.listeners=PLAINTEXT://your-host:9092

# Куда писать данные (партиционированные логи сообщений)
log.dirs=/tmp/kafka-logs

# Количество партиций для новых топиков по умолчанию
num.partitions=1

# Адрес ZooKeeper — здесь брокер регистрируется при старте
zookeeper.connect=localhost:2181

# Таймаут подключения к ZooKeeper в миллисекундах
zookeeper.connection.timeout.ms=18000

# Как долго хранить данные (по умолчанию 7 дней)
log.retention.hours=168

Пока ничего не меняем — дефолты подходят для первого запуска.

Шаг 5. Запуск ZooKeeper

Сначала запускаем ZooKeeper — Kafka не стартует без него:

/opt/kafka/bin/zookeeper-server-start.sh -daemon /opt/kafka/config/zookeeper.properties

Флаг -daemon запускает процесс в фоне. Логи пишутся в /opt/kafka/logs/zookeeper.out.

Проверяем, что ZooKeeper поднялся:

grep "binding to port" /opt/kafka/logs/zookeeper.out
# [INFO] binding to port 0.0.0.0/0.0.0.0:2181

Шаг 6. Запуск Kafka-брокера

/opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

Проверяем в логе:

grep "started" /opt/kafka/logs/server.log | tail -5
# [KafkaServer id=0] started

Убеждаемся, что оба процесса работают:

jps -l | grep -E "Kafka|QuorumPeer"
# 12345 org.apache.zookeeper.server.quorum.QuorumPeerMain
# 12346 kafka.Kafka

jps — утилита JDK для просмотра запущенных Java-процессов. QuorumPeerMain —  это ZooKeeper, kafka.Kafka — брокер.

Шаг 7. Быстрая проверка работы

Мы ещё не разобрали утилиты bin/ подробно — это тема уроков 5-8. Но минимальную проверку сделаем прямо сейчас.

Создаём топик:

/opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 \
  --create \
  --topic test-topic \
  --partitions 1 \
  --replication-factor 1

Created topic test-topic.

Отправляем несколько сообщений (первый терминал):

/opt/kafka/bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 \
  --topic test-topic

После запуска появляется символ >. Вводите текст и нажимайте Enter. Завершить — Ctrl+C.

> Привет, Kafka!
> Это первое сообщение
> Всё работает

Читаем сообщения (второй терминал):

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

Привет, Kafka!
Это первое сообщение
Всё работает

Подробно об этих трёх утилитах — в уроках 6, 7 и 8.

Шаг 8. Корректная остановка

Порядок важен: сначала останавливаем Kafka, потом ZooKeeper. Если сделать наоборот — брокер не успеет завершить работу корректно.

/opt/kafka/bin/kafka-server-stop.sh
/opt/kafka/bin/zookeeper-server-stop.sh

Проверяем:

jps -l | grep -E "Kafka|QuorumPeer"
# Пустой вывод — всё остановлено

Альтернатива: запуск через systemd

Запуск из терминала удобен для экспериментов. Если нужно, чтобы сервисы поднимались автоматически после перезагрузки, используют systemd.

Юнит для ZooKeeper:

sudo nano /etc/systemd/system/zookeeper.service

[Unit]
Description=Apache ZooKeeper
After=network.target

[Service]
Type=simple
User=root
ExecStart=/opt/kafka/bin/zookeeper-server-start.sh /opt/kafka/config/zookeeper.properties
ExecStop=/opt/kafka/bin/zookeeper-server-stop.sh
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Юнит для Kafka:

sudo nano /etc/systemd/system/kafka.service

[Unit]
Description=Apache Kafka
Requires=zookeeper.service
After=zookeeper.service

[Service]
Type=simple
User=root
ExecStart=/opt/kafka/bin/kafka-server-start.sh /opt/kafka/config/server.properties
ExecStop=/opt/kafka/bin/kafka-server-stop.sh
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Включаем и запускаем:

sudo systemctl daemon-reload
sudo systemctl enable zookeeper kafka
sudo systemctl start zookeeper && sudo systemctl start kafka
sudo systemctl status kafka

Что здесь не так для продакшна

Наша установка годится для обучения. В реальных кластерах картина другая:

• ZooKeeper разворачивается отдельным ансамблем из 3 или 5 узлов для отказоустойчивости.
• Данные хранятся не в /tmp, а на выделенных дисках с отдельными точками монтирования.
• advertised.listeners настраивается явно с реальным FQDN брокера.
• Kafka и ZooKeeper изолированы на отдельные машины или контейнеры.
• Новые кластеры разворачиваются сразу в KRaft-режиме — без ZooKeeper.

Именно о KRaft пойдёт речь в следующем уроке.

Что дальше

В уроке 2 устанавливаем Apache Kafka 4.2.0 в режиме KRaft — без ZooKeeper, с контроллером, встроенным прямо в брокер. Разберём, что изменилось архитектурно и почему Apache в итоге отказался от внешнего координатора.

Референсные ссылки

• Apache Kafka 3.9 Documentation — официальная документация по версии 3.9
• KIP-500: Replace ZooKeeper with a Self-Managed Metadata Quorum — оригинальный KIP с обоснованием отказа от ZooKeeper
• Apache ZooKeeper Administrator Guide — руководство администратора ZooKeeper
• Kafka Quickstart — официальный quickstart от Apache