30 
Содержание
- Зачем переназначать партиции
- Три фазы переназначения
- Фаза 1. Генерация плана
- Фаза 2. Выполнение
- Фаза 3. Проверка
- Флаги kafka-reassign-partitions.sh
- Формат JSON-плана назначений
- Шаг 1. Добавляем брокер и перебалансируем данные
- Шаг 2. Троттлинг - контроль скорости переноса
- Шаг 3. Отмена переназначения
- Мониторинг через kafka-log-dirs.sh
- Что нельзя сделать через kafka-reassign-partitions.sh
- Что дальше
- Референсные ссылки
- Все уроки курса
В уроке 21 мы разбирали kafka-leader-election.sh — инструмент для управления лидерами партиций после сбоев и перезапусков брокеров. Там вопрос стоял просто: вернуть лидерство туда, где оно должно быть по конфигурации.
Сегодня задача масштабнее — физически переместить партиции между брокерами. Это нужно при добавлении нового брокера в кластер, выводе старого из эксплуатации или выравнивании нагрузки на диски. Утилита kafka-reassign-partitions.sh — основной инструмент для этого в стандартной поставке Kafka.
Тема переназначения партиций подробно разбирается в практической части курса «Администрирование кластера Kafka» — там же работа с Cruise Control и стратегии балансировки в production.
Apache Kafka: администрирование кластера
Код курса
KAFKA
Ближайшая дата курса
13 июля, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Зачем переназначать партиции
Kafka распределяет партиции по брокерам автоматически — но только в момент создания топика. После этого кластер не перебалансируется сам, даже если добавить новые брокеры. Новые брокеры будут простаивать, пока вы вручную не перенесёте на них часть партиций.
Основные сценарии, когда нужна переназначение партиций:
- Масштабирование вширь. Добавили новый брокер в кластер — нужно раскидать на него часть партиций, чтобы он реально участвовал в работе.
- Вывод брокера из эксплуатации. Перед тем как выключить брокер, все его партиции нужно перенести на оставшихся участников.
- Балансировка дисков. Если один лог-каталог заполнился сильнее других, можно переместить партиции между директориями на том же брокере.
- Повышение фактора репликации. Изменить количество реплик для существующего топика можно только через переназначение.
Во всех этих случаях используется один и тот же инструмент — kafka-reassign-partitions.sh — и один и тот же трёхфазный процесс.
Три фазы переназначения
Переназначение в Kafka всегда проходит три фазы: генерация плана, выполнение, проверка. Пропускать фазы нельзя — логика утилиты построена вокруг JSON-файла с планом, который передаётся между шагами. 
Фаза 1. Генерация плана
Флаг —generate принимает список топиков и список целевых брокеров, после чего предлагает оптимальное распределение партиций. Утилита ничего не меняет — только выводит два JSON-блока: текущее распределение и предложенное новое.
Перед вызовом нужно подготовить файл с топиками:
{
"topics": [
{"topic": "orders"},
{"topic": "payments"}
],
"version": 1
}
Сохраните его, например, как topics-to-move.json. Теперь запускаем генерацию плана:
# Генерируем план переназначения для топиков orders и payments # на брокеры с ID 1, 2, 3 (включая только что добавленный брокер 3) kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --topics-to-move-json-file /tmp/topics-to-move.json \ --broker-list "1,2,3" \ --generate
Вывод будет содержать два JSON-блока. Первый — Current partition replica assignment — это текущее состояние, его нужно сохранить как резервную копию. Второй — Proposed partition reassignment configuration — это план, который нужно сохранить в файл для следующей фазы.
# Генерируем план и сразу сохраняем предложенное назначение в файл kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --topics-to-move-json-file /tmp/topics-to-move.json \ --broker-list "1,2,3" \ --generate 2>/dev/null \ | tail -1 > /tmp/reassign-plan.json
Фаза 2. Выполнение
Флаг —execute принимает JSON-план и запускает фактический перенос данных. Это асинхронная операция: команда возвращает управление сразу, а репликация идёт в фоне.
# Запускаем переназначение по плану kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --reassignment-json-file /tmp/reassign-plan.json \ --execute
После этой команды Kafka начинает копировать сегменты логов на новые брокеры. Скорость зависит от объёма данных и сетевой пропускной способности. Без троттлинга утилита использует всю доступную полосу — это может повлиять на production-трафик.
Фаза 3. Проверка
Флаг —verify запрашивает статус выполнения по тому же JSON-файлу и показывает, какие партиции уже перенесены, а какие ещё в процессе.
# Проверяем статус переназначения kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --reassignment-json-file /tmp/reassign-plan.json \ --verify
В выводе каждая партиция получает один из статусов: Completed, Still in progress или Failed. Когда все партиции показывают Completed, переназначение завершено. После этого —verify автоматически снимает троттлинг (если он был установлен через —throttle).
Флаги kafka-reassign-partitions.sh
| Флаг | Фаза | Описание | Обязательный |
|---|---|---|---|
| —bootstrap-server | все | Адрес брокера в формате host:port | да |
| —generate | 1 | Сгенерировать план переназначения (ничего не меняет) | один из трёх* |
| —execute | 2 | Запустить переназначение по JSON-плану | один из трёх* |
| —verify | 3 | Проверить статус текущего или завершённого переназначения | один из трёх* |
| —cancel | 2 | Отменить активное переназначение | нет |
| —list | любая | Показать активные переназначения в кластере | нет |
| —topics-to-move-json-file | 1 | JSON-файл со списком топиков для —generate | с —generate |
| —broker-list | 1 | Через запятую: ID целевых брокеров для —generate | с —generate |
| —reassignment-json-file | 2, 3 | JSON-план для —execute, —verify, —cancel | с —execute/verify/cancel |
| —throttle | 2 | Лимит скорости репликации в байтах в секунду | нет |
| —additional | 2 | Добавить партиции к уже идущему переназначению | нет |
| —preserve-throttles | 3 | Не снимать троттлинг автоматически после —verify | нет |
| —timeout | 2 | Таймаут ожидания ответа от брокеров (мс, по умолчанию 10000) | нет |
* Один из трёх режимов — —generate, —execute или —verify — обязателен в каждом вызове утилиты.
Apache Kafka для инженеров данных
Код курса
DEVKI
Ближайшая дата курса
24 августа, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Формат JSON-плана назначений
JSON-план — центральный элемент работы с утилитой. Понимать его структуру важно, потому что иногда приходится редактировать план вручную, а не принимать автогенерированный вариант целиком.
{
"version": 1,
"partitions": [
{
"topic": "orders",
"partition": 0,
"replicas": [3, 1],
"log_dirs": ["any", "any"]
},
{
"topic": "orders",
"partition": 1,
"replicas": [1, 2],
"log_dirs": ["any", "any"]
},
{
"topic": "payments",
"partition": 0,
"replicas": [2, 3],
"log_dirs": ["/data/kafka-logs", "any"]
}
]
}
Ключевые поля:
- replicas — список ID брокеров в нужном порядке. Первый брокер становится preferred replica (лидером по умолчанию).
- log_dirs — пути к лог-директориям на каждом брокере из списка replicas. Значение «any» означает, что Kafka выберет директорию сама. Конкретный путь используется для балансировки дисков на одном брокере.
Количество элементов в replicas и log_dirs должно совпадать. Порядок важен: replicas[0] соответствует log_dirs[0].
Шаг 1. Добавляем брокер и перебалансируем данные
Типичный production-сценарий: в кластере было 2 брокера с ID 1 и 2, добавили брокер с ID 3. Нужно перенести часть партиций на него.
# 1. Готовим список топиков для балансировки
cat > /tmp/topics-to-move.json << 'EOF' {"topics": [{"topic": "orders"}, {"topic": "payments"}], "version": 1} EOF # 2. Генерируем план на все три брокера, сохраняем текущее состояние и план kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --topics-to-move-json-file /tmp/topics-to-move.json \ --broker-list "1,2,3" \ --generate 2>/dev/null > /tmp/reassign-output.txt
# Сохраняем текущее состояние (резервная копия)
head -1 /tmp/reassign-output.txt > /tmp/current-assignment.json
# Сохраняем новый план
tail -1 /tmp/reassign-output.txt > /tmp/reassign-plan.json
# 3. Проверяем план перед выполнением (опционально)
cat /tmp/reassign-plan.json | python3 -m json.tool
Перед тем как запускать —execute, сверьте план: убедитесь, что брокер 3 действительно появился в списке реплик и что фактор репликации не изменился случайно.
# 4. Запускаем переназначение с троттлингом 50 MB/s kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --reassignment-json-file /tmp/reassign-plan.json \ --throttle 52428800 \ --execute # 5. Проверяем статус через несколько минут kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --reassignment-json-file /tmp/reassign-plan.json \ --verify
Шаг 2. Троттлинг — контроль скорости переноса
Без ограничения скорости переназначение может занять всю сетевую полосу между брокерами. В production-кластере это означает задержки для реальных продьюсеров и консьюмеров. Флаг —throttle задаёт лимит в байтах в секунду.
| Ориентир | Значение —throttle | Когда использовать |
|---|---|---|
| 10 MB/s | 10485760 | Рабочие часы, высокая нагрузка на кластер |
| 50 MB/s | 52428800 | Стандартный баланс скорость/нагрузка |
| 200 MB/s | 209715200 | Ночное окно обслуживания |
| без лимита | -1 (не указывать флаг) | Только dev/test-окружения |
Если переназначение уже запущено без троттлинга, его можно добавить на ходу — повторите —execute с тем же файлом плана и нужным значением —throttle. Это не перезапускает переназначение, а только обновляет лимит.
# Добавляем троттлинг к уже запущенному переназначению kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --reassignment-json-file /tmp/reassign-plan.json \ --throttle 10485760 \ --execute
После завершения переназначения (когда —verify покажет Completed для всех партиций) троттлинг снимается автоматически. Если этого не произошло — вызовите —verify ещё раз без флага —preserve-throttles.
Шаг 3. Отмена переназначения
Если переназначение нужно остановить — например, оно влияет на production сильнее, чем ожидалось — используйте флаг —cancel.
# Отменяем активное переназначение kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --reassignment-json-file /tmp/reassign-plan.json \ --cancel
Важно понимать: отмена не откатывает уже перенесённые данные. Партиции, которые успели переехать на новые брокеры, останутся там. Полный откат к исходному состоянию потребует запуска —execute с файлом current-assignment.json, который вы сохранили на шаге генерации плана. Вот почему резервная копия текущего назначения — не опциональный шаг.
# Откат к исходному распределению после отмены kafka-reassign-partitions.sh \ --bootstrap-server localhost:9092 \ --reassignment-json-file /tmp/current-assignment.json \ --throttle 52428800 \ --execute
Мониторинг через kafka-log-dirs.sh
Флаг —verify показывает статус на уровне партиций, но не даёт деталей по объёму перенесённых данных. Для этого удобнее использовать kafka-log-dirs.sh (урок 16) и смотреть на поле isFuture.
Пока переназначение идёт, в выводе kafka-log-dirs.sh партиция появляется дважды: один раз с текущим расположением (isFuture: false) и один раз с новым (isFuture: true). Когда запись с isFuture: true исчезает — партиция полностью перенесена.
# Считаем, сколько партиций ещё в процессе переноса kafka-log-dirs.sh \ --bootstrap-server localhost:9092 \ 2>/dev/null \ | jq '[.. | .isFuture? | select(. == true)] | length'
Если команда вернула 0 — переназначение завершено для всех партиций во всём кластере, независимо от того, что показывает —verify. Это более надёжная проверка на финальном этапе.
Проверить, что брокер 3 получил партиции, можно через kafka-topics.sh:
# Смотрим, как распределились партиции после переназначения kafka-topics.sh \ --bootstrap-server localhost:9092 \ --describe --topic orders
Apache Kafka: администрирование кластера
Код курса
KAFKA
Ближайшая дата курса
13 июля, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Что нельзя сделать через kafka-reassign-partitions.sh
Утилита мощная, но у неё есть границы. Часть задач администрирования партиций придётся решать другими инструментами.
- Изменить количество партиций. Это делается только через kafka-topics.sh с флагом —alter —partitions. kafka-reassign-partitions.sh работает только с уже существующими партициями.
- Автоматически оптимизировать балансировку. Утилита не знает о реальной нагрузке на партиции — только о их расположении. Для умной балансировки с учётом трафика нужен Cruise Control или аналоги.
- Переназначить партиции внутренних топиков. Системные топики типа __consumer_offsets лучше не трогать через эту утилиту без острой необходимости.
- Следить за прогрессом в реальном времени. Нет ни progress bar, ни процентов. Только периодические вызовы —verify или мониторинг через kafka-log-dirs.sh.
Для production-кластеров с большим объёмом данных рекомендуется рассмотреть Cruise Control — он умеет планировать переназначения с учётом нагрузки, темпа сети и реплагируемых объёмов, плюс предоставляет REST API для автоматизации.
Что дальше
В уроке 23 разберём kafka-replica-verification.sh — утилиту для проверки согласованности данных между репликами. Это логичное продолжение: после переназначения партиций стоит убедиться, что реплики не разошлись по содержимому.
Референсные ссылки
- Apache Kafka Documentation. Expanding your cluster (official docs, 2025)
- Apache Kafka Documentation. Setting quotas for partition reassignment (official docs, 2025)
- Apache Kafka Wiki. KIP-696: Partition reassignment with AdminClient (Confluence, 2025)
- GitHub. ReassignPartitionsCommand.java — исходный код утилиты (Apache Kafka 4.x, 2025)
- Confluent Blog. How Kafka handles partition reassignment at scale (Confluent, 2025)
Все уроки курса