Быстрый старт Apache Kafka — установка Kafka 4.2 с помощью CLI и локальные примеры

Apache Kafka 4.2.0 — это текущая поддерживаемая ветка релизов, и она является лучшей отправной точкой для современного быстрого старта, поскольку Kafka 4.x полностью работает без ZooKeeper и по умолчанию построена вокруг KRaft.

Это руководство представляет собой практический быстрый старт, ориентированный на командную строку: установка Kafka, запуск локального брокера, изучение основных инструментов командной строки Kafka и завершение двумя примерами сквозного тестирования, которые можно сразу вставить в терминал.

Что такое Apache Kafka и для чего она используется

Apache Kafka — это платформа потоковой передачи событий. В практическом смысле потоковая передача событий означает захват данных событий в реальном времени из различных источников (баз данных, датчиков, приложений), надежное хранение результирующих потоков и их обработку или маршрутизацию в реальном времени (или с задержкой).

Kafka объединяет три ключевые возможности в одной платформе: публикация и подписка на потоки событий, надежное хранение потоков столько, сколько это необходимо, и обработка потоков по мере их возникновения или задним числом. Именно это сочетание делает Kafka популярной для использования в конвейерах данных реального времени, интеграции, обмена сообщениями и аналитике потоков данных.

Для понимания места Kafka в более широкой инфраструктуре данных см. раздел Инфраструктура данных для систем ИИ: объектное хранилище, базы данных, поиск и архитектура данных ИИ, который охватывает объектное хранилище, совместимое с S3, архитектуру PostgreSQL, оптимизацию Elasticsearch и уровни данных, созданные специально для ИИ.

Если вы разрабатываете решения на базе AWS и вам нужен управляемый альтернативный сервис, статья Построение микросервисов, ориентированных на события, с использованием AWS Kinesis, посвящена реализации микросервисов с использованием Kinesis Data Streams.

Для обработки потоков с сохранением состояния на базе Kafka см. руководство Apache Flink на K8s и Kafka: PyFlink, Go, операции и цены на управляемые сервисы.

Для сервисов, которые записывают данные в базу данных перед отправкой в Kafka, паттерн транзакционного ящика отправки гарантирует, что события не будут потеряны между фиксацией транзакции в базе данных и вызовом отправки в Kafka.

С операционной точки зрения Kafka — это распределенная система серверов и клиентов, взаимодействующих через высокопроизводительный протокол TCP: брокеры хранят и обслуживают данные; клиенты (продюсеры и консьюмеры) записывают и читают события, часто в больших масштабах и с обеспечением отказоустойчивости.

Несколько понятий, которые вы будете встречать постоянно в командной строке:

• Топики организуют события. Топик поддерживает многопродюсерную и многослушательскую модель, а события можно читать многократно, поскольку срок хранения определяет, когда старые данные удаляются.
• Партиции (разделы) распределяют топик между брокерами для масштабируемости; порядок гарантируется в пределах каждой партиции.
• Фактор репликации определяет отказоустойчивость. В документации примеры обычно рекомендуют фактор репликации 2 или 3 для производственных сред (в одноузловом локальном быстром старте обычно используется 1).

Установка Apache Kafka

Официальный быстрый старт Kafka использует бинарный релиз (архив tarball) или официальный образ Docker. Оба варианта подходят для локальной разработки.

Предварительные требования, которые не следует пропускать

Kafka 4.x требует современной версии Java: для сервера и инструментов базовым требованием для локального запуска является Java 17+, а в Kafka 4.0 поддержка Java 8 была удалена.

Если вы устанавливаете Kafka специально для изучения, стремитесь к использованию поддерживаемой версии JDK, такой как Java 17 или 21. На странице поддержки Java для Kafka указано, что полностью поддерживаются Java 17, 21 и 25, в то время как Java 11 поддерживается только для подмножества модулей (клиенты и потоки).

Установка из официального бинарного релиза

