A new cloud native GitLab chart is in development with increased scalability and resilience, among other benefits. The cloud native chart will replace both the gitlab and gitlab-omnibus charts when available later this year.

Due to the significant architectural changes, migrating will require backing up data out of this instance and restoring it into the new deployment. For more information on available GitLab Helm Charts, please see our overview.

The different images can be found in the gitlab-ce and gitlab-ee
repositories on Docker Hub

Note:
There is no guarantee that other release versions of GitLab, other than what are
used by default in the chart, will be supported by a chart install.

Custom Omnibus GitLab configuration

In addition to the configuration options provided for GitLab in the Helm Chart, you can also pass any custom configuration
that is valid for the Omnibus GitLab Configuration.

The setting to pass these values in is omnibusConfigRuby. It accepts any valid
Ruby code that could used in the Omnibus /etc/gitlab/gitlab.rb file. In
Kubernetes, the contents will be stored in a ConfigMap.

Persistent storage

By default, persistent storage is enabled for GitLab and the charts it depends
on (Redis and PostgreSQL).

Components can have their claim size set from your values.yaml, and each
component allows you to optionally configure the storageClass variable so you
can take advantage of faster drives on your cloud provider.

Note:
You can make use of faster SSD drives by adding a StorageClass to your cluster
and using the storageClass setting in the above config to the name of
your new storage class.

Routing

By default, the GitLab chart uses a service type of LoadBalancer which will
result in the GitLab service being exposed externally using your cloud provider's
load balancer.

This field is configurable in your values.yml by setting the top-level
serviceType field. See the Service documentation for more
information on the possible values.

Ingress routing

Optionally, you can enable the Chart's ingress for use by an ingress controller
deployed in your cluster.

To enable the ingress, edit its section in your values.yaml:

ingress:## If true, gitlab Ingress will be created##enabled:true## gitlab Ingress hostnames## Must be provided if Ingress is enabled##hosts:-gitlab.example.com## gitlab Ingress annotations##annotations:kubernetes.io/ingress.class:nginx

You must also provide the list of hosts that the ingress will use. In order for
you ingress controller to work with the GitLab Ingress, you will need to specify
its class in an annotation.

Note:
The Ingress alone doesn't expose GitLab externally. You need to have a Ingress controller setup to do that.
Setting up an Ingress controller can be done by installing the nginx-ingress helm chart. But be sure
to read the documentation.
Note:
If you would like to use the Registry, you will also need to ensure your Ingress supports a sufficiently large request size.

Preserving Source IPs

If you are using the LoadBalancer serviceType you may run into issues where user IP addresses in the GitLab
logs, and used in abuse throttling are not accurate. This is due to how Kubernetes uses source NATing on cluster nodes without endpoints.

To fix this you can add the following service annotation to your values.yaml

## For minikube, set this to NodePort, elsewhere use LoadBalancer## ref: http://kubernetes.io/docs/user-guide/services/#publishing-services---service-types##serviceType:LoadBalancer## Optional annotations for gitlab service.serviceAnnotations:service.beta.kubernetes.io/external-traffic:"OnlyLocal"

Note:
If you are using the ingress routing, you will likely also need to specify the annotation on the service for the ingress
controller. For nginx-ingress you can check the
configuration documentation
on how to add the annotation to the controller.service.annotations array.

Note:
When using the nginx-ingress controller on Google Kubernetes Engine (GKE), and using the external-traffic annotation,
you will need to additionally set the controller.kind to be DaemonSet. Otherwise only pods running on the same node
as the nginx controller will be able to reach GitLab. This may result in pods within your cluster not being able to reach GitLab.
See the Kubernetes documentation and
nginx-ingress configuration documentation
for more information.

External database

You can configure the GitLab Helm chart to connect to an external PostgreSQL
database.

Note:
This is currently our recommended approach for a Production setup.

To use an external database, in your values.yaml, disable the included
PostgreSQL dependency, then configure access to your database:

