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

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

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

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

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

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 ( див. детальніше на сторінці Обмеження доступу до адміністративних та реєстрових компонентів).

    Якщо відсутній доступ до 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. Забороніть робити зміни у реєстрі за допомогою 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

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

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

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

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

  1. Перенесіть реалми.

    Для перенесення реалмів, виконайте вхід до Keycloak на кластері B:

    • В Openshift-консолі знайдіть проєкт (namespace) user-management, відкрийте Networking > Routes та перейдіть за посиланням до сервісу keycloak.

      Дані для логіну можна отримати із секретів keycloak у тому ж проєкті. Для цього перейдіть до Workloads > Secrets, знайдіть у пошуку секрет із назвою keycloak, та у розділі Data скопіюйте дані для входу до сервісу.

    • За допомогою Select realm (1) > Add realm (2) > Import (3), виберіть файл keycloak-export-<назва реєстру>-/-realm.json та створити реалми (оберіть стратегію SKIP, запропоновану Keycloak). Так пройдіться по усіх директоріях із назвою keycloak-export-<назва реєстру>-*.

    image

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

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

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

    image

  3. Створіть реєстр через 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 збірки.

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

  5. Перенесіть файли конфігурації 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. Перевірка наявності CustomResourceDefintition.

    Якщо до цього на кластері не було жодного реєстру, обов’язково перевірте наявність існування CustomResourceDefintition. Для цього виконайте логін через oc cli на кластері B та виконати наступну команду:

    oc get customresourcedefinition ingressclassparameterses.configuration.konghq.com

    Якщо команда завершиться з помилкою та видасть у консолі No resources found, то перейдіть до директорії, де знаходиться скрипт migration.sh, та з кореневого шляху виконайте наступну команду:

    for file in $(ls crds); do oc apply -f crds/$file; done

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

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

    У випадку, коли процес завершується помилкою або триває понад 1-2 години, зверніться до спеціалістів команди технічної підтримки L2-L3 "ЕПАМ".

  2. Після завершення пайплайну перейдіть в Openshift-консоль > Projects > <назва реєстру>, та перевірте, що немає под у статусі помилок.

    У випадку, коли пода із назвою 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. Після перевірки, що усі поди у статусі Running, перенесіть конфігурацію реєстру до 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.

    • Змініть розмір kafka-дисків. Залишаючись у цьому файлі, знайдіть поле:

      storage:
  zookeeper:
    size: 5Gi
  kafka:
    size: 20Gi

    • Змініть розмір kafka.size відповідно до розміру актуального диска в Openshift-консолі (Openshift-консоль > Project → <назва реєстру> → Storage > PersistentVolumeClaims ). У пошуку знайдіть data-0-kafka-cluster-kafka-0 та його Capacity. Поверніться до редагування values.gtmpl та встановіть бажаний розмір диска:

      storage:
  zookeeper:
    size: 5Gi
  kafka:
    size: 40Gi

      • де 40Gi - актуальний розмір диска з Capacity.

    • Видаліть усіх GerritGroupMember. Для цього виконайте вхід до кластера B через ос cli та виконати наступну команду:

      oc -n <назва-реєстру> delete gerritgroupmember --all

  4. Після застосування змін має запуститися Jenkins-процес MASTER-Build-<назва реєстру>.

  5. Після з завершення Jenkins-пайплайну MASTER-Build-<назва реєстру>, виправте Jenkins Credentials у Jenkins реєстру.

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

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

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

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

  6. Оновіть посилання на Nexus у репозиторії регламенту.

    Для цього перейдіть до Openshift-консолі > Project → <назва реєстру> > Gerrit та виконайте логін.

    Далі перевірте наявність доступу до проєктів у Gerrit та клонуйте локально репозиторій registry-regulations. Для цього:

    • У вебінтерфейсі Gerrit, перейдіть у налаштування > HTTP Credentials > згенеруйте новий пароль за допомогою Generate New Password, та збережіть цей пароль у нотатках.

    • Перейдіть до репозиторію registry-regulations > та скопіюйте команду для клону Anonymous HTTP > Clone with commit-msg hook.

    • Вставте команду для клону репозиторію до термінала та виконайте. Команда запитає логін та пароль. Логін в цьому випаду буде ваш email, а пароль — той, який ви згенерували у першому підпункті.

      Детальніше про роботу з репозиторієм Gerrit див. на сторінці Процес розгортання регламенту в Gerrit.

      Якщо в системі git user відрізняється від вашого user на сервері Gerrit, виконайте наступні команди:

      git config --global user.name "New Author Name"
git config --global user.email "<email@address.example>"

      Наприклад:

      git config --global user.name "Jonh Doe"
git config --global user.email "jong_doe@doemail.com"

  7. Змініть мінорну версію в settings.yaml у кореневій (root) директорії репозиторію registry-regulations згідно із приладом:

    settings:
  general:
    package: ua.gov.mdtu.ddm.dataplatform.template
    register: registry
    version: 2.21.0

    Наприклад, додайте до версії +1:

    settings:
  general:
    package: ua.gov.mdtu.ddm.dataplatform.template
    register: registry
    version: 2.21.1

  8. Замініть згадування DNS-кластера А на кластер B. Для цього у терміналі перейдіть до директорії registry-regulations/data-model

    cd registry-regulations/data-model

    Та виконайте наступну команду по заміні DNS:

    find "." \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i -e  's/<Cluster A DNS wildcard> /<Cluster B DNS Wildcard> /g'

    Cluster A DNS wildcard/Cluster B DNS wildcard — це apps.* (наприклад, apps.reestr1.eua.gov.ua). Як повинно виглядати sed правило:

    's/apps.cluster-a.dns.wildcard.com/apps.cluster-b.dns.wildcard.com/g'

  9. Виконайте commit змін та push до репозиторію:

    git add --all
    git commit -m "Update nexus URL"
    git push origin refs/heads/master:refs/for/master

  10. Перейдіть у реєстровий Gerrit, проставте відмітки Code-Review +2, та за допомогою кнопки Submit застосуйте зміни до master-гілки.

  11. Після внесення змін до master-гілки перейдіть до Jenkins реєстру та перевірте, що Jenkins-пайплайни у Jenkins Folder registry-regulations завершилися зі статусом Success.

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

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

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

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

Перенесіть конфігурацію реєстру із кластера А на кластер B відповідно до документації:
У випадку будь-яких проблем із міграцією, зверніться до Anatolii_Stoliarov@epam.com.

© 2023 Платформа Реєстрів.