Официальный быстрый старт для Kafka 4.2.0 начинается с загрузки и распаковки бинарного дистрибутива:

tar -xzf kafka_2.13-4.2.0.tgz
cd kafka_2.13-4.2.0

Примечания для продвинутых читателей:

• “2.13” в имени файла отражает версию Scala, использованную при сборке. Для бинарных файлов Kafka 4.x основной линией дистрибутива является Scala 2.13, а поддержка Scala 2.12 была удалена в Kafka 4.0.
• Если вам важна целостность цепочки поставок, на странице загрузки явно указано, что вы можете проверять загрузки с использованием опубликованных процедур Apache и KEYS.

Установка с помощью Docker

Kafka также предоставляет официальные образы Docker на Docker Hub. В быстром старте показано, как можно получить и запустить Kafka 4.2.0 следующим образом:

docker pull apache/kafka:4.2.0
docker run -p 9092:9092 apache/kafka:4.2.0

Также существует линия образов “native” (на базе нативных образов GraalVM). Документация Kafka и предложение по улучшению Kafka (KIP) для этой линии образов описывают их как экспериментальные, предназначенные для локальной разработки и тестирования, а не для производственных сред.

Примечание по платформе для пользователей Windows

Дистрибутивы Kafka включают скрипты для Windows (пакетные файлы). В документации Kafka исторически отмечалось, что в Windows следует использовать скрипты bin\windows\ и .bat вместо Unix-скриптов bin/ .sh.

Запуск Kafka локально с KRaft

Если вы задаетесь вопросом: “Нужен ли мне ZooKeeper для запуска Apache Kafka?”, современный ответ — нет. Kafka 4.0 — это первый крупный релиз, разработанный для работы полностью без ZooKeeper, работающий в режиме KRaft по умолчанию, что снижает операционные накладные расходы как для локального, так и для производственного использования.

Запуск локального брокера на одном узле из распакованного архива

Быстрый старт Kafka 4.2 использует три команды:

1. Генерация UUID кластера
2. Форматирование каталогов журналов
3. Запуск сервера

# Генерация UUID кластера
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Форматирование каталогов журналов (локальный автономный формат)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Запуск брокера Kafka
bin/kafka-server-start.sh config/server.properties

Почему шаг “форматирования” важен в KRaft: документация по операциям KRaft в Kafka объясняет, что kafka-storage.sh random-uuid генерирует идентификатор кластера и что каждый сервер должен быть отформатирован с помощью kafka-storage.sh format. Одним из аргументов в пользу этого является то, что автоматическое форматирование может скрывать ошибки, особенно связанные с журналом метаданных, поэтому предпочтительным является явное форматирование.

Что вы запускаете в этом быстром старте

Для локальной разработки Kafka может работать в упрощенной “комбинированной” настройке (контроллеры и брокеры объединены). В документации KRaft Kafka отмечается, что комбинированные серверы проще для разработки, но не рекомендуются для критически важных сред развертывания (где контроллеры должны быть изолированы и масштабироваться независимо).

В “реальных” кластерах контроллеры KRaft и брокеры являются отдельными ролями (process.roles), и контроллеры обычно развертываются в виде кворума из 3 или 5 узлов (доступность зависит от того, что большинство узлов живо).

Основы CLI Kafka и основные параметры командной строки

Kafka поставляется с большим количеством инструментов командной строки в директории bin/. Официальная документация по операциям подчеркивает два полезных свойства:

• Общие инструменты находятся в директории bin/ дистрибутива.
• Каждый инструмент выводит полное описание использования командной строки при запуске без аргументов.

Также важно для Kafka 4.x: команды AdminClient больше не принимают --zookeeper. В документации по совместимости Kafka отмечается, что начиная с Kafka 4.0, для взаимодействия с кластером необходимо использовать --bootstrap-server.

Флаги подключения Kafka, которые вы будете использовать постоянно

