Deployment Guide
Before running helm install
, you need to make some decisions about how you will run GitLab.
Options can be specified using Helm’s --set option.name=value
command line option.
A complete list of command line options can be found here.
This guide will cover required values and common options.
Selecting configuration options
In each section collect the options that will be combined to use with helm install
.
Secrets
There are some secrets that need to be created (e.g. SSH keys). By default they will be generated automatically, but if you want to specify them, you can follow the secrets guide.
Networking and DNS
By default, the chart relies on Kubernetes Service
objects of type: LoadBalancer
to expose GitLab services using name-based virtual servers configured withIngress
objects. You’ll need to specify a domain which will contain records to resolve
gitlab
, registry
, and minio
(if enabled) to the appropriate IP for your chart.
Include these options in your Helm install command:
--set global.hosts.domain=example.com
Dynamic IPs with external-dns
If you plan to use an automatic DNS registration service like external-dns, you won’t need any additional configuration for GitLab, but you will need to deploy it to your cluster. If external-dns is your choice, the project page has a comprehensive guide for each supported provider.
If you provisioned a GKE cluster using the scripts in this repo, external-dns is already installed in your cluster.
Static IP
If you plan to manually configure your DNS records they should all point to a
static IP. For example if you choose example.com
and you have a static IP
of 10.10.10.10
, then gitlab.example.com
, registry.example.com
and
minio.example.com
(if using MinIO) should all resolve to 10.10.10.10
.
If you are using GKE, there is some documentation here for configuring static IPs and DNS. Consult your Cloud and/or DNS provider’s documentation for more help on this process.
Include these options in your Helm install command:
--set global.hosts.externalIP=10.10.10.10
Persistence
By default the chart will create Volume Claims with the expectation that a dynamic provisioner will create the underlying Persistent Volumes. If you would like to customize the storageClass or manually create and assign volumes, please review the storage documentation.
Important: After initial installation, making changes to your storage settings requires manually editing Kubernetes objects, so it’s best to plan ahead before installing your production instance of GitLab to avoid extra storage migration work.
TLS certificates
You should be running GitLab using https which requires TLS certificates. By default the chart will install and configure cert-manager to obtain free TLS certificates. If you have your own wildcard certificate, you already have cert-manager installed, or you have some other way of obtaining TLS certificates, read about more TLS options here.
For the default configuration, you must specify an email address to register your TLS certificates.
Include these options in your Helm install command:
--set certmanager-issuer.email=me@example.com
PostgreSQL
By default this chart provides an in-cluster PostgreSQL database, for trial purposes only.
NOTE: This configuration is not recommended for use in production.
- A single StatefulSet is provided by bitnami/PostgreSQL by default.
- As of 4.0.0 of these charts, replication is available internally, but not enabled by default. Such functionality has not been load tested by GitLab.
You can read more about setting up your production-ready database in the advanced database docs.
If you have an external PostgreSQL database ready, the chart can be configured to use it as shown below.
Include these options in your Helm install command:
--set postgresql.install=false
--set global.psql.host=production.postgress.hostname.local
--set global.psql.password.secret=kubernetes_secret_name
--set global.psql.password.key=key_that_contains_postgres_password
Redis
All Redis configuration settings have been moved and consolidated on the charts/globals.md page.
NOTE: This configuration is not recommended for use in production.
- A single StatefulSet is provided by bitnami/Redis by default.
- As of 4.0.0 of these charts, replication is available internally, but not enabled by default. Such functionality has not been load tested by GitLab.
You can read more about setting up a production-ready Redis instance in the advanced Redis docs.
MinIO
By default this chart provides an in-cluster MinIO deployment to provide an object storage API.
NOTE: This configuration is not recommended for use in production.
- A singleton, non-resilient Deployment is provided by our MinIO fork.
You can read more about setting up your production-ready object storage in the external object storage
Prometheus
We use the upstream Prometheus chart,
and do not override values from our own defaults.
We do, however, default disable alertmanager
, nodeExporter
, and
pushgateway
.
Refer to the Prometheus chart documentation for the
exhaustive list of configuration options and ensure they are sub-keys to
prometheus
, as we use this as requirement chart.
For instance, the requests for persistent storage can be controlled with:
prometheus:
alertmanager:
enabled: false
persistentVolume:
enabled: false
size: 2Gi
pushgateway:
enabled: false
persistentVolume:
enabled: false
size: 2Gi
server:
persistentVolume:
enabled: true
size: 8Gi
Outgoing email
By default outgoing email is disabled. To enable it, provide details for your SMTP server
using the global.smtp
and global.email
settings. You can find details for these settings in the
command line options.
If your SMTP server requires authentication make sure to read the section on providing
your password in the secrets documentation.
You can disable authentication settings with --set global.smtp.authentication=""
.
If your Kubernetes cluster is on GKE, be aware that SMTP port 25 is blocked.
Incoming email
By default incoming email is disabled. To enable it, provide details of your
IMAP server and access credentials using the global.appConfig.incomingEmail
settings. You can find details for these settings in the command line options.
You will also have to create a Kubernetes secret containing IMAP password as
described in the secrets guide.
To use reply-by-email feature, where users can reply to notification emails to comment on issues and MRs, you need to configure both outgoing email and incoming email settings.
Service desk email
By default service desk email is disabled. To enable it, provide details of your
IMAP server and access credentials using the global.appConfig.serviceDeskEmail
settings. You can find details for these settings in the command line options.
You will also have to create a Kubernetes secret containing IMAP password as
described in the secrets guide.
Deploy the Community Edition
By default, the Helm charts use the Enterprise Edition of GitLab. If desired, you can instead use the Community Edition. Learn more about the difference between the two.
To deploy the Community Edition, include this option in your Helm install command:
--set global.edition=ce
RBAC
This chart defaults to creating and using RBAC. If your cluster does not have RBAC enabled, you will need to disable these settings:
--set certmanager.rbac.create=false
--set nginx-ingress.rbac.createRole=false
--set prometheus.rbac.create=false
--set gitlab-runner.rbac.create=false
CPU and RAM Resource Requirements
The resource requests, and number of replicas for the GitLab components (not PostgreSQL, Redis, or MinIO) in this Chart are set by default to be adequate for a small production deployment. This is intended to fit in a cluster with at least 8vCPU and 30gb of RAM. If you are trying to deploy a non-production instance, you can reduce the defaults in order to fit into a smaller cluster.
The minimal GKE example values file provides an example of tuning the resources to fit within a 3vCPU 12gb cluster.
The minimal Minikube example values file provides an example of tuning the resources to fit within a 2vCPU, 4gb Minikube instance.
Deploy using Helm
Once you have all of your configuration options collected, we can get any dependencies and
run Helm. In this example, we’ve named our Helm release gitlab
.
helm repo add gitlab https://charts.gitlab.io/
helm repo update
helm upgrade --install gitlab gitlab/gitlab \
--timeout 600s \
--set global.hosts.domain=example.com \
--set global.hosts.externalIP=10.10.10.10 \
--set certmanager-issuer.email=me@example.com
helm install
is used there is a slight difference in the way
that Helm v2 and Helm v3 operate. When using Helm v2 if a release name
was not specified with the --name
option it would randomly generate the
release name. Helm v3 requires that the release name be specified as a
positional argument on the command line unless the --generate-name
option is used.120s
= 2m
and 210s
= 3m30s
). The
--timeout
option is handled as the number of seconds without the
unit specification.--timeout
option is deceptive in that there are
multiple components that are deployed during an Helm install or upgrade
in which the --timeout
is applied. The --timeout
value is applied to
the installation of each component individually and not applied for the
installation of all the components. So intending to abort the Helm install
after 3 minutes by using --timeout=3m
may result in the install completing
after 5 minutes because none of the installed components took longer than
3 minutes to install.You can also use --version <installation version>
option if you would like to install a specific version of GitLab.
Mappings between chart versions and GitLab versions can be found here.
Instructions for installing a development branch rather than a tagged release can be found in the developer deploy documentation.
GitLab Operator (experimental)
If you would like to use GitLab Operator to achieve zero downtime upgrades, please follow the documentation for using the operator.
Monitoring the Deployment
This will output the list of resources installed once the deployment finishes which may take 5-10 minutes.
The status of the deployment can be checked by running helm status gitlab
which can also be done while
the deployment is taking place if you run the command in another terminal.
Initial login
You can access the GitLab instance by visiting the domain specified during
installation. If you manually created the secret for initial root password, you
can use that to sign in as root
user. If not, GitLab would’ve automatically
created a random password for root
user. This can be extracted by the
following command (replace <name>
by name of the release - which is gitlab
if you used the command above).
kubectl get secret <name>-gitlab-initial-root-password -ojsonpath='{.data.password}' | base64 --decode ; echo