Миграция данных Camunda 8 Operate в Камунда.РФ Пульт

Инструкция описывает перенос исторических данных Camunda 8 Operate из ElasticSearch / OpenSearch в базы данных Камунда.РФ Пульт. Инструкция содержит два варианта запуска: локальный запуск и запуск в Kubernetes.

Версия утилиты

Инструкция описывает утилиту operate-to-pult версии 1.1.3 и новее. Актуальная проверенная версия — 1.1.6. В версии 1.1.2 и старше набор команд другой: вместо migrate и raw-migrate там to-crawler и to-harvester. Проверьте версию по первой строке лога: operate2pult start version=... git=... build=....

Назначение

Утилита operate-to-pult (CLI operate2pult) читает историю процессов из индексов ElasticSearch / OpenSearch и записывает её в один из приёмников.

Команда	Источник	Приёмник	Что делает
migrate	Индексы Operate <prefix>-*	Postgres: схемы crawler и harvester	Переносит всю историю сервера за один проход. Окно по времени не задаётся. Основной маршрут миграции.
raw-migrate	Сырые индексы Zeebe <prefix>_*	Postgres: схемы crawler и harvester	Переносит историю за указанное окно за один проход. Обязателен флаг --from.
definitions	<prefix>-process-* (индексы Operate)	Kafka	Отправляет все модели процессов (BPMN). Фильтр по времени отсутствует.
export	Сырые индексы Zeebe <prefix>*	Kafka	Отправляет сырые записи Zeebe в топик. Приёмник — сервис harvester.
cleanup	—	Postgres	Удаляет все строки одного server-id из выбранной схемы. Нужен для повторного прогона.

Какую команду выбрать

• migrate — если сервис Operate доступен и нужен полный архив сервера. Команда читает агрегированные индексы Operate, поэтому переносит всю историю, которую хранит Operate, независимо от срока хранения сырых индексов Zeebe.

• raw-migrate — если Operate недоступен или неполон, либо нужен только конкретный промежуток времени. Команда читает сырые индексы Zeebe, поэтому её глубина ограничена политикой очистки экспортёра.

Обе команды пишут в обе схемы за один проход и требуют оба DSN. Разделять миграцию на два прогона не нужно.

Заметка

Команды export и definitions к миграции в Postgres отношения не имеют: они кладут записи в Kafka, откуда их читает работающий сервис harvester. Отдельный прогон definitions для переноса моделей процессов больше не нужен — смотрите раздел «Модели процессов за границей окна».

Откуда утилита берёт данные

Кластер Zeebe пишет каждое событие процесса в поток записей. Экспортёр (elasticsearch-exporter или opensearch-exporter) складывает эти записи в индексы с префиксом zeebe-record. Это сырые записи Zeebe.

Сервис Operate читает те же записи и строит собственные индексы с префиксом operate. Это агрегированное представление: по одному документу на сущность вместо потока событий жизненного цикла.

Группа индексов	Содержимое	Кто читает	Срок хранения
operate-process-*, operate-list-view-*, operate-flownode-instance-*, operate-variable-*, operate-incident-*	Агрегированные данные Operate: модели, экземпляры процессов, активности, переменные, инциденты.	migrate	Задаётся настройками Operate.
operate-process-*	Развёрнутые BPMN-модели.	definitions	Задаётся настройками Operate.
zeebe-record_process_*, zeebe-record_process-instance_*, zeebe-record_variable_*, zeebe-record_incident_*, zeebe-record_user-task_*	Сырые записи Zeebe.	raw-migrate	Ограничен политикой очистки экспортёра. Смотрите предупреждение ниже.

Команда export читает более широкий набор: все индексы с префиксом zeebe-record.

Проверьте политику очистки перед миграцией через raw-migrate

У экспортёра Zeebe есть параметр retention. По умолчанию параметр выключен. Если администратор включил его, индексы zeebe-record_* старше заданного возраста удаляются (значение по умолчанию — 30 дней, политика zeebe-record-retention-policy). Удалённые записи перенести нельзя. Начало окна миграции не может быть раньше срока хранения.

Команды migrate это ограничение не касается: она читает индексы Operate.

Проверьте фактическую глубину истории до запуска. Команда выводит список индексов и их даты:

curl 'http://es-host:9200/_cat/indices/zeebe-record_*?v&s=index'

Модели процессов за границей окна

Запись о модели появляется в индексе один раз — в момент развёртывания модели. Поэтому модель, развёрнутая раньше начала окна миграции, в само окно не попадает.

Команда raw-migrate решает это сама. Между фазами COPY и MERGE она выполняет фазу missing-entries: забирает terms-запросом из тех же индексов zeebe-record_*, но уже без фильтра по времени, всё, на что ссылаются перенесённые данные и чего в окне не оказалось — модели процессов и родительские экземпляры процессов. Цикл повторяется до сходимости, предел итераций задаёт флаг --missing-cap (по умолчанию 10). Если за это число итераций ссылки не разрешились, в лог пишется предупреждение missing-entries did not converge within cap; proceeding, и перенос продолжается.

