Инструкция по обновлению Monq до версии 9.3.0

В этом обновлении

Модуль	Новая версия
pl	9.3.0
sm	9.3.0
cl	9.3.0
fm	9.3.0
mcs	9.3.0
plugins	9.3.0

Уровень простоя

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

ВНИМАНИЕ

В рамках обновления выполняется перенос файловых хранилищ с NFS в S3. Перед обновлением подготовьте инфраструктуру S3 хранилища!

На время миграции:

старые сборки автотестов могут быть недоступны в течение длительного времени из-за продолжительной перекачки файлов
аватарки пользователей могут быть кратковременно недоступны

ВАЖНО

До завершения миграции все переносимые файлы будут недоступны обновлённым сервисам. Новые версии сервисов читают файлы из S3 и не смогут получить их, пока данные остаются только в NFS.

Ограничение затрагивает:

файлы сборок проектов — fm-projects-api-service
файлы учётных записей (иконки) — pl-identity-service
файлы пространств (иконки) — pl-userspaces-api-service
вложенные файлы RSM — sm-rsm-attached-files-service
сценарии контент-паков — pl-content-installer-service
плагины агентов — pl-agents-service-scheduler

Особое внимание следует уделить контент-пакам и плагинам агентов: они станут доступны только после того, как сервис pl-s3-migrator перенесёт соответствующие файлы в S3.

Проведение миграции 9.2.1 → 9.3.0

Требования

Требуемая версия Monq: 9.2.1

Требуемая версия monqctl: 1.19.2

Для запуска обновления требуется скачать клиент управления Monq monqctl и выполнить конфигурацию контекста monqctl, если ранее не выполнялось.

Для установки новой версии monqctl выполните:

curl -fsSL https://downloads.monq.ru/tools/monqctl/v1.19.2/linux-x64/monqctl.zip -o /tmp/monqctl.zip && unzip -oq /tmp/monqctl.zip -d /usr/local/bin && rm -f /tmp/monqctl.zip

Выполнить предрелизную подготовку

Проверить контекст monqctl и статус реестра микросервисов

# Просмотреть текущий контекст, с которым работает monqctl
monqctl config current-context

# Просмотреть статус реестра микросервисов из контекста
monqctl registry get status

# Просмотреть статус сервисов в реестре микросервисов из контекста
monqctl registry get services

Выполнить обновление реестра микросервисов

monqctl registry update registry --version=3.20.0.1

Закрытый контур / обновление из папки

На системе с доступом к сети интернет, установленном и настроенном monqctl, выполнить экспорт реестра микросервисов в локальную директорию

monqctl registry export registry 3.20.0.1 --dest=./<registry export directory>

После переноса папки на сервер выполнить обновление реестра микросервисов

monqctl registry update registry --version=3.20.0.1 --sourceDir=<папка с экспортированным обновлением>

Проверить статус реестра микросервисов

monqctl registry get status

Дождаться

пока команда monqctl registry get status выдаст обновленную версию:
Version: "3.20.0.1"

Настроить S3 для реестра микросервисов

Значения заменить параметрами целевого окружения. Проверить доступность S3 из кластера и убедиться, что квота бакета позволяет разместить все данные из /storage в NFS, примонтированного в Kubernetes.

Если S3-хранилище развёрнуто по стандартной инструкции MONQ, используйте:

S3_REGION="production"
S3_BUCKET="monq"

Если используется существующее или самостоятельно настроенное S3-хранилище, уточните значения у администратора S3:

S3_REGION — регион, заданный при развёртывании S3-инстанса. Значение зависит от конфигурации хранилища, например us-east-1, eu, production.
S3_BUCKET — предварительно созданный бакет для хранения данных MONQ.

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

# Заменить значения перед запуском.
S3_ENDPOINT="<endpoint>"
S3_PORT=3900
S3_ACCESS_KEY="<access-key>"
S3_SECRET_KEY="<secret-key>"
S3_REGION="production"
S3_BUCKET="monq"
S3_WITH_SSL=false

S3_CONFIG="$(mktemp)"
trap 'rm -f -- "$S3_CONFIG"' EXIT

monqctl registry get services S3 --output=json |
  jq \
    --arg endpoint "$S3_ENDPOINT" \
    --argjson port "$S3_PORT" \
    --arg accessKey "$S3_ACCESS_KEY" \
    --arg secretKey "$S3_SECRET_KEY" \
    --arg region "$S3_REGION" \
    --arg bucket "$S3_BUCKET" \
    --argjson withSSL "$S3_WITH_SSL" \
    '.JsonConfig += {
      Endpoint: $endpoint,
      Port: $port,
      AccessKey: $accessKey,
      SecretKey: $secretKey,
      Region: $region,
      Bucket: $bucket,
      WithSSL: $withSSL
    }' > "$S3_CONFIG" &&
  monqctl registry apply service S3 --file "$S3_CONFIG"

monqctl registry get services S3 --output=json |
  jq '.JsonConfig |= del(.AccessKey, .SecretKey)'

Проверить доступность сервиса S3:

monqctl registry get services | grep -a S3

Установить контекст релиза, с которым будет работать `monqctl` в рамках контекста установленного Monq

Команда при этом скачивает и подготавливает релиз для установки.

monqctl release use-version 9.3.0 --product=monq

Закрытый контур / обновление из папки

На системе с доступом к сети интернет, установленном и настроенном monqctl, выполнить экспорт релиза в папку

monqctl release version export 9.3.0 --product=monq --dest=<export directory>

После переноса папки на сервер выполнить команду с аргументом --sourceDir

monqctl release use-version 9.3.0 --product=monq --sourceDir=<папка с экспортированным обновлением>

MONQ Platform (pl)

Выполнить импорт контейнеров

monqctl release update images --module=pl

Обновить локализацию

monqctl release update db pgsql --module=pl --microservice=pl-i18n-service --file pl-i18n-service.sql

Остановить работу сервиса fm-projects-api-service

Требуется остановить сервис перед миграцией на S3 из-за возможного расхождения ключей RabbitMq

monqctl instance scale deployment fm-projects-api-service --replicas=0
monqctl instance clear cache --microservice=fm-projects-api-service

Выполнить обновление контент-паков

monqctl release update content-packs --module=plugins --replace --file=content-packs/linux.zip
monqctl release update content-packs --module=plugins --replace --file=content-packs/max.zip
monqctl release update content-packs --module=plugins --replace --file=content-packs/windows.zip
monqctl release update content-packs --module=plugins --replace --file=content-packs/k8s.zip

Выполнить обновление и конфигурацию микросервисов

Вместе с этим обновлением запустится сервис-мигратор pl-s3-migrator. Он создаст конфигурацию для себя в Consul и начнет копирование файлов из NFS хранилища в S3 в фоне. На этом этапе можно продолжить обновление компонентов дальше.

monqctl release update microservices --module=pl

Применить обновление маршрутизации

monqctl release update routing --module=pl

Продолжать только при пустом выводе команды:

watch "kubectl get pod -A | grep -v Running"

Выполнить обновление библиотеки Automaton v2

monqctl release update automaton-libraries --module=pl --file=automaton-libs/automaton.fm.autotests.import
monqctl release update automaton-libraries --module=pl --file=automaton-libs/automaton.metrics.import

При появлении ошибки повторить команду через небольшую паузу: pl-automaton-v2-service мог не успеть перезапуститься либо обновление библиотеки уже выполняется.

Перезапустить сервисы Automaton v2

monqctl instance restart microservice --microservice=pl-automaton-v2-service
monqctl instance restart microservice --microservice=pl-automaton-v2-processor-service-compiler
monqctl instance restart microservice --microservice=pl-automaton-v2-processor-service
monqctl instance restart microservice --microservice=pl-automaton-v2-processor-service-runner

Сбросить кэш сервисов локализации и идентификации

monqctl instance clear cache --microservice=pl-i18n-service
monqctl instance clear cache --microservice=pl-identity-service

Удалить устаревшую очередь и привязки ключей маршрутизации

monqctl instance delete queue pl_events_history_api_service_tags
monqctl instance delete queue-binding --queue=pl_automaton_v2_service --bindingKey=cl.automaton-parser.log.scenario
monqctl instance delete queue-binding --queue=pl_automaton_v2_service --bindingKey=cl.automaton-parser.log.debug

MONQ Service Monitor (sm)

Выполнить импорт контейнеров

monqctl release update images --module=sm

Выполнить конфигурацию базы данных

monqctl release update db pgsql --module=sm --microservice=sm-rsm-maps-service --file sqls/sm-rsm-maps-service.sql

Выполнить обновление и конфигурацию микросервисов

monqctl release update microservices --module=sm

Продолжать только при пустом выводе команды:

watch "kubectl get pod -A | grep -v Running"

Запустить миграцию данных

monqctl release update migrator --module=sm --command="migrate rsm-config-items"

MONQ Collector (cl)

Выполнить импорт контейнеров

monqctl release update images --module=cl

Выполнить обновление и конфигурацию микросервисов

monqctl release update microservices --module=cl

Продолжать только при пустом выводе команды:

watch "kubectl get pod -A | grep -v Running"

Test Forge (fm)

Выполнить импорт контейнеров

monqctl release update images --module=fm

Выполнить конфигурацию базы данных ClickHouse

monqctl release update db clickhouse --module=fm --microservice=fm-projects-api-service --file sqls/fm-projects-api-service-clickhouse.sql
monqctl release update db pgsql --module=fm --microservice=fm-projects-api-service --file sqls/fm-projects-api-service.sql

Выполнить обновление и конфигурацию микросервисов

monqctl release update microservices --module=fm

Продолжать только при пустом выводе команды:

watch "kubectl get pod -A | grep -v Running"

Запустить сервис fm-projects-api-service

monqctl instance scale deployment fm-projects-api-service --replicas=1

MONQ Metrics (mcs)

Внимание

Перед применением SQL рекомендуется создать резервную копию БД mcs-thresholds-service в PostgreSQL. Миграция удаляет устаревшие таблицы и колонки, а также очищает таблицу ForecastModels.

Выполнить импорт контейнеров

monqctl release update images --module=mcs

Выполнить конфигурацию баз данных PostgreSQL и ClickHouse

monqctl release update db pgsql --module=mcs --microservice=mcs-thresholds-service --file sqls/mcs-thresholds-service.sql
monqctl release update db pgsql --module=mcs --microservice=mcs-thresholds-service --file sqls/mcs-thresholds-service-2.sql
monqctl release update db pgsql --module=mcs --microservice=mcs-thresholds-service --file sqls/mcs-thresholds-service-3.sql
monqctl release update db pgsql --module=mcs --microservice=mcs-thresholds-service --file sqls/mcs-thresholds-service-4.sql
monqctl release update db clickhouse --module=mcs --microservice=mcs-thresholds-service --file sqls/mcs-thresholds-service-clickhouse.sql

Выполнить обновление и конфигурацию микросервисов

monqctl release update microservices --module=mcs

Продолжать только при пустом выводе команды:

watch "kubectl get pod -A | grep -v Running"

Выполнить обновление набора прав

monqctl release update user-grants --module=mcs --file=user-grants.json

Сбросить кэш для микросервисов

monqctl instance clear cache --microservice=pl-work-groups-api-service

PLUGINS (plugins)

В релизе обновляются только контейнеры микросервисов.

Выполнить импорт контейнеров

monqctl release update images --module=plugins

Выполнить обновление микросервисов

monqctl release update microservices --module=plugins

Продолжать только при пустом выводе команды:

watch "kubectl get pod -A | grep -v Running"

Проверка миграции данных в S3

Дождаться завершения работы пода pl-s3-migrator и проверить его логи. При успешном завершении должна появиться запись следующего вида:

[2026-09-01 12:53:35 +00:00 INF] Migration completed. Total: 100, Migrated: 100, Failed: 0

Миграция считается успешной, если:

Migrated совпадает с Total;
Failed равно 0;
перенесённые данные доступны в целевом бакете.

Внимание

При ошибке миграции не удалять сервис pl-s3-migrator и данные из NFS. Сохранить логи и устранить причину ошибки, затем повторить проверку.

После успешной проверки перезагрузить сервисы, которые при старте кэшируют некоторые метаданные из ФС в памяти:

monqctl instance restart microservice --microservice=pl-content-installer-service
monqctl instance restart microservice --microservice=pl-agents-service

Удалить временный сервис миграции файлов:

monqctl registry delete microservice pl-s3-migrator

Очистка данных в NFS

КРИТИЧЕСКИ ВАЖНО

Выполнять очистку только после успешного завершения pl-s3-migrator, проверки Migrated = Total, Failed = 0, проверки доступности данных в S3 и функционального тестирования сервисов. Удаление данных необратимо.

Перед выполнением рекомендуется создать резервную копию NFS.

Вручную удалить данные из NFS по следующим путям:

