Migrate a Helm release of the GitLab chart to a GitLabCore resource

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed
  • Status: Experiment

Use kubectl bridge migrate --from-helm to move an instance that you installed with Helm from the GitLab chart to a GitLabCore resource (apps.gitlab.com/v2alpha1) of the same name. After the migration, you manage the instance in Bridge, not with Helm.

The GitLabCore resource takes over the objects of the release in place. The command deletes no object of the release other than its Jobs, so the instance stays up. Only the pods whose configuration changes restart.

Bridge is an experiment in an early development phase. Migrate only an instance you can afford to lose.

Data the migration keeps

The migration keeps:

  • The Gitaly volumes, and with them the Git repositories.
  • The Secrets the GitLab chart generated, such as the Rails secrets and the root password.
  • The external PostgreSQL, Redis, and object storage, and the data in them.
  • The Gateway and its load balancer, so the instance keeps its IP addresses.
  • The cert-manager issuer of the Gateway, so certificates keep being issued and renewed.
  • The records of the Helm release. The command hides them from Helm, and does not delete them. To delete them after the migration, see Delete the release records.

The command deletes the Jobs of the release, such as the migrations Job. They ran once, and the GitLabCore resource runs Jobs of its own.

What stays without a manager

A GitLabCore resource never installs a component that a cluster runs once, nor RBAC or custom resource definitions. The objects of the release it does not render stay in the cluster, and keep running, but nothing manages or upgrades them after the migration:

  • The bundled cert-manager, Envoy Gateway, GitLab Runner, and Prometheus, which the chart installs by default. The Gateway and its certificates depend on cert-manager and Envoy Gateway.
  • The Roles, RoleBindings, ClusterRoles, ClusterRoleBindings, and custom resource definitions of the release.
  • The hooks of the release that Helm left in the cluster, other than Jobs, such as the RBAC of the certificate Job of Envoy Gateway.

The command removes the Helm annotations and the app.kubernetes.io/managed-by: Helm label from these objects, and lists them when the migration is done. To manage one of these components again, install it from its own chart. For example, Helm 3.17 and later take over the existing objects of a component with helm install --take-ownership.

To take Envoy Gateway out of the release before you migrate, see Move off the bundled Envoy Gateway.

How the command drafts the GitLabCore resource

The command reads the values you set on the release, as helm get values shows them, and drafts a GitLabCore resource that renders the same chart values:

  • spec.version.chartVersion pins the chart version of the release, with the Static type. To follow GitLab releases after the migration, set a GitLab version in version, or change the version type.
  • A setting moves into a structured field, such as spec.domain, only when the chart values stay the same. Every other setting stays in spec.chart.values.
  • The components the chart turns on by default, such as the container registry, the Toolbox, and the Gateway API, stay on.
  • When the chart requested a certificate for the Gateway, the Gateway keeps the issuer <release_name>-gw-issuer the chart created.
  • The Operator generates the shared Secrets through a GitLabSecrets resource instead of the shared secrets Job. It keeps every existing Secret, and adds only missing keys.

The command prints every difference from the release, grouped by topic, such as Components:, Persistence:, or Secrets:.

Prerequisites

  • An Operator with Bridge enabled (bridge.enabled set to true) that watches the namespace of the release, and has finished rolling out. For more information, see Try Bridge in a development environment.
  • The v2alpha1 custom resource definitions in the cluster.
  • The kubectl bridge plugin, built from the same branch as the Operator image.
  • A release that Helm stores in Secrets or ConfigMaps, the default storage drivers, whose latest revision is deployed and runs GitLab chart 10.5.0 or later.
  • The release does not use the bundled NGINX Ingress, HAProxy, or Traefik, and does not request cert-manager certificates for its Ingresses (global.ingress.configureCertmanager). For more information, see Prepare a release with bundled controllers.
  • Flux does not manage the release. Its helm-controller installs the release again once Helm no longer finds it. Argo CD keeps no Helm release, so the command cannot migrate an instance Argo CD renders.
  • No GitLabCore resource of the same name exists in the namespace.
  • Your kubeconfig identity has the permissions the command needs.

Optional. Back up the instance before you migrate it.

Permissions the command needs

The command acts as your kubeconfig identity. In the namespace of the release, it needs:

ResourcesVerbs
Secrets and ConfigMapslist, patch
gitlabcores.apps.gitlab.comget, create
Every kind of object of the releaseget, patch
Jobsdelete

It also patches the cluster-scoped objects of the release, such as its ClusterRoles. To check the Operator, the command lists Deployments in all namespaces. Without that permission, the command cannot check the Operator, and warns instead.

Prepare a release with bundled controllers

The command refuses a release that runs a bundled Ingress controller, or that requests cert-manager certificates for its Ingresses. It keeps the bundled Envoy Gateway running without a manager. Change the release with helm upgrade before you migrate it. Then check that GitLab is reachable, and run the command with --dry-run again.

Move off a bundled Ingress controller

The bundled NGINX Ingress, HAProxy, and Traefik charts are deprecated. A GitLabCore resource does not install them. The command refuses a release that sets nginx-ingress.enabled, nginx-ingress-geo.enabled, haproxy.install, or traefik.install to true.

Move the release to one of these options:

If the release requests certificates for its Ingresses, also keep the certificates of the Ingresses.

Move off the bundled Envoy Gateway

The chart installs Envoy Gateway by default (global.gatewayApi.installEnvoy). A GitLabCore resource does not install it, so the migration keeps the bundled Envoy Gateway running without a manager. Nothing upgrades it after the migration.

