Первый кластер: запуск и первые команды CLI

Практический урок: от пустого сервера до записи и чтения первого события через стандартные CLI-утилиты Kafka.

kafka CLI — набор консольных утилит (kafka-topics, kafka-console-producer, kafka-console-consumer), которыми создают топики и гоняют сообщения вручную.

Зачем это нужно

Прежде чем писать продюсеров и консьюмеров в коде, полезно «пощупать» Kafka руками. CLI-утилиты идут в комплекте и позволяют создать топик, отправить событие и тут же его прочитать — лучший способ убедиться, что кластер живой и понять модель на практике.

Запуск в режиме KRaft

Современная Kafka (3.x+) умеет работать без ZooKeeper, в режиме KRaft. Для локального знакомства проще всего поднять её в Docker одним сервисом-брокером:

# один брокер Kafka в режиме KRaft через Docker
docker run -d --name kafka -p 9092:9092 \
  -e KAFKA_NODE_ID=1 \
  -e KAFKA_PROCESS_ROLES=broker,controller \
  -e KAFKA_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093 \
  -e KAFKA_CONTROLLER_QUORUM_VOTERS=1@localhost:9093 \
  -e KAFKA_CONTROLLER_LISTENER_NAMES=CONTROLLER \
  apache/kafka:latest

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

# создать топик orders: 3 партиции, 1 реплика (локально брокер один)
kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic orders \
  --partitions 3 --replication-factor 1

# посмотреть список топиков
kafka-topics.sh --bootstrap-server localhost:9092 --list

# подробное описание топика
kafka-topics.sh --bootstrap-server localhost:9092 \
  --describe --topic orders

Вывод --describe:

Topic: orders  PartitionCount: 3  ReplicationFactor: 1
  Partition: 0  Leader: 1  Replicas: 1  Isr: 1
  Partition: 1  Leader: 1  Replicas: 1  Isr: 1
  Partition: 2  Leader: 1  Replicas: 1  Isr: 1

Пишем и читаем

# продюсер: каждая строка из stdin становится событием
kafka-console-producer.sh --bootstrap-server localhost:9092 \
  --topic orders
# вводим строки:
# {"id":1,"sum":100}
# {"id":2,"sum":250}

# консьюмер: читаем с самого начала лога
kafka-console-consumer.sh --bootstrap-server localhost:9092 \
  --topic orders --from-beginning

Вывод консьюмера:

{"id":1,"sum":100}
{"id":2,"sum":250}

Как работает под капотом

Флаг --bootstrap-server указывает на любой брокер кластера: клиент подключается, узнаёт у него полную карту брокеров и партиций и дальше работает напрямую с нужными. --from-beginning заставляет консьюмера читать с оффсета 0, иначе он стартует с конца и видит только новые события. Консьюмер без явной группы получает случайную — поэтому при повторном запуске с --from-beginning он снова читает всё: его сохранённого оффсета ещё нет.

Частые ошибки

• Забыть --from-beginning. Тогда консьюмер ждёт только новые сообщения и «ничего не видит» из уже записанных.
• Неверный --bootstrap-server. Указали недоступный хост/порт — клиент висит на подключении.
• Создать топик с 1 партицией «на потом». Число партиций трудно уменьшить; продумайте его сразу (об этом — в разделе про партиции).

Итоги

• Kafka 3.x поднимается без ZooKeeper в режиме KRaft; локально удобно через Docker.
• kafka-topics создаёт и описывает топики; продюсер и консьюмер из консоли гоняют сообщения.
• --from-beginning читает лог с начала; без него консьюмер видит только новые события.