dbHost:"<reachablepostgreshostname>"dbPassword:"<passwordfortheuserwithaccesstothedb>"dbUsername:"<userwithread/writeaccesstothedatabase>"dbDatabase:"<databasenameonpostgrestoconnecttoforGitLab>"postgresql:# Sets whether the PostgreSQL helm chart is used as a dependencyenabled:false

You can also configure the chart to use an external Redis server, but this is
not required for basic production use:

dbHost:"<reachableredishostname>"dbPassword:"<password>"redis:# Sets whether the Redis helm chart is used as a dependencyenabled:false

Sending email

By default, the GitLab container will not be able to send email from your cluster.
In order to send email, you should configure SMTP settings in the
omnibusConfigRuby section, as per the GitLab Omnibus documentation.

Note:
Some cloud providers restrict emails being sent out on SMTP, so you will have
to use a SMTP service that is supported by your provider. See this
Google Cloud Platform page
as and example.

HTTPS configuration

In addition to having a Ingress Controller deployed and the basic ingress
settings configured, you will also need to specify in the ingress settings
which hosts to use HTTPS for.

Make sure externalUrl now includes https:// instead of http:// in its
value, and update the omnibusConfigRuby section:

externalUrl:'https://gitlab.example.com'omnibusConfigRuby:|# This is example config of what you may already have in your omnibusConfigRuby objectunicorn['worker_processes'] = 2;gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"];# These are the settings needed to support proxied SSLnginx['listen_port'] = 80nginx['listen_https'] = falsenginx['proxy_set_headers'] = {"X-Forwarded-Proto" => "https","X-Forwarded-Ssl" => "on"}ingress:enabled:trueannotations:kubernetes.io/ingress.class:nginx# kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt supporthosts:-gitlab.example.com## gitlab Ingress TLS configuration## Secrets must be created in the namespace, and is not done for you in this chart##tls:-secretName:gitlab-tlshosts:-gitlab.example.com

You will need to create the named secret in your cluster, specifying the private
and public certificate pair using the format outlined in the
ingress documentation.

Alternatively, you can use the kubernetes.io/tls-acme annotation, and install
the kube-lego chart to your cluster to have Let's Encrypt issue your
certificate. See the kube-lego documentation
for more information.

Enabling the GitLab Container Registry

The GitLab Registry is disabled by default but can be enabled by providing an
external URL for it in the configuration. In order for the Registry to be easily
used by GitLab CI and your Kubernetes cluster, you will need to set it up with
a TLS certificate, so these examples will include the ingress settings for that
as well. See the HTTPS Configuration section
for more explanation on some of these settings.

Example config:

externalUrl:'https://gitlab.example.com'omnibusConfigRuby:|# This is example config of what you may already have in your omnibusConfigRuby objectunicorn['worker_processes'] = 2;gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"];registry_external_url 'https://registry.example.com';# These are the settings needed to support proxied SSLnginx['listen_port'] = 80nginx['listen_https'] = falsenginx['proxy_set_headers'] = {"X-Forwarded-Proto" => "https","X-Forwarded-Ssl" => "on"}registry_nginx['listen_port'] = 80registry_nginx['listen_https'] = falseregistry_nginx['proxy_set_headers'] = {"X-Forwarded-Proto" => "https","X-Forwarded-Ssl" => "on"}ingress:enabled:trueannotations:kubernetes.io/ingress.class:nginx# kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt supporthosts:-gitlab.example.com-registry.example.com## gitlab Ingress TLS configuration## Secrets must be created in the namespace, and is not done for you in this chart##tls:-secretName:gitlab-tlshosts:-gitlab.example.com-registry.example.com

Installing GitLab using the Helm Chart

You may see a temporary error message SchedulerPredicates failed due to PersistentVolumeClaim is not bound while storage provisions. Once the storage provisions, the pods will automatically restart. This may take a couple minutes depending on your cloud provider. If the error persists, please review the prerequisites to ensure you have enough RAM, CPU, and storage.

Add the GitLab Helm repository and initialize Helm:

helm repo add gitlab https://charts.gitlab.io
helm init

Once you have configured GitLab in your values.yml file,
run the following: