Migration from Omnibus to Code

1. If GitLab uses local file storage for Docker Registry, you need to migrate the data to an S3 bucket that connects to Code, according to this guide:

   aws --endpoint-url <https://your-object-storage-backend.com> s3 sync registry s3://mybucket
   

• If you are using the s3cmd utility, run the command s3cmd --configure to set up the connection configuration for S3. Then, use the following command to transfer data to the S3 bucket that is connected to Code:

  s3cmd sync registry s3://mybucket
  

  where registry is the path to the Docker Registry storage folder in the file system.

2. Blob objects that use S3 Object Storage for data storage should be migrated to S3 buckets connected to the Code Operator, according to this guide:

   • Configure two connections in rclone: old and new, where:
     • old is the connection to the S3 Storage linked to GitLab.
     • new is the connection to the S3 Storage bucket in the Code Operator.
   • Run the command:

     rclone sync -P old:BUCKET_NAME new:BUCKET_NAME
     

3. Create a backup archive according to this guide. Add the SKIP option for objects migrated in step 2. If Object Storage is not used at all, the SKIP option can be omitted.

4. Upload the created backup archive to the administrator’s computer, then upload it to the S3 storage for backups specified in the ModuleConfig for Code, under the bucketName field:

   backup:
     enabled: true
     restoreFromBackupMode: true
     s3:
       bucketName: d8-code-backup
   

   The S3 bucket d8-code-backup should contain the backup archive, for example: 1742909494_2025_03_25_17.8.1_gitlab_backup.tar.

5. Create secrets in the d8-code namespace:

   • rails-secret-v1
   • shell-host-keys

   Place the corresponding values into these secrets.

6. Generate the ModuleConfig manifest and configure the backup block:

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

7. Connect to the toolbox pod on the master host of the Deckhouse cluster. Example:

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

8. Inside the toolbox, run:

   backup-utility --restore -t <backup_timestamp>
   

   For example:

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

9. Disable the restore mode in the ModuleConfig for Code:

   • Run the command:

     /opt/deckhouse/bin/kubectl edit mc code
     

   • Change the value of restoreFromBackupMode to false.

10. Wait for the operator to restart the pods.

Migration from Code to Omnibus

1. Switch Code to backup mode by setting the backup.restoreFromBackupMode parameter to true in the ModuleConfig. This will temporarily disable all Code consumer components during the restore process.

2. Use the toolbox pod and the built-in backup-utility tool to create a backup archive:

   kubectl -n d8-code exec <Toolbox pod name> -it -- backup-utility --restore -t <timestamp|URL>
   

   For example:

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

3. Wait for the backup creation process to complete. Upon completion, the backup will be saved in the S3 storage specified in the ModuleConfig under the backup section:

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

   The name of the created archive will follow the format <timestamp>_gitlab_backup.tar. Example:

   1742909494_2025_03_25_17.8.1_gitlab_backup.tar.

4. Stop the puma and sidekiq services:

   gitlab-ctl stop puma
   gitlab-ctl stop sidekiq
   

   If GitLab is deployed in Docker, run these commands inside the container.

5. Download and transfer the backup archive to the directory where GitLab backups are stored:

   • By default, this is /var/opt/gitlab/backups.
   • If a different directory is used, move the backup there.
   • If S3 Object Storage is used for storing backups, upload the archive there.

6. Restore the gitlab-secrets.json file:

   • Create a copy of the current gitlab-secrets.json file from your Linux/Docker installation. To do this, copy the file /etc/gitlab/gitlab-secrets.json to the administrator’s host.

   • Retrieve rails-secrets.json from Code. Run the following command on the host where the kubectl command is executed for the Deckhouse cluster:

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

   • Move the created rails-secrets.json file to the same directory as the gitlab-secrets.json file, and run the command:

     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
     

   • Replace the current gitlab-secrets.json file with the generated gitlab-secrets-updated.json. To do this, copy gitlab-secrets-updated.json to the host/container where GitLab is running, into the /etc/gitlab/gitlab-secrets.json directory:

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

7. Restore the SSH host keys:

   • On the host where the kubectl command is executed for the Deckhouse cluster, run the following commands:

     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
     

   • Copy the generated files to the host with your Linux/Docker installation into the /etc/gitlab directory:

     cp ssh_host_* /etc/gitlab/
     

8. After replacing the gitlab-secrets.json file, run the command:

   gitlab-ctl reconfigure
   

9. Once the command completes, start the restore process:

   gitlab-backup restore BACKUP=<timestamp>
   

   For example:

   gitlab-backup restore BACKUP=1742909494_2025_03_25_17.8.1
   

10. After restoring, restart GitLab and check its status:

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