- Introduction
- Limitations
- GitLab Helm chart quick start guide
- Troubleshooting
- Installation
- Upgrading
- Uninstall
- Advanced
- Architecture
- Development
GitLab cloud native Helm Chart
This is the official, recommended, and supported method to install GitLab on a cloud native environment.
Introduction
The gitlab/gitlab
chart is the best way to operate GitLab on Kubernetes. This chart
contains all the required components to get started, and can scale to large deployments.
This chart includes all the components for a complete experience, but each part can be installed separately.
- Core GitLab components:
- NGINX Ingress
- Registry
- GitLab/Gitaly
- GitLab/GitLab Exporter
- GitLab/GitLab Grafana
- GitLab/GitLab Shell
- GitLab/Migrations
- GitLab/Sidekiq
- GitLab/Webservice
- Optional dependencies:
- Optional additions:
- Prometheus
- Grafana
- Unprivileged GitLab Runner using the Kubernetes executor
- Automatically provisioned SSL via Let’s Encrypt, using Jetstack’s cert-manager
Limitations
Some features of GitLab are not currently available using the Helm chart:
Database limitations:
- GitLab Geo functionality requires the use of external database service(s).
GitLab Helm chart quick start guide
For those looking to get up and running with these charts as fast as possible, in a non-production use case, we provide a Quick Start Guide for Proof of Concept (PoC) deployments.
This guide walks the user through deploying these charts with default values & features, but does not meet production ready requirements. If you wish to deploy these charts into production under sustained load, you should follow the complete Installation guide below.
Troubleshooting
We’ve done our best to make these charts as seamless as possible, but occasionally troubles do surface outside of our control. We’ve collected tips and tricks for troubleshooting common issues. Please examine these first before raising an Issue, and feel free to add to them by raising a Merge Request!
See Troubleshooting.
Installation
The gitlab/gitlab
chart contains all required dependencies. In production, you
may want to enable optional features or advanced configuration.
This guide walks all of the options and features of these charts in great depth.
If you are just looking to deploy a Proof of Concept for testing, we strongly suggest you follow our Quick Start for your first iteration.
Global settings
The complexity of these charts lends themselves to the use of global properties. There are many common global settings that apply to multiple charts. See the Globals documentation for details on the different global configuration values and their application.
Complete properties list
We’re often asked to put a table of all possible properties directly into this index. These charts are massive in scale, and as such the number of properties exceeds the amount of context we’re comfortable placing here. Please see our (nearly) comprehensive list of properties and defaults.
Upgrading
Once your GitLab Chart is installed, configuration changes and chart updates
should be done using helm upgrade
:
helm repo add gitlab https://charts.gitlab.io/
helm repo update
helm get values gitlab > gitlab.yaml
helm upgrade gitlab gitlab/gitlab -f gitlab.yaml
For more detailed information see Upgrading.
Uninstall
To uninstall the GitLab Chart, run the following:
helm uninstall gitlab
helm delete --purge gitlab
.For the purposes of continuity, these charts have some Kubernetes objects that
are not removed when performing helm uninstall
. These are items we require you to
consciously remove them, as they affect re-deployment should you choose to.
- PVCs for stateful data, which you must consciously remove
- Gitaly: This is your repository data.
- PostgreSQL (if internal): This is your metadata.
- Redis (if internal): This is cache & job queues, which can be safely removed.
- Secrets, if generated by our shared-secrets Job. These charts are designed to never generate Kubernetes Secrets via Helm directly. As such, Helm can’t remove them. They contain passwords, encryption secrets, etc. They should not be callously destroyed.
- ConfigMaps
-
ingress-controller-leader-RELEASE-nginx
: This is generated by the NGINX Ingress controller itself, and is outside the control of our chart. It can be safely removed.
-
The PVCs and Secrets will have the release
label set, so you can find these with:
kubectl get pvc,secret -lrelease=gitlab
Advanced
Beyond the basic deployments of GitLab in cloud native environments, more complex configuration is possible. This section serves a guide point for those tasks which require further planning, such as large scale deployments or migrating from the Omnibus GitLab.
Advanced Configuration
Advanced and large scale deployments have the ability to make use of external services, extended functionality, and alternate providers.
Examples of advanced configurations:
- GitLab Geo
- External object storage providers
- External PostgreSQL, Redis, Gitaly
- External Ingress providers
Migrate from Omnibus GitLab to Kubernetes
It is possible to migrate from Omnibus GitLab to these charts. Doing so generally requires migrating existing data to object storage, and thus is an Advanced Configuration.
To migrate your existing Omnibus GitLab instance to these charts, follow the migration documentation.
Architecture
These charts are complex, as they coordinate the deployment of a complete application suite. We provide documentation of the goals, structure, design decisions, and resource consumption.
Development
For those interested in contributing to these charts, we provide development guidelines covering the gamut of working with this project. They can be found under development.
GitLab version mappings
The GitLab chart doesn’t have the same version number as GitLab itself. Breaking changes are anticipated that may need to be introduced to the chart that would warrant a major version bump, and the requirement for these changes could completely block other development on these charts until completed.
To quickly see the full list of the gitlab
chart versions and the GitLab version
they map to, issue the following command with Helm:
helm repo add gitlab https://charts.gitlab.io/
helm search repo -l gitlab/gitlab
helm search -l gitlab/gitlab
For more information, visit the version mappings docs.
Contributing
See the developer documentation to learn how to contribute to the GitLab charts, in addition to our Contributing Guidelines.