Migrating GitLab Omnibus to Kubernetes with GitLab Operator

Overview

This guide outlines the process to migrate an existing GitLab installation using the Omnibus package to a Kubernetes cluster managed by the GitLab Operator. Note that GitLab Operator does not support direct migration from Omnibus or Helm chart installations. Instead, you must perform a backup and restore operation.

The migration leverages GitLab’s backup and restore functionality, which is compatible between different deployment methods.

Prerequisites

  • A running GitLab Omnibus installation.
  • A Kubernetes cluster with GitLab Operator installed.
  • Access to object storage (recommended for production).
  • Sufficient storage space for backups.
  • Same GitLab version on both source and target.

Migration Steps

1. Prepare the Omnibus Installation

Ensure your GitLab instance is healthy:

sudo gitlab-ctl status

Verify repository integrity:

sudo gitlab-rake gitlab:git:fsck

For production deployments, migrate uploads, artifacts, and other data to external object storage to avoid storing large amounts of data in the backup.

Follow the object storage migration guide.

3. Create a Backup

Create a backup of your Omnibus installation, excluding directories already migrated to object storage:

sudo gitlab-backup create EXCLUDE=artifacts,uploads,lfs,pages,registry

The backup file will be stored in /var/opt/gitlab/backups/ by default.

4. Deploy GitLab Operator

Install GitLab Operator on your Kubernetes cluster following the installation documentation.

Create a GitLab custom resource with appropriate configuration for your environment.

5. Restore the Backup

Use the Toolbox pod to restore the backup to your Operator-managed GitLab instance.

First, copy the backup file to a location accessible by the Toolbox pod, then run:

kubectl exec -it <toolbox-pod-name> -- /bin/bash
gitlab-backup restore BACKUP=<backup-filename>

6. Migrate Secrets

Copy secrets from /etc/gitlab/gitlab-secrets.json on the Omnibus server to your GitLab custom resource configuration.

7. Restart Pods

Restart all GitLab pods to apply changes:

kubectl delete pods -l app.kubernetes.io/instance=<gitlab-instance-name>

8. Verify the Migration

  • Access the GitLab UI and verify users, groups, projects, and issues are present.
  • Check that uploaded files and avatars load correctly.
  • Test repository access and CI/CD pipelines.

Troubleshooting

  • If restore fails, check the Toolbox pod logs.
  • Ensure network connectivity between the backup location and Kubernetes cluster.
  • For large backups, consider using persistent volumes or cloud storage.

Resources