Стадия жизненного цикла модуля: General Availability
У модуля есть требования для установки

Миграция из Omnibus в Code

Важно: До шага 11 оператор может показывать ошибки

Что не входит в архив бэкапа

  • Архив бэкапа Omnibus не включает /etc/gitlab/gitlab.rb и /etc/gitlab/gitlab-secrets.json.
  • Архив бэкапа Omnibus не включает SSH- и TLS-ключи хоста.
  • Для Omnibus данные из Object Storage не включаются в архив автоматически.

Эти типы данных нужно переносить и резервировать отдельно (ниже в шагах уже описан поток для Object Storage, секретов и SSH-ключей).

  1. Если GitLab использует локальное файловое хранилище для Docker Registry, необходимо перенести данные в S3-бакет, который подключается к Code, согласно этой инструкции:

    aws --endpoint-url <https://your-object-storage-backend.com> s3 sync registry s3://mybucket
    • В случае использования утилиты s3cmd, то выполните команду s3cmd --configure для настройки конфигурации подключения к s3. И далее команды для переноса данных в S3-бакет, который подключается к Code:
    s3cmd sync registry s3://mybucket

    где registry — путь к папке хранилища Docker Registry в файловой системе.

  2. Blob-объекты, которые используют S3 Object Storage для хранения данных, рекомендуется перенести в S3-бакеты, подключенные к Code Operator, согласно данной инструкции:

    • Настройте в rclone два подключения: old и new, где:
      • old — подключение к S3 Storage, подключенному к GitLab.
      • new — подключение к S3 Storage бакету в Code Operator.
    • Выполните команду: 
      rclone sync -P old:BUCKET_NAME new:BUCKET_NAME

  3. Создайте архив с бэкапом согласно инструкции. Если объекты были перенесены в пункте 2, добавьте опцию SKIP для соответствующих компонентов. Если Object Storage не используется, SKIP можно не указывать.

    Пример:

    sudo gitlab-backup create

  4. Загрузите созданный архив с бэкапом на компьютер администратора, а затем загрузите его в S3-хранилище для бэкапов, указанное в CodeInstance Code, поле bucketName:

    backup:
  enabled: true
  s3:
    bucketName: d8-code-backup
    tmpBucketName: d8-code-backup-tmp

    В S3-бакете d8-code-backup должен храниться архив с бэкапом, например: 1742909494_2025_03_25_17.8.1_gitlab_backup.tar. tmpBucketName используется как временное хранилище в процессе backup/restore и должен быть настроен как отдельный бакет с короткой retention/lifecycle политикой.

  5. Создайте секреты в пространстве имен d8-code:

    Поместите в них значения из соответствующих пунктов.

  6. Сгенерируйте манифест CodeInstance и настройте блок backup:

    backup:
  enabled: true
  s3:
    bucketName: code-backup
    tmpBucketName: code-backup-tmp
    external:
      accessKey: S3AccessKey
      provider: YCloud | Generic | AWS | AzureRM
      secretKey: S3SecretKey
    mode: External

Предусловия восстановления

  • Исходный бэкап и целевой GitLab должны быть одной и той же версии.
  • toolbox должен быть включен и находиться в состоянии Running.
  • Перед восстановлением нужно остановить клиентов БД в целевом окружении (на следующем шаге workload’ы масштабируются в ноль).
  • Имя архива бэкапа должно оставаться в формате <backup_id>_gitlab_backup.tar.
  • Если бэкап создан в Omnibus, могут появляться ошибки о создании/использовании старой PostgreSQL роли из бэкапа и/или о создании PostgreSQL extension. Эти сообщения обычно не являются критичными и не нарушают восстановление и дальнейшую работу после восстановления.

Матрица команд backup/restore

  • Создание бэкапа из Toolbox: backup-utility (при необходимости добавьте вручную --skip ...).
  • Восстановление по ID бэкапа из backup-бакета: backup-utility --restore -t <backup_id>.
  • Восстановление по URL или локальному пути: backup-utility --restore -f <URL|file:///path/to/<backup_id>_gitlab_backup.tar>.

  1. Отмасштабируйте все deployments до нуля:

    kubectl -n d8-code scale --replicas=0 deploy/sidekiq-default
kubectl -n d8-code scale --replicas=0 deploy/webservice-default

  2. Подключитесь к pod toolbox на мастер-хосте кластера Deckhouse. Убедитесь что toolbox включён. Пример:

    /opt/deckhouse/bin/kubectl -n d8-code exec -it -c toolbox toolbox-64d4fb84cf-b7dwb -- bash

  3. Внутри toolbox выполните:

    backup-utility --restore -t <backup_timestamp>

    Например:

    backup-utility --restore -t 1742909494_2025_03_25_17.8.1

  4. Для наката миграций непосредственно Code, запустите:

cd /srv/gitlab
gitlab-rake db:migrate
  1. Создайте сервисный аккаунт для работы оператора

Запустите на рабочей станции:

SERVICE_ACCOUNT_PAT_TOKEN=$(kubectl -n d8-code get secret code-service-account -o jsonpath='{ .data.api-token }'  | base64 -d)

Внутри toolbox выполните:

cd /srv/gitlab
export SERVICE_ACCOUNT_PAT_TOKEN=<token>
gitlab-rake gitlab:generate:service_account_with_token
  1. Отмасштабируйте все deployments обратно:
kubectl -n d8-code scale --replicas=1 deploy/sidekiq-default
kubectl -n d8-code scale --replicas=1 deploy/webservice-default

  1. Дождитесь завершения перезапуска подов оператором.

  2. Убедитесь, что восстановление и миграции завершились успешно:

kubectl -n d8-code get pods
kubectl -n d8-code exec -it -c toolbox deploy/toolbox -- gitlab-rake db:migrate:status
kubectl -n d8-code exec -it -c toolbox deploy/toolbox -- gitlab-rake gitlab:check SANITIZE=true

Восстановление считается успешным, когда все pod в состоянии Ready, нет ожидающих миграций, и gitlab:check завершается без критичных ошибок.

Миграция из Code в Omnibus

  1. Отмасштабируйте все deployments до нуля:

    kubectl -n d8-code scale --replicas=0 deploy/sidekiq-default
kubectl -n d8-code scale --replicas=0 deploy/webservice-default

  2. Откат миграций Code из базы данных. Зайдите в pod toolbox и выполните следующие команды из директории /srv/gitlab

    Важно: компонент toolbox теперь опциональный (по умолчанию включён). Если pod toolbox отсутствует, убедитесь что он включён в CodeInstance (spec.features.toolbox.enabled: true) и дождитесь reconcile.

    bundle exec rake fe:db:migrations:rollback

  3. Используйте pod toolbox и встроенную в него утилиту backup-utility для создания архива с бэкапом:

    kubectl -n d8-code exec -it -c toolbox deploy/toolbox -- backup-utility

    Если бэкап запускается вручную, параметры --skip нужно подбирать самостоятельно, когда часть данных уже перенесена или архивируется вне этого процесса.

  4. Дождитесь завершения процесса создания бэкапа. По завершении бэкап будет сохранен в S3-хранилище, указанное в CodeInstance в секции backup:

    backup:
  enabled: true
  s3:
    bucketName: code-backup
    tmpBucketName: code-backup-tmp
    external:
      accessKey: S3AccessKey
      provider: YCloud | Generic | AWS | AzureRM
      secretKey: S3SecretKey
    mode: External

    Имя созданного архива будет соответствовать формату <timestamp>_gitlab_backup.tar. Пример:

    1742909494_2025_03_25_17.8.1_gitlab_backup.tar.

  5. Остановите службы puma и sidekiq:

    gitlab-ctl stop puma
gitlab-ctl stop sidekiq

    Если GitLab развёрнут в Docker, выполните эти команды внутри контейнера.

  6. Скачайте и перенесите архив с бэкапом в директорию, где хранятся бэкапы GitLab:

    • По умолчанию это /var/opt/gitlab/backups.
    • Если используется другая директория, переместите бэкап туда.
    • Если используется S3 Object Storage для хранения бэкапов, загрузите архив туда.

  7. Восстановите файл gitlab-secrets.json:

    • Создайте копию текущего файла gitlab-secrets.json своей Linux/Docker установки. Для этого скопируйте файл /etc/gitlab/gitlab-secrets.json на хост администратора.

    • Получите rails-secrets.json из Code. Для этого выполните следующую команду на хосте, где выполняется команда kubectl для кластера Deckhouse:

      kubectl -n d8-code get secret rails-secret-v1 -ojsonpath='{.data.secrets\.yml}' | yq '@base64d | from_yaml | .production' -o json > rails-secrets.json

    • Перенесите созданный файл rails-secrets.json в ту же директорию, куда поместили файл gitlab-secrets.json, и выполните команду:

      yq eval-all 'select(filename == "gitlab-secrets.json").gitlab_rails = select(filename == "rails-secrets.json") | select(filename == "gitlab-secrets.json")' -ojson gitlab-secrets.json rails-secrets.json > gitlab-secrets-updated.json

    • Замените текущий файл gitlab-secrets.json на полученный файл gitlab-secrets-updated.json. Для этого скопируйте gitlab-secrets-updated.json на хост/контейнер, где запущен GitLab, в папку /etc/gitlab/gitlab-secrets.json:

      cp gitlab-secrets-updated.json /etc/gitlab/gitlab-secrets.json

  8. Восстановите SSH-ключи хоста:

    • На хосте, где выполняется команда kubectl для кластера Deckhouse, выполните следующие команды:

      kubectl -n d8-code get secrets shell-host-keys -ojsonpath='{.data.ssh_host_ecdsa_key}' | base64 -d > ssh_host_ecdsa_key
kubectl -n d8-code get secrets shell-host-keys -ojsonpath='{.data.ssh_host_ecdsa_key.pub}' | base64 -d > ssh_host_ecdsa_key.pub
kubectl -n d8-code get secrets shell-host-keys -ojsonpath='{.data.ssh_host_ed25519_key}' | base64 -d > ssh_host_ed25519_key
kubectl -n d8-code get secrets shell-host-keys -ojsonpath='{.data.ssh_host_ed25519_key.pub}' | base64 -d > ssh_host_ed25519_key.pub
kubectl -n d8-code get secrets shell-host-keys -ojsonpath='{.data.ssh_host_rsa_key}' | base64 -d > ssh_host_rsa_key
kubectl -n d8-code get secrets shell-host-keys -ojsonpath='{.data.ssh_host_rsa_key.pub}' | base64 -d > ssh_host_rsa_key.pub

    • Скопируйте полученные файлы на хост с вашей Linux/Docker установкой в директорию /etc/gitlab:

      cp ssh_host_* /etc/gitlab/

  9. После замены файла gitlab-secrets.json выполните команду:

gitlab-ctl reconfigure
  1. По завершении выполнения команды запустите восстановление:
gitlab-backup restore BACKUP=<timestamp>

Например:

gitlab-backup restore BACKUP=1742909494_2025_03_25_17.8.1

  1. После восстановления перезапустите GitLab и проверьте его состояние:

    gitlab-ctl restart
gitlab-rake gitlab:check SANITIZE=true

  2. Убедитесь, что нет ожидающих миграций:

gitlab-rake db:migrate:status