Міграція реєстрів

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

Ця сторінка надає практичне керівництво з виконання міграції між OKD кластерами A та B.

1. Позначення та скорочення

  • Кластер А — кластер, на якому розгорнуто наявний реєстр.

  • Кластер B — кластер, куди буде перенесено наявний реєстр (цільовий кластер).

Міграція реєстру виконується з останньої резервної копії наявного реєстру та, відповідно до інструкції, буде переноситися із кластера А до кластера B й відновлюватися вже на цьому кластері.

2. Передумови для міграції

📌 Примітка до організації міграції

  1. Планування: важливо розробити чіткий графік міграції. Він має включати:

    • Дату та час створення бекапу.

    • Час відновлення.

    • Визначений час завершення роботи надавачів послуг перед бекапом.

  2. Комунікація: важливо забезпечити, щоб усі користувачі-надавачі послуг були вчасно повідомлені:

    • Сповіщайте користувачів за допомогою зовнішніх комунікаційних каналів поза межами Платформи.

    • Вкажіть їм про необхідність завершення роботи до визначеного у графіку часу.

Дотримуючись цих рекомендацій, ви забезпечите плавний процес міграції без непотрібних затримок та незручностей для користувачів.

  1. Процес міграції включає запуск bash-скрипту, що здійснює перенесення даних з кластера А до кластера B. Для успішної міграції, цей скрипт має бути виконаний на платформі Linux з архітектурою мікропроцесора x86-64 (відомою також як AMD64, Intel 64, чи x64)

  2. Користувач, який буде переносити реєстр на інший кластер, повинен бути доданий до адміністраторів Платформи на обох кластерах через control-plane-console.

    Див. детальніше — Створення адміністратора платформи.

  3. На кластері, на який переноситься реєстр, повинна бути розгорнута та версія платформи, у якої версія control-plane-gerrit буде дорівнювати версії самого реєстру (наприклад, версія платформи — 1.9.4.11, версія реєстру — 1.9.4.7, версія control-plane-gerrit – 1.9.4.7). Цю версію можна перевірити наявністю гілки у репозиторії cluster-mgmt в центральному Gerrit. Якщо гілка з версією реєстру існує, то версію реєстру можна переносити на кластер B. Якщо ні, то існує два шляхи:

    • Оновити платформу на кластері B, яка буде відповідати версії самого реєстру.

    • Оновити реєстр на кластері A до версії, яка вже існує на кластері B.

  4. Одночасний доступ до кластера А та кластера B.

  5. Наявність наступних команд в Terminal:

    • oc

    • velero

    • rclone

    • vault

  6. Стабільне з’єднання з інтернетом. Чим більша пропускна здатність, тим швидше буде проходити міграція. В іншому випадку, можна використовувати jumpbox (із доступом до обох кластерів), який знаходиться або в AWS, або в іншого cloud-провайдера. Використання jumpbox зменшить час перенесення резервної копії з одного кластера на інший.

    Якщо ви використовуєте jumpbox, то необхідно перевірити доступ до платформних Minio/Vault з IP-адреси jumpbox. Для отримання IP jumpbox виконайте наступну команду:

    ssh sshmyip.com

    Далі необхідно перевірити наявність або додати IP-адресу jumpbox до переліку дозволенних CIDR на рівні керування платформою для кластера А та кластера B ( див. детальніше на сторінці CIDR: Обмеження доступу до Платформних та реєстрових компонентів).

    Якщо відсутній доступ до control-plane-console, зверніться до L2-команди для перевірки доступу.

    При міграції реєстру, важливо щоб перед початком міграції, на кластері B не було ресурсів пов’язаних із реєстром.

    Якщо раніше реєстр не існував на цьому кластері, то подальші дії можна не виконувати.

    Якщо реєстр існував, то для видалення усіх ресурсів потрібно перевірити/видалити наступне:

    • Видаліть реєстр через інтерфейс адміністративної панелі Control Plane.

      Детальніше про це ви можете переглянути на сторінці Видалення реєстру.

    • Підтвердьте зміни та дочекатися видалення реєстру.

    • Після видалення перевірте відсутність проєкту у центральному компоненті Gerrit.

      • Перейдіть до Gerrit (Openshift-консоль > Projects > control-plane > Networking > Routes > control-plane-gerrit ).

      • Автентифікуйтеся через openshift-sso, відкрийте меню Browse > Repositories та виконайте пошук за назвою реєстру.

      • Якщо пошук знаходить репозиторій, то перейдіть до Openshift-консоль > Projects > control-plane > Home > API Explorer > у пошуку ( Filter by kind …​ ) знайдіть gerritproject > <назва реєстру> > Actions > Delete GerritProject.

      • Після видалення Gerrit-проєкту, перейдіть до Gerrit-консолі та перевірте, що репозиторій відсутній. Якщо репозиторій існує, видаліть його через Gerrit-консоль ( відкрийте репозиторій реєстру > Commands > Delete project).

    • Видаліть директорію в Minio.

      • Для перевірки створених директорій в Minio, перейдіть до MinioUI (для кластерів vSphere цей Route можна знайти в OpenShift-консолі > Projects > control-plane > Networking > Routes > platform-minio-ui.

      • У випадку відсутності Route, перейдіть до секретів за шляхом:
        Openshift-консоль > Project > control-plane > Workloads > Secrets > backup-credentials, скопіюйте поле backup-s3-like-storage-url та додайте до URL порт (Наприклад, https://endpoint.com:9001 ).

        Дані для аутентифікації в Minio знаходяться в Openshift-консолі > Project > control-plane > Secrets > backup-credentials, де username — це поле backup-s3-like-storage-access-key-id, а password —  backup-s3-like-storage-secret-access-key.

      • Після аутентифікації перевірте/видаліть директорії, пов’язані у реєстрі в бакеті. Такими є:

        • openshift-backups/backups/<назва-реєстру>*;

        • openshift-backups/restic/<назва-реєстру>;

        • obc-backups/<назва реєстру>.

3. Підготовка реєстру до міграції

Перед початком міграції необхідно повністю обмежити доступ для кінцевих користувачів до цього реєстру.

  1. Зробіть резервну копію реєстру на кластері A.

    Перед перенесенням реєстру на новий кластер, необхідно запустити Jenkins-процес Create-registry-backup-<назва реєстру>.

    Якщо Jenkins pipeline завершився зі статусом Success, то резервна копія виконана успішно.

    Для отримання назви резервної копії, перейдіть до логів/журналів подій останнього запуску Jenkins pipeline (Console Output), та за пошуком на сторінці знайдіть повідомлення накшталт:

    [INFO] Velero backup - <назва реєстру>-<час> done with Completed status

    Наприклад, таке:

    [INFO] Velero backup - abc-02-2023-04-18-19-03-14 done with Completed status

    • де abc-02-2023-04-18-19-03-14 — назва резервної копії.

    Для версій реєстру < 1.9.3 необхідно виконати у Terminal наступну команду:

    velero backup describe <назва бекапу>

    Назву бекапу можна знайти в логах останнього запуску Jenkins-процесу Create-registry-backup-<назва реєстру>.

    Детальніше про створення резервних копій та відновлення реєстрів див. у розділі Резервне копіювання та відновлення.

  2. Якщо останній velero backup завершився зі статусом Completed, то можна переходити далі. У випадку, коли статус velero backup відрізняється від Completed, необхідно долучати спеціалістів із технічної підтримки L2-L3 для перевірки працездатності Jenkins-пайплайну.

  3. Отримайте консистентні дані у бекапах бакетів реєстру, що мігрується.

    1. Для початку, отримайте актуальні бекапи S3-бакетів реєстру в проєкті velero. Відкрийте розділ Workloads, потім перейдіть до CronJobs. Тут використовуйте пошукову панель для фільтрації бакетів за назвою реєстру, наприклад, migrationreg.

      migrate registry 01
      Зображення 1. CronJobs

    2. Відкрийте кожну CronJob і змініть час її запуску на найближчий можливий, та додайте value для змінної оточення MAX_AGE. Для прикладу, встановіть запуск через 10-15 хвилин. Щоб це зробити, перейдіть до налаштувань кожної CronJob, відкрийте її YAML-конфігурацію і змініть параметр spec.schedule. Наприклад, для запуску CronJob щодня о 10:50 за UTC, використовуйте наступну конфігурацію:

      CronJob details. YAML-конфігурація
      spec:
  schedule: 50 10 * * *

      При роботі з cron, час вказується за UTC.
      migrate registry 02
      Зображення 2. CronJob details. Schedule

      Для конфігурації MAX_AGE використовуйте наступну конфігурацію:

      spec:
  ...
  jobTemplate:
    ...
    spec:
      template:
        ...
        spec:
          ...
          containers:
            ...
            env:
            - name: MAX_AGE
              value: '2y'

    3. Після цього дочекайтеся запуску і завершення усіх CronJob. Прогрес і статус можна перевірити в розділі Jobs, обравши відповідний Job і переглянувши розділ Status, де має бути позначка ✅ Complete.

      migrate registry 03
      Зображення 3. CronJob details. Jobs
      migrate registry 04
      Зображення 4. Job details. Status

    4. Завдяки цим діям ви отримаєте консистентні дані з бекапів бакетів реєстру, який перебуває у процесі міграції.

  4. Забороніть робити зміни у реєстрі за допомогою Jenkins пайплайнів.

    У кожному пайплайні для реєстру перейдіть до секції Configure та знайдіть параметр Disable this project у секції Build Triggers, встановіть напроти нього прапорець та збережіть зміни за допомогою кнопки Save.

4. Міграція резервної копії із кластера А до кластера B

  1. Отримайте логін-команди для обох кластерів.

    Для цього виконайте вхід до Openshift-консолі та у правому верхньому кутку, натисканням на свій username, перейдіть до Copy login command, скопіюйте токен доступу у полі Log in with token та збережіть його у текстовому редакторі.

    Операцію потрібно повторити для обох кластерів: А та B.

  2. Отримайте назву останньої резервної копії, яка була створена на кластері А (наприклад, abc-02-2023-04-18-19-03-14).

  3. Відкрийте термінал та виконайте наступні команди:

    Експорт логіну для кластера А
    export A_CLUSTER_LOGIN="oc login --token …"

    Вставте між лапок "…​" після --token отриману в пункті 1 команду логіну для кластера А. В кінці логін-команди не повинно бути перенесення на наступний рядок.

    Експорт логіну для кластера В
    export B_CLUSTER_LOGIN="oc login --token …"

    Вставте між лапок "…​" після --token отриману в пункті 1 команду логіну для кластера В. В кінці логін-команди не повинно бути перенесення на наступний рядок.

    Експорт назви реєстру
    export REGISTRY_NAME="abc-02"
    abc-02 — назва реєстру
    Експорт назви резервної копії
    export BACKUP_NAME="<назва резервної копії>"
    Приклад назви резервної копії: abc-02-2023-04-18-19-03-14.

    У випадку, коли реєстр попередньо був мігрований на кластер A, а не розгорнутий на цій Платформі, виконайте додатковий export:

    export VAULT_KEY="<назва ключа>"

    • де <назва ключа> — ключ для unseal процесу, який можна знайти в Openshift-консолі ( Кластер А ) > Projects > <назва реєстру> > ConfigMaps > hashicorp-vault-config. Поле key_name і є назвою ключа.

      Наприклад:

      key_name        = "autounseal-migration"

    У випадку міграції великого реєстру, виконайте експорт наступної змінної:

    export LARGE_DATA="true"

  4. Збережіть архів, розархівуйте його в нову директорію наступною командою:

    unzip registry-migration.zip -d registry-migration

    Перейдіть в директорію registry-migration (cd) та виконайте команду:

    chmod +x migration.sh && ./migration.sh

  5. Після виконання скрипту, виконайте логін у терміналі за допомогою oc cli на кластері B, та перевірте наступне:

    • Наявність velero backup на кластері B.

    • Наявність директорій із назвою keycloak-export у папці, де знаходиться скрипт.

5. Підготовка до відновлення на кластері B

  1. Створіть реєстр через control-plane-console.

    • Створіть реєстр з тим же ім’ям, і такою ж версією на кластері B. При створенні реєстру призначте усіх адміністраторів, що були у реєстрі на кластері A, та вкажіть актуальні дані.

      Дані про ключ

      Поля заповніть або з актуальними ключами для цього реєстру, або використовуйте тестові ключі. У майбутньому, після міграції, інформацію про ключі можна актуалізувати через консоль Control Plane. За даними для ключів звертатись до L2-L3 підтримки.

      Детальніше про оновлення ключів реєстру — див. на сторінці Оновлення ключів та сертифікатів цифрового підпису для реєстру.

      Шаблон реєстру

      Оберіть такий самий шаблон, як і шаблон цього реєстру на кластері A. Для отримання назви шаблону, перейдіть до Openshift-консолі > Projects > control-plane > API Explorer > У пошуку визначте codebase > Перейдіть до codebase > Instances > Відкрийте codebase <назва реєстру> > Перевірте наступні налаштування:

      Приклад 1. codebase.yaml
      metadata:
  annotations:
    registry-parameters/template-name: templates/registry-tenant-template-minimal

      • де templates/registry-tenant-template-minimal — назва шаблону розгортання реєстру.
      Якщо функціональність консолі дозволяє додати DNS для keycloak або порталів, на цьому етапі необхідно пропустити цей крок, адже трафік поки налаштований на кластер A).

    • Після створення, одразу перейдіть до Jenkins (namespace control-plane > Networking > Routes > jenkins), та зупиніть першу збірку MASTER-Build-<назва реєстру>.

      Дочекайтеся створення директорії <назва реєстру> та створення Jenkins-пайплайну. Після запуску одразу зробити Abort збірки.

  2. Залишаючись у консолі Jenkins, змініть конфігурацію MASTER-Build-<назва реєстру>:
    Перейдіть до MASTER-Build-<назва реєстру> > Configure, та у секції Build Triggers встановіть прапорець на параметрі Disable this project. Далі збережіть зміни кнопкою Save.

  3. Перенесіть файли конфігурації values.yaml та values.gotmpl з репозиторію реєстру кластера А на кластер B.

    • Перейдіть до репозиторію реєстру на кластері А:
      Відкрийте Control-plane-console > Дашборд > Gerrit > Browse > Repositories > оберіть репозиторій <назва реєстру>.
      У репозиторії реєстру перейдіть до Branches > master, далі перейдіть до deploy-templates, відкрийте файл values.yaml ( values.gotmpl ) > Скопіюйте raw-код до буфера обміну.

    • Далі перейдіть до репозиторію реєстру на кластері B:
      Control-plane-console > Дашборд > Gerrit ) > Browse > Repositories та оберіть репозиторій <назва реєстру>. Через commands > Create change створіть зміну (change) із наступними параметрами:

      • Select branch for new change: master.

      • Description: Update registry before migration.

        Після створення зміни, у самому change натисніть Edit > ADD/OPEN/UPLOAD — знайдіть файл values.yaml (values.gotmpl). Перенесіть до цього файлу скопійовану конфігурацію values.yaml (values.gotmpl) із кластера А.

    • Повторіть операцію для обох файлів: values.yaml та values.gotmpl.

    • Збережіть зміни, дочекайтеся проходження пайплайну Code Review (СІ Jenkins +1), проставте Code-review +2,та виконайте злиття змін до master-гілки кнопкою Submit.

