Миграция со старой версии LCM

Важно

Миграция возможна только на версии ks2026.2.1 и выше.

При переходе со старой (pre-k0s) версии LCM на версию в режиме k0s (см. Установка инсталлятора) данные перечисленных ниже сервисов LCM переносятся вручную с помощью скрипта migrate_services.sh:

  • GitLab — полная резервная копия (база данных, конфигурация gitlab.rb и секреты gitlab-secrets.json);

  • NetBox — миграция базы данных через экспорт и импорт SQL, а также перенос медиафайлов;

  • Nexus — полная резервная копия и восстановление содержимого /nexus-data (репозитории и встроенная БД).

Секреты Vault через migrate_services.sh не переносятся: в Vault нового LCM отдельно копируются только секреты региона — утилитой koc (см. Перенос секретов региона в Vault нового LCM).

Общая схема перехода

Переход выполняется в несколько этапов и предполагает, что старый и новый LCM работают одновременно на разных узлах до перевода потребителей на новый LCM:

  1. Проверка предварительных требований.

  2. Резервное копирование сервисов на старом LCM.

  3. Перенос резервных копий на новый LCM.

  4. Восстановление сервисов на новом LCM.

  5. Наполнение LCM данными (upload.sh).

  6. Переезд на новую доменную зону.

  7. Финальная проверка.

Важно

  • Все действия на старом LCM выполняются от имени пользователя root.

  • Все действия на новом LCM выполняются от имени пользователя, установившего новый LCM (например, kolla).

  • Версии GitLab и Nexus на новом LCM должны совпадать с версиями на старом LCM. Скрипт проверяет совпадение версий и прерывает восстановление при расхождении.

  • Восстановление должно выполняться на том же узле, на котором выполнялась установка нового LCM.

Предварительные требования

Перед началом миграции убедитесь, что выполнены следующие условия.

  1. Спланируйте место под данные Nexus:

    • Проверьте фактический размер данных Nexus на старом LCM: командой docker exec nexus du -sh /nexus-data или в веб-интерфейсе Nexus в разделе Administration > Repository > Blob Stores (используемый объём blob store).

    • При подготовке lcm-config.yaml нового LCM задайте размер тома Nexus больше этого значения с учётом последующих обновлений — параметр nexus_pv_size. Значение применяется при установке, поэтому задайте его до развёртывания нового LCM.

    • Убедитесь в наличии свободного места под резервную копию Nexus на старом узле (/root/service_backups) и на новом (~/service_backups) — ориентировочно по размеру данных Nexus на каждом.

  2. Разверните новый LCM:

    • Убедитесь, что инфраструктура соответствует требованиям.

    • Установите новый (k0s) LCM полностью по инструкции Установка инсталлятора: кластер k0s поднят, все сервисы (Vault, GitLab, NetBox, Nexus) запущены, upload.sh запускать не надо.

    Восстановление выполняется поверх уже работающих сервисов и завершится ошибкой, если необходимые Kubernetes-секреты ещё не созданы.

  3. Проверьте совпадение версий сервисов — версии GitLab и Nexus на новом LCM должны совпадать с версиями на старом:

    • GitLab — версия должна совпадать точно.

    • Nexus — версия кластера должна быть не ниже версии из резервной копии (Nexus автоматически мигрирует встроенную БД только вперёд; понижение версии не поддерживается).

  4. Подготовьте учётные данные и доступы:

    • GitLab — пароль пользователя root и пароль пользователя ks-admin.

    • NetBox — пароль пользователя admin.

    • Nexus — пароль пользователя admin.

    • Vault — доступ к Vault старого и нового LCM для переноса секретов региона утилитой koc (approle role-id/secret-id каждого Vault).

    Пароли GitLab, NetBox и Nexus запрашиваются восстановлением в интерактивном режиме и проверяются на соответствие восстановленным данным, поэтому вводите текущие пароли из старой установки.

  5. Обеспечьте сетевой доступ:

    • SSH-доступ к старому LCM-узлу (пользователь root) и к новому LCM-узлу (пользователь установки).

    • Возможность скопировать директорию с резервными копиями со старого узла на новый.

    • Доступ к системе управления DNS — для регистрации записей новой доменной зоны и перевода потребителей на новый LCM (этап 5).

Скрипт migrate_services.sh

Все операции резервного копирования и восстановления выполняются одним скриптом migrate_services.sh, который входит в состав нового (k0s) инсталлятора и находится в его корневой директории.

Примечание

Резервное копирование выполняется на старом LCM-узле. Если скрипта migrate_services.sh в его инсталляторе ещё нет (зависит от версии старого инсталлятора), скопируйте скрипт с нового инсталлятора на старый узел (см. этап 1). Для режима backup достаточно самого файла скрипта — файл конфигурации lcm-config.yaml требуется только для режима restore на новом узле.

Формат команды:

# Резервное копирование
$ bash migrate_services.sh backup [service]

# Восстановление
$ bash migrate_services.sh restore [service] lcm-k0s/lcm-config.yaml

Параметры команды:

  • backup|restore — режим работы скрипта: резервное копирование (backup) или восстановление (restore).

  • [service] — имя сервиса (gitlab, netbox, nexus); если параметр не указан, действие выполняется для всех сервисов.

  • lcm-k0s/lcm-config.yaml — путь к файлу конфигурации LCM. Обязателен для режима restore и не используется в режиме backup.

Примеры использования:

# Резервное копирование всех сервисов
$ bash migrate_services.sh backup

# Восстановление всех сервисов
$ bash migrate_services.sh restore lcm-k0s/lcm-config.yaml

# Резервное копирование только Nexus
$ bash migrate_services.sh backup nexus

# Восстановление только GitLab
$ bash migrate_services.sh restore gitlab lcm-k0s/lcm-config.yaml

Примечание

На каждый запуск скрипта создаётся лог-файл в текущей директории в формате migrate_services_<дата>_<время>.log. Резервные копии сохраняются в директории <домашняя директория пользователя>/service_backups (для root — /root/service_backups).

Этап 1. Резервное копирование на старом LCM

  1. Зайдите на старый LCM-узел по SSH под пользователем root.

  2. Перейдите в директорию инсталлятора:

    $ cd installer

    Если скрипта migrate_services.sh в директории инсталлятора нет, скопируйте его из нового (k0s) инсталлятора на старый узел. Для режима backup достаточно самого файла скрипта.

  3. Запустите резервное копирование всех сервисов:

    $ bash migrate_services.sh backup

    В ходе выполнения скрипт запросит пароль пользователя admin для Nexus (для запуска задачи Compact blob store перед архивированием).

  4. Дождитесь сообщения об успешном завершении. Резервные копии будут сохранены в директории /root/service_backups.

Этап 2. Перенос резервных копий на новый LCM

Скопируйте директорию с резервными копиями со старого LCM-узла (/root/service_backups) в директорию service_backups в домашней директории пользователя установки на новом (k0s) LCM-узле (например, /home/kolla/service_backups). Можно выбрать другую директорию, например /tmp, поменяв переменную BACKUP_DIR в migrate_services.sh: BACKUP_DIR="${HOME}/service_backups" → BACKUP_DIR="/tmp/service_backups".

# Пример копирования через scp (выполняется со старого LCM-узла)
$ scp -r /root/service_backups kolla@<новый-lcm-узел>:/home/kolla/

Примечание

Скрипт восстановления ищет резервные копии в директории <домашняя директория пользователя>/service_backups. Убедитесь, что директория с резервными копиями расположена именно там и принадлежит пользователю установки.

Этап 3. Восстановление на новом LCM

Предупреждение

Восстановление перезаписывает текущие данные сервисов нового LCM. Выполняйте его только на свежей установке — до переезда на новую доменную зону (этап 5) и до передачи нового LCM в эксплуатацию.

  1. Зайдите на новый (k0s) LCM-узел по SSH под пользователем, от которого выполнялась установка.

  2. Перейдите в директорию инсталлятора:

    $ cd installer

  3. Запустите восстановление всех сервисов:

    $ bash migrate_services.sh restore lcm-k0s/lcm-config.yaml

  4. Подтвердите запуск восстановления (скрипт предупредит о перезаписи данных и запросит подтверждение y).

  5. В процессе восстановления введите запрошенные учётные данные для каждого сервиса:

    • GitLab — текущий пароль root и пароль ks-admin (проверяется по восстановленной базе).

    • NetBox — текущий пароль admin.

    • Nexus — текущий пароль admin (проверяется по восстановленной установке).

  6. Дождитесь сообщения об успешном завершении восстановления всех сервисов.

Перенос секретов региона в Vault нового LCM

Секреты Vault скрипт migrate_services.sh не переносит. В Vault нового LCM — независимо от того, внутренний он или внешний — переносятся только секреты региона: поддерево <vault_prefix>/<region> (openrc, passwords_yml, job_key, ssl_certificates). Перенос выполняется утилитой koc (входит в состав инсталлятора) — логическим копированием поддерева KV из Vault старого LCM в Vault нового.

Важно

