Installing GitLab using Helm

Install GitLab on Kubernetes with the cloud native GitLab Helm chart.

Important considerations

The following considerations should be well noted for implementing production GitLab environments.

Default Helm chart configuration not intended for production

Installing GitLab using only the Helm charts creates a proof of concept (POC) implementation where all GitLab services are placed into the cluster. GitLab Cloud Native Hybrid Reference Architectures specify that the stateful components such as PostgreSQL or Gitaly (Git repository storage dataplane) run outside the cluster on PaaS or compute instances. This is required in order to scale and reliably service the many varieties of workloads found in production GitLab environments. Additionally it is allowable, and generally preferable, to take advantage of Cloud PaaS for PostgreSQL, Redis, and object storage for all non-Git repository storages.

Configure Helm charts to external stateful data

The GitLab Helm charts can be configured to point to external stateful storage for items such as the PostgreSQL, Redis, all Non-Git repository storage as well as Git repository storage (Gitaly). The Infrastructure as Code (IaC) options below use this approach. For production-grade implementation the appropriate chart parameters should be used to point to prebuilt, externalized state stores that align with the chosen Reference Architecture.

Use GitLab Cloud Native Hybrid Reference Architectures

The Reference Architecture for deploying GitLab instances to Kubernetes is called Cloud Native Hybrid specifically because not all GitLab services can run in the cluster for production-grade implementations. Each Cloud Native Hybrid Reference Architecture is detailed within the overall architecture page. For instance, here is the Cloud Native Hybrid reference architecture alternative for the 3,000 user count.

GitLab Cloud Native Hybrid deployment with Infrastructure as Code (IaC) and builder resources

GitLab develops Infrastructure as Code that is capable of configuring the combination of Helm charts and supplemental cloud infrastructure:

Requirements

To deploy GitLab on Kubernetes, the following are required:

  1. kubectl 1.16 or higher, compatible with your cluster (+/- 1 minor release from your cluster).
  2. Helm v3 (3.3.1 or higher).

  3. A Kubernetes cluster, version 1.16 through 1.21. 8vCPU and 30GB of RAM is recommended.

note
If using the in-chart NGINX Ingress Controller (nginx-ingress.enabled=true), then Kubernetes 1.19 or newer is required.
note
Support for Kubernetes 1.22 is under active development - see &6883 for more information.
note
Helm v2 has reached end of lifecyle. If GitLab has been previously installed with Helm v2, you should use Helm v3 as soon as possible. Please consult the Helm migration document.

Environment setup

Before proceeding to deploying GitLab, you need to prepare your environment.

Tools

helm and kubectl must be installed on your computer.

Cloud cluster preparation

note
Kubernetes 1.16 through 1.21 is required, due to the usage of certain Kubernetes features.

Follow the instructions to create and connect to the Kubernetes cluster of your choice:

Deploying GitLab

With the environment set up and configuration generated, you can now proceed to the deployment of GitLab.

Upgrading GitLab

If you are upgrading an existing Kubernetes installation, follow the upgrade documentation instead.

Migrate from or to the GitLab Helm chart

To migrate your existing GitLab Linux package installation to your Kubernetes cluster, or vice versa, follow the migration documentation.