Большинству инструментов нужна точка входа в кластер:

• --bootstrap-server host:port
  Используйте это для операций с топиками, группами потребителей и большинства команд, обращенных к брокеру. Это каноничная замена для рабочих процессов администрирования на базе ZooKeeper в Kafka 4.x.

KRaft вводит различие между конечными точками брокера и контроллера для некоторых инструментов. Например, kafka-features.sh и части инструментов метаданных могут использовать конечные точки контроллера, в то время как многие административные операции используют конечные точки брокера. На странице операций KRaft показаны оба стиля в примерах.

Управление топиками с помощью kafka-topics.sh

Вы будете использовать kafka-topics.sh для основного жизненного цикла:

• Создание, описание, перечисление топиков (в быстром старте показаны --create, --describe, --topic).
• Задание масштаба и надежности через партиции и фактор репликации. В руководстве по операциям показаны --partitions и --replication-factor и объясняется, как они влияют на масштабируемость и отказоустойчивость.
• Добавление переопределений для конкретного топика при создании с помощью --config key=value (в документации по конфигурации топиков приведены конкретные примеры).

Хорошая команда создания, ориентированная на производство, выглядит следующим образом (эта точная форма используется в официальной документации по операциям):

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic my_topic_name \
  --partitions 20 --replication-factor 3 \
  --config x=y

Производство и потребление с помощью консольных клиентов

В быстром старте используются консольный продюсер и консьюмер, так как они быстры для валидации и дымовых тестов:

• kafka-console-producer.sh --topic ... --bootstrap-server ...
• kafka-console-consumer.sh --topic ... --from-beginning --bootstrap-server ...

Kafka 4.2 также включает улучшения согласованности CLI. В заметках об обновлении:

• kafka-console-producer устаревает --max-partition-memory-bytes и рекомендует использовать --batch-size.
• kafka-console-consumer устаревает --property (свойства форматтера) в пользу --formatter-property.
• kafka-console-producer устаревает --property (свойства считывателя сообщений) в пользу --reader-property.

Если вы поддерживаете внутренние руководства по эксплуатации, эти заметки стоит обновить сейчас, прежде чем Kafka 5.0 удалит устаревшие флаги.

Проверка отставания потребителей с помощью kafka-consumer-groups.sh

Для реальных систем вопрос “Успевает ли мой потребитель?” является ежедневным. Руководство по операциям демонстрирует:

• Перечисление групп: --list
• Описание группы с смещениями и отставанием: --describe --group ...
• Описание участников и назначений: --members и --verbose
• Удаление групп: --delete
• Безопасный сброс смещений: --reset-offsets

Пример:

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

Одна оговорка по конфигурации для локального Docker и удаленных клиентов

Если вы запускаете Kafka в контейнерах или за балансировщиками нагрузки, вам рано или поздно понадобится правильно настроить слушатели. В документации по конфигурации брокера Kafka объясняется, что advertised.listeners — это адреса, которые брокеры рекламируют клиентам и другим брокерам, особенно когда адрес привязки не является адресом, который должны использовать клиенты.

Примеры быстрого старта, которые вы можете запустить прямо сейчас

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

Пример: запуск топика и сквозная передача сообщений

Это каноничный поток “создать, произвести, потреблять” из быстрого старта Kafka 4.2.

Откройте терминал A и создайте топик:

bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

Теперь опишите его (необязательно, но полезно, когда вы изучаете партиции и фактор репликации):

bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

Откройте терминал B и запустите продюсера:

bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092

Введите несколько строк (каждая строка становится событием), затем оставьте продюсера запущенным:

Это мое первое событие
Это мое второе событие

Откройте терминал C и запустите консьюмера с начала:

bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

Вы должны увидеть те же строки, что и напечатанные ранее.

