GitLab Runner Helm Chart

noteThis chart has been tested on Google Kubernetes Engine and Azure Container Service. Other Kubernetes installations may work as well, if not please open an issue.

The official way of deploying a GitLab Runner instance into your Kubernetes cluster is by using the gitlab-runner Helm chart.

This chart configures GitLab Runner to:

  • Run using the GitLab Runner Kubernetes executor.
  • For each new job it receives from GitLab CI/CD, it will provision a new pod within the specified namespace to run it.

Prerequisites

  • Your GitLab server’s API is reachable from the cluster.
  • Kubernetes 1.4+ with Beta APIs enabled.
  • The kubectl CLI installed locally and authenticated for the cluster.
  • The Helm client installed locally on your machine.

Installing GitLab Runner using the Helm Chart

Add the GitLab Helm repository:

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

If using Helm 2, you must also initialize Helm:

helm init

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

# For Helm 2
helm install --namespace <NAMESPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

# For Helm 3
helm install --namespace <NAMESPACE> gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

Where:

  • <NAMESPACE> is the Kubernetes namespace where you want to install the GitLab Runner.
  • <CONFIG_VALUES_FILE> is the path to values file containing your custom configuration. See the Configuring GitLab Runner using the Helm Chart section to create it.

If you want to install a specific version of GitLab Runner Helm Chart, add --version <RUNNER_HELM_CHART_VERSION> to your helm install command.

Upgrading GitLab Runner using the Helm Chart

Before upgrading GitLab Runner, pause the runner in GitLab and ensure any jobs have completed. Pausing the runner prevents problems arising with the jobs, such as authorization errors when they complete.

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

helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner

Where:

If you want to update to a specific version of GitLab Runner Helm Chart instead of the latest one, add --version <RUNNER_HELM_CHART_VERSION> to your helm upgrade command.

Check available GitLab Runner Helm Chart versions

Versions of Helm Chart and GitLab Runner do not follow the same versioning. Use the command below to get version mappings between Helm Chart and GitLab Runner:

# For Helm 2
helm search -l gitlab/gitlab-runner

# For Helm 3
helm search repo -l gitlab/gitlab-runner

Example of the output is shown below:

NAME                    CHART VERSION   APP VERSION DESCRIPTION
...
gitlab/gitlab-runner    0.14.0          12.8.0      GitLab Runner
gitlab/gitlab-runner    0.13.1          12.7.1      GitLab Runner
gitlab/gitlab-runner    0.13.0          12.7.0      GitLab Runner
gitlab/gitlab-runner    0.12.0          12.6.0      GitLab Runner
gitlab/gitlab-runner    0.11.0          12.5.0      GitLab Runner
gitlab/gitlab-runner    0.10.1          12.4.1      GitLab Runner
gitlab/gitlab-runner    0.10.0          12.4.0      GitLab Runner
...

Configuring GitLab Runner using the Helm Chart

Create a values.yaml file for your GitLab Runner configuration. See Helm docs for information on how your values file will override the defaults.

The default configuration can always be found in the values.yaml in the chart repository.

Required configuration

