gitlab-org--gitlab-foss/doc/install/kubernetes/gitlab_omnibus.md

GitLab-Omnibus Helm Chart

CAUTION: Caution: This chart is deprecated. We recommend using the gitlab chart instead. A comparison of the two charts is available in this video.

For more information on available GitLab Helm Charts, see the charts overview.

• This GitLab-Omnibus chart has been tested on Google Kubernetes Engine and Azure Container Service.
• This work is based partially on: https://github.com/lwolf/kubernetes-gitlab/. GitLab would like to thank Sergey Nuzhdin for his work.

Introduction

This chart provides an easy way to get started with GitLab, provisioning an installation with nearly all functionality enabled. SSL is automatically provisioned via Let's Encrypt.

This Helm chart is suited for small to medium deployments and is deprecated and replaced by the cloud native GitLab chart. Due to the significant architectural changes, migrating will require backing up data out of this instance and importing it into the new deployment.

The deployment includes:

• A GitLab Omnibus Pod, including Mattermost, Container Registry, and Prometheus
• An auto-scaling GitLab Runner using the Kubernetes executor
• Redis
• PostgreSQL
• NGINX Ingress
• Persistent Volume Claims for Data, Registry, Postgres, and Redis

Limitations

High Availability and Geo are not supported.

Requirements

• At least 4 GB of RAM available on your cluster. 41GB of storage and 2 CPU are also required.
• Kubernetes 1.4+ with Beta APIs enabled
• Persistent Volume provisioner support in the underlying infrastructure
• A wildcard DNS entry, which resolves to the external IP address
• The kubectl CLI installed locally and authenticated for the cluster
• The Helm client installed locally on your machine

Networking requirements

This chart configures a GitLab server and Kubernetes cluster which can support dynamic Review Apps, as well as services like the integrated Container Registry and Mattermost.

To support the GitLab services and dynamic environments, a wildcard DNS entry is required which resolves to the load balancer or external IP. Configuration of the DNS entry will depend upon the DNS service being used.

External IP (recommended)

To provision an external IP on GCP and Azure, simply request a new address from the Networking section. Ensure that the region matches the region your container cluster is created in. It is important that the IP is not assigned at this point in time. It will be automatically assigned once the Helm chart is installed, and assigned to the Load Balancer.

Now that an external IP address has been allocated, ensure that the wildcard DNS entry you would like to use resolves to this IP. Please consult the documentation for your DNS service for more information on creating DNS records.

Finally, set the baseIP setting to this IP address when deploying GitLab.

Load Balancer IP

If you do not specify a baseIP, an IP will be assigned to the Load Balancer or Ingress. You can retrieve this IP by running the following command after deploying GitLab:

kubectl get svc -w --namespace nginx-ingress nginx

The IP address will be displayed in the EXTERNAL-IP field, and should be used to configure the Wildcard DNS entry. For more information on creating a wildcard DNS entry, consult the documentation for the DNS server you are using.

For production deployments of GitLab, we strongly recommend using a external IP.

Configuring and Installing GitLab

For most installations, two parameters are required:

• baseDomain: the base domain of the wildcard host entry. For example, mycompany.io if the wild card entry is *.mycompany.io.
• legoEmail: Email address to use when requesting new SSL certificates from Let's Encrypt.

Other common configuration options:

• baseIP: the desired external IP address
• gitlab: Choose the desired edition, either ee or ce. ce is the default.
• gitlabEELicense: For Enterprise Edition, the license can be installed directly via the Chart
• provider: Optimizes the deployment for a cloud provider. The default is gke for Google Kubernetes Engine, with acs also supported for the Azure Container Service.

For additional configuration options, consult the values.yaml.

Choosing a different GitLab release version

The version of GitLab installed is based on the gitlab setting (see section above), and the value of the corresponding helm setting: gitlabCEImage or gitabEEImage.

gitlab: CE
gitlabCEImage: gitlab/gitlab-ce:9.5.2-ce.0
gitlabEEImage: gitlab/gitlab-ee:9.5.2-ee.0

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

Persistent storage

NOTE: Note: If you are using a machine type with support for less than 4 attached disks, like an Azure trial, you should disable dedicated storage for Postgres and Redis.

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, along with whether to provision separate storage for Postgres and Redis.

Basic configuration:

redisImage: redis:3.2.10
redisDedicatedStorage: true
redisStorageSize: 5Gi
postgresImage: postgres:9.6.3
# If you disable postgresDedicatedStorage, you should consider bumping up gitlabRailsStorageSize
postgresDedicatedStorage: true
postgresStorageSize: 30Gi
gitlabRailsStorageSize: 30Gi
gitlabRegistryStorageSize: 30Gi
gitlabConfigStorageSize: 1Gi

Routing and SSL

Ingress routing and SSL are automatically configured within this Chart. An NGINX ingress is provisioned and configured, and will route traffic to any service. SSL certificates are automatically created and configured by kube-lego.

NOTE: Note: Let's Encrypt limits a single TLD to five certificate requests within a single week. This means that common DNS wildcard services like nip.io and xip.io are unlikely to work.

Installing GitLab using the Helm Chart

NOTE: Note: 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 start. This may take a couple minutes depending on your cloud provider. If the error persists, please review the requirements sections to ensure you have enough RAM, CPU, and storage.

Add the GitLab Helm repository and initialize Helm:

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

Once you have reviewed the configuration settings, you can install the chart. We recommending saving your configuration options in a values.yaml file for easier upgrades in the future:

helm install --name gitlab -f values.yaml gitlab/gitlab-omnibus

Or you can pass them on the command line:

helm install --name gitlab --set baseDomain=gitlab.io,baseIP=192.0.2.1,gitlab=ee,gitlabEELicense=$LICENSE,legoEmail=email@gitlab.com gitlab/gitlab-omnibus

Updating GitLab using the Helm Chart

If you are upgrading from a previous version to 0.1.35 or above, you will need to change the access mode values for GitLab's storage. To do this, set the following in values.yaml or on the CLI:

gitlabDataAccessMode=ReadWriteMany
gitlabRegistryAccessMode=ReadWriteMany
gitlabConfigAccessMode=ReadWriteMany

Once your GitLab Chart is installed, configuration changes and chart updates should be done using helm upgrade:

helm upgrade -f values.yaml gitlab gitlab/gitlab-omnibus

Upgrading from CE to EE using the Helm Chart

If you have installed the Community Edition using this chart, upgrading to Enterprise Edition is easy.

If you are using a values.yaml file to specify the configuration options, edit the file and set gitlab=ee. If you would like to run a specific version of GitLab EE, set gitlabEEImage to be the desired GitLab docker image. Then you can use helm upgrade to update your GitLab instance to EE:

helm upgrade -f values.yaml gitlab gitlab/gitlab-omnibus

You can also upgrade and specify these options via the command line:

helm upgrade gitlab --set gitlab=ee,gitlabEEImage=gitlab/gitlab-ee:9.5.5-ee.0 gitlab/gitlab-omnibus

Uninstalling GitLab using the Helm Chart

To uninstall the GitLab Chart, run the following:

helm delete --purge gitlab

Troubleshooting

Storage errors when updating gitlab-omnibus versions prior to 0.1.35

Users upgrading gitlab-omnibus from a version prior to 0.1.35, may see an error like: Error: UPGRADE FAILED: PersistentVolumeClaim "gitlab-gitlab-config-storage" is invalid: spec: Forbidden: field is immutable after creation.

This is due to a change in the access mode for GitLab storage in version 0.1.35. To successfully upgrade, the access mode flags must be set to ReadWriteMany as detailed in the update section.