Kafka в Docker Compose: KRaft без ZooKeeper
Kafka в Docker Compose: KRaft без ZooKeeper
До Kafka 2.8 брокер требовал ZooKeeper для хранения метаданных кластера: какие партиции где живут, кто из брокеров активен, где лидер. Это два процесса, два набора настроек, два набора логов. В 2.8 появился KRaft (Kafka Raft) как early access, в 3.3 он стал готов к production, в 3.5 ZooKeeper объявлен deprecated, а в Kafka 4.0 (2025) ZooKeeper-режим убран полностью. В уроке используется Kafka 4.0 - только KRaft.
KRaft встраивает Raft-консенсус прямо в брокер. Брокер сам ведёт метаданные, сам выбирает лидера. Для локальной разработки это означает один контейнер вместо двух.
Минимальный docker-compose.yml
services:
kafka:
image: confluentinc/cp-kafka:8.0.0 # Confluent Platform 8.0 = Apache Kafka 4.0
hostname: kafka
ports:
- "9092:9092"
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_LISTENERS: INTERNAL://0.0.0.0:29092,EXTERNAL://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT
KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
# ISR (In-Sync Replicas) - реплики, успевающие за лидером; при одном брокере минимум 1
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true"
CLUSTER_ID: "MkU3OEVBNTcwNTJENDM2Qk"
Разберём каждую переменную:
KAFKA_NODE_ID: 1 - уникальный числовой идентификатор узла в кластере. При одном узле всегда 1.
KAFKA_PROCESS_ROLES: broker,controller - узел совмещает роли: broker принимает запросы продюсеров и консьюмеров, controller управляет метаданными. В production-кластере роли разделяют.
KAFKA_LISTENERS - на каких адресах слушать. Клиентских listener-ов два: INTERNAL (порт 29092) для контейнеров в Docker-сети и EXTERNAL (порт 9092) для приложений на хост-машине. CONTROLLER://0.0.0.0:9093 - для внутреннего Raft-протокола между контроллерами.
KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092 - адреса, которые брокер отдаёт клиентам как «сюда подключайся». Клиент сначала идёт на bootstrap-адрес, а дальше работает с тем адресом, который брокер вернул в метаданных для того listener-а, к которому клиент подключился. Поэтому:
- приложение на хост-машине подключается к
localhost:9092(EXTERNAL) и получаетlocalhost:9092; - контейнер (kafka-ui, api) подключается к
kafka:29092(INTERNAL) и получаетkafka:29092.
Если оставить один listener с localhost, контейнер получит в метаданных localhost:9092, то есть адрес самого себя, и не подключится.
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP и KAFKA_INTER_BROKER_LISTENER_NAME - имена INTERNAL/EXTERNAL придуманы нами, поэтому Kafka нужно сказать, что оба работают по PLAINTEXT, и какой из них использовать для связи между брокерами.
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093 - список всех контроллеров кластера. Формат: nodeId@hostname:port. Здесь один контроллер - сам этот узел, по имени kafka внутри Docker-сети.
CLUSTER_ID - уникальный идентификатор кластера в base64. Генерируется один раз командой:
docker run --rm confluentinc/cp-kafka:8.0.0 kafka-storage random-uuid
В примере захардкожен для воспроизводимости. Не меняй его без пересоздания volumes.
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1 - топик __consumer_offsets хранит смещения consumer groups. При одном брокере replication factor должен быть 1, иначе Kafka не создаст этот внутренний топик и consumer groups работать не будут (подробнее - в «Типичных ошибках» ниже).
С Kafka UI для удобной инспекции
В разработке удобно видеть топики, consumer groups и сообщения в веб-интерфейсе:
services:
kafka:
image: confluentinc/cp-kafka:8.0.0 # Confluent Platform 8.0 = Apache Kafka 4.0
hostname: kafka
ports:
- "9092:9092"
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_LISTENERS: INTERNAL://0.0.0.0:29092,EXTERNAL://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT
KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true"
CLUSTER_ID: "MkU3OEVBNTcwNTJENDM2Qk"
healthcheck:
# Брокер готов, когда отвечает на запрос метаданных по своему listener-у
test: ["CMD", "kafka-topics", "--bootstrap-server", "localhost:9092", "--list"]
interval: 10s
timeout: 10s
retries: 10
kafka-ui:
# Поддерживаемый форк provectuslabs/kafka-ui (оригинал не развивается с 2024).
# Конкретный тег вместо latest - чтобы пример воспроизводился.
image: ghcr.io/kafbat/kafka-ui:v1.4.2
ports:
- "8080:8080"
environment:
KAFKA_CLUSTERS_0_NAME: local
KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:29092 # INTERNAL listener
depends_on:
kafka:
condition: service_healthy
Как и у RabbitMQ, depends_on без условия ждёт только запуска контейнера, а не готовности брокера. Healthcheck выше считает Kafka готовой, когда kafka-topics --list получает ответ от брокера, а condition: service_healthy заставляет kafka-ui ждать этого момента.
После docker compose up -d открывай http://localhost:8080 - увидишь все топики, партиции, consumer groups и lag.
Управление топиками
Запустив Kafka, можно работать с топиками через CLI внутри контейнера:
# Создать топик вручную (если KAFKA_AUTO_CREATE_TOPICS_ENABLE=false).
# Если топик уже есть, команда упадёт с TopicExistsException;
# флаг --if-not-exists делает её безопасной для повторного запуска (init-скрипты)
docker compose exec kafka \
kafka-topics --create \
--bootstrap-server localhost:9092 \
--topic lesson-events \
--partitions 3 \
--replication-factor 1
# Список всех топиков
docker compose exec kafka \
kafka-topics --list --bootstrap-server localhost:9092
# Детальная информация: партиции, лидеры, реплики
docker compose exec kafka \
kafka-topics --describe \
--bootstrap-server localhost:9092 \
--topic lesson-events
# Изменить количество партиций (только увеличивать)
docker compose exec kafka \
kafka-topics --alter \
--bootstrap-server localhost:9092 \
--topic lesson-events \
--partitions 6
Вывод --describe выглядит так:
Topic: lesson-events PartitionCount: 3 ReplicationFactor: 1
Topic: lesson-events Partition: 0 Leader: 1 Replicas: 1 Isr: 1
Topic: lesson-events Partition: 1 Leader: 1 Replicas: 1 Isr: 1
Topic: lesson-events Partition: 2 Leader: 1 Replicas: 1 Isr: 1
Leader: 1 - брокер с Node ID 1 является лидером для этой партиции. Isr: 1 - список In-Sync Replicas: реплик, которые не отстают от лидера и могут подхватить партицию, если лидер упадёт (про ISR подробнее в уроке о гарантиях доставки).
Тест через console producer и consumer
Быстрая проверка что всё работает - через встроенные CLI-утилиты:
# Терминал 1: consumer (слушает с начала топика)
docker compose exec kafka \
kafka-console-consumer \
--bootstrap-server localhost:9092 \
--topic lesson-events \
--from-beginning
# Терминал 2: producer (пишем сообщения построчно)
docker compose exec kafka \
kafka-console-producer \
--bootstrap-server localhost:9092 \
--topic lesson-events
# Вводим сообщения:
> {"event":"lesson.completed","userId":42}
> {"event":"lesson.completed","userId":43}
В терминале 1 появятся оба сообщения. Consumer с --from-beginning читает с offset=0 - при каждом запуске увидишь все накопленные сообщения.
Полезные команды для диагностики
# Посмотреть offset consumer group
docker compose exec kafka \
kafka-consumer-groups \
--bootstrap-server localhost:9092 \
--describe \
--group my-service
# Вывод:
# GROUP TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG
# my-service lesson-events 0 42 45 3
# my-service lesson-events 1 38 38 0
# my-service lesson-events 2 51 51 0
# Сбросить offset на начало (для replay)
docker compose exec kafka \
kafka-consumer-groups \
--bootstrap-server localhost:9092 \
--group my-service \
--topic lesson-events \
--reset-offsets \
--to-earliest \
--execute
# Удалить топик
docker compose exec kafka \
kafka-topics --delete \
--bootstrap-server localhost:9092 \
--topic lesson-events
Kafka в общем docker-compose.yml проекта
Если в проекте уже есть PostgreSQL и RabbitMQ, добавляй Kafka в тот же файл:
services:
postgres:
image: postgres:16
environment:
POSTGRES_DB: backendstart
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
ports:
- "5432:5432"
rabbitmq:
image: rabbitmq:4-management
hostname: rabbitmq
ports:
- "5672:5672"
- "15672:15672"
kafka:
image: confluentinc/cp-kafka:8.0.0 # Confluent Platform 8.0 = Apache Kafka 4.0
hostname: kafka
ports:
- "9092:9092"
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_LISTENERS: INTERNAL://0.0.0.0:29092,EXTERNAL://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT
KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true"
CLUSTER_ID: "MkU3OEVBNTcwNTJENDM2Qk"
healthcheck:
# Брокер готов, когда отвечает на запрос метаданных по своему listener-у
test: ["CMD", "kafka-topics", "--bootstrap-server", "localhost:9092", "--list"]
interval: 10s
timeout: 10s
retries: 10
api:
build: .
depends_on:
postgres:
condition: service_started
rabbitmq:
condition: service_started
kafka:
condition: service_healthy
environment:
KAFKA_BROKERS: kafka:29092 # INTERNAL listener: api живёт в Docker-сети
RABBITMQ_URL: amqp://guest:guest@rabbitmq:5672/
DATABASE_URL: postgres://app:secret@postgres:5432/backendstart
Внимание: api-контейнер подключается к kafka:29092, а не к localhost:9092 и не к kafka:9092. По порту 9092 брокер отдал бы в метаданных localhost:9092, и api пытался бы подключиться к самому себе. Именно для этого в compose два клиентских listener-а.
Типичные ошибки
CLUSTER_ID не задан - образ Kafka в KRaft-режиме требует CLUSTER_ID, чтобы отформатировать хранилище. Без него контейнер не стартует и сразу завершается с ошибкой:
ERROR Exiting Kafka due to fatal exception during startup
org.apache.kafka.common.KafkaException: No `meta.properties` or `--cluster-id` was provided
Решение: добавь CLUSTER_ID в переменные, либо сгенерируй uuid через kafka-storage random-uuid.
advertised.listeners указывает не туда - если KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092, то Go-приложение на хост-машине не найдёт хост kafka; если PLAINTEXT://localhost:9092, то не подключатся контейнеры. Клиент подключается к bootstrap, получает адрес партиции-лидера из метаданных - и именно этот адрес используется для реальных запросов. Решение - два listener-а, как в compose выше: EXTERNAL://localhost:9092 для хоста и INTERNAL://kafka:29092 для Docker-сети.
Kafka не стартует после смены CLUSTER_ID - если данные (каталог с meta.properties) сохранились в volume, а CLUSTER_ID поменяли, Kafka откажется стартовать из-за несовпадения cluster.id. Решение: либо верни прежний CLUSTER_ID, либо удали volume вместе с данными. И помни: в compose этого урока volume для /var/lib/kafka/data нет, поэтому данные топиков пропадают при каждом пересоздании контейнера (docker compose down).
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 3 при одном брокере - Kafka не создаст внутренний топик __consumer_offsets, потому что не может удовлетворить replication factor. Решение: при одном брокере все три *REPLICATION_FACTOR и MIN_ISR должны быть 1.
Связанные уроки
- Docker - docker-compose - базовый синтаксис compose-файлов
- Message Brokers - Intro - сравнение RabbitMQ и Kafka, когда что выбирать
- Message Brokers - RabbitMQ compose - запуск RabbitMQ аналогичным способом
Мини-задание
- Запусти
docker compose up -dс конфигом выше и убедись что Kafka стартовала (docker compose logs kafka | grep "Kafka Server started") - Создай топик
lesson-eventsс 3 партициями черезkafka-topics --create - Открой два терминала: в первом запусти console-consumer с
--from-beginning, во втором - console-producer. Отправь 3 сообщения и проверь что они дошли - Выполни
kafka-topics --describeи запиши: кто лидер каждой партиции и что такое ISR - Добавь
kafka-uiв compose и откройhttp://localhost:8080- найди топик и посмотри сообщения в нём