Required tools
Before deploying GitLab to your Kubernetes cluster, there are some tools you must have installed locally.
kubectl
kubectl is the tool that talks to the Kubernetes API. kubectl 1.12 or higher is required and it needs to be compatible with your cluster (+/- 1 minor release from your cluster).
> Install kubectl locally by following the Kubernetes documentation.
The server version of kubectl cannot be obtained until we connect to a cluster. Proceed with setting up Helm.
Helm
Helm is the package manager for Kubernetes. The gitlab
chart is tested and
supported with Helm v2 (2.12 or higher required, excluding 2.15).
Starting with version v3.0.0
of the chart, Helm v3 (3.0.2 or higher required)
is also fully supported.
[Helm3]
.helm
(client) installed locally, and tiller
(server) installed inside Kubernetes.Getting Helm
You can get Helm from the project’s releases page, or follow other options under the official documentation of installing Helm.
Tiller is deployed into the cluster and interacts with the Kubernetes API to deploy your applications. If role based access control (RBAC) is enabled, Tiller will need to be granted permissions to allow it to talk to the Kubernetes API.
If RBAC is not enabled, skip to initializing Helm.
If you are not sure whether RBAC is enabled in your cluster, or to learn more, read through our RBAC documentation.
Preparing for Helm with RBAC
kubectl
installed and it’s up to date. Older versions do not
have support for RBAC and will generate errors.Helm v3.0 does not install Tiller in the cluster and as such uses the user’s RBAC permissions to peform the deployment of the chart.
Prior versions of Helm do install Tiller on the cluster and will need to be granted permissions to perform operations. These instructions grant cluster wide permissions, however for more advanced deployments permissions can be restricted to a single namespace.
To grant access to the cluster, we will create a new tiller
service account
and bind it to the cluster-admin
role:
apiVersion: v1
kind: ServiceAccount
metadata:
name: tiller
namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
name: tiller
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: tiller
namespace: kube-system
For ease of use, these instructions will utilize the sample YAML file in this repository. To apply the configuration, we first need to connect to the cluster.
Connecting to the GKE cluster
The command to connect to the cluster can be obtained from the Google Cloud Platform Console by the individual cluster, by looking for the Connect button in the clusters list page.
Alternatively, use the command below, filling in your cluster’s information:
gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-id>
Connecting to an EKS cluster
For the most up to date instructions, follow the Amazon EKS documentation on connecting to a cluster.
Connect to a local Minikube cluster
If you are doing local development, you can use minikube
as your
local cluster. If kubectl cluster-info
is not showing minikube
as the current
cluster, use kubectl config set-cluster minikube
to set the active cluster.
Upload the RBAC config
Upload the RBAC config in GKE
For GKE, you need to grab the admin credentials:
gcloud container clusters describe <cluster-name> --zone <zone> --project <project-id> --format='value(masterAuth.password)'
This command will output the admin password. We need the password to authenticate
with kubectl
and create the role.
We will also create an admin user for this cluster. Use a name you prefer but for this example we will include the cluster’s name in it:
CLUSTER_NAME=name-of-cluster
kubectl config set-credentials $CLUSTER_NAME-admin-user --username=admin --password=xxxxxxxxxxxxxx
kubectl --user=$CLUSTER_NAME-admin-user create -f https://gitlab.com/gitlab-org/charts/gitlab/raw/master/doc/installation/examples/rbac-config.yaml
Upload the RBAC config in non-GKE clusters
For other clusters like Amazon EKS, you can directly upload the RBAC configuration:
kubectl create -f https://gitlab.com/gitlab-org/charts/gitlab/raw/master/doc/installation/examples/rbac-config.yaml
Initializing Helm
If Helm v3 is being used, there no longer is an init
sub command and the
command is ready to be used once it is installed. Otherwise if Helm v2 is
being used, then Helm needs to deploy Tiller with a service account:
helm init --service-account tiller
If your cluster previously had Helm/Tiller installed, run the following command to ensure that the deployed version of Tiller matches the local Helm version:
helm init --upgrade --service-account tiller
Next steps
Once kubectl and Helm are configured, you can continue to configuring your Kubernetes cluster.
Additional information
The Distribution Team has a training presentation for Helm Charts.
Templates
Templating in Helm is done via golang’s text/template and sprig.
Some information on how all the inner workings behave:
Tips and tricks
Helm repository has some additional information on developing with Helm in it’s tips and tricks section.
Local Tiller
If you are using Helm v2 and not able to run Tiller in your cluster, a script is included that should allow you to use Helm with running Tiller in your cluster. The script uses your personal Kubernetes credentials and configuration to apply the chart.
To use the script, skip this entire section about initializing Helm. Instead, make sure you have Docker installed locally and run:
bin/localtiller-helm --client-only
After that, you can substitute bin/localtiller-helm
anywhere these
instructions direct you to run helm
.
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc