10 
Содержание
Изучаем Apache Kafka с нуля. Урок 5. Утилиты Kafka bin/ — переменные окружения и основы
ПО: Apache Kafka 4.2.0 | Окружение: Ubuntu 22.04 LTS, Java 17 | Уровень: начинающий
В четвёртом уроке мы собрали трёхнодовый Kafka-кластер в Docker Compose. Для проверки его работы запускали команды через docker exec и прописывали полный путь к скриптам внутри контейнера. Это нормально для разового теста, но неудобно в повседневной работе. Самое время разобраться с инструментарием Kafka как следует.
Папка утилит Kafka bin/ — это командный центр всего, что мы будем делать в уроках 6-33. Здесь живут 30+ shell-скриптов для управления топиками, отправки сообщений, мониторинга потребителей, диагностики кластера и многого другого. Каждому из них будет посвящён отдельный урок. Но прежде чем нырять в детали — нужен фундамент.
В этом уроке мы настроим переменную KAFKA_HOME, добавим bin/ в PATH, создадим алиасы для часто используемых команд и разберём принципиальное различие между флагами —bootstrap-server и —bootstrap-controller. Без этих вещей каждый раз придётся вспоминать полный путь к скрипту и думать, к какому порту подключаться. Если хотите разобраться с использованием утилит Kafka bin/ на уровне администратора — посмотрите на курс KAFKA. Администрирование кластера Kafka: там вся работа с утилитами рассматривается в контексте реальных продакшн-задач.
Что живёт в папке Kafka bin/
После распаковки дистрибутива Kafka 4.2.0 папка утилит Kafka bin/ содержит больше 50 файлов. Большинство из них — shell-скрипты-обёртки, которые вызывают Java-классы Kafka. Вот ключевые утилиты, сгруппированные по назначению.
| Группа | Утилита | Что делает |
|---|---|---|
| Жизненный цикл | kafka-server-start.sh | Запускает брокер / контроллер |
| Жизненный цикл | kafka-server-stop.sh | Останавливает брокер / контроллер |
| Жизненный цикл | kafka-storage.sh | Форматирует хранилище KRaft, генерирует cluster.id |
| Топики и данные | kafka-topics.sh | Создаёт, изменяет, удаляет и просматривает топики |
| Топики и данные | kafka-console-producer.sh | Отправляет сообщения в топик из консоли |
| Топики и данные | kafka-console-consumer.sh | Читает сообщения из топика в консоль |
| Потребители и офсеты | kafka-consumer-groups.sh | Управляет группами потребителей и лагом |
| Потребители и офсеты | kafka-get-offsets.sh | Показывает текущие офсеты по партициям |
| Потребители и офсеты | kafka-delete-records.sh | Удаляет записи до указанного офсета |
| Метаданные кластера | kafka-cluster.sh | Показывает cluster.id и базовую информацию |
| Метаданные кластера | kafka-metadata-quorum.sh | Статус KRaft-кворума, список воутеров и наблюдателей |
| Метаданные кластера | kafka-metadata-shell.sh | Интерактивная оболочка для просмотра метаданных |
| Конфигурация и ACL | kafka-configs.sh | Читает и изменяет конфигурацию брокеров и топиков |
| Конфигурация и ACL | kafka-acls.sh | Управляет правами доступа (ACL) |
| Диагностика | kafka-broker-api-versions.sh | Список API-версий, поддерживаемых брокером |
| Диагностика | kafka-log-dirs.sh | Размер и расположение логов по партициям |
| Диагностика | kafka-dump-log.sh | Дамп содержимого файлов логов на диске |
| Производительность | kafka-producer-perf-test.sh | Нагрузочный тест продюсера |
| Производительность | kafka-consumer-perf-test.sh | Нагрузочный тест потребителя |
| Connect / Streams | connect-standalone.sh | Запускает Kafka Connect в standalone-режиме |
| Connect / Streams | connect-distributed.sh | Запускает Kafka Connect в distributed-режиме |
Это не полный список, но именно эти утилиты мы разберём в следующих уроках. Все они запускаются одинаково: скрипт .sh плюс набор флагов. Главное — правильно указать адрес подключения.
Переменная KAFKA_HOME
KAFKA_HOME — это переменная окружения, которая хранит путь к корневой папке дистрибутива Kafka. Сама Kafka не требует её наличия для работы. Она нужна вам — чтобы не писать длинные пути каждый раз.
Предположим, вы распаковали Kafka в /opt/kafka (мы делали это в уроке 2). Добавьте KAFKA_HOME в файл профиля оболочки. Для bash это ~/.bashrc, для zsh — ~/.zshrc.
# Проверено: Apache Kafka 4.2.0, Ubuntu 22.04 echo 'export KAFKA_HOME=/opt/kafka' >> ~/.bashrc source ~/.bashrc
Теперь проверяем, что переменная установлена корректно.
echo $KAFKA_HOME # Ожидаемый вывод: /opt/kafka
С этого момента вместо /opt/kafka/bin/kafka-topics.sh можно писать $KAFKA_HOME/bin/kafka-topics.sh. Уже короче, но всё ещё не очень удобно. Идём дальше.
Добавление bin/ в PATH
PATH — это переменная окружения, которая содержит список директорий, где оболочка ищет исполняемые файлы. Если добавить туда папку утилит Kafka bin/ от Kafka, можно вызывать любую утилиту просто по имени скрипта — без указания полного пути.
# Проверено: Apache Kafka 4.2.0, Ubuntu 22.04 echo 'export PATH=$PATH:$KAFKA_HOME/bin' >> ~/.bashrc source ~/.bashrc
Важно: обе строки — KAFKA_HOME и PATH — должны идти в одном файле, и KAFKA_HOME должен быть объявлен первым. Иначе в строке PATH переменная $KAFKA_HOME будет пустой.
После этого проверяем, что оболочка находит скрипты Kafka.
which kafka-topics.sh # Ожидаемый вывод: /opt/kafka/bin/kafka-topics.sh kafka-topics.sh --version # Ожидаемый вывод: 4.2.0
Если which ничего не вернул — проверьте, что в ~/.bashrc нет опечаток в пути, и выполните source ~/.bashrc повторно.
Алиасы для ежедневной работы
Даже с настроенным PATH некоторые команды остаются длинными. Например, каждый раз добавлять —bootstrap-server localhost:9092 — это лишние 30 символов, ну а когда вы используете не один сервер а несколько да еще с FQDN то 100-200 символов дополнительно. Алиасы решают эту проблему.
Алиас — это псевдоним для любой команды или части команды. Добавьте полезные алиасы в конец ~/.bashrc.
# Проверено: Apache Kafka 4.2.0, Ubuntu 22.04 # Алиасы для Kafka - добавить в ~/.bashrc # Короткий доступ к утилитам (если bin/ уже в PATH, это не нужно, # но удобно для явного указания версии) alias kf='$KAFKA_HOME/bin' # Частые операции с топиками alias ktopics='kafka-topics.sh --bootstrap-server localhost:9092' # Группы потребителей alias kcgroups='kafka-consumer-groups.sh --bootstrap-server localhost:9092' # Быстрая проверка брокера alias kcheck='kafka-broker-api-versions.sh --bootstrap-server localhost:9092'
После добавления выполните source ~/.bashrc. Теперь вместо полной команды можно писать так.
# Список всех топиков - было kafka-topics.sh --bootstrap-server localhost:9092 --list # Список всех топиков - стало ktopics --list
Алиасы работают только в интерактивной оболочке. В скриптах и cron-задачах используйте полные команды — это делает скрипты переносимыми и понятными для других.
—bootstrap-server и —bootstrap-controller
Это один из ключевых вопросов, который возникает у всех, кто начинает работать с утилитами Kafka. Объясняем конкретно и с таблицей.
В архитектуре KRaft каждый узел Kafka слушает два порта. Брокерский порт (по умолчанию 9092) принимает клиентский трафик — сообщения продюсеров, запросы потребителей, административные API. Контроллерный порт (по умолчанию 9093) предназначен для внутренней работы кластера — KRaft-кворума, репликации метаданных.
Флаги для утилит Kafka bin/ отражают эту разницу напрямую.
| Флаг | К чему подключается | Порт (по умолчанию) | Для каких утилит |
|---|---|---|---|
| —bootstrap-server | Broker listener | 9092 | Все клиентские и большинство admin-утилит: kafka-topics.sh, kafka-console-producer.sh, kafka-consumer-groups.sh, kafka-configs.sh, kafka-metadata-quorum.sh и другие |
| —bootstrap-controller | Controller listener | 9093 | Утилиты, которым нужен прямой доступ к контроллеру: kafka-metadata-quorum.sh (режим —describe), kafka-features.sh в некоторых сценариях |
На практике —bootstrap-server localhost:9092 используется в 95% случаев. Флаг —bootstrap-controller localhost:9093 появился в Kafka 3.7+ и нужен только для операций, требующих прямого обращения к контроллеру без прохода через брокер. В остальных ситуациях брокер сам маршрутизирует запрос к нужному контроллеру.
Отдельно важно не путать флаг —bootstrap-controller с параметром конфигурации сервера controller.quorum.voters. Это разные вещи. controller.quorum.voters — это строка в server.properties, которая перечисляет узлы KRaft-кворума. Утилиты bin/ этот параметр напрямую не принимают.
Запуск утилит из Docker-контейнера
Если Kafka у вас работает в Docker (уроки 3-4), ситуация чуть другая. Утилиты bin/ находятся внутри контейнера, а не на хост-машине. Есть три способа с ними работать.
Вариант 1 — docker exec. Запускаем команду внутри запущенного контейнера. Это самый распространённый подход для разовых операций.
# Проверено: Apache Kafka 4.2.0, Docker Compose v2.35 docker exec -it kafka-kraft-single kafka-topics.sh \ --bootstrap-server localhost:9092 \ --list
В официальном образе apache/kafka:4.2.0 папка bin/ уже добавлена в PATH контейнера. Поэтому достаточно писать имя скрипта без полного пути.
Вариант 2 — интерактивная оболочка. Заходим в контейнер и работаем как на обычном хосте.
docker exec -it kafka-kraft-single bash # Внутри контейнера - PATH уже настроен kafka-topics.sh --bootstrap-server localhost:9092 --list
Вариант 3 — установить Kafka на хост отдельно. Скачать дистрибутив Kafka 4.2.0 на хост-машину только для того, чтобы использовать bin/. Контейнер при этом будет работать по-прежнему. Подключение идёт к проброшенному порту хоста.
# Проверено: Apache Kafka 4.2.0, Ubuntu 22.04 (хост), Docker контейнер на localhost:9092 # Kafka установлена на хосте, контейнер работает с проброшенным портом 9092 kafka-topics.sh --bootstrap-server localhost:9092 --list
Третий вариант удобен, если нужно автоматизировать операции на хосте без постоянного использования docker exec. Главное — совпадение версий: клиентские утилиты должны быть той же мажорной версии, что и брокер.
Первая команда — проверяем, что всё работает
Лучший способ убедиться, что окружение настроено правильно — запустить реальную команду. Используем kafka-broker-api-versions.sh: она подключается к брокеру и выводит список поддерживаемых API с версиями. Если команда отработала без ошибок — PATH настроен, порт доступен, брокер отвечает.
# Проверено: Apache Kafka 4.2.0, Ubuntu 22.04 kafka-broker-api-versions.sh --bootstrap-server localhost:9092
В начале вывода увидите примерно следующее.
localhost:9092 (id: 1 rack: null) -> ( Produce(0): 0 to 11 [usable: 11], Fetch(1): 0 to 17 [usable: 17], ListOffsets(2): 0 to 9 [usable: 9], ... )
Здесь id: 1 — это идентификатор брокера, а числа в скобках — диапазон версий API. Это поведение брокера нормально. Подробнее про эту утилиту поговорим в уроке 25.
Если вместо этого видите ошибку Connection refused — брокер не запущен или слушает на другом порту. Если видите ошибку kafka-broker-api-versions.sh: command not found — PATH настроен неверно, проверьте ~/.bashrc и выполните source.
Что дальше
Окружение настроено, первая команда отработала. Теперь начинается самое интересное — разбор конкретных утилит.
В следующем уроке берём kafka-topics.sh: создаём топики, меняем число партиций, выставляем retention и смотрим на внутреннее устройство раздела. Это базовая операция, которую вы будете выполнять постоянно, поэтому урок 6 — один из самых важных в курсе.
Перейти к следующему уроку: Урок 6. kafka-topics.sh — управление топиками
Референсы
- Apache Kafka 4.2.0 Documentation — Quickstart (обновлено 2025)
- Apache Kafka KRaft Mode — официальная документация (обновлено 2025)
- KIP-919: Allow AdminClient to Talk Directly with KRaft Controller (Kafka Wiki, 2024)
- Kafka KRaft mode: What you need to know (Red Hat Developers, 2024)
- apache/kafka — Official Docker Image (Docker Hub, 2025)