Ограничение фазы missing-entries

Фаза читает те же индексы zeebe-record_*. Если запись о модели уже удалена политикой retention, дотянуть её неоткуда — Пульт покажет историю без диаграммы процесса. В этом случае используйте migrate: индексы Operate хранят модели независимо от срока хранения сырых записей.

У команды migrate этой проблемы нет: окно по времени не задаётся, переносится весь архив.

Термины

Термин	Значение
Окно миграции	Интервал времени между --from и --to. Применяется только в raw-migrate. Утилита переносит записи, у которых timestamp попадает в интервал.
Прогон	Один запуск migrate или raw-migrate. Утилита заводит запись прогона в таблице export_runs в каждой из двух целевых баз — с разными id, но одинаковым server_id.
Целевые БД	Базы Postgres со схемами crawler и harvester. Как правило, это две разные базы, и обе нужны одновременно.
Staging-таблица	Служебная таблица прогона o2p_stg_*_<run_id> типа UNLOGGED. Утилита создаёт её на старте и удаляет на выходе. Это обычная таблица, а не TEMPORARY.
server-id	Имя исходного сервера Camunda в Пульте. Все строки помечаются этим значением.

Требования к окружению

Общие требования

Ресурс	Требование
Хранилище-источник	ElasticSearch 7 или 8, либо OpenSearch 1.x или 2.x. Доступ по HTTP или HTTPS. Открыт API поиска и API scroll.
Postgres	Обе целевые схемы уже развёрнуты (миграции pult-data-model и crawler выполнены).
Kafka	Нужна только для команд export и definitions. Топик создан заранее.
Время	Часы источника и приёмника синхронны. Границы окна утилита сравнивает с полем timestamp записи.

Источник данных: ElasticSearch или OpenSearch

Утилита работает с обоими хранилищами. Утилита использует только базовые запросы: _search, параметр scroll, _search/scroll и фильтр range по полю timestamp. OpenSearch 1.x и 2.x поддерживают эти запросы.

Камунда.РФ 8 содержит два экспортёра записей Zeebe: elasticsearch-exporter и opensearch-exporter. Оба экспортёра дают одинаковые имена индексов:

<prefix>_<valueType>_<version>_<дата>
# пример: zeebe-record_process-instance_8.5.0_2026-05-01

Префикс по умолчанию — zeebe-record для обоих экспортёров. Поэтому значение --index-prefix не зависит от типа хранилища.

Проверьте источник перед миграцией

Перед основным прогоном выполните проверку доступа и получите список индексов: curl 'http://os-host:9200/_cat/indices?v'. Затем перенесите узкое окно командой raw-migrate (например, один час) и сверьте row_counts в export_runs.

Права в хранилище-источнике

Утилите нужен пользователь с правом чтения индексов. Утилита открывает scroll-контексты и удерживает их 10 минут. Названия привилегий даны для ElasticSearch. В OpenSearch используйте роль с действиями indices:data/read/search и indices:data/read/scroll.

Команда	Шаблон индексов	Привилегия
migrate	<prefix>-process-*, <prefix>-list-view-*, <prefix>-flownode-instance-*, <prefix>-variable-*, <prefix>-incident-*	read, view_index_metadata
raw-migrate	<prefix>_process_*, <prefix>_process-instance_*, <prefix>_variable_*, <prefix>_incident_*, <prefix>_user-task_*	read, view_index_metadata
export	<prefix>*	read, view_index_metadata
definitions	<prefix>-process-*	read, view_index_metadata

Внимание: два разных префикса

Команды raw-migrate и export читают индексы экспортёра Zeebe. Их префикс обычно равен zeebe-record, а разделитель — знак подчёркивания. Команды migrate и definitions читают агрегированные индексы Operate. Их префикс обычно равен operate, а разделитель — дефис. Задайте для них отдельное значение --index-prefix.

У команды migrate флаг --index-prefix можно не задавать: без него подставляется значение operate. У raw-migrate флаг обязателен.

Отдельного флага для логина и пароля нет. Передайте учётные данные в самом URL. Правило одинаково для ElasticSearch и OpenSearch:

--elastic=https://user:password@es-host:9200

Ограничение TLS

Образ содержит только публичный набор корневых сертификатов. Если хранилище-источник использует внутренний удостоверяющий центр, смонтируйте свой бандл в /etc/ssl/certs/ca-certificates.crt. Иначе соединение по HTTPS завершится ошибкой.

Права в Postgres

Утилита создаёт служебные и временные таблицы. Роль должна иметь право CREATE в целевой схеме. Права только на INSERT недостаточно. Права нужны в обеих базах: и в схеме crawler, и в схеме harvester.

Объект	Право	Причина
База данных	CONNECT	Подключение пула. Утилита открывает пул к каждой из двух баз.
Целевая схема	USAGE, CREATE	Создание export_runs, server_tags и staging-таблиц.
Целевые таблицы	SELECT, INSERT, UPDATE, DELETE	Загрузка, фазы обновления, команда cleanup.
Последовательности целевых таблиц	USAGE	Выдача значений id при слиянии из staging (схема harvester).

Право SELECT на целевые таблицы нужно ещё и потому, что staging создаётся как CREATE UNLOGGED TABLE ... (LIKE <целевая таблица>).

Пример выдачи прав для схемы harvester:

GRANT CONNECT ON DATABASE harvester TO o2p_migrator;
GRANT USAGE, CREATE ON SCHEMA public TO o2p_migrator;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO o2p_migrator;
GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO o2p_migrator;

Заметка

Таблицы адресуются без имени схемы. Если целевые таблицы лежат не в public, задайте путь поиска в DSN: postgres://user:pass@host:5432/db?search_path=crawler.

Требования к Kafka

Требования применяются только к командам export и definitions.

• Топик создан заранее. Утилита не создаёт топики.

• Значение max.message.bytes — не меньше 12 МиБ. Рекомендуемое значение — 33554432 (32 МиБ). BPMN-модели дают крупные сообщения.

• Право Write на топик и право Describe на топик.

• Аутентификация: только SASL SCRAM-SHA-256 через --kafka-user и --kafka-password. Настройки TLS для Kafka нет.

Пример создания топика:

kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic banana-dev --partitions 3 --replication-factor 1 \
  --config max.message.bytes=33554432

Планирование ресурсов

Утилита накапливает строки в буферах и записывает их в Postgres командой COPY. Размер буфера подбирается по таблице, а не задаётся одним числом:

Таблица	Строк в буфере	Причина
definitions, history_process_definition	5 000	Тело BPMN-модели занимает килобайты.
variables, history_variable_entity	50 000	Значение переменной может быть крупным JSON.
Остальные	200 000	Экземпляры процессов, активности, инциденты, служебные таблицы.

Сверху каждый буфер ограничен бюджетом около 128 МиБ: буфер сбрасывается в Postgres по тому пределу, который наступит раньше — по числу строк или по объёму.

Дальше поведение команд расходится:

• migrate читает индексы Operate по одному и выполняет этапы последовательно, закрывая буферы этапа перед переходом к следующему. Пик памяти определяется самым тяжёлым этапом.

• raw-migrate читает один общий поток сырых записей и раскладывает его сразу по всем буферам обеих схем. Все буферы живут одновременно, поэтому пик — их сумма. Здесь уменьшение --copy-chunk-size даёт наибольший эффект, если под упирается в лимит.

Флаг --copy-chunk-size

Флаг работает по-разному в двух командах. Это единственное отличие, которое стоит держать в голове при подборе лимитов.

Команда	Поведение флага	Значение по умолчанию
migrate	Потолок для всех таблиц: применяется, только если задано меньше табличного значения. Расход памяти можно уменьшить, увеличить — нельзя.	200 000
raw-migrate	Прямое значение для всех буферов, кроме definitions (5 000) и variables (50 000) — их флаг не меняет. Увеличение флага увеличивает расход памяти.	200 000

Значение больше 200 000 для migrate бесполезно

--copy-chunk-size=500000 у migrate не даёт ничего: табличные значения меньше, и потолок не применяется. Если пода не хватает памяти, уменьшайте флаг, а не увеличивайте.

Лимиты Pod

В таблице ниже: PI — process instance (экземпляр процесса), FNI — flow node instance (экземпляр элемента BPMN: задачи, шлюза, события).

Объём	RAM лимита Pod	CPU
< 1 млн PI, < 10 млн FNI	2 GiB	2
1 – 10 млн PI, 10 – 50 млн FNI или переменных	4 GiB	2
> 10 млн PI либо очень крупные переменные	8 GiB	2

В Kubernetes задайте значение в resources.limits.memory контейнера. При локальном запуске подготовьте такой же объём свободной памяти.

Значения рассчитаны на migrate. Для raw-migrate берите следующую ступень вверх либо уменьшайте --copy-chunk-size: у этой команды буферы обеих схем заполняются одновременно.

Если под упирается в потолок памяти

Включите --aggressive-gc. Флаг вызывает runtime.GC и возврат памяти операционной системе между этапами. Плата — пауза в несколько сотен миллисекунд на каждой границе этапа.

Время

Скорость ограничена хранилищем-источником и Postgres. По замерам — 50–100 тыс. записей в минуту. Это эмпирические ориентиры, а не гарантия утилиты.

Записей	Время
1 млн	10 – 20 мин
10 млн	1.5 – 3.5 ч
20 млн	3 – 7 ч
50 млн	8 – 17 ч

Если скорость стабильно ниже 30 тыс. записей в минуту, узкое место либо в хранилище-источнике (параллельные нагрузки, медленная сеть), либо в Postgres (нехватка ресурсов на запись журнала и индексов).

Место на диске Postgres

Размер основной таблицы — примерно 550 байт на строку. Пик при миграции — в 2.5–3 раза больше основной таблицы: буферная копия, индексы и журналы.

Записей	Основная таблица crawler	Пик при миграции	Размер тома
1 млн	~0.6 ГиБ	~1.5 ГиБ	8 ГиБ
5 млн	~3 ГиБ	~7.5 ГиБ	16 ГиБ
10 млн	~6 ГиБ	~15 ГиБ	32 ГиБ
20 млн	~12 ГиБ	~30 ГиБ	64 ГиБ
50 млн	~30 ГиБ	~75 ГиБ	128 ГиБ

Возьмите том с двукратным запасом от пика: Postgres не уменьшает файлы автоматически. В схеме harvester объём в 5–10 раз меньше: для каждой переменной и активности остаётся одна актуальная строка.

Порядок миграции

Миграция состоит из трёх этапов. Соблюдайте порядок этапов.

Этап	Действие	Причина
1	Остановите кластер Zeebe. Остановите сервисы harvester и crawler.	Остановка кластера фиксирует границу истории. Остановка сервисов освобождает целевые таблицы: только утилита пишет в них во время миграции.
2	Выполните миграцию.	Утилита переносит историю в базы Пульта.
3	Запустите сервисы harvester и crawler. Запустите кластер с настроенным Kafka-экспортёром.	Экспортёр передаёт новые события в Пульт в реальном времени. История и новые события соединяются без разрыва.

Остановите сервисы harvester и crawler на время миграции

Сервисы читают топики Kafka и пишут в те же таблицы, что и утилита: harvester — по колонке server_id, crawler — по колонке source_id. Утилита требует, чтобы целевые таблицы для указанного server-id были пустыми. Работающий сервис наполняет таблицу и прерывает прогон ошибкой target tables already contain data for this server.

Кроме того, одновременная запись даёт гонки при генерации идентификаторов.

Остановите сервисы командой kubectl -n <namespace> scale deployment harvester crawler --replicas=0. Проверьте, что подов не осталось.

Шаги этапа 2

1. Выберите команду: migrate для полного архива из живого Operate, raw-migrate для среза по времени или когда Operate недоступен.

2. Для raw-migrate определите окно миграции: задайте --from и при необходимости --to. Начало окна не может быть раньше срока хранения индексов.

3. Проверьте доступы: ElasticSearch / OpenSearch и обе целевые базы.

4. Очистите целевые таблицы по server-id командой cleanup — отдельно для harvester и для crawler.

5. Выполните перенос одной командой. Она пишет в обе схемы за один проход.

6. Проверьте результат по таблице export_runs в обеих базах и в интерфейсе Пульта.

Опасно

Целевые таблицы должны быть пустыми для указанного --server-id. Утилита проверяет по пять таблиц в каждой схеме: history_process_definition, history_process_instance, history_execution_entity, history_variable_entity, history_incident_entity в crawler и definitions, process, activities, variables, incidents в harvester. Утилита также прерывает прогон, если в export_runs есть запись со статусом running или completed. Для повторного прогона сначала выполните cleanup.

Формат времени

Флаги --from и --to команды raw-migrate принимают три формата:

• 2026-05-01

• 2026-05-01T10:30

• 2026-05-01T10:30:00Z (RFC 3339)

Обе границы включаются в окно. Если --to не задан, переносятся все записи от --from до конца индекса.

Граница включительная

Значение --to=2026-05-01 означает момент 2026-05-01T00:00:00, а не «весь день 1 мая». Если переносите историю несколькими окнами подряд, помните: запись ровно на границе попадёт в оба окна. Повторный перенос идемпотентен — строки сливаются по ключу, дублей не будет.

Вариант A. Локальный запуск

Используйте локальный запуск для малых объёмов и для проверки доступов. Для больших объёмов используйте вариант B: длительный прогон в кластере устойчивее к обрыву сессии.

Требования

• Go версии 1.25.7 или новее.

• Сетевой доступ к ElasticSearch / OpenSearch и к обеим целевым базам. Для кластерных адресов используйте kubectl port-forward.

• Переменные прокси сняты. Внешний прокси не может обратиться к внутренним адресам.

Сборка

cd operate-to-pult
CGO_ENABLED=0 GOOS=linux go build -o build/exporter ./cmd
./build/exporter --help

Подготовка сессии

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxy

# Проброс портов, если сервисы работают в кластере
kubectl -n <namespace> port-forward svc/db 5432:5432 &
kubectl -n <namespace> port-forward svc/zeebe-elasticsearch 9200:9200 &

Очистка целевых схем

./build/exporter --server-id=banana-dev cleanup \
  --pipeline=harvester \
  --db-url='postgres://user:pass@localhost:5432/harvester?sslmode=disable' \
  --yes

./build/exporter --server-id=banana-dev cleanup \
  --pipeline=crawler \
  --db-url='postgres://user:pass@localhost:5432/crawler?sslmode=disable' \
  --yes

Перенос из индексов Operate

./build/exporter \
  --server-id=banana-dev \
  --elastic=http://localhost:9200 \
  --index-prefix=operate \
  --log-format=json \
  migrate \
  --crawler-db-url='postgres://user:pass@localhost:5432/crawler?sslmode=disable' \
  --harvester-db-url='postgres://user:pass@localhost:5432/harvester?sslmode=disable' \
  --server-version=8.5.0

Перенос из сырых индексов Zeebe

./build/exporter \
  --server-id=banana-dev \
  --elastic=http://localhost:9200 \
  --index-prefix=zeebe-record \
  --log-format=json \
  raw-migrate \
  --crawler-db-url='postgres://user:pass@localhost:5432/crawler?sslmode=disable' \
  --harvester-db-url='postgres://user:pass@localhost:5432/harvester?sslmode=disable' \
  --server-version=8.5.0 \
  --from=2026-05-01

Длительный прогон

Обрыв сессии прекращает прогон. Запускайте длительную миграцию через nohup или tmux. После обрыва выполните cleanup для обеих схем и запустите прогон заново: возобновление не поддерживается.

Вариант B. Запуск в Kubernetes

Требования

Требование	Описание
Образ	<реестр образов>/operate-to-pult:<тег>. Точку входа задавать не нужно: она уже задана в образе. Передавайте только args.
Права оператора	В целевом namespace: create, get, delete для jobs; get, list, log для pods.
ServiceAccount пода	Права в Kubernetes API не нужны. Утилита не обращается к API кластера. Используйте default.
Секреты	Секреты с логином и паролем Postgres должны лежать в том же namespace, что и Job.
Доступ к реестру	imagePullSecrets с доступом к реестру образов.
Сеть	Разрешите исходящий трафик к ElasticSearch / OpenSearch и Postgres. Проверьте NetworkPolicy.

Одна задача — один Pod

Разместите очистку в initContainers: Kubernetes выполняет init-контейнеры последовательно. Сам перенос разместите в containers. Задайте backoffLimit: 0. Иначе Kubernetes пересоздаст под целиком: init-контейнеры выполнят cleanup заново и молча сотрут результат прерванного прогона, начав миграцию с нуля. Перезапуск должен быть осознанным действием оператора.

Пример манифеста

Манифест выполняет полную миграцию в таком порядке: очистка схемы harvester, очистка схемы crawler, перенос данных.

apiVersion: batch/v1
kind: Job
metadata:
  name: operate2pult-migrate-banana-dev
  namespace: krf
spec:
  backoffLimit: 0
  activeDeadlineSeconds: 86400   # предел 24 часа
  template:
    spec:
      restartPolicy: Never
      imagePullSecrets:
        - name: docker-registry-secret

      initContainers:
        - name: cleanup-harvester
          image: <реестр образов>/operate-to-pult:<тег>
          args:
            - --server-id=banana-dev
            - --log-format=json
            - cleanup
            - --pipeline=harvester
            - --yes
          env:
            - name: HARVESTER_PG_USER
              valueFrom:
                secretKeyRef: { name: harvester.db.credentials, key: username }
            - name: HARVESTER_PG_PASS
              valueFrom:
                secretKeyRef: { name: harvester.db.credentials, key: password }
            - name: POSTGRES_URL
              value: "postgres://$(HARVESTER_PG_USER):$(HARVESTER_PG_PASS)@db:5432/harvester?sslmode=require"
          resources:
            requests: { cpu: 100m, memory: 128Mi }
            limits:   { cpu: "1",  memory: 512Mi }

        - name: cleanup-crawler
          image: <реестр образов>/operate-to-pult:<тег>
          args:
            - --server-id=banana-dev
            - --log-format=json
            - cleanup
            - --pipeline=crawler
            - --yes
          env:
            - name: CRAWLER_PG_USER
              valueFrom:
                secretKeyRef: { name: crawler.db.credentials, key: username }
            - name: CRAWLER_PG_PASS
              valueFrom:
                secretKeyRef: { name: crawler.db.credentials, key: password }
            - name: POSTGRES_URL
              value: "postgres://$(CRAWLER_PG_USER):$(CRAWLER_PG_PASS)@db:5432/crawler?sslmode=require"
          resources:
            requests: { cpu: 100m, memory: 128Mi }
            limits:   { cpu: "1",  memory: 512Mi }

      containers:
        - name: migrate
          image: <реестр образов>/operate-to-pult:<тег>
          args:
            - --server-id=banana-dev
            - --elastic=https://<адрес ES>:9200
            - --index-prefix=operate       # индексы Operate, не zeebe-record
            - --log-format=json
            - migrate
            - --es-page-size=1000
          env:
            - name: CRAWLER_PG_USER
              valueFrom:
                secretKeyRef: { name: crawler.db.credentials, key: username }
            - name: CRAWLER_PG_PASS
              valueFrom:
                secretKeyRef: { name: crawler.db.credentials, key: password }
            - name: HARVESTER_PG_USER
              valueFrom:
                secretKeyRef: { name: harvester.db.credentials, key: username }
            - name: HARVESTER_PG_PASS
              valueFrom:
                secretKeyRef: { name: harvester.db.credentials, key: password }
            - name: CRAWLER_POSTGRES_URL
              value: "postgres://$(CRAWLER_PG_USER):$(CRAWLER_PG_PASS)@db:5432/crawler?sslmode=require"
            - name: HARVESTER_POSTGRES_URL
              value: "postgres://$(HARVESTER_PG_USER):$(HARVESTER_PG_PASS)@db:5432/harvester?sslmode=require"
          resources:
            requests: { cpu: 500m, memory: 512Mi }
            limits:   { cpu: "2",  memory: 8Gi }

Вариант для raw-migrate

Замените в главном контейнере --index-prefix=operate на --index-prefix=zeebe-record, команду migrate — на raw-migrate и добавьте обязательный --from=2026-05-01. Остальные контейнеры и переменные окружения не меняются.

Готовый манифест для стенда лежит в репозитории платформы: c8-extensions/operate-to-pult/JobMigrate.yaml.

Запуск и наблюдение

kubectl -n <namespace> apply -f JobMigrate.yaml
kubectl -n <namespace> get job operate2pult-migrate-banana-dev -w

# Логи переноса
kubectl -n <namespace> logs -f job/operate2pult-migrate-banana-dev -c migrate

Что искать в логах:

Строка	Команда	Значение
stage starting stage=<name> / stage done stage=<name>	migrate	Границы этапов переноса. В строке stage done есть heap_alloc_mb и heap_sys_mb — по ним видно фактический расход памяти.
progress stage=… processed=N total=M elapsed=… eta=… finish_at=…	обе	Пишется раз в 10 секунд, содержит прогноз окончания.
copy chunk committed table=… rows=… elapsed=…	обе	Каждый сброс буфера в Postgres.
migrate done server_id=… row_counts={…}	migrate	Последняя строка успешного прогона.
raw-migrate done crawler_row_counts={…} harvester_row_counts={…}	raw-migrate	Последняя строка успешного прогона: счётчики строк отдельно по каждой схеме.

Проверьте лимит памяти

Под с превышением лимита получает OOMKilled. Прогон остаётся в статусе running. Увеличьте лимит памяти либо, для raw-migrate, уменьшите --copy-chunk-size. Затем выполните cleanup для обеих схем и повторите прогон.

Перезапуск задачи

kubectl -n <namespace> delete job operate2pult-migrate-banana-dev
kubectl -n <namespace> apply -f JobMigrate.yaml

Манифест начинается с шагов cleanup. Поэтому повторный запуск безопасен.

Повторный прогон и очистка

Команда cleanup удаляет все строки одного --server-id из таблиц выбранной схемы. Команда освобождает server_tag для схемы crawler и помечает записи в export_runs статусом cleaned. Все действия выполняются в одной транзакции. Команду можно запускать многократно.

# Проверить параметры без изменений в базе
./build/exporter --server-id=banana-dev cleanup \
  --pipeline=harvester \
  --db-url='postgres://user:pass@localhost:5432/harvester?sslmode=disable'

# Выполнить удаление
./build/exporter --server-id=banana-dev cleanup \
  --pipeline=harvester \
  --db-url='postgres://user:pass@localhost:5432/harvester?sslmode=disable' \
  --yes

Опасно

Без флага --yes команда выводит план и завершается без изменений. С флагом --yes команда удаляет данные без дополнительного вопроса. Проверьте значение --server-id и адрес базы перед запуском.

Запускайте cleanup отдельно для каждой схемы: harvester и crawler — это разные базы данных. Команде не нужны --elastic и --index-prefix.

Проверка результата

Выполните запрос в каждой из двух целевых баз: прогон записывается в обе.

SELECT id, pipeline, status, es_from, es_to, started_at, finished_at, row_counts
FROM export_runs
WHERE server_id = 'banana-dev'
ORDER BY started_at DESC
LIMIT 5;

Поле	Ожидаемое значение
pipeline	crawler в базе crawler, harvester в базе harvester.
status	completed. Статус failed означает ошибку прогона. Статус running означает прерванный прогон.
es_from, es_to	Границы окна для raw-migrate. Для migrate остаются пустыми: окно не задаётся.
row_counts	JSON с числом строк по каждой таблице. Нулевые значения означают пустое окно миграции.
failed_table	NULL для успешного прогона.
error_message	NULL для успешного прогона.

Дополнительно проверьте, что таблицы o2p_stg_% отсутствуют:

SELECT tablename FROM pg_tables WHERE tablename LIKE 'o2p\_stg\_%';

Утилита удаляет staging-таблицы даже при ошибке. Оставшиеся таблицы означают аварийное завершение процесса. Удалите их вручную.

Затем откройте Пульт и проверьте историю процессов выбранного сервера.

Типовые ошибки

Сообщение	Причина	Решение
target tables already contain data for this server	В целевых таблицах уже есть строки этого server-id. Сообщение содержит имя таблицы.	Выполните cleanup для этой схемы. Затем повторите прогон.
an export run for this server already exists	В export_runs есть прогон со статусом running или completed.	Выполните cleanup. Команда пометит прогон как cleaned.
server_tags table is full (32 servers per database)	В базе crawler уже 32 сервера. Ключи сущностей используют 5-битный тег.	Освободите тег командой cleanup для ненужного сервера. Либо используйте другую базу.
--elastic is required for migrate	Не задан адрес хранилища-источника.	Задайте --elastic перед именем команды. Это глобальный флаг.
--elastic and --index-prefix are required for raw-migrate	Не заданы адрес хранилища-источника или префикс индекса.	Задайте оба флага перед именем команды. Это глобальные флаги.
Required flag "crawler-db-url" not set (или harvester-db-url)	Задан только один DSN.	Обе команды переноса пишут в обе схемы, нужны оба DSN.
kafka-broker and kafka-topic are required for this command	Команда export или definitions запущена без параметров Kafka.	Задайте --kafka-broker и --kafka-topic.
missing-entries did not converge within cap; proceeding	Предупреждение raw-migrate: за --missing-cap итераций ссылки на модели и родительские экземпляры не разрешились.	Увеличьте --missing-cap. Если записи удалены политикой retention, используйте migrate.
Прогон завершился, но данных нет	Префикс индекса не совпадает с реальным именем индексов.	Проверьте имена: curl 'http://es-host:9200/_cat/indices?v'. Для migrate и definitions нужен префикс Operate, для raw-migrate — префикс экспортёра Zeebe.
circuit_breaking_exception от хранилища-источника	Кластер перегружен длинным scroll-запросом.	Для migrate уменьшите --es-page-size (по умолчанию 1000). Для raw-migrate до версии 1.1.7 этот флаг на чтение не влияет: сузьте окно миграции и перенесите данные частями.

Ограничения текущей версии

• Возобновление прогона не поддерживается. Флаг --resume команды export завершает работу с ошибкой not supported yet.

• Прогон нельзя продолжить с места обрыва: после сбоя нужен cleanup обеих схем и полный повторный прогон.

• Поле business_key:

  • migrate — заполняется, если задан --business-key-mapping (переменная BUSINESS_KEY_MAPPING). Формат правил тот же, что у crawlerConfig.businessKeyMapping;
  • raw-migrate — флага нет, поле остаётся пустым.

• Часть полей схемы pult-data-model вычисляется из уже загруженных данных, и утилита их не заполняет. Начиная с версии 1.1.6 их догоняют backfill-раннеры сервисов harvester и crawler: они включены по умолчанию, выполняются по одному и после успешного прохода отмечаются в таблице backfill_state, поэтому рестарт пода не запускает полный скан заново. После миграции делать ничего не нужно.

  В версии 1.1.5 раннеры выключены по умолчанию. Включите нужные — LAST_ACTIVITY_BACKFILL_ENABLED=true для process.last_activity и DEFINITION_ELEMENTS_BACKFILL_ENABLED=true для таблицы definition_elements — дождитесь окончания работы и снимите флаги: отметки о завершении в этой версии нет, и при каждом рестарте пода полный скан повторяется. Имена переменных общие у harvester и crawler, поэтому задавайте их адресно нужному сервису, например kubectl set env deploy/krf-harvester LAST_ACTIVITY_BACKFILL_ENABLED=true. Если прописать переменную в общие значения чарта, раннеры запустятся в обоих сервисах и в двух разных базах.

• Фильтр --tenant-id есть только у migrate.

• Для Kafka доступен только механизм SASL SCRAM-SHA-256. Настройка TLS отсутствует.

• Логин и пароль хранилища-источника задаются только внутри URL.

• Одна база crawler вмещает данные 32 серверов и до 128 партиций на сервер.

Справочник параметров

Глобальные флаги

Задаются перед именем команды.

Флаг	Переменная	По умолчанию	Назначение
--server-id (обязательный)	SERVER_ID	—	Имя сервера в Пульте.
--elastic	ELASTIC_SERVER	—	Адрес ElasticSearch / OpenSearch. Обязателен для команд чтения данных.
--index-prefix	ELASTIC_INDEX_PREFIX	—	Префикс имени индекса. Обязателен для raw-migrate. У migrate при пустом значении подставляется operate. Командам export и definitions нужен фактически, но проверки нет. Команда cleanup его не использует.
--log-level	LOG_LEVEL	info	Уровень логирования: debug, info, warn, error.
--log-format	LOG_FORMAT	text	Формат логов: text или json. Для Kubernetes используйте json.
--kafka-broker	KAFKA_BROKER	—	Адреса брокеров. Только для export и definitions.
--kafka-topic	KAFKA_TOPIC	—	Имя топика. Только для export и definitions.
--kafka-user, --kafka-password	KAFKA_USER, KAFKA_PASSWORD	—	Учётные данные SASL SCRAM-SHA-256.
--chunk	ELASTIC_CHUNK_SIZE	1000	Размер страницы при чтении. Учитывается только командами export и definitions; у команд переноса за это отвечает --es-page-size.
--offset	ELASTIC_OFFSET	0	Число пропускаемых записей. Только для export и definitions.
--no-save-progress	NO_SAVE_PROGRESS	false	Отключает запись файла .export_offset. Только для export и definitions.

Флаги команды migrate

Флаг	Переменная	По умолчанию	Назначение
--crawler-db-url (обязательный)	CRAWLER_POSTGRES_URL	—	DSN базы со схемой crawler.
--harvester-db-url (обязательный)	HARVESTER_POSTGRES_URL	—	DSN базы со схемой harvester.
--server-version	SERVER_VERSION	—	Версия исходного сервера Camunda. Записывается в строку данных.
--tenant-id	TENANT_ID	—	Фильтр по tenantId. Пустое значение — все тенанты.
--copy-chunk-size	COPY_CHUNK_SIZE	200 000	Потолок размера буфера COPY. Применяется, только если меньше табличного значения.
--es-page-size	ES_PAGE_SIZE	1000	Размер scroll-страницы при чтении индексов Operate.
--business-key-mapping	BUSINESS_KEY_MAPPING	—	JSON-массив правил заполнения business_key. Пример: [{"processMask":".*","servers":["banana-dev"],"variable":"orderId"}].
--aggressive-gc	AGGRESSIVE_GC	false	Возвращать память операционной системе между этапами.

Флаги команды raw-migrate

Флаг	Переменная	По умолчанию	Назначение
--crawler-db-url (обязательный)	CRAWLER_POSTGRES_URL	—	DSN базы со схемой crawler.
--harvester-db-url (обязательный)	HARVESTER_POSTGRES_URL	—	DSN базы со схемой harvester.
--from (обязательный)	ELASTIC_EXPORT_FROM	—	Начало окна миграции, включительно.
--to	ELASTIC_EXPORT_TO	—	Конец окна миграции, включительно. Без флага — до конца индекса. Во встроенной справке --help версий до 1.1.7 граница ошибочно названа исключительной.
--server-version	SERVER_VERSION	—	Версия исходного сервера Camunda. Записывается в строку данных.
--copy-chunk-size	COPY_CHUNK_SIZE	200 000	Размер буфера COPY. Не влияет на definitions и variables.
--es-page-size	ES_PAGE_SIZE	1000	Размер scroll-страницы при чтении сырых индексов. Действует с версии 1.1.7. В более ранних версиях флаг принимается, но размер страницы не меняет.
--missing-cap	MISSING_CAP	10	Максимум итераций фазы missing-entries.
--aggressive-gc	AGGRESSIVE_GC	false	Возвращать память операционной системе между фазами.

Флаги команды cleanup

Флаг	Переменная	По умолчанию	Назначение
--db-url (обязательный)	POSTGRES_URL	—	DSN целевой базы.
--pipeline (обязательный)	PIPELINE	—	Схема очистки: harvester или crawler.
--yes	—	false	Подтверждает удаление. Без флага команда выводит план и завершается.

Изменения по версиям

Версия утилиты совпадает с версией платформы Камунда.РФ и печатается первой строкой лога.

Версия	Изменение
1.1.7 (в подготовке)	--es-page-size начинает действовать в команде raw-migrate. Встроенная справка --to приведена в соответствие с поведением: граница окна включительная. Устранены сбои и зависания прогона raw-migrate, запись приведена в соответствие со схемой приёмника.
1.1.6	Backfill-раннеры сервисов harvester и crawler включены по умолчанию и отмечаются в таблице backfill_state. Включать их на время миграции и снимать флаг после прогона больше не нужно.
1.1.3	Команды to-crawler и to-harvester заменены на migrate и raw-migrate. DSN приёмников задаются раздельно: --crawler-db-url и --harvester-db-url.