Gitlab runners with Kubernetes in (nearly) no time

Photo by chuttersnap on Unsplash

The gitlab ci/cd toolchain has become a great companion for me in the past years. Since I started using kubernetes more and more I always wanted to utilize the power of kubernetes for the gitlab runners. Furthermore I wanted to get rid of that pesky little badly secured gitlab instance and secure it with TLS (“https”) which became quite necessary later…

As always there is not much to do after you once made it work and invested an hour or two. To spare you the time, let’s get to the details.


General workflow

  1. Make sure you have the proper certificates at hand: One for the gitlab nginx and (if needed) your local CA.
  2. Create a namespace for your runners.
  3. Insert the certificates as a secret in your kubernetes cluster.
  4. Modify the gitlab-runner yaml file for your needs.
  5. Use the yaml file and helm to install the runners in your kubernetes cluster.

1. Security / Certificates

For obvious reasons it is a good idea to secure the gitlab nginx with TLS. In my case I used TinyCA for local network signing, which can be obtained easily through the package manager of various distributions. But anything that will result in a certificate which works for you will do.

2. Create the namespace

Basically you can be creative here, but seriously do not name it ‘gitlab’ because that can seriously interfere with your routing inside kubernetes!

Here let’s call it runners:

kubectl create namespace runners

3. Create a secret with your certificates

The runners need to be sure that your code repository is exactly what it is supposed to be. We don’t want a man-in-the-middle. So we create a secret with the certificates. This needs at least the certificate from your nginx and in my case I even had to include the CA certificate. (So the crt file contained two BEGIN CERTIFICATE and two END CERTIFICATE blocks.)

kubectl --namespace runners \
  create secret generic gitlab-domain-cert \

IMPORTANT sidenote: The crt file has to be formated as in <the-full-hostname-of-gitlab>.crt . Otherwise it won’t work.

4. Modify the gitlab runner yaml file

You need to get a configuration file for your runner. (A click on ‘raw’ helps.) Next step is to modify some values:

  • gitlabUrl should be your gitlab instance url including https.
  • runnerRegistrationToken should be the token gitlab provides in its GUI = webpage runner admin settings.
  • certsSecretName has to be the name of our previously set secret: gitlab-domain-cert
  • namespace has to be runners
  • Change RBAC to your needs.
  • (optional) Personally I reduced checkInterval to 5 seconds.

5. Use helm to install your runners

With all the configuration in place, you can initiate the helm magic.

helm install --namespace runners \
  --name gitlab-runner \
  -f gitlab-helm-runner-settings.yml \

And you’re done 🙂