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.chartVersionpins the chart version of the release, with theStatictype. To follow GitLab releases after the migration, set a GitLab version inversion, 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 inspec.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-issuerthe chart created. - The Operator generates the shared Secrets through a
GitLabSecretsresource 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.enabledset totrue) that watches the namespace of the release, and has finished rolling out. For more information, see Try Bridge in a development environment. - The
v2alpha1custom resource definitions in the cluster. - The
kubectl bridgeplugin, 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
deployedand 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-controllerinstalls 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
GitLabCoreresource 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:
| Resources | Verbs |
|---|---|
| Secrets and ConfigMaps | list, patch |
gitlabcores.apps.gitlab.com | get, create |
| Every kind of object of the release | get, patch |
| Jobs | delete |
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:
- An Ingress controller that you install and manage outside the release. For more information, see Configure the GitLab chart with an external Ingress Controller.
- The Gateway API, the chart default. For more information, see Migrate to Envoy Gateway.
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:
global:
gatewayApi:
installEnvoy: false
configureEnvoy: trueThe 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>-issuerthrough a Job. - Adds the annotation
cert-manager.io/issuer: <release_name>-issuerto 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:
List the TLS Secrets of the Ingresses:
kubectl get ingress --namespace <namespace> \ --output 'custom-columns=NAME:.metadata.name,SECRETS:.spec.tls[*].secretName'Save these values as
certificates.yaml. Add atls.secretNamefor every Ingress the previous step lists, such as the Ingresses of GitLab Pages: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-tlsIf the release sets
global.ingress.useNewIngressForCertstotrue, leave out theacme.cert-manager.io/http01-edit-in-placeannotation.Upgrade the release on the chart version it runs:
helm upgrade <release_name> gitlab/gitlab --namespace <namespace> \ --version <chart_version> --reuse-values --values certificates.yamlCheck that the Ingresses list the same TLS Secrets as in the first step, and that the certificates are ready:
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:
kubectl bridge migrate <release_name> --from-helm --namespace <namespace> --dry-runThe 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
Run the command without
--dry-run:kubectl bridge migrate <release_name> --from-helm --namespace <namespace>Accept each warning, then confirm the handover.
The command then:
- Changes the
ownerlabel of every record of the release fromhelmtohelm-migrated. From then on,helm listno longer shows the release, andhelm upgradeandhelm uninstallfail. - Hands the fields Helm applied over to the
GitLabCoreresource, so that it removes the settings it no longer renders. - Removes the Helm metadata from the objects that stay without a manager, and deletes the Jobs of the release.
- Creates the
GitLabCoreresource, 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:
kubectl label secrets,configmaps --namespace <namespace> \
--selector name=<release_name>,owner=helm-migrated owner=helm --overwriteThen 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:
kubectl delete secrets,configmaps --namespace <namespace> \
--selector name=<release_name>,owner=helm-migratedAfter you delete the records, the command reports that it finds no Helm release of that name.