Migrate from the Helm chart to the Linux package

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

To migrate from a Helm installation to a Linux package (Omnibus) installation:

On the left sidebar, at the bottom, select Admin Area.
Select Overview > Components to check your current version of GitLab.
Prepare a clean machine and install the Linux package that matches your GitLab Helm chart version.
Verify the integrity of Git repositories on your GitLab Helm chart instance before the migration.
Create a backup of your GitLab Helm chart instance, and make sure to back up the secrets as well.
Back up /etc/gitlab/gitlab-secrets.json on your Linux package instance.
Install the yq tool (version 4.21.1 or later) on the workstation where you run kubectl commands.
Create a copy of your /etc/gitlab/gitlab-secrets.json file on your workstation.

Run the following command to obtain the secrets from your GitLab Helm chart instance. Replace GITLAB_NAMESPACE and RELEASE with appropriate values:

kubectl get secret -n GITLAB_NAMESPACE RELEASE-rails-secret -ojsonpath='{.data.secrets\.yml}' | yq '@base64d | from_yaml | .production' -o json > rails-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

The result is gitlab-secrets-updated.json, which you can use to replace the old version of /etc/gitlab/gitlab-secrets.json on your Linux package instance.
After replacing /etc/gitlab/gitlab-secrets.json, reconfigure your Linux package instance:
```
sudo gitlab-ctl reconfigure
```
In the Linux package instance, configure object storage, and make sure it works by testing LFS, artifacts, uploads, and so on.
If you use the Container Registry, configure its object storage separately. It does not support the consolidated object storage.
Sync the data from your object storage connected to the Helm chart instance with the new storage connected to the Linux package instance. A couple of notes:
- For S3-compatible storages, use the s3cmd utility to copy the data.
- If you plan to use an S3-compatible object storage like MinIO with your Linux package instance, you should configure the options endpoint pointing to your MinIO and set path_style to true in /etc/gitlab/gitlab.rb.
- You may re-use your old object storage with the new Linux package instance. In this case, you do not need to sync data between two object storages. However, the storage could be de-provisioned when you uninstall GitLab Helm chart if you are using the built-in MinIO instance.
Copy the GitLab Helm backup to /var/opt/gitlab/backups on your Linux package GitLab instance, and perform the restore.

(Optional) Restore SSH host keys to avoid host mismatch errors on Git SSH clients:

Convert <name>-gitlab-shell-host-keys secret back to files using the following script (required tools: jq, base64, and kubectl):

mkdir ssh
HOSTKEYS_JSON="hostkeys.json"
GITLAB_NAMESPACE="my_namespace"
kubectl get secret -n ${GITLAB_NAMESPACE} gitlab-gitlab-shell-host-keys -o json > ${HOSTKEYS_JSON}

for k in $(jq -r '.data | keys | .[]' ${HOSTKEYS_JSON}); \
do \
  jq -r --arg host_key ${k} '.data[$host_key]' ${HOSTKEYS_JSON}  | base64 --decode > ssh/$k ; \
done

Upload the converted files to the GitLab Rails nodes.

On the target Rails node:

Back up the /etc/ssh/ directory, for example:

sudo tar -czvf /root/ssh_dir.tar.gz -C /etc ssh

Remove the existing host keys:

sudo find /etc/ssh -type f -name "/etc/ssh/ssh_*_key*" -delete

Move the converted host key files in place (/etc/ssh):

for f in ssh/*; do sudo install -b -D  -o root -g root -m 0600 $f /etc/${f} ; done

Restart the SSH daemon:
```
sudo systemctl restart ssh.service
```

After the restore is complete, run the doctor Rake tasks to make sure that the secrets are valid.
After everything is verified, you may uninstall the GitLab Helm chart instance.