Путь в NFS	Сервис	Причина удаления
`/storage/fm-builds-aggregator-api-service`	`fm-builds-aggregator-api-service`	Устаревшие данные
`/storage/fm-data-api-service`	`fm-data-api-service`	Данные перенесены в S3
`/storage/pl-identity-management-service`	`pl-identity-management-service`	Функциональность перенесена в `pl-identity-service`
`/storage/pl-identity-service`	`pl-identity-service`	Данные перенесены в S3
`/storage/pl-userspaces-api-service`	`pl-userspaces-api-service`	Данные перенесены в S3
`/storage/pl-content-installer-service`	`pl-content-installer-service`	Данные перенесены в S3
`/storage/pl-agents-service-scheduler`	`pl-agents-service-scheduler`	Данные перенесены в S3
`/storage/mcs-thresholds-service`	`mcs-thresholds-service`	Перенос данных в S3 не требуется
`/storage/sm-rsm-attached-files-service`	`sm-rsm-attached-files-service`	Данные перенесены в S3

В этом обновлении​

Проведение миграции 9.2.1 → 9.3.0​

Требования​

Выполнить предрелизную подготовку​

Проверить контекст monqctl и статус реестра микросервисов​

Выполнить обновление реестра микросервисов​

Проверить статус реестра микросервисов​

Настроить S3 для реестра микросервисов​

Установить контекст релиза, с которым будет работать monqctl в рамках контекста установленного Monq​

MONQ Platform (pl)​

Выполнить импорт контейнеров​

Обновить локализацию​

Остановить работу сервиса fm-projects-api-service​

Выполнить обновление контент-паков​

Выполнить обновление и конфигурацию микросервисов​

Применить обновление маршрутизации​

Выполнить обновление библиотеки Automaton v2​

Перезапустить сервисы Automaton v2​

Сбросить кэш сервисов локализации и идентификации​

Удалить устаревшую очередь и привязки ключей маршрутизации​

MONQ Service Monitor (sm)​

Выполнить импорт контейнеров​

Выполнить конфигурацию базы данных​

Выполнить обновление и конфигурацию микросервисов​

Запустить миграцию данных​

MONQ Collector (cl)​

Выполнить импорт контейнеров​

Выполнить обновление и конфигурацию микросервисов​

Test Forge (fm)​

Выполнить импорт контейнеров​

Выполнить конфигурацию базы данных ClickHouse​

Выполнить обновление и конфигурацию микросервисов​

Запустить сервис fm-projects-api-service​

MONQ Metrics (mcs)​

Выполнить импорт контейнеров​

Выполнить конфигурацию баз данных PostgreSQL и ClickHouse​

Выполнить обновление и конфигурацию микросервисов​

Выполнить обновление набора прав​

Сбросить кэш для микросервисов​

PLUGINS (plugins)​

Выполнить импорт контейнеров​

Выполнить обновление микросервисов​

Проверка миграции данных в S3​

Очистка данных в NFS​

В этом обновлении

Проведение миграции 9.2.1 → 9.3.0

Требования

Выполнить предрелизную подготовку

Проверить контекст monqctl и статус реестра микросервисов

Выполнить обновление реестра микросервисов

Проверить статус реестра микросервисов

Настроить S3 для реестра микросервисов

Установить контекст релиза, с которым будет работать `monqctl` в рамках контекста установленного Monq

MONQ Platform (pl)

Выполнить импорт контейнеров

Обновить локализацию

Остановить работу сервиса fm-projects-api-service

Выполнить обновление контент-паков

Выполнить обновление и конфигурацию микросервисов

Применить обновление маршрутизации

Выполнить обновление библиотеки Automaton v2

Перезапустить сервисы Automaton v2

Сбросить кэш сервисов локализации и идентификации

Удалить устаревшую очередь и привязки ключей маршрутизации

MONQ Service Monitor (sm)

Выполнить импорт контейнеров

Выполнить конфигурацию базы данных

Выполнить обновление и конфигурацию микросервисов

Запустить миграцию данных

MONQ Collector (cl)

Выполнить импорт контейнеров

Выполнить обновление и конфигурацию микросервисов

Test Forge (fm)

Выполнить импорт контейнеров

Выполнить конфигурацию базы данных ClickHouse

Выполнить обновление и конфигурацию микросервисов

Запустить сервис fm-projects-api-service

MONQ Metrics (mcs)

Выполнить импорт контейнеров

Выполнить конфигурацию баз данных PostgreSQL и ClickHouse

Выполнить обновление и конфигурацию микросервисов

Выполнить обновление набора прав

Сбросить кэш для микросервисов

PLUGINS (plugins)

Выполнить импорт контейнеров

Выполнить обновление микросервисов

Проверка миграции данных в S3

Очистка данных в NFS