For GitLab Runner to function, your configuration file must specify the following:

  • gitlabUrl - the GitLab server full URL (e.g., https://gitlab.example.com) to register the runner against.
  • runnerRegistrationToken - The registration token for adding new runners to GitLab. This must be retrieved from your GitLab instance.

Unless you need to specify any additional configuration, you are ready to install GitLab Runner.

Additional configuration

Introduced configuration template in Helm Chart 0.23.0. See deprecation issue.

You can use a configuration template file to configure the runner. You can use the configuration template to configure any field on the runner, without having the Helm chart be aware of specific runner configuration options.

Here’s a snippet of the default settings found in the values.yaml file in the chart repository. It is important to note that, for the config: section, the format should be toml (<parameter> = <value> instead of <parameter>: <value>), as we are embedding config.toml in values.yaml.

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"

The rest of the configuration is documented in the values.yaml.

Migrating to the new configuration template

Introduced configuration template in Helm Chart 0.23.0. See deprecation issue.

Many of the fields accepted by the values.yaml file will be removed with the introduction of Helm Chart version 1.0. We recommend migrating away from them as soon as possible. These fields are marked with a DEPRECATED: comment above them.

All the configuration options supported by the Kubernetes executor are listed in the Kubernetes executor docs. For many of the fields, the old name in values.yaml is the same as the keyword. For some, you must rename them. For example, if you are using helpers to set CPU limits:

helpers:
    cpuLimit: 200m

Now you can set them as helper_cpu_limit. Ensure you are using toml formatting (= rather than :) in the config: section:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"
        helper_cpu_limit = "200m"

## helpers:
##    cpuLimit: 200m
noteMake sure to comment or remove the old configuration values from your values.yaml file to avoid conflicts.

Using cache with configuration template

To use the cache with your configuration template, set the following variables in values.yaml:

  • runners.cache.secretName with the secret name for your object storage provider (s3access, gcsaccess, google-application-credentials, or azureaccess).
  • runners.config with the other settings for the cache. Use toml formatting.

S3

For example, here is an example that configures S3 with static credentials:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"
        [runners.cache]
          Type = "s3"
          Path = "runner"
          Shared = true
          [runners.cache.s3]
            ServerAddress = "s3.amazonaws.com"
            BucketName = "my_bucket_name"
            BucketLocation = "eu-west-1"
            Insecure = false

  cache:
      secretName: s3access

Next, create an s3access Kubernetes secret that contains accesskey and secretkey:

kubectl create secret generic s3access \
    --from-literal=accesskey="YourAccessKey" \
    --from-literal=secretkey="YourSecretKey"

Google Cloud Storage (GCS)

Static credentials directly configured

The following example shows how to configure GCS with credentials with an access ID and a private key:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"
        [runners.cache]
          Type = "gcs"
          Path = "runner"
          Shared = true
          [runners.cache.gcs]
            BucketName = "runners-cache"

  cache:
      secretName: gcsaccess

Next, create a gcsaccess Kubernetes secret that contains gcs-access-id and gcs-private-key:

kubectl create secret generic gcsaccess \
    --from-literal=gcs-access-id="YourAccessID" \
    --from-literal=gcs-private-key="YourPrivateKey"

Static credentials in a JSON file downloaded from GCP

The following example shows how to configure GCS with credentials in a JSON file downloaded from Google Cloud Platform:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"
        [runners.cache]
          Type = "gcs"
          Path = "runner"
          Shared = true
          [runners.cache.gcs]
            BucketName = "runners-cache"

  cache:
      secretName: google-application-credentials

Next, create a Kubernetes secret google-application-credentials and load the JSON file with it:

kubectl create secret generic google-application-credentials \
    --from-file=gcs-application-credentials-file=./path-to-your-google-application-credentials-file.json

Azure

The following example shows how to configure Azure Blob Storage:

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "ubuntu:16.04"
        [runners.cache]
          Type = "s3"
          Path = "runner"
          Shared = true
          [runners.cache.azure]
            ContainerName = "my_container_name"
            StorageDomain = "blob.core.windows.net"

  cache:
      secretName: azureaccess

Next, create an azureaccess Kubernetes secret that contains azure-account-name and azure-account-key:

kubectl create secret generic azureaccess \
    --from-literal=azure-account-name="YourAccountName" \
    --from-literal=azure-account-key="YourAccountKey"

Read more about the caching in Helm Chart in values.yaml.

Enabling RBAC support

If your cluster has RBAC enabled, you can choose to either have the chart create its own service account or provide one on your own.

To have the chart create the service account for you, set rbac.create to true:

rbac:
  create: true

To use an already existing service account, use:

rbac:
  create: false
  serviceAccountName: your-service-account

Controlling maximum Runner concurrency

A single GitLab Runner deployed on Kubernetes is able to execute multiple jobs in parallel by automatically starting additional Runner pods. The concurrent setting controls the maximum number of pods allowed at a single time, and defaults to 10:

## Configure the maximum number of concurrent jobs
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
concurrent: 10

Running Docker-in-Docker containers with GitLab Runner

See running privileged containers for the runners for how to enable it, and the GitLab Runner documentation on running dind.

Running privileged containers for the runners

You can tell the GitLab Runner to run using privileged containers. You may need this enabled if you need to use the Docker executable within your GitLab CI/CD jobs.

This comes with several risks that you can read about in the GitLab CI/CD Runner documentation.

If you are okay with the risks, and your GitLab Runner instance is registered against a specific project in GitLab that you trust the CI jobs of, you can enable privileged mode in values.yaml:

runners:
  ## Run all containers with the privileged flag enabled
  ## This will allow the docker:stable-dind image to run if you need to run Docker
  ## commands. Please read the docs before turning this on:
  ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind
  ##
  privileged: true

Best practices for building containers without privileged mode

Building containers within containers with Docker-in-Docker requires Docker privileged mode. Google’s Kaniko is an alternative that works without privileged mode, and it has been tested on the Kubernetes GitLab Runner.

The Least Privilege Container Builds with Kaniko on GitLab video is a walkthrough of the Kaniko Docker Build working example project. It makes use of the documentation for Building images with Kaniko and GitLab CI/CD.

The working example project can be copied to your own group or instance for testing. More details on what other GitLab CI patterns are demonstrated are available at the project page Kaniko Docker Build.

Using an image from a private registry

Using an image from a private registry requires the configuration of imagePullSecrets. For more details on how to create imagePullSecrets see the documentation.

runners:
  ## Specify one or more imagePullSecrets
  ##
  ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
  ##
  imagePullSecrets:
  - [your-image-pull-secret]

Take note of the format. The value is not prefixed by a ‘name’ tag as is the convention in Kubernetes resources.

Providing a custom certificate for accessing GitLab

You can provide a Kubernetes Secret to the GitLab Runner Helm Chart, which will be used to populate the container’s /home/gitlab-runner/.gitlab-runner/certs directory.

Each key name in the Secret will be used as a filename in the directory, with the file content being the value associated with the key:

  • The key/file name used should be in the format <gitlab-hostname>.crt, for example gitlab.your-domain.com.crt.
  • Any intermediate certificates need to be concatenated to your server certificate in the same file.
  • The hostname used should be the one the certificate is registered for.

The GitLab Runner Helm Chart does not create a secret for you. In order to create the secret, you tell Kubernetes to store the certificate as a secret and present it to the GitLab Runner containers as a file. To do this, run the following command:

kubectl
  --namespace <NAMESPACE>
  create secret generic <SECRET_NAME>
  --from-file=<CERTIFICATE_FILENAME>

Where:

  • <NAMESPACE> is the Kubernetes namespace where you want to install the GitLab Runner.
  • <SECRET_NAME> is the Kubernetes Secret resource name. (For example: gitlab-domain-cert.)
  • <CERTIFICATE_FILENAME> is the filename for the certificate in your current directory that will be imported into the secret.

If the source file <CERTIFICATE_FILENAME> is not in the current directory or does not follow the format <gitlab-hostname.crt> then it will be necessary to specify the filename to use on the target:

kubectl
  --namespace <NAMESPACE>
  create secret generic <SECRET_NAME>
  --from-file=<TARGET_FILENAME>=<CERTIFICATE_FILENAME>

Where:

  • <TARGET_FILENAME> is the name of the certificate file as presented to the Runner containers. (For example: gitlab-hostname.crt.)
  • <CERTIFICATE_FILENAME> is the filename for the certificate relative to your current directory that will be imported into the secret. (For example: cert-directory/my-gitlab-certificate.crt)

You then need to provide the secret’s name to the GitLab Runner chart. Add the following to your values.yaml:

## Set the certsSecretName in order to pass custom certificates for GitLab Runner to use
## Provide resource name for a Kubernetes Secret Object in the same namespace,
## this is used to populate the /home/gitlab-runner/.gitlab-runner/certs/ directory
## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates
##
certsSecretName: <SECRET NAME>

Where:

  • <SECRET_NAME> is the Kubernetes Secret resource name, as in the above example, gitlab-domain-cert.

More information on how GitLab Runner uses these certificates can be found in the Runner Documentation.

Set pod labels to CI environment variables keys

At the moment it is not possible to use environment variables as pod labels within the values.yaml file. We are working on it in this issue: Can’t set environment variable key as pod label. Use the workaround described in the issue as a temporary solution.

Store registration tokens or runner tokens in secrets

To register a new runner, you can specify runnerRegistrationToken in values.yml. To register an existing runner, you can use runnerToken. It can be a security risk to store tokens in values.yml, especially if you commit these to git.

Instead, you can store the values of these tokens inside of a Kubernetes secret, and then update the runners.secret value in values.yml with the name of the secret.

If you have an existing registered runner and want to use that, set the runner-token with the token used to identify that runner. If you want to have a new runner registered you can set the runner-registration-token with the registration token that you would like.

For example:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "NlZrN1pzb3NxUXlmcmVBeFhUWnIK" #base64 encoded registration token
  runner-token: ""
runners:
  secret: gitlab-runner-secret

This example uses the secret gitlab-runner-secret and takes the value of runner-registration-token to register the new runner.

Switching to the Ubuntu-based gitlab-runner Docker image

By default the GitLab Runner Helm Chart uses the Alpine version of the gitlab/gitlab-runner image, which uses musl libc. In some cases, you may want to switch to the Ubuntu-based image, which uses glibc.

To do so, update your values.yaml file with the following values:

# Specify the Ubuntu image. Remember to set the version. You can also use the `ubuntu` or `latest` tags.
image: gitlab/gitlab-runner:v13.0.0

# Update the security context values to the user ID in the ubuntu image
securityContext:
  fsGroup: 999
  runAsUser: 999

Uninstalling GitLab Runner using the Helm Chart

Before uninstalling GitLab Runner, pause the runner in GitLab and ensure any jobs have completed. Pausing the runner prevents problems arising with the jobs, such as authorization errors when they complete.

To uninstall the GitLab Runner Chart, run the following:

helm delete --namespace <NAMESPACE> <RELEASE-NAME>

Where:

  • <NAMESPACE> is the Kubernetes namespace where GitLab Runner is installed.
  • <RELEASE-NAME> is the name you gave the chart when installing it. In the Installing GitLab Runner using the Helm Chart section, we called it gitlab-runner.

Troubleshooting a Kubernetes installation

ERROR: Job failed (system failure): secrets is forbidden

If you see the following error:

Using Kubernetes executor with image alpine ...
ERROR: Job failed (system failure): secrets is forbidden: User "system:serviceaccount:gitlab:default" cannot create resource "secrets" in API group "" in the namespace "gitlab"

Enable RBAC support to correct the error.