- Use the cache with a configuration template
- Enable RBAC support
- Control maximum runner concurrency
- Run Docker-in-Docker containers with GitLab Runner
- Use privileged containers for the runners
- Use an image from a private registry
- Access GitLab with a custom certificate
- Set pod labels to CI environment variable keys
- Switch to the Ubuntu-based
gitlab-runner
Docker image - Run with non-root user
- Use a FIPS-compliant GitLab Runner
- Use a configuration template
Configure the GitLab Runner Helm chart
This page describes optional configuration you can add to your GitLab Runner Helm chart.
Use the cache with a configuration template
To use the cache with your configuration template, set these variables in values.yaml
:
-
runners.cache.secretName
: The secret name for your object storage provider. Options:s3access
,gcsaccess
,google-application-credentials
, orazureaccess
. -
runners.config
: Other settings for the cache, in TOML format.
Amazon S3
To configure Amazon S3 with static credentials:
-
Add this example to your
values.yaml
, changing values where needed:runners: config: | [[runners]] [runners.kubernetes] image = "ubuntu:22.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 AuthenticationType = "access-key" cache: secretName: s3access
-
Create an
s3access
Kubernetes secret that containsaccesskey
andsecretkey
:kubectl create secret generic s3access \ --from-literal=accesskey="YourAccessKey" \ --from-literal=secretkey="YourSecretKey"
Google Cloud Storage (GCS)
Google Cloud Storage can be configured with static credentials in multiple ways.
Static credentials directly configured
To configure GCS with credentials with an access ID and a private key:
-
Add this example to your
values.yaml
, changing values where needed:runners: config: | [[runners]] [runners.kubernetes] image = "ubuntu:22.04" [runners.cache] Type = "gcs" Path = "runner" Shared = true [runners.cache.gcs] BucketName = "runners-cache" cache: secretName: gcsaccess
-
Create a
gcsaccess
Kubernetes secret that containsgcs-access-id
andgcs-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
To configure GCS with credentials in a JSON file downloaded from Google Cloud Platform:
-
Add this example to your
values.yaml
, changing values where needed:runners: config: | [[runners]] [runners.kubernetes] image = "ubuntu:22.04" [runners.cache] Type = "gcs" Path = "runner" Shared = true [runners.cache.gcs] BucketName = "runners-cache" cache: secretName: google-application-credentials secrets: - name: google-application-credentials
-
Create a Kubernetes secret called
google-application-credentials
and load the JSON file with it. Change the path as needed:kubectl create secret generic google-application-credentials \ --from-file=gcs-application-credentials-file=./PATH-TO-CREDENTIALS-FILE.json
Azure
To configure Azure Blob Storage:
-
Add this example to your
values.yaml
, changing values where needed:runners: config: | [[runners]] [runners.kubernetes] image = "ubuntu:22.04" [runners.cache] Type = "azure" Path = "runner" Shared = true [runners.cache.azure] ContainerName = "CONTAINER_NAME" StorageDomain = "blob.core.windows.net" cache: secretName: azureaccess
-
Create an
azureaccess
Kubernetes secret that containsazure-account-name
andazure-account-key
:kubectl create secret generic azureaccess \ --from-literal=azure-account-name="YourAccountName" \ --from-literal=azure-account-key="YourAccountKey"
To learn more about Helm chart caching, see values.yaml
.
Enable RBAC support
If your cluster has RBAC (role-based access controls) enabled, the chart can create its own service account, or you can provide one.
-
To have the chart create the service account for you, set
rbac.create
to true:rbac: create: true
-
To use an existing service account, set a
serviceAccountName
:rbac: create: false serviceAccountName: your-service-account
Control maximum runner concurrency
A single runner deployed on Kubernetes can run multiple jobs in parallel by starting additional Runner pods.
To change the maximum number of pods allowed at one time, edit the
concurrent
setting. It 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
For more information about this setting, see the global section in the advanced configuration documentation for GitLab Runner.
Run Docker-in-Docker containers with GitLab Runner
To use Docker-in-Docker containers with GitLab Runner:
- To enable it, see Use privileged containers for the runners.
- For instructions on running Docker-in-Docker, see the GitLab Runner documentation.
Use privileged containers for the runners
To use the Docker executable in your GitLab CI/CD jobs, configure the runner to use privileged containers.
Prerequisites:
- You understand the risks, which are described in the GitLab CI/CD Runner documentation.
- Your GitLab Runner instance is registered against a specific project in GitLab, and you trust its CI/CD jobs.
To enable privileged mode in values.yaml
, add these lines:
runners:
config: |
[[runners]]
[runners.kubernetes]
# Run all containers with the privileged flag enabled.
privileged = true
...
For more information, see the advanced configuration information about the
[runners.kubernetes]
section.
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 uses the documentation for Building images with Kaniko and GitLab CI/CD.
For testing, copy the working example project to your own group or instance. For more details about the other GitLab CI/CD patterns available, see Kaniko Docker Build.
Use an image from a private registry
To use an image from a private registry, configure imagePullSecrets
.
-
Create one or more secrets in the Kubernetes namespace used for the CI/CD job. This command creates a secret that works with
image_pull_secrets
:kubectl create secret docker-registry <SECRET_NAME> \ --namespace <NAMESPACE> \ --docker-server="https://<REGISTRY_SERVER>" \ --docker-username="<REGISTRY_USERNAME>" \ --docker-password="<REGISTRY_PASSWORD>"
-
For GitLab Runner Helm chart version 0.53.x and later, in
config.toml
, setimage_pull_secret
from the template provided inrunners.config
:runners: config: | [[runners]] [runners.kubernetes] ## Specify one or more imagePullSecrets ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ ## image_pull_secrets = [your-image-pull-secret]
For more information, see Pull an image from a private registry in the Kubernetes documentation.
-
For GitLab Runner Helm chart version 0.52 and earlier, in
values.yaml
, set a value forrunners.imagePullSecrets
. When you set this value, the container adds--kubernetes-image-pull-secrets "<SECRET_NAME>"
to the image entrypoint script. This eliminates the need to configure theimage_pull_secrets
parameter in the Kubernetes executorconfig.toml
settings.runners: imagePullSecrets: [your-image-pull-secret]
imagePullSecrets
is not prefixed by a name
tag, as is the convention in Kubernetes resources. This value requires
an array of one or more secret names, even if you use only one registry credential.For more details on how to create imagePullSecrets
, see
Pull an Image from a Private Registry
in the Kubernetes documentation.
Access GitLab with a custom certificate
To use a custom certificate, provide a Kubernetes secret
to the GitLab Runner Helm chart. This secret is added to the container’s
/home/gitlab-runner/.gitlab-runner/certs
directory:
Prepare your certificate
Each key name in the Kubernetes secret is used as a filename in the directory, with the file content being the value associated with the key:
- The filename used should be in the format
<gitlab.hostname>.crt
, for examplegitlab.your-domain.com.crt
. - Concatenate any intermediate certificates together with your server certificate in the same file.
- The hostname used should be the one the certificate is registered for.
Create a Kubernetes secret
If you installed GitLab Helm chart using the auto-generated self-signed wildcard certificate method, a secret was created for you.
If you did not install GitLab Helm chart with the auto-generated self-signed wildcard certificate, create a secret. These commands store your certificate as a secret in Kubernetes, and present it to the GitLab Runner containers as a file.
-
If your certificate is in the current directory, and follows the format
<gitlab.hostname.crt>
, modify this command as needed:kubectl create secret generic <SECRET_NAME> \ --namespace <NAMESPACE> \ --from-file=<CERTIFICATE_FILENAME>
-
<NAMESPACE>
: The Kubernetes namespace where you want to install the GitLab Runner. -
<SECRET_NAME>
: The Kubernetes Secret resource name, likegitlab-domain-cert
. -
<CERTIFICATE_FILENAME>
: The filename for the certificate in your current directory to import into the secret.
-
-
If your certificate is in another directory, or doesn’t follow the format
<gitlab.hostname.crt>
, you must specify the filename to use as the target:kubectl create secret generic <SECRET_NAME> \ --namespace <NAMESPACE> \ --from-file=<TARGET_FILENAME>=<CERTIFICATE_FILENAME>
-
<TARGET_FILENAME>
is the name of the certificate file as presented to the Runner containers, likegitlab.hostname.crt
. -
<CERTIFICATE_FILENAME>
is the filename for the certificate, relative to your current directory, to import into the secret. For example:cert-directory/my-gitlab-certificate.crt
.
-
Provide the secret to the chart
In values.yaml
, set certsSecretName
to the resource name of a Kubernetes secret object in the same namespace.
This enables you to pass your custom certificate for GitLab Runner to use. In the previous example, the resource
name was gitlab-domain-cert
:
certsSecretName: <SECRET NAME>
For more information, see the supported options for self-signed certificates targeting the GitLab server.
Set pod labels to CI environment variable keys
You can’t use environment variables as pod labels in the values.yaml
file.
For more information, see Can’t set environment variable key as pod label.
Use the workaround described in the issue as a temporary solution.
Switch 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
. You might need to switch to the Ubuntu-based image, which uses glibc
.
To do this, specify the image your values.yaml
file with the following values:
# Specify the Ubuntu image, and set the version. You can also use the `ubuntu` or `latest` tags.
image: gitlab/gitlab-runner:v17.3.0
# Update the security context values to the user ID in the Ubuntu image
securityContext:
fsGroup: 999
runAsUser: 999
Run with non-root user
By default, the GitLab Runner images don’t work with non-root users. The GitLab Runner UBI and GitLab Runner Helper UBI images are designed for that scenario.
To use them, change the GitLab Runner and GitLab Runner Helper images in values.yaml
:
image:
registry: registry.gitlab.com
image: gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-ocp
tag: v16.11.0
securityContext:
runAsNonRoot: true
runAsUser: 999
runners:
config: |
[[runners]]
[runners.kubernetes]
helper_image = "registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocp:x86_64-v16.11.0"
[runners.kubernetes.pod_security_context]
run_as_non_root = true
run_as_user = 59417
Although run_as_user
points to the user ID of nonroot
user (59417), the images work with any user ID.
It’s important that this user ID is part of the root group. Being part of the root group doesn’t give it any specific privileges.
Use a FIPS-compliant GitLab Runner
To use a FIPS-compliant GitLab Runner, change the GitLab Runner image
and the Helper image in values.yaml
:
image:
registry: docker.io
image: gitlab/gitlab-runner
tag: ubi-fips
runners:
config: |
[[runners]]
[runners.kubernetes]
helper_image_flavor = "ubi-fips"
Use a configuration template
To configure the behavior of GitLab Runner build pod in Kubernetes,
use a configuration template file.
Configuration templates can configure any field on the runner, without sharing specific runner configuration options
with the Helm chart. For example, these default settings
found in the values.yaml
file in the chart
repository:
runners:
config: |
[[runners]]
[runners.kubernetes]
image = "ubuntu:22.04"
Values in the config:
section should use TOML (<parameter> = <value>
instead of <parameter>: <value>
, as
config.toml
is embedded in values.yaml
.
For executor-specific configuration, see the values.yaml
file.