Table of Contents
Was this article helpful?
Try Vultr Today with

$50 Free on Us!

Want to contribute?

You could earn up to $600 by adding new articles.

How to Install GitLab Runner on Vultr Kubernetes Engine

Author: Adhing'a Fredrick

Last Updated: Fri, Nov 25, 2022


GitLab Runner is an open-source software system that runs CI/CD jobs and sends the results to GitLab. The runner application is installed and configured on the machine you want to use for builds. Each project in GitLab can have its own runners, and each runner is a container that can be started and stopped as you need.

Kubernetes is an open-source software system that automates applications deployment, scaling, and maintains containerized applications. It works by grouping application containers into logical units for access and management.

GitLab runner on Kubernetes is used to manage CI/CD projects. This tutorial explains how to install GitLab Runner on Vultr Kubernetes Engine.


To follow through this tutorial, you need the following:

Setting Up GitLab Runner

Get the runner details from GitLab. These are the runner URL and the token. The token is used to authenticate the runner to GitLab. On your project's directory, get the details from Settings > CI/CD > Runners settings page, as shown below.

GitLab Runner

Copy the runner URL and the registration token and save them for later GitLab runner configuration.

Install the Runner on Vultr Kubernetes Engine (VKE)

To deploy the runner on your VKE cluster, you have to configure access to the cluster. This is done using a kubeconfig file. The kubeconfig file is used to provide access to Kubernetes API servers. It is used by kubectl and other Kubernetes components to find the appropriate API server and authenticate.

  1. Get the kubeconfig file for your VKE cluster.

    • In you Vultr account, navigate to Products > Kubernetes > {Your cluster} > Overview.

    • Click the Download Configuration button on the top right of the dashboard.

    VKE configuration file

  2. Run the following command to access your VKE cluster:

    $ kubectl --kubeconfig={PATH TO THE VKE CLUSTER CONFIG FILE} get nodes

    Expected output:

    NAME                         STATUS   ROLES    AGE   VERSION
    gitlab-runner-1e796f3ba099   Ready    <none>   18d   v1.24.4
    gitlab-runner-4c11d4f0a353   Ready    <none>   18d   v1.24.4
    gitlab-runner-4ca2d1cacafb   Ready    <none>   18d   v1.24.4     
  3. Create a namespace called gitlab-runner using the kubectl as shown below:

    $ kubectl --kubeconfig={PATH TO THE VKE CLUSTER CONFIG FILE} create namespace gitlab

    A namespace is used to isolate resources within a single Kubernetes cluster. For example, you can use namespaces to deploy multiple applications to the same cluster without interfering with each other. This helps with maintenance and future upgrades.

  4. Obtain a copy of the Helm chart of GitLab Runner by running the command below:

    git clone

    Or, run the command below if you are using an ssh key.

    git clone
  5. Navigate to the cloned repository and configure your GitLab Runner in the values.yaml file as follows:

    ## GitLab Runner Image
    ## Specify a imagePullPolicy for the main runner deployment
    imagePullPolicy: IfNotPresent
    ## Timeout, in seconds, for liveness and readiness probes of a runner pod.
    probeTimeoutSeconds: 300
    ## The GitLab Server URL (with protocol) that want to register the runner against
    ## The Registration Token for adding new Runners to the GitLab Server. 
    runnerRegistrationToken: "Token"
    ## For RBAC support:
      create: true
       - resources: ["configmaps", "pods", "pods/attach", "secrets", "services"]
         verbs: ["get", "list", "watch", "create", "patch", "update", "delete"]
       - apiGroups: [""]
         resources: ["pods/exec"]
         verbs: ["create", "patch", "delete"]
    ## Configuration for the Pods that the runner launches for each new job
      config: |
            namespace = "{{.Release.Namespace}}"
            image = "ubuntu:16.04"

    NOTE To avoid the Readiness probe failed error, configure the templates\deployment.yaml file as follows:

          initialDelaySeconds: 300
          initialDelaySeconds: 300
  6. After configuring the Helm Chart, deploy the runner using the following command:

    helm --kubeconfig={PATH_TO_VKE_CLUSTER_CONFIG FILE} install --namespace <NAMESPACE> gitlab-runner -f <PATH_TO_CONFIG_VALUES_FILE>  gitlab/gitlab-runner

    Expected Output:

    NAME: gitlab-runner
    LAST DEPLOYED: Thu Nov 17 17:22:08 2022
    NAMESPACE: gitlab
    STATUS: deployed
    TEST SUITE: None
    Your GitLab Runner should now be registered against the GitLab instance reachable at: ""
    Runner namespace "gitlab" was found in runners.config template.


    • <NAMESPACE> is the Kubernetes namespace.

    • <PATH_TO_CONFIG_VALUES_FILE> is the path to the helm chart. In this case, *.tgz file.

  7. Check the status of the pod or deployment by running the command below:

    kubectl --kubeconfig={PATH_TO_VKE_CLUSTER_CONFIG FILE} describe pods gitlab-runner --namespace=<NAMESPACE>

    Expected Output:

      Type    Reason     Age   From               Message
      ----    ------     ----  ----               -------
      Normal  Scheduled  30s   default-scheduler  Successfully assigned gitlab-b/gitlab-runner-85d94848d7-zs5q9 to gitlab-runner-4c11d4f0a353
      Normal  Pulling    30s   kubelet            Pulling image ""
      Normal  Pulled     25s   kubelet            Successfully pulled image "" in 4.909922707s
      Normal  Created    25s   kubelet            Created container gitlab-runner
      Normal  Started    25s   kubelet            Started container gitlab-runner

To check if the pods have been started, go to GitLab under the registered GitLab runners. The runner will be displayed as shown in the figure below.

Registered Runner


You've finished installing GitLab Runner in Vultr Kubernetes Engine (VKE) cluster using Helm Chart. You can now manage your CD/CI projects using the runner you've just installed.

Want to contribute?

You could earn up to $600 by adding new articles.