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 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 - найди топик и посмотри сообщения в нём

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.