To manage Envoy Gateway yourself, install it outside the release before you migrate. Then upgrade the release with these values:

yaml
global:
  gatewayApi:
    installEnvoy: false
    configureEnvoy: true

The chart then no longer installs Envoy Gateway. It still renders the GatewayClass, the EnvoyProxy, and the Envoy Gateway policies for your installation. To use another Gateway API provider instead, see Using an external Gateway API provider.

Keep the certificates of the Ingresses

When global.ingress.configureCertmanager is true, the chart:

  • Creates the cert-manager Issuer <release_name>-issuer through a Job.
  • Adds the annotation cert-manager.io/issuer: <release_name>-issuer to every Ingress.
  • Names the TLS Secret of each Ingress after the release, such as <release_name>-gitlab-tls.

A GitLabCore resource does not run that Job, so the command refuses the release. Set the annotation and the TLS Secrets in the values yourself instead. The Ingresses then keep their certificates, and cert-manager keeps renewing them through the existing Issuer.

When global.ingress.configureCertmanager is false, an Ingress without a tls.secretName uses a self-signed wildcard certificate. Name the TLS Secret of every Ingress.

To keep the certificates:

  1. List the TLS Secrets of the Ingresses:

    shell
    kubectl get ingress --namespace <namespace> \
      --output 'custom-columns=NAME:.metadata.name,SECRETS:.spec.tls[*].secretName'
  2. Save these values as certificates.yaml. Add a tls.secretName for every Ingress the previous step lists, such as the Ingresses of GitLab Pages:

    yaml
    global:
      ingress:
        configureCertmanager: false
        annotations:
          cert-manager.io/issuer: <release_name>-issuer
          acme.cert-manager.io/http01-edit-in-place: "true"
    gitlab:
      webservice:
        ingress:
          tls:
            secretName: <release_name>-gitlab-tls
      kas:
        ingress:
          tls:
            secretName: <release_name>-kas-tls
    registry:
      ingress:
        tls:
          secretName: <release_name>-registry-tls

    If the release sets global.ingress.useNewIngressForCerts to true, leave out the acme.cert-manager.io/http01-edit-in-place annotation.

  3. Upgrade the release on the chart version it runs:

    shell
    helm upgrade <release_name> gitlab/gitlab --namespace <namespace> \
      --version <chart_version> --reuse-values --values certificates.yaml
  4. Check that the Ingresses list the same TLS Secrets as in the first step, and that the certificates are ready:

    shell
    kubectl get certificates --namespace <namespace>

The upgrade removes the Job that created the Issuer, and keeps the Issuer, because Helm did not create it. After the migration, the Issuer stays without a manager.

For more information about the TLS options of the chart, see Configure TLS for the GitLab chart.

Review the draft

Run the command with --dry-run. The command checks the release, prints the GitLabCore resource it drafts, and changes nothing:

shell
kubectl bridge migrate <release_name> --from-helm --namespace <namespace> --dry-run

The output lists the structured fields the draft moved settings into, the differences from the release, the warnings you must accept, and the blockers. Resolve every blocker, and run the command again until the output lists none.

Migrate the instance

  1. Run the command without --dry-run:

    shell
    kubectl bridge migrate <release_name> --from-helm --namespace <namespace>
  2. Accept each warning, then confirm the handover.

The command then:

  1. Changes the owner label of every record of the release from helm to helm-migrated. From then on, helm list no longer shows the release, and helm upgrade and helm uninstall fail.
  2. Hands the fields Helm applied over to the GitLabCore resource, so that it removes the settings it no longer renders.
  3. Removes the Helm metadata from the objects that stay without a manager, and deletes the Jobs of the release.
  4. Creates the GitLabCore resource, waits until it is available, and lists the objects of the release it did not take over.

To skip the prompts, for example in a script, add --yes. By default, the command waits up to 30 minutes for the GitLabCore resource to become available. To change that limit, use --timeout.

Continue an interrupted migration

If the command stops, for example at a timeout, it undoes nothing. Run the same command again. The command reads the step from the records of the release. While Helm still finds the release, the command shows the draft and asks for confirmation again. After it hid every record, it continues without asking.

Hand the release back to Helm before the GitLabCore exists

If the command stops before it creates the GitLabCore resource, you can hand the release back to Helm. Restore the owner label of the records:

shell
kubectl label secrets,configmaps --namespace <namespace> \
  --selector name=<release_name>,owner=helm-migrated owner=helm --overwrite

Then run helm upgrade with the values of the release, so that Helm applies its metadata again.

After the GitLabCore resource exists, the command does not support handing the instance back to Helm. Deleting the GitLabCore resource deletes every object it manages, including the volume claims and Secrets the release rendered, such as the backup volume of the Toolbox. The Gitaly volumes and the Secrets the chart generated stay.

Delete the release records

After the migration, the records of the release stay in the namespace, hidden from Helm. Helm keeps a record for each revision, up to 10 by default. Each record holds the values of the release without encryption, including any password or token you passed with --set or a values file.

Delete the records only after the command prints Done.. Until then, the command continues an interrupted migration from them, and you need them to hand the release back to Helm. Deleting the records does not change the objects of the instance.

To delete the records, run the command that the migration prints:

shell
kubectl delete secrets,configmaps --namespace <namespace> \
  --selector name=<release_name>,owner=helm-migrated

After you delete the records, the command reports that it finds no Helm release of that name.