Running GitLab-Runners on Kubernetes

Posted on May 14, 2018

In the DevOps era, automation is paramount. Having reliable, predictable, and fast pipelines is a must. Fortunately, there are many options for you to try, like Jenkins, Buildbot, Drone, Concourse and so on. If you are trying to run jobs on Kubernetes there is also the new Jenkins X available. This brings major changes to Jenkins, like running jobs in the cluster. Yet, if you host your code on GitLab, you should use their CI/CD tool. It can save you a lot of time and money when done right. In this article, we will showcase the main steps behind running GitLab-Runners on Kubernetes.

The first step is to configure your projects to use the CI/CD pipeline offered by GitLab. Closely following, you can start deploying. At first, you can use GitLab’s free shared runners. Yet, if you are deploying your code when the servers are overcrowded, you are in for a world of hurt. To makes things easier, GitLab enables you to run jobs in your own cluster, easily.

Then, go to your project, then to Settings –> CI/CD –> Runners settings. Here, fetch the URL and the token to use when creating your runner. This is not the token for your configuration file. It’s just a token that registers your runner, and it generates another token that is used to identify it.

How to run a GitLab Runner on a Kubernetes Container

The next step is running a gitlab-runner container locally to configure you runner:

docker run --rm --entrypoint="" -it gitlab/gitlab-runner:latest bash

Once you are in the Kubernetes container run the following command:

gitlab-runner register

It will open a prompt where it will ask for the URL and token that you copied earlier. It will ask you for other things too, like:

After finishing the registration, the command will generate a configuration file located in /etc/gitlab-runner/config.toml

This is the file that you will use when creating your runner pod on Kubernetes.

Store this configuration file in a ConfigMap:

apiVersion: v1
kind: ConfigMap
  name: gitlab-runner
  namespace: gitlab
  config.toml: |
    concurrent = 4
      name = "Kubernetes Runner"
      url = ""
      token = "xxxxx"
      executor = "kubernetes"
        host = ""
        bearer_token_overwrite_allowed = false
        namespace = "gitlab"
        namespace_overwrite_allowed = ""
        privileged = true
        service_account_overwrite_allowed = ""
        pod_annotations_overwrite_allowed = ""

concurrent specifies the number of parallel jobs that the runner will run. Next, set the privileged field to true if you plan on using the docker:dind image as a service. If you do so, set the DOCKER_HOST environment variable in your build container to tcp://localhost:2375 in your Settings –> CI/CD from your root directory where you can see all the projects.

After this you can pack the gitlab-runner into a deployment and mount the configmap like this:

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
        imagePullPolicy: Always
        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

We hope that this was all you needed to know in order to run GitLab Runners on Kubernetes. If you want to learn more about Kubernetes-related topics, take a look at our tutorials. Happy deploying!

Keep Reading

Take Advantage of the Cloud

Schedule a Call