37 
Содержание
- Что такое feature-флаги в Apache Kafka
- Синтаксис и подкоманды kafka-features.sh
- Шаг 1. Просмотр текущих feature-флагов
- Шаг 2. Обновление metadata.version после upgrade брокеров
- Шаг 3. Понижение версии и когда это нужно
- Сценарий. Rolling upgrade с Kafka 3.9 на 4.2
- Шаг 4. Проверка после обновления
- Связь с kafka-metadata-shell.sh и kafka-configs.sh
- Что дальше
- Референсы
- Все уроки курса
В уроке 13 мы разбирались с kafka-metadata-shell.sh — интерактивным шеллом для чтения содержимого KRaft-метаданных. Если вы там заходили в директорию /features/ и видели там metadata.version с каким-то числом — это как раз то, чем управляет утилита сегодняшнего урока.
kafka-features.sh отвечает за управление feature-флагами кластера. Звучит абстрактно, но на практике это почти всегда означает одно: вы обновили версию Kafka на всех брокерах, и теперь нужно сказать кластеру «окей, можешь использовать возможности новой версии». Именно для этого и нужна эта утилита.
Тема особенно актуальна для администраторов, которые занимаются обновлением production-кластеров. В курсе «Администрирование кластера Kafka» rolling upgrade разбирается как отдельная практическая задача со всеми типичными ошибками и способами их избежать.
Что такое feature-флаги в Apache Kafka
Feature-флаги — это механизм версионирования возможностей кластера. Каждый флаг имеет числовой уровень (level), который отражает, до какой версии протокола кластер «разморозился». Флаги хранятся в KRaft-метаданных и реплицируются вместе со всем остальным состоянием кластера.
Самый важный флаг — metadata.version. Он контролирует, какие возможности протокола активны прямо сейчас. Пока этот уровень не повышен, брокеры новой версии работают в режиме совместимости со старым протоколом — это и позволяет делать rolling upgrade без остановки кластера.
Кроме metadata.version существуют и другие флаги: например, transaction.version для новой реализации транзакций или group.version для новой логики consumer groups в Kafka 4.x. Все они управляются через ту же утилиту.
Числовые уровни флагов соответствуют внутренним версиям IBP (Inter-Broker Protocol). Для Kafka 4.2.0 актуальны такие ориентиры.
| Релиз Kafka | metadata.version (финальный уровень) | Примечание |
|---|---|---|
| 3.7.x | 17 | Последняя версия с поддержкой ZooKeeper |
| 3.8.x | 18 | KRaft стабилен, ZooKeeper deprecated |
| 3.9.x | 20 | Последняя версия с ZooKeeper в составе |
| 4.0.x | 22 | ZooKeeper удалён, только KRaft |
| 4.1.x | 23 | Новая реализация consumer groups |
| 4.2.x | 24 | Актуальная версия на момент публикации |
Числа в таблице отражают финальный (максимальный) уровень для каждого релиза. Конкретные значения можно уточнить командой describe — она показывает и поддерживаемый диапазон, и текущий активный уровень.
Apache Kafka для инженеров данных
Код курса
DEVKI
Ближайшая дата курса
24 августа, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Синтаксис и подкоманды kafka-features.sh
Утилита работает через подкоманды — как большинство современных инструментов Kafka. Общий синтаксис такой.
kafka-features.sh <подкоманда> [флаги]
Доступны три подкоманды. Каждая отвечает за строго определённое действие.
- describe. Показывает текущее состояние всех feature-флагов кластера — поддерживаемый диапазон уровней и активный финализированный уровень.
- upgrade. Повышает уровень одного или нескольких флагов. Основная рабочая команда после обновления брокеров.
- downgrade. Понижает уровень флага. Требует явного флага —unsafe, потому что откат протокола может нарушить совместимость данных.
Все три подкоманды требуют подключения к живому брокеру — через флаг —bootstrap-server.
Шаг 1. Просмотр текущих feature-флагов
Начнём с самого простого — посмотрим, что сейчас активно в кластере.
kafka-features.sh describe --bootstrap-server localhost:9092
Пример вывода для кластера Kafka 4.2.0 с уже обновлённым metadata.version.
Feature: group.version SupportedMinVersion: 0 SupportedMaxVersion: 1 FinalizedVersionLevel: 1 Epoch: 3 Feature: metadata.version SupportedMinVersion: 1 SupportedMaxVersion: 24 FinalizedVersionLevel: 24 Epoch: 5 Feature: transaction.version SupportedMinVersion: 0 SupportedMaxVersion: 2 FinalizedVersionLevel: 2 Epoch: 3
Что здесь важно: SupportedMaxVersion — это максимум, который поддерживает ваша версия Kafka. FinalizedVersionLevel — это то, что реально активно прямо сейчас. Если они совпадают — вы уже на максимуме. Если нет — есть куда апгрейдить.
Чтение вывода на кластере после rolling upgrade
Типичная ситуация: вы обновили все брокеры с 3.9 на 4.2, но describe показывает такую картину.
Feature: metadata.version SupportedMinVersion: 1 SupportedMaxVersion: 24 FinalizedVersionLevel: 20 Epoch: 2
Видно: брокеры уже поддерживают уровень 24 (Kafka 4.2), а активен всё ещё уровень 20 (Kafka 3.9). Кластер работает в режиме совместимости. Пора обновить флаг.
Шаг 2. Обновление metadata.version после upgrade брокеров
Есть два способа указать целевую версию: через числовой уровень или через номер релиза. В Kafka 4.x появился удобный флаг —release-version, который избавляет от необходимости помнить числа.
# Способ 1: через номер релиза (удобнее) kafka-features.sh upgrade \ --release-version 4.2 \ --bootstrap-server localhost:9092
# Способ 2: через конкретный уровень флага kafka-features.sh upgrade \ --feature metadata.version=24 \ --bootstrap-server localhost:9092
Оба варианта дают одинаковый результат. Флаг —release-version просто транслирует номер версии в соответствующий числовой уровень автоматически. Если всё прошло успешно, утилита ответит кратко.
Successfully upgraded finalized feature: metadata.version from level 20 to level 24.
Обновление нескольких флагов за раз
Флаг —feature можно передать несколько раз — по одному на каждый обновляемый флаг. Либо использовать —release-version, который обновляет все флаги, связанные с этим релизом, автоматически.
# Обновить несколько флагов явно kafka-features.sh upgrade \ --feature metadata.version=24 \ --feature transaction.version=2 \ --feature group.version=1 \ --bootstrap-server localhost:9092
Использовать —release-version проще и безопаснее — меньше шансов пропустить связанный флаг.
Apache Kafka: администрирование кластера
Код курса
KAFKA
Ближайшая дата курса
13 июля, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Шаг 3. Понижение версии и когда это нужно
Downgrade — редкая и рискованная операция. Понижение уровня флага не откатывает данные, которые уже записаны в новом формате. Поэтому Kafka требует явного подтверждения через флаг —unsafe.
# Понижение metadata.version - только для тестовых сред! kafka-features.sh downgrade \ --feature metadata.version=20 \ --unsafe \ --bootstrap-server localhost:9092
Когда это может понадобиться на практике: вы обновили кластер, обнаружили критическую проблему и хотите откатиться на прежнюю версию Kafka. Если metadata.version уже поднят — старые брокеры (версии 3.9) не смогут читать метаданные нового формата. Понижение уровня флага возвращает кластер в понятный для старых брокеров формат.
Но важный нюанс: сообщения в топиках, которые уже записаны в новом формате, останутся в нём. Downgrade не является откатом данных — только протокола.
Сценарий. Rolling upgrade с Kafka 3.9 на 4.2
Разберём полный сценарий обновления кластера из трёх брокеров. Это стандартная процедура, которую выполняют в production.
Ключевое правило этого сценария: kafka-features.sh upgrade запускается только после того, как все брокеры уже перешли на новую версию. Запускать обновление флага при смешанном кластере (часть брокеров на 3.9, часть на 4.2) — это путь к проблемам совместимости.
Шаг 4. Проверка после обновления
После upgrade всегда стоит перепроверить состояние флагов — убедиться, что финализированный уровень совпадает с ожидаемым.
# Проверяем состояние флагов после обновления kafka-features.sh describe --bootstrap-server localhost:9092
Feature: group.version SupportedMinVersion: 0 SupportedMaxVersion: 1 FinalizedVersionLevel: 1 Epoch: 4 Feature: metadata.version SupportedMinVersion: 1 SupportedMaxVersion: 24 FinalizedVersionLevel: 24 Epoch: 6 Feature: transaction.version SupportedMinVersion: 0 SupportedMaxVersion: 2 FinalizedVersionLevel: 2 Epoch: 4
Если FinalizedVersionLevel равен SupportedMaxVersion для каждого флага — всё сделано правильно. Кластер работает на полную мощность текущей версии Kafka.
Связь с kafka-metadata-shell.sh и kafka-configs.sh
Данные, которые меняет kafka-features.sh, видны в нескольких местах. В kafka-metadata-shell.sh их можно увидеть в директории /features/metadata.version — там хранится текущий финализированный уровень.
# Проверить metadata.version через kafka-metadata-shell.sh kafka-metadata-shell.sh --snapshot /var/kafka/data/__cluster_metadata-0/00000000000000000000.checkpoint # Внутри шелла: # cat /features/metadata.version
Через kafka-configs.sh feature-флаги не управляются — это разные механизмы. Configs работает с конфигурацией брокеров и топиков, features — с версионированием протокола. Про kafka-configs.sh подробно поговорим в следующем уроке.
Apache Kafka: администрирование кластера
Код курса
KAFKA
Ближайшая дата курса
13 июля, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Что дальше
В уроке 15 разберём kafka-configs.sh — инструмент для управления конфигурацией брокеров, топиков и клиентов. Там же посмотрим, как читать и менять настройки на лету без перезапуска кластера.
Референсы
- Apache Kafka Documentation. Upgrade Guide (2025)
- Apache Kafka Documentation. KRaft Mode (2025)
- KIP-584. Versioning scheme for features — Apache Kafka Wiki
- KIP-1022. Formatting and Updating Features — Apache Kafka Wiki
- kafka-features.sh source — GitHub Apache Kafka (2025)