Почему это валидирует больше, чем просто “работает”: В быстром старте Kafka объясняется, что брокеры надежно хранят события и что события могут быть прочитаны многократно и несколькими потребителями. Эта надежность — причина того, почему этот шаблон быстрого старта является первым делом, которое вы должны сделать после любой установки или обновления.

Пример: запуск простого конвейера Kafka Connect из файла в топик и обратно в файл

Kafka Connect отвечает на часто задаваемый вопрос: “Как перемещать данные в Kafka и из нее, не написав кастомных продюсеров и консьюмеров для всего”. В обзоре Kafka Connect описывается как инструмент для масштабируемой и надежной потоковой передачи между Kafka и другими системами через коннекторы.

Быстрый старт Kafka 4.2 включает минимальную локальную демонстрацию Connect с использованием коннекторов источника и стока для файлов.

Из вашей директории Kafka сначала установите путь плагина воркера, включив предоставленный jar-файл коннектора файлов:

echo "plugin.path=libs/connect-file-4.2.0.jar" >> config/connect-standalone.properties

Создайте небольшой входной файл:

echo -e "foo\nbar" > test.txt

Запустите воркер Connect в автономном режиме с конфигурацией как коннектора источника, так и коннектора стока:

bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/connect-file-source.properties \
  config/connect-file-sink.properties

Что должно произойти (и почему это полезно):

• Коннектор источника читает строки из test.txt и производит их в топик connect-test.
• Коннектор стока читает из connect-test и записывает в test.sink.txt.

Проверьте файл стока:

more test.sink.txt

Вы должны увидеть:

foo
bar

Вы также можете проверить топик напрямую:

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

Этот второй пример отлично тренирует мышечную память, так как он также учит вас, где находится конфигурация Connect (конфигурация воркера плюс конфигурации коннекторов), и показывает минимальный цикл “инжиниринг, хранение, экспорт”.

Устранение неполадок и следующие шаги

Большинство проблем “Быстрый старт Kafka не запускается” сводятся к небольшому набору основных причин.

Брокер не запускается

Начните с официальных требований:

• Быстрый старт Kafka 4.2 явно требует Java 17+. Если у вас более старая версия JDK, исправьте это сначала.
• В режиме KRaft форматирование хранилища является обязательным явным шагом. Если вы пропустите kafka-storage.sh format, вы, вероятно, столкнетесь с ошибками запуска или ошибками метаданных.

Если вы экспериментировали и теперь хотите начать с чистого листа, в быстром старте Kafka показано, как удалить локальные директории данных, используемые в демонстрации:

rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs

Команды CLI не работают, хотя брокер запущен

В Kafka 4.x убедитесь, что вы используете --bootstrap-server (а не --zookeeper). В документации по совместимости Kafka явно отмечается удаление --zookeeper из команд AdminClient, начиная с Kafka 4.0.

Сюрпризы сетевой настройки Docker

Если Kafka находится в Docker, а ваш клиентский инструмент находится вне Docker (или на другой машине), вам может понадобиться правильная реклама слушателей. В документации по конфигурации брокера объясняется, что advertised.listeners используется, когда адреса, к которым должны подключаться клиенты, отличаются от адресов привязки (listeners).

Куда двигаться после быстрого старта

Если вы выполнили примеры в этом посте, вы уже ответили на самые распространенные первые поисковые запросы:

• для чего используется Kafka (потоковая передача событий от начала до конца)
• как установить Kafka локально (tarball или Docker)
• почему ZooKeeper исчез и KRaft стал стандартным в 4.x
• какие инструменты CLI важны в повседневной работе (топики, продюсер, консьюмер, группы)

Отсюда наиболее ценными следующими шагами обычно являются:

• Прочитайте “Введение” в Kafka для более глубокого понимания топиков, партиций и репликации.
• Изучите Быстрый старт Kafka Streams, если хотите создать первое приложение обработки (Быстрый старт Streams демонстрирует запуск демо WordCount и проверку результатов с помощью консольного консьюмера).