Если новый LCM использует внешний Vault, он должен быть заранее подготовлен: созданы KV-engine, метод аутентификации approle и политика доступа к пути <vault_engine>/data/<vault_prefix>/*, а параметры (vault_addr, vault_namespace, vault_engine, vault_prefix и др.) заданы в lcm-config.yaml.

Порядок переноса:

  1. Получите исполняемый файл koc из Nexus нового LCM: https://nexus.<new_lcm_name>.vm.lab.itkey.com/repository/k-add/koc. Запускать koc нужно с узла, которому доступны оба Vault — старого и нового LCM.

  2. Подготовьте параметры подключения к обоим Vault: адрес, аутентификацию (approle role-id/secret-id) и KV-mount. Пути-префиксы источника и назначения задаются позиционными аргументами и, как правило, различаются; к префиксу добавляется имя региона — источник <old_vault_prefix>/<region>, назначение <new_vault_prefix>/<region>. Уточните фактические пути в своей инсталляции.

  3. Получите токен для обращения к Vault (при наличии можно использовать root-токен, например root_token: hvs.XXXX):

    $ TOKEN=$(curl -k -X POST https://<vault_url>/v1/auth/approle/login \
    -H "Content-Type: application/json" \
    -H "X-Vault-Namespace: XX_XX" \
    -d '{ "role_id": "<approle-id-of-this-vault>", "secret_id": "<secret-id-of-this-vault>"}' \
    | jq -r '.auth.client_token')

    Токен обычно выдаётся на ограниченное время. Проверьте срок его действия:

    $ curl -k -X GET https://<vault_url>/v1/auth/token/lookup-self -H "X-Vault-Token: $TOKEN" -H "X-Vault-Namespace: XX_XXX"

  4. Выполните пробный прогон с флагом --dry-run и проверьте список планируемых записей. Пример с использованием namespace в <new-vault>:

    $ ./koc --insecure-vault vault \
    --vault-addr https://<new-vault>/ \
    --vault-namespace '<namespace-of-new-vault>' \
    --vault-token "$TOKEN" \
    --vault-kv-mount '<mount-of-new-vault>' \
    kv copy -r \
    --dry-run \
    --src-vault-addr https://<src-vault> \
    --src-vault-token "$TOKEN1" \
    --src-vault-kv-mount secret_v2 \
    'deployments/<old_region_prefix>' \
    'deployments/<new_region_prefix>'

  5. Убедившись в корректности, повторите команду без --dry-run. Добавьте флаг --skip-existing, чтобы не перезаписывать секреты, уже имеющиеся в новом Vault. Повторите перенос для каждого региона.

Параметры команды koc vault kv copy:

  • флаги назначения (Vault нового LCM) задаются как --vault-* (--vault-addr, --vault-role-id, --vault-secret-id, --vault-kv-mount);

  • флаги источника (Vault старого LCM) — как --src-vault-*; незаданные значения наследуются от назначения;

  • -r — рекурсивно копировать всё поддерево; --dry-run — показать изменения без записи; --skip-existing — не трогать уже существующие секреты назначения;

  • --insecure-vault / --insecure-src-vault — отключить проверку TLS-сертификата назначения/источника.

Примечание

Если Vault нового LCM использует namespace (Vault Enterprise или совместимый менеджер секретов с поддержкой namespace, например СекМан), укажите namespace назначения флагом --vault-namespace; значение должно совпадать с vault_namespace из lcm-config.yaml. Если namespace есть и у источника, задайте его флагом --src-vault-namespace — для Vault старого LCM это, как правило, не требуется.

После переноса секретов запустите upload.sh (этап 4) — он досоздаст недостающие baseline-секреты, не затрагивая уже перенесённые.

Этап 4. Наполнение LCM данными

После восстановления запустите upload.sh для полного наполнения LCM данными, как описано в разделе Наполнение LCM данными:

$ cd ..
$ bash upload.sh lcm-k0s/lcm-config.yaml --force-vars

upload.sh обращается к сервисам LCM по их доменным именам (gitlab.<new_lcm_name>..., nexus.<new_lcm_name>... и т.д.), которые берутся из lcm-config.yaml нового LCM. Эти имена зарегистрированы в DNS ещё при установке нового LCM и уже разрешаются в его VIP-адреса, поэтому запускать upload.sh можно без дополнительной настройки.

Флаг --force-vars принудительно перезаписывает уже существующие CI/CD-переменные GitLab значениями из нового lcm-config.yaml — это нужно, чтобы обновить в них ссылки на новую доменную зону. Без флага upload.sh сохранил бы старые значения, восстановленные из резервной копии старого LCM.

Этап 5. Переезд на новую доменную зону

Новый LCM обслуживается в отдельной доменной зоне <new_lcm_name>. DNS-записи новой зоны создаются как при обычной установке (см. Установка инсталлятора) и указывают на VIP-адреса нового кластера; записи старой зоны остаются на старом LCM. Поскольку доменные имена меняются, потребители не переключаются автоматически — их необходимо перевести на новую зону вручную.

  1. Убедитесь, что для новой зоны в DNS зарегистрированы все записи сервисов, указывающие на соответствующие VIP-адреса нового LCM:

    • vault.<new_lcm_name>.vm.lab.itkey.com → vault_vip

    • nexus.<new_lcm_name>.vm.lab.itkey.com → nexus_vip

    • docker.<new_lcm_name>.vm.lab.itkey.com → nexus_vip

    • netbox.<new_lcm_name>.vm.lab.itkey.com → netbox_vip

    • gitlab.<new_lcm_name>.vm.lab.itkey.com → gitlab_vip

    • grafana.<new_lcm_name>.vm.lab.itkey.com → grafana_vip

    • docs.<new_lcm_name>.vm.lab.itkey.com → docs_vip

    • s3.<new_lcm_name>.vm.lab.itkey.com → s3_vip

    • vmauth.<new_lcm_name>.vm.lab.itkey.com → grafana_vip

  2. Просмотрите и обновите ссылки на доменную зону LCM в перенесённых данных. Часть из них upload.sh обновляет автоматически (например, групповую CI/CD-переменную GitLab DOMAIN), однако ссылки, сохранённые внутри проектов, пайплайнов, вебхуков и хранимых конфигураций регионов, необходимо просмотреть и при необходимости исправить вручную.

  3. Переконфигурируйте каждый регион, обслуживаемый этим LCM, на новую доменную зону (docker-реестр docker.<new_lcm_name>, репозитории пакетов и адреса сервисов LCM) и повторно примените конфигурацию региона.

  4. Добавьте в доверенные сертификаты каждого региона корневой сертификат (CA) нового LCM, которым подписаны сертификаты его сервисов (GitLab, Nexus, NetBox и др.). Без этого регион не сможет обращаться к сервисам нового LCM по HTTPS (ошибка проверки TLS-сертификата). Добавьте корневой сертификат в CA-бандл региона (certificates/ca/ca-bundle.crt) — на узлы он распространяется при применении конфигурации региона.

    Примечание

    Если новый LCM использует внешний Vault со своим корневым сертификатом, добавьте в доверенные сертификаты региона также CA внешнего Vault.

  5. Обновите адреса LCM у остальных потребителей: CI-раннеров, внешних интеграций, пользовательских закладок.

  6. Проверьте, что имена новой зоны разрешаются в VIP-адреса нового LCM:

    $ nslookup gitlab.<new_lcm_name>.vm.lab.itkey.com

Примечание

Доступ к сервисам осуществляется исключительно по DNS-именам (для корректной проверки TLS-сертификатов). После переезда на новую доменную зону проверяйте сервисы по их доменным именам, а не по IP-адресам.

Этап 6. Финальная проверка

После переезда на новую доменную зону убедитесь в работоспособности нового LCM:

  1. Откройте веб-интерфейсы сервисов по их доменным именам и проверьте авторизацию:

    • GitLab — https://gitlab.<new_lcm_name>.vm.lab.itkey.com;

    • NetBox — https://netbox.<new_lcm_name>.vm.lab.itkey.com;

    • Nexus — https://nexus.<new_lcm_name>.vm.lab.itkey.com;

    • Grafana — https://grafana.<new_lcm_name>.vm.lab.itkey.com;

    • Docs — https://docs.<new_lcm_name>.vm.lab.itkey.com.

  2. Убедитесь, что Vault разблокирован, а Raft-кластер (в режиме multi-node) собран из всех узлов.

  3. Убедитесь, что в Nexus присутствуют восстановленные репозитории и содержимое.

  4. Проверьте анонимный доступ к docker-реестру Nexus. Настройки безопасности Nexus переносятся из старой установки вместе с базой данных: если в старом Nexus анонимный доступ был отключён, на новом LCM он тоже окажется выключенным, и анонимная загрузка образов из docker-реестра будет недоступна. При необходимости включите его вручную в веб-интерфейсе Nexus (https://nexus.<new_lcm_name>.vm.lab.itkey.com) под пользователем admin:

    1. В разделе Administration > Security > Anonymous Access включите параметр Allow anonymous users to access the server; используемая роль — nx-anonymous.

    2. В разделе Administration > Security > Realms перенесите Docker Bearer Token в список активных (Active) и сохраните порядок.

    3. В разделе Administration > Repository > Repositories > k-images установите флажок Allow anonymous docker pull (требует активного realm Docker Bearer Token) и сохраните изменения.

  5. Проверьте, что содержимое GitLab (проекты, пользователи) и NetBox (объекты) соответствует старой установке.