6. Відновлення реєстру на кластері B

Увімкніть доступ для кінцевих користувачів до реєстру ЛИШЕ після завершення процесу відновлення реєстру.

  1. Відрийте до Jenkins (namespace control-plane > Networking > Routes > jenkins), перейдіть до папки із назвою реєстру та запустіть Jenkins-пайплайн Restore-registry-<назва реєстру>. Після запуску пайплайну оберіть версію (на етапі cleanup-registry-before-restore) та дочекайтеся, коли процес завершиться.

    Процес може завершитися зі статусом UNSTABLE. Це пов’язано зі зміною конфігурації пайплайну MASTER-Build-<registry-name>, де <registry-name> — назва реєстру.
    У випадку, коли процес завершується помилкою або триває понад 1-2 години, зверніться до спеціалістів команди технічної підтримки L2-L3.

  2. Після завершення пайплайну перейдіть в Openshift-консоль → Projects → <registry-name>, та перевірте, що відсутні поди у статусі з помилками, та усі поди у статусі Running/Сompleted.

    У випадку, коли пода із назвою bpms-* не запущена і має статус помилки, виправте паролі у postgres для operational-instance та analytical-instance под, для цього потрібно:

    • Перейдіть в Openshift-консоль > Secrets, знайдіть secret для operational-instance — operational-pguser-postgres (для analytical-instance — це analytical-pguser-postgres).

    • Перейдіть в Secret та скопіюйте поле password.

    • Перейдіть в Openshift-консоль > Pods > знайдіть поду operational-instance або analytical-instance та виконайте по черзі наступні команди:

      psql
      ALTER ROLE postgres WITH PASSWORD '<password>';

      • де <password> — поле password, скопійоване у Secret, для відповідного екземпляра — operational або analytical.

    • Після виконання усіх операцій, видаліть поду bpms та дочекайтеся, коли вона буде у статусі Running (активна/запущена).

    У випадку, коли пода registry-rest-api запускається з помилкою ImagePullBackOff, додайте IP кластера B до анотації Openshift Route > Nexus.

    • Для цього перейдіть в Openshift-консоль > Project > <назва реєстру> > Routes > Nexus > YAML та перевірте наступне поле у .yaml-конфігурації:.

      Приклад 2. route.yaml
      metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: <NAT Cluster IP>/32,....

      Якщо IP-адреса кластера B відсутня, додайте її до haproxy.router.openshift.io/ip_whitelist із маскою /32.

  3. Перейдіть в Jenkins, змініть конфігурацію MASTER-Build-<registry-name>:

    Перейдіть до MASTER-Build-<registry-name> > Configure, та у секції BuildTriggers приберіть прапорець на параметрі Disable this project. Далі збережіть зміни кнопкою Save.

  4. Перенесіть конфігурацію реєстру до values.yaml/values.gotmpl.

    • Увійдіть до control-plane-gerrit (Openshift-консоль > Projects → control-plane → Networking → gerrit > Логін через openshift-sso).

      У Gerrit перейдіть до Browse > Repositories та оберіть репозиторій <назва реєстру>. Через commands > Create change створіть зміну (change) із наступними параметрами:

      • Select branch for new change: master.

      • Description: Update registry after migration.

        Після створення change, у самому change натисніть Edit.

    • Додайте конфігурацію vault у values.gotmpl.

      Для цього візьміть актуальну конфігурацію vault з config-map hashicorp-vault-config (Openshift-консоль > Projects > <назва реєстру> > Workloads > ConfigMaps > hashicorp-vault-config) та скопіюйте поле як у наступному прикладі:

      ui = true

listener "tcp" {
  tls_disable = 1
  address = "[::]:8200"
  cluster_address = "[::]:8201"
}
storage "file" {
  path = "/vault/data"
}
seal "transit" {
   address         = "https://<vault url>"
   disable_renewal = "false"
   key_name        = "<key name>"
   mount_path      = "transit/"
   tls_skip_verify = "true"
}

    • де <vault URL> — посилання до vault, <key name> — назва ключа (у конфігурації з config-map будуть актуальні поля).

      Далі в change натисніть ADD/OPEN/UPLOAD, у пошуку вкажіть values.gotmpl та виберіть потрібний файл. В самому файлі додайте конфігурацію як у прикладі:

      vault:
  platformVaultToken: {{ env "platformVaultToken" }}
  openshiftApiUrl: {{ env "openshiftApiUrl" }}
  centralVaultUrl: {{ b64dec $centralVaultUrl }}
  server:
    dataStorage:
      storageClass: ocs-storagecluster-ceph-rbd
    auditStorage:
      storageClass: ocs-storagecluster-ceph-rbd

    standalone:
      config: |
       ui = true

       listener "tcp" {
         tls_disable = 1
         address = "[::]:8200"
         cluster_address = "[::]:8201"
       }
       storage "file" {
         path = "/vault/data"
       }
       seal "transit" {
          address         = "https://<vault url>"
          disable_renewal = "false"
          key_name        = "<key name>"
          mount_path      = "transit/"
          tls_skip_verify = "true"
       }

    • Після додавання натисніть Save and Publish. Дочекайтесь коли пройде Jenkins Code-Review пайплайн (повинна з’явитись оцінка +1 від edp-ci), та натисніть Reply > Code-Review - +2 > Submit

  5. Після застосування змін має запуститися Jenkins-процес MASTER-Build-<назва реєстру>. Дочекайтесь завершення Jenkins-пайплайну MASTER-Build-<назва реєстру>.

  6. Перенесіть користувачів.

    В адмін-консолі Keycloak, перейдіть до реалму (1), та у лівому меню реалму оберіть Import (2). При імпорті оберіть стратегію SKIP), далі натисніть Select file (3) та виберіть файл із директорії keycloak-export/<ім’я реалму>-users-*.json.

    Якщо файлів більше одного, то виконайте імпорт усіх файлів.

    image

  7. Виправте Jenkins Credentials у Jenkins реєстру.

    У випадку, коли доступу немає, додайте себе як адміністратора реєстру через control-plane-console.

    • Для цього перейдіть в Openshift-консоль > Projects > <назва реєстру> > Workloads > Secrets > gerrit-control-plane-sshkey та скопіюйте поле id_rsa.

    • Після цього перейдіть у реєстровий Jenkins (Networking > Routes > jenkins) > Manage Jenkins > Manage Credentials > edp-ci (gerrit-control-plane-sshkey) > натисніть Update.

    • У полі Private Key за допомогою Replace вставте скопійоване значення.

  8. Після внесення зміни Private Key перейдіть в папку registry-regulations та оберіть пайплайн MASTER-Build-registry-regulations, далі натисніть Build with Parameters та оберіть галочку на параметрі FULL_DEPLOY та натисніть Build і дочекайтесь завершення зі статусом Success.

7. Перевірка реєстру

  1. Переконайтеся, що Кабінети користувачів працюють у штатному режимі, та бізнес-процеси мігрували успішно.

  2. Усі Jenkins pipeline мають завершитися зі статусом Success.

8. Перенесення конфігурації реєстру

Перенесіть конфігурацію реєстру із кластера А на кластер B відповідно до документації: