GitLab Operator

GitLab Operator is an implementation of the Operator pattern for managing the lifecycle and upgrades of a GitLab instance. The GitLab Operator strengthens the support of OpenShift from GitLab, but is intended to be as native to Kubernetes as for OpenShift. The GitLab Operator provides a method of synchronizing and controlling various stages of cloud-native GitLab installation/upgrade procedures. Using the Operator provides the ability to perform rolling upgrades with minimal down time. The first goal is to support OpenShift, the subsequent goal will be for automation of day 2 operations like upgrades as noted.

The Operator offers the benefit of Day 2 operators to the GitLab installation, there are many automation benefits to utilizing the Operator vs Helm. The Operator utilizes the Helm Chart but the Operator will continuously run making upgrading, backups, and more, automatic.

The GitLab Operator aims to:

  • Manage the full lifecycle of GitLab instances in your OpenShift container platforms.
  • Ease the installation and configuration of GitLab instances.
  • Offer seamless upgrades from version to version.
  • Ease backup and restore of GitLab and its components.
  • Aggregate and visualize metrics using Prometheus and Grafana.
  • Set up auto-scaling.

The GitLab Operator does not include the GitLab Runner. For more information, see the GitLab Runner Operator repository.

Known limitations

Below are the known limitations of the GitLab Operator:

  • Certain components not supported:
    • Praefect: see issue #136
    • KAS: see issue #139


Before you install GitLab with GitLab Operator, you must:

  1. Create or use an existing Kubernetes or OpenShift cluster:
  2. Install the following services and software:

    • Ingress controller

      An Ingress controller is required to provide external access to the application and secure communication between components. The GitLab Operator will deploy our forked NGINX chart from the GitLab Helm Chart by default. If you prefer to use an external Ingress controller, we recommend NGINX Ingress by 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 to nginx).

      When configuring the GitLab custom resource (CR), be sure to set nginx-ingress.enabled=false to disable the NGINX objects from the GitLab Helm Chart.

    • Certificate manager

      For the TLS certificates, we recommend Cert Manager to create certificates used to secure the GitLab and Registry URLs. Follow the relevant instructions in the link based on your platform and preferred tooling.

    • Metrics server

      • Kubernetes: Install the metrics server so the HorizontalPodAutoscalers can retrieve pod metrics.
      • OpenShift: OpenShift ships with Prometheus Adapter by default, so there is no manual action required here.
  3. Configure the Domain Name services:

    You will need an internet-accessible domain to which you can add a DNS record. See our networking and DNS documentation for more details on connecting your domain to the GitLab components. You will use the configuration mentioned in this section when defining your GitLab custom resource (CR).

Install the GitLab Operator

This document describes how to deploy the GitLab Operator via manifests in your Kubernetes or OpenShift cluster.

If using OpenShift, these steps normally are handled by the Operator Lifecycle Manager (OLM) once an operator is bundle published. However, to test the most recent operator images, users may need to install the operator using the deployment manifests available in the operator repository.

  1. Deploy the GitLab Operator:

    PLATFORM=kubernetes # or "openshift"
    kubectl create namespace gitlab-system
    kubectl apply -f${GL_OPERATOR_VERSION}/gitlab-operator-${PLATFORM}-${GL_OPERATOR_VERSION}.yaml
    18899486 is the ID of the GitLab Operator project.

    This command first deploys the service accounts, roles and role bindings used by the operator, and then the operator itself.

    By default, the Operator will only watch the namespace where it is deployed. If you’d like it to watch at the cluster scope, then remove the WATCH_NAMESPACE environment variable from the Deployment in the manifest under: spec.template.spec.containers[0].env and re-run the kubectl apply command above.

    Running the Operator at the cluster scope is considered experimental. See issue #100 for more information.
  2. Create a GitLab custom resource (CR), by creating a new YAML file (for example named mygitlab.yaml). Here is an example of the content to put in this file:

    kind: GitLab
      name: example
        version: "X.Y.Z" # select a version from the CHART_VERSIONS file in the root of this project
              domain: # Provide a real base domain for GitLab. "gitlab." and "registry." will be exposed as subdomains.
              externalIP: "" # If using a static wildcard DNS record for the base domain, enter the IP address it resolves to here.
              configureCertmanager: true
            email: # use your real email address here

    For more details on configuration options to use under spec.chart.values, see the GitLab Helm Chart documentation.

  3. Deploy a GitLab instance using your new GitLab CR:

    kubectl -n gitlab-system apply -f mygitlab.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 -n gitlab-system logs deployment/gitlab-controller-manager -c manager -f

    You can also list GitLab resources and check their status:

    kubectl get gitlabs -n gitlab-system

    When the CR is reconciled (the status of the GitLab resource will be RUNNING), you can access GitLab in your browser at the domain you set up in the custom resource.

    To log in use the base domain you specified, with the gitlab subdomain, for example: An initial administrator account has also been created. The username is root and the password is stored in the <name>-gitlab-initial-root-password secret. By default, this is in the gitlab-system namespace, and must be base64 decoded to use.

  kubectl -n gitlab-system get secret <name>-gitlab-initial-root-password -ojsonpath='{.data.password}' | base64 --decode ; echo

Uninstall the GitLab Operator

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’s installed (gitlab-system by default) will not be deleted automatically. This is to ensure persistent volumes are not lost unintentionally.

To remove the GitLab Operator and its associated resources:

  1. Uninstall the GitLab instance:

    kubectl -n gitlab-system delete -f mygitlab.yaml

    This will remove the GitLab instance, and all associated objects except for PVCs as noted above.

  2. Uninstall the GitLab Operator.

    PLATFORM=kubernetes # or "openshift"
    kubectl delete -f${GL_OPERATOR_VERSION}/gitlab-operator-${PLATFORM}-${GL_OPERATOR_VERSION}.yaml

    This will delete the Operator’s resources, including the running Deployment of the Operator. This will not delete objects associated with a GitLab instance.