If you’ve read my Journey to k8s post, you’re probably wondering how to go about actually making the migration. It’s possible based on your current environment that things may vary however the general steps should all be the same.

This guide is meant to serve as a work along article. Following these steps, minus configuring your own specific instance’s settings, should serve to help you stand up a working instance of your GitLab instance on Kubernetes and make a successful migration off of an on-premise Linux installation.

NOTE: In order to follow along with this guide, you must already have an understanding of Kubernetes, helm charts, as well as your current, in-place omnibus Gitlab installation environment. It also assumes you have a working Kubernetes cluster with persistent volumes setup, in this guide’s case using NFS.

Getting Started

In this tutorial, we’ll be migrating from a currently existing on-premise Linux package-based GitLab installation to a helm chart deployment of GitLab on Kubernetes. As mentioned, we’ll need an already existing Kubernetes cluster with persistent volumes, with added bonuses such as, an ingress controller, Cert-Manager, and logging and metrics tools such as OpenTelemetry, Prometheus, and Grafana.

The reason for this migration is to utilize the inherent benefits of Kubernetes, allowing automatic scaling of resources as needed, as well as allowing for very easy to do rolling updates by simply upgrading the helm chart, completely minimizing any downtime and ensuring your infrastructure is as secure as possible and as up to date as possible. Not to mention all of the cool tools GitLab adds all the time 👀.



There are a few prerequisites to the migration.

  1. Having a working and functional omnibus GitLab installation with no down services, this can be confirmed using gitlab-ctl status.
  2. To verify the integrity of your Git repositories prior to the migration.
  3. A Helm charts based deployment on your Kubernetes cluster, running the same GitLab version as the package-based installation is required.
  4. You need to set up the object storage that the Helm chart based deployment will use. For production use, we recommend you use an external object storage and have the login credentials to access it ready. If you are using the built-in MinIO service, read the docs on how to grab the login credentials from it.

High-Level Steps

The migration can be broken down into a few high-level steps, all of which can be found here.

  1. Migrate any existing files (uploads, artifacts, LFS objects) from the package-based installation to object storage
  2. Create a backup tarball and exclude the already migrated uploads
  3. Restore from the package-based installation to the Helm chart, starting with the secrets.