Run GitLab Runner on a Kubernetes cluster

Tip: We also provide a GitLab Runner Helm Chart.

To install the GitLab CI Runner on Kubernetes there are several resources that need to be defined and then pushed to the cluster with kubectl. This topic covers how to:

  1. Register the new runner using the API.
  2. Define the runner ConfigMap in a yaml file.
  3. Define the runner Deployment yaml file.
  4. Push the definitions to a Kubernetes cluster using kubectl.

Register the new runner using the API

The runner must first be registered to your project, group or instance so that its runner token (not to be confused with the runner registration token) can be provided to the ConfigMap below. To do this:

  1. Register a new runner using the GitLab Runners API (example within) and provide the registration token from the CI/CD settings section of your project, group or instance as described in Configuring GitLab Runners.

  2. Copy the runner token that is returned by the runner API registration command and paste it as the value of the token = "...." field of your ConfigMap.

Define the Runner ConfigMap

Create a file named runner_config.yml from the following example:

apiVersion: v1
kind: ConfigMap
  name: gitlab-runner
  namespace: gitlab
  config.toml: |
    concurrent = 4

      name = "Kubernetes Runner"
      url = ""
      token = "...."
      executor = "kubernetes"
        namespace = "gitlab"
        image = "busybox"

Update the url and token with your values. The parameter image is optional and is the default Docker image used to be used to run jobs.

Note: Don’t use the gitlab-managed-apps namespace for this runner. It should be reserved for applications installed through the GitLab UI.

Define the Runner Deployment

Create a file named runner_deployment.yml from the following example:

apiVersion: extensions/v1beta1
kind: Deployment
  name: gitlab-runner
  namespace: gitlab
  replicas: 1
      name: gitlab-runner
        name: gitlab-runner
      - args:
        - run
        image: gitlab/gitlab-runner:latest
        name: gitlab-runner
        - mountPath: /etc/gitlab-runner
          name: config
        - mountPath: /etc/ssl/certs
          name: cacerts
          readOnly: true
      restartPolicy: Always
      - configMap:
          name: gitlab-runner
        name: config
      - hostPath:
          path: /usr/share/ca-certificates/mozilla
        name: cacerts

Push the definitions to Kubernetes

Assuming that your kubectl context has already been set to the cluster in question, issue these commands:

kubectl apply -f runner_config.yml

kubectl apply -f runner_deployment.yml

The new runner will now show up in the GitLab web UI at the appropriate level (instance, group or project).

For more details see Kubernetes executor and the [runners.kubernetes] section of advanced configuration.