39 
Содержание
- Что такое утилита kafka-configs.sh и как она устроена
- Шаг 1. Описание конфигурации топика
- Шаг 2. Изменение конфигурации топика
- Шаг 3. Сброс параметра к значению по умолчанию
- Шаг 4. Работа с конфигурациями брокера
- Шаг 5. Управление логгерами брокера
- Шаг 6. Квоты для пользователей и клиентов
- Часто используемые параметры топиков
- Admin API как альтернатива
- Типичные ошибки и как их избежать
- Что дальше
- Референсы
- Все уроки курса
В уроке 14 мы разобрали kafka-features.sh — утилиту для управления feature-флагами кластера и версией метаданных KRaft. Там же стало понятно, что Kafka хранит в метаданных не только версии функций, но и переопределённые конфигурации топиков и брокеров. Посмотреть эти конфигурации в режиме read-only можно через kafka-metadata-shell.sh из урока 13 — раздел /configs/.
Но читать мало. Нужно уметь менять конфигурации на ходу — без перезапуска брокеров и без правки статических файлов server.properties. Именно для этого существует kafka-configs.sh.
Эта утилита — один из главных инструментов в арсенале администратора Kafka. В курсе «Администрирование кластера Kafka» управлению конфигурациями уделен отдельный блок: там разбирают приоритеты конфигов, как они применяются в реальных кластерах и почему статический server.properties — это крайний случай, а не норма.
Что такое утилита kafka-configs.sh и как она устроена
kafka-configs.sh управляет динамическими конфигурациями кластера Kafka. Это не те настройки, что прописаны в server.properties на диске. Это конфигурации, которые хранятся в метаданных кластера и применяются без перезапуска.
Утилита работает с пятью типами объектов — так называемыми entity.
- topics. Конфигурации конкретного топика: срок хранения, максимальный размер сообщения, политика очистки и другие параметры уровня топика.
- brokers. Динамические конфигурации брокера: настройки репликации, лимиты по трафику, логгирование и прочее, что можно изменить без рестарта.
- broker-loggers. Уровни логирования для конкретного брокера — полезно при диагностике без выключения ноды.
- users. Квоты для пользователей SASL/ACL: лимиты на скорость продьюсинга и консьюминга.
- clients. Квоты для клиентских идентификаторов — по client.id, не по имени пользователя.
Каждая операция строится из трёх обязательных частей: действие (—describe или —alter), тип объекта (—entity-type) и способ подключения к кластеру (—bootstrap-server).
Шаг 1. Описание конфигурации топика
Начнём с самого распространённого случая — смотреть, что переопределено для конкретного топика. Команда —describe покажет только те параметры, которые были явно изменены. Параметры по умолчанию она не выводит.
# Посмотреть переопределённые конфигурации топика orders kafka-configs.sh \ --bootstrap-server localhost:9092 \ --describe \ --entity-type topics \ --entity-name orders
Если у топика ничего не переопределено, вы увидите пустой вывод. Это нормально — значит, топик работает на дефолтных настройках брокера. Если нужно посмотреть вообще все параметры, включая дефолтные, добавляйте флаг —all.
# Все параметры топика, включая унаследованные от брокера kafka-configs.sh \ --bootstrap-server localhost:9092 \ --describe \ --entity-type topics \ --entity-name orders \ --all
Вывод покажет три типа значений: DEFAULT_CONFIG — параметр взят с брокера, STATIC_BROKER_CONFIG — задан в server.properties, DYNAMIC_TOPIC_CONFIG — переопределён для этого топика явно.
Dynamic configs for topic orders are:
retention.ms=604800000 sensitive=false synonyms={DYNAMIC_TOPIC_CONFIG:retention.ms=604800000, DEFAULT_CONFIG:log.retention.ms=86400000}
max.message.bytes=5242880 sensitive=false synonyms={DYNAMIC_TOPIC_CONFIG:max.message.bytes=5242880, DEFAULT_CONFIG:message.max.bytes=1048588}
Шаг 2. Изменение конфигурации топика
Операция —alter применяет изменение немедленно — без перезапуска брокера. Для добавления или изменения параметров используется флаг —add-config.
# Установить срок хранения 7 дней для топика orders kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type topics \ --entity-name orders \ --add-config retention.ms=604800000
Несколько параметров можно передать за один вызов — через запятую без пробелов.
# Изменить сразу несколько параметров топика kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type topics \ --entity-name orders \ --add-config retention.ms=604800000,max.message.bytes=5242880,compression.type=lz4
После успешного применения утилита выводит короткое подтверждение без деталей. Проверить результат стоит отдельным —describe.
Шаг 3. Сброс параметра к значению по умолчанию
Чтобы убрать переопределение и вернуть параметр к дефолту брокера, используется —delete-config. После этого топик начнёт использовать значение из настроек брокера.
# Удалить переопределение retention.ms - топик вернётся к дефолту брокера kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type topics \ --entity-name orders \ --delete-config retention.ms
Важный момент — —delete-config не сбрасывает значение в ноль и не «удаляет» параметр полностью. Он просто убирает переопределение уровня топика. Параметр продолжает работать, но теперь берётся с уровня брокера.
Шаг 4. Работа с конфигурациями брокера
Динамические конфигурации брокера меняются похожим образом, только —entity-type указывается как brokers, а —entity-name — это числовой идентификатор брокера.
# Посмотреть динамические конфигурации брокера 1 kafka-configs.sh \ --bootstrap-server localhost:9092 \ --describe \ --entity-type brokers \ --entity-name 1
Для изменений на уровне всего кластера сразу — без указания конкретного брокера — используется флаг —entity-default. Это удобно, когда нужно применить настройку ко всем брокерам одной командой.
# Установить лимит репликации для всех брокеров кластера kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type brokers \ --entity-default \ --add-config leader.replication.throttled.rate=10485760
Лимиты репликации особенно нужны при переносе партиций — чтобы не положить сеть на продакшне, пока Kafka перебрасывает данные между брокерами.
Apache Kafka: администрирование кластера
Код курса
KAFKA
Ближайшая дата курса
13 июля, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Шаг 5. Управление логгерами брокера
Тип сущности broker-loggers отвечает только за уровни логирования. Это отдельный механизм от обычных конфигов брокера — он меняет уровень log4j-логгера в реальном времени.
# Посмотреть текущие уровни логгеров для брокера 1 kafka-configs.sh \ --bootstrap-server localhost:9092 \ --describe \ --entity-type broker-loggers \ --entity-name 1
# Временно включить DEBUG для репликации на брокере 1 kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type broker-loggers \ --entity-name 1 \ --add-config kafka.server.ReplicaManager=DEBUG
После диагностики уровень стоит вернуть обратно — DEBUG генерирует огромный объём логов и ощутимо нагружает брокер.
Шаг 6. Квоты для пользователей и клиентов
Квоты в Kafka ограничивают скорость продьюсинга и консьюминга для конкретного принципала или клиента. Это один из стандартных инструментов управления нагрузкой в многотенантных кластерах.
# Установить квоту для пользователя alice: продьюсинг 1 MB/s, консьюминг 2 MB/s kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type users \ --entity-name alice \ --add-config producer_byte_rate=1048576,consumer_byte_rate=2097152
# Установить квоту по client.id для клиентского приложения kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type clients \ --entity-name analytics-service \ --add-config consumer_byte_rate=5242880
Квоты можно комбинировать: задать сначала для пользователя, потом для связки пользователь + клиент. В этом случае применяется более специфичное правило.
# Квота для конкретной связки user=alice, client.id=analytics-service kafka-configs.sh \ --bootstrap-server localhost:9092 \ --alter \ --entity-type users \ --entity-name alice \ --entity-type clients \ --entity-name analytics-service \ --add-config producer_byte_rate=524288
Посмотреть все квоты для пользователя или клиента можно тем же —describe. А чтобы снять квоту — —delete-config с нужным ключом.
Часто используемые параметры топиков
Ниже — параметры, которые на практике меняются чаще всего. Все они применяются через —add-config при —entity-type topics.
- retention.ms. Срок хранения сообщений в миллисекундах. Значение -1 означает «хранить вечно». По умолчанию берётся из log.retention.ms брокера.
- retention.bytes. Максимальный размер лога партиции в байтах. После превышения старые сегменты удаляются. По умолчанию -1 (без ограничений).
- max.message.bytes. Максимальный размер одного сообщения для этого топика. Важно согласовывать с fetch.max.bytes на консьюмере.
- cleanup.policy. Политика очистки: delete (удалять по времени/объёму) или compact (сжимать, оставляя последнее значение по ключу). Можно указать оба через запятую: compact,delete.
- compression.type. Тип сжатия: gzip, snappy, lz4, zstd или producer (сжатие задаётся продьюсером).
- min.insync.replicas. Минимальное число реплик в ISR для подтверждения записи. Критичный параметр для надёжности — меняйте с пониманием последствий.
- segment.ms. Максимальное время жизни активного сегмента лога до принудительного закрытия. Влияет на частоту сброса на диск и работу compaction.
Полный список параметров топиков — в официальной документации Kafka. Там же указано, какие из них доступны для динамического изменения.
Admin API как альтернатива
Всё, что делает kafka-configs.sh, можно сделать через Kafka Admin API программно. Утилита — это просто обёртка над теми же API-вызовами.
Для чтения конфигураций используется метод describeConfigs(), для изменения — alterConfigs() или более гибкий incrementalAlterConfigs(), который позволяет добавлять и удалять параметры атомарно в одном вызове.
// Пример: изменение конфигурации топика через AdminClient (Java)
AdminClient admin = AdminClient.create(props);
Map<ConfigResource, Collection<AlterConfigOp>> updates = new HashMap<>();
ConfigResource resource = new ConfigResource(ConfigResource.Type.TOPIC, "orders");
updates.put(resource, List.of(
new AlterConfigOp(
new ConfigEntry("retention.ms", "604800000"),
AlterConfigOp.OpType.SET
)
));
admin.incrementalAlterConfigs(updates).all().get();
Когда использовать утилиту, а когда API — зависит от задачи. kafka-configs.sh удобнее для ручных операций и скриптов на bash. AdminClient нужен, если управление конфигурациями встроено в приложение или CI/CD-пайплайн.
Типичные ошибки и как их избежать
Несколько вещей, на которых часто спотыкаются при первом знакомстве с утилитой.
- Опечатка в имени параметра. Kafka не предупреждает о неизвестных ключах — она просто сохраняет их в метаданных, и они никогда не применяются. Всегда проверяйте результат через —describe после —alter.
- Несогласованность min.insync.replicas и replication.factor. Если выставить min.insync.replicas=3 для топика с двумя репликами, запись в топик станет невозможной. Брокер будет отклонять сообщения с ошибкой NotEnoughReplicasException.
- Путаница между entity-type brokers и broker-loggers. Это разные типы. Логгеры не влияют на поведение брокера, только на объём и детальность логов.
- Применение —entity-default без понимания приоритетов. Конфиг уровня «все брокеры» перекрывается конфигом конкретного брокера. Если для брокера 2 задан параметр явно, cluster-default его не затронет.
Хорошая практика — после любого —alter делать —describe —all и убеждаться, что параметр отображается с нужным уровнем (DYNAMIC_TOPIC_CONFIG или DYNAMIC_BROKER_CONFIG).
Apache Kafka для инженеров данных
Код курса
DEVKI
Ближайшая дата курса
24 августа, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Что дальше
В уроке 16 разберём kafka-log-dirs.sh — утилиту для анализа размеров и расположения лог-директорий партиций. Это прямое продолжение темы: после того как вы поменяли retention.bytes через kafka-configs.sh, именно kafka-log-dirs.sh поможет проверить, освободилось ли место на диске.
Референсы
- Apache Kafka Documentation. Topic-Level Configs — полный список параметров топиков с описанием (2025)
- Apache Kafka Documentation. Broker Configs — полный список параметров брокера, включая динамические (2025)
- Apache Kafka Documentation. Quotas — управление квотами для пользователей и клиентов (2025)
- Apache Kafka Documentation. Updating Broker Configs — какие параметры брокера допускают динамическое изменение (2025)
- KIP-226. Dynamic Broker Configuration — оригинальный KIP с обоснованием механизма динамических конфигов (2025)