- Prerequisites
- Installing the GitLab Operator
- Installing GitLab
- Recommended next steps
- Uninstall the GitLab Operator
- Troubleshoot the GitLab Operator
Installation
This document describes how to deploy the GitLab Operator by using manifests in your Kubernetes or OpenShift cluster.
If using OpenShift, installation is typically handled by the Operator Lifecycle Manager (OLM). Installation using OLM is considered experimental.GitLab does not support any issues related to instances deployed using OLM. For more information on potential issues with OLM, seeissue 241.
Prerequisites
- Create or use an existing Kubernetes or OpenShift cluster
- Install pre-requisite services and software
- Configure Domain Name Services
Cluster
To create a traditional Kubernetes cluster, consider usingofficial toolingor your preferred method of installation.
The GitLab Operator supports the following Kubernetes versions:
Kubernetes release | Status | Minimum Operator version | Architectures | End of life |
---|---|---|---|---|
1.30 | In qualification | x86-64 | 2025-06-28 | |
1.29 | Supported | 1.0.0 | x86-64 | 2025-02-28 |
1.28 | Supported | 1.0.0 | x86-64 | 2024-10-28 |
1.27 | Supported | 0.29.0 | x86-64 | 2024-06-28 |
1.26 | Deprecated | 0.24.0 | x86-64 | 2024-02-28 |
1.25 | Deprecated | 0.24.0 | x86-64 | 2023-10-28 |
1.24 | Deprecated | 0.24.0 | x86-64 | 2023-07-28 |
1.23 | Deprecated | 0.24.0 | x86-64 | 2023-02-28 |
1.22 | Deprecated | 0.24.0 | x86-64 | 2022-10-28 |
To create an OpenShift cluster, see theOpenShift cluster setup documentationfor an example of how to create adevelopment environment.
The GitLab Operator supports the following OpenShift versions:
OpenShift release | Status | Minimum Operator version | Architectures | End of life |
---|---|---|---|---|
4.17 | In qualification | x86-64 | ||
4.16 | Supported | 1.3.0 | x86-64 | 2027-06-27 |
4.15 | Supported | 0.31.0 | x86-64 | 2025-08-27 |
4.14 | Supported | 0.27.0 | x86-64 | 2026-10-31 |
4.13 | Supported | 0.24.0 | x86-64 | 2024-11-17 |
4.12 | Supported | 0.24.0 | x86-64 | 2025-01-17 |
4.11 | Deprecated | 0.24.0 | x86-64 | 2024-02-10 |
The GitLab Operator aims to support new minor Kubernetes and OpenShift versions three months after their initial releases. We welcome any compatibility issues with releases newer than those listed above in ourissue tracker.
Some GitLab features might not work on deprecated versions and versions older than the versions listed above.
For some components, like theagent for KubernetesandGitLab Charts,GitLab might support different cluster versions.
Starting with 16.7, the Operator is built for x86-64 and arm64. The arm64 images are not tested in CI and are not recommended for production use.
If you are on a multi-arch cluster you may want to add anode selector
for thekubernetes.io/arch
labelto the Operator Deployment.
Patch the Deployment to be scheduled on x86-64/amd64 nodes only:
kubectl patch deployments gitlab-controller-manager\
-p'{ "spec": { "template": { "spec": { "nodeSelector": { "kubernetes.io/arch": "amd64" }}}}}'
If you are using the Operator Helm chart you can add the node selector to yourvalues.yaml
instead:
nodeSelector:
kubernetes.io/arch:amd64
This ensures that the Operator runs onamd64
nodes, using the platform that we currently test.
Seeepic 10928for more information on the arm64 support for CNG images.
Ingress controller
An Ingress controller is required to provide external access to the application and secure communication between components.
The GitLab Operator deploys ourforked NGINX chart from the GitLab Helm Chartby default.
If you prefer to use an external Ingress controller, useNGINX Ingressby the Kubernetes community to deploy an Ingress Controller. Follow the relevant instructions in the link based on your platform and preferred tooling. Take note of the Ingress class value for later (it typically defaults tonginx
).
When configuring the GitLab CR, be sure to setnginx-ingress.enabled=false
to disable the NGINX objects from the GitLab Helm Chart.
TLS certificates
To create a certificate for the operator’s Kubernetes webhook,cert-manageris used. You should usecert-managerfor the GitLab certificates as well.
Because the operator needs a certificate for the Kubernetes webhook, you can’t use the cert-manager bundled with the GitLab Chart. Instead, install cert-manager before you install the operator.
Follow theinstallation documentationto install a supported cert-manager releasefor your platform and tooling.
Metrics
Install themetrics serverso the HorizontalPodAutoscalers can retrieve pod metrics.
OpenShift ships withPrometheus Adapterby default, so all you need to do is setspec.chart.values.prometheus.install=false
in your GitLab custom resource to prevent the GitLab Operator from installing another instance.
Configure Domain Name Services
You need an internet-accessible domain to which you can add a DNS record.
See ournetworking and DNS documentationfor more details on connecting your domain to the GitLab components. You use the configuration mentioned in this section when defining your GitLab custom resource (CR).
Ingress in OpenShift requires extra consideration. See ournotes on OpenShift Ingressfor more information.
Installing the GitLab Operator
Start by selecting an installation method.
First, retrieve a release manifest from the Operator releases page. Select the manifest that matches your target platform: Kuberentes or OpenShift.
Next, create the namespace where the operator will be installed.
In the manifest, the namespace is set togitlab-system
by default.
To change the namespace, either update the manifest manually or consider
using the Helm chart where this key and others can be easily configured.
kubectl create namespace gitlab-system
Finally, apply the manifest:
kubectl apply-fgitlab-operator-<platform>.yaml
First, add the GitLab Helm repository and retrieve the latest udpates.
helm repo add gitlab https://charts.gitlab.io
helm repo update
You can then install the GitLab Operator chart:
helminstallgitlab-operator gitlab/gitlab-operator\
--create-namespace\
--namespacegitlab-system
Seevalues.yaml
for all available configuration options.
The GitLab Operator is available in the following OLM channels:
Channel | Listing | Source |
---|---|---|
OperatorHub Community Operators | Link | Link |
OpenShift Community Operators | Available in the embedded OperatorHub in OpenShift and OKD | Link |
OpenShift Certified Operators | Link | Link |
Confirm the installation by checking the status of the Operator Deployment:
kubectl-ngitlab-system get deployment gitlab-controller-manager
Installing GitLab
-
Create a GitLab custom resource (CR).
Create a new file named something like
mygitlab.yaml
.Here is an example of the content to put in this file:
apiVersion:apps.gitlab.com/v1beta1 kind:GitLab metadata: name:gitlab spec: chart: version:"X.Y.Z "# https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/<OPERATOR_VERSION>/CHART_VERSIONS values: global: hosts: domain:example.com# use a real domain here ingress: configureCertmanager:true certmanager-issuer: email:[email protected]# use your real email address here
For more details on configuration options to use under
spec.chart.values
, see theGitLab Helm Chart documentation. -
Deploy a GitLab instance using your new GitLab CR.
kubectl-ngitlab-system apply-fmygitlab.yaml
This command sends your GitLab CR up to the cluster for the GitLab Operator to reconcile. You can watch the progress by tailing the logs from the controller pod:
kubectl-ngitlab-system logs deployment/gitlab-controller-manager-cmanager-f
You can also list GitLab resources and check their status:
$kubectl-ngitlab-system get gitlab NAME STATUS VERSION gitlab Ready 5.2.4
When the CR is reconciled (the status of the GitLab resource isRunning
), you can access GitLab in your browser athttps://gitlab.example.com
.
To log in you need to retrieve the initial root password for your deployment. See theHelm Chart documentationfor further instructions.
Recommended next steps
After completing your installation, consider taking the recommended next steps, including authentication options and sign-up restrictions.
OpenShift
If you run OpenShift, change the approval strategy for the GitLab Operator from automatic (the default) to manual. This prevents OpenShift from installing new operator versions until approval is given.
You can also set a customstartingCSV
to pin the Operator’s version or to upgrade to a non-latest version.
- The approval strategy can be changed from theOpenShift web console or byediting the Subscription.
- Set
.spec.approved
totrue
of theInstallPlan
to approve an manual upgrade. - Each GitLab Operator supports a defined subset of GitLab chart versions: upgrades to the GitLab Operator must also involve updating the chart version in the GitLab custom resource.
- If the Operator and specified chart version are incompatible, configuration changes to the chart can fail with errors about the chart version.
Uninstall the GitLab Operator
Follow the steps below to remove the GitLab Operator and its associated resources.
Items to note prior to uninstalling the operator:
- The operator does not delete the Persistent Volume Claims or Secrets when a GitLab instance is deleted.
- When deleting the Operator, the namespace where it is installed (
gitlab-system
by default) is not deleted automatically. This ensures that persistent volumes are not lost unintentionally.
Uninstall an instance of GitLab
kubectl-ngitlab-system delete-fmygitlab.yaml
This removes the GitLab instance, and all associated objects except for Persistent Volume Claims as noted above).
Uninstall the GitLab Operator
GL_OPERATOR_VERSION=<your_installed_version># https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/releases
PLATFORM=kubernetes# or "openshift"
kubectl delete-fhttps://gitlab.com/api/v4/projects/18899486/packages/generic/gitlab-operator/${GL_OPERATOR_VERSION}/gitlab-operator-${PLATFORM}-${GL_OPERATOR_VERSION}.yaml
This deletes the Operator’s resources, including the running Deployment of the Operator. Thisdoes notdelete objects associated with a GitLab instance.
Troubleshoot the GitLab Operator
Troubleshooting the Operator can be found introubleshooting.md.