Tutorial: Configure GitLab Runner to use the Google Kubernetes Engine

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

This tutorial describes how to configure GitLab Runner to use the Google Kubernetes Engine (GKE) to run jobs.

In this tutorial, you configure GitLab Runner to run jobs in the Standard cluster mode.

To configure GitLab Runner to use the GKE:

  1. Set up your environment.
  2. Create and connect to a cluster.
  3. Install and configure the Kubernetes Operator.
  4. Optional. Verify that the configuration was successful.

Before you begin

Before you can configure GitLab Runner to use the GKE you must:

Set up your environment

Install the tools to configure and use GitLab Runner in the GKE.

  1. Install and configure Google Cloud CLI. You use Google Cloud CLI to connect to the cluster.
  2. Install and configure kubectl. You use kubectl to communicate with the remote cluster from your local environment.

Create and connect to a cluster

This step describes how to create a cluster and connect to it. After you connect to the cluster, you use kubectl to interact with it.

  1. In the Google Cloud Platform, create a standard cluster.

  2. Install the kubectl authentication plugin: 

    gcloud components install gke-gcloud-auth-plugin

  3. Connect to the cluster: 

    gcloud container clusters get-credentials CLUSTER_NAME --zone=CLUSTER_LOCATION

  4. View the cluster configuration: 

    kubectl config view

  5. Verify that you are connected to the cluster: 

    kubectl config current-context

Install and configure the Kubernetes Operator

Now that you have a cluster, you’re ready to install and configure the Kubernetes Operator.

  1. Install cert-manager. Skip this step if you already have a certificate manager installed: 

    kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.yaml

  2. Install the Operator Lifecycle Manager (OLM), a tool that manages the Kubernetes Operators that run on the cluster: 

    curl --silent --location "https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.24.0/install.sh" \
 | bash -s v0.24.0

  3. Install the Kubernetes Operator: 

    kubectl create -f https://operatorhub.io/install/gitlab-runner-operator.yaml

  4. Operator Lifecycle Manager v0.25.0 and later only. Add your own certificate manager or use cert-manager.

    • To add your own certificate provider:

      1. In the gitlab-runner-operator.yaml, define the certificate namespace and certificate name in the env setting: 

        cat > gitlab-runner-operator.yaml << EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: gitlab-runner-operator
namespace: gitlab-ns
spec:
channel: stable
name: gitlab-runner-operator
source: operatorhubio-catalog
ca: webhook-server-cert
sourceNamespace: olm
config:
env:
   - name: CERTIFICATE_NAMESPACE
   value: cert_namespace_desired_value
   - name: CERTIFICATE_NAME
   value: cert_name_desired_value
EOF

      2. Apply the gitlab-runner-operator.yaml to the Kubernetes cluster: 

        kubectl apply -f gitlab-runner-operator.yaml

    • To use the cert-manager:

      1. Use the certificate-issuer-install.yaml to install a Certificate and Issuer in the default namespace, in addition to the operator installation: 

        cat > certificate-issuer-install.yaml << EOF
apiVersion: v1
kind: Namespace
metadata:
labels:
   app.kubernetes.io/component: controller-manager
   app.kubernetes.io/managed-by: olm
   app.kubernetes.io/name: gitlab-runner-operator
name: gitlab-runner-system
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: gitlab-runner-serving-cert
namespace: gitlab-runner-system
spec:
dnsNames:
- gitlab-runner-webhook-service.gitlab-runner-system.svc
- gitlab-runner-webhook-service.gitlab-runner-system.svc.cluster.local
issuerRef:
  kind: Issuer
  name: gitlab-runner-selfsigned-issuer
secretName: webhook-server-cert
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: gitlab-runner-selfsigned-issuer
namespace: gitlab-runner-system
spec:
selfSigned: {}
EOF

      2. Apply the certificate-issuer-install.yaml to the Kubernetes cluster: 

        kubectl create -f certificate-issuer-install.yaml

  5. Create a secret that contains the runner-registration-token from your GitLab project: 

     cat > gitlab-runner-secret.yml << EOF
 apiVersion: v1
 kind: Secret
 metadata:
   name: gitlab-runner-secret
 type: Opaque
 stringData:
   runner-token: YOUR_RUNNER_AUTHENTICATION_TOKEN
 EOF

  6. Apply the secret: 

    kubectl apply -f gitlab-runner-secret.yml

  7. Create the custom resource definition file and include the following information: 

     cat > gitlab-runner.yml << EOF
 apiVersion: apps.gitlab.com/v1beta2
 kind: Runner
 metadata:
   name: gitlab-runner
 spec:
   gitlabUrl: https://gitlab.example.com
   buildImage: alpine
   token: gitlab-runner-secret
 EOF

  8. Apply the custom resource definition file: 

    kubectl apply -f gitlab-runner.yml

That’s it! You’ve configured GitLab Runner to use the GKE. In the next step, you can check if your configuration is working.

Verify your configuration

To check if runners are running in the GKE cluster, you can either:

  • Use the following command: 

    kubectl get pods

    You should see the following output. This shows that your runners are running in the GKE cluster: 

    NAME                             READY   STATUS    RESTARTS   AGE
gitlab-runner-hash-short_hash    1/1     Running   0          5m

  • Check the job log in GitLab:

    1. On the left sidebar, select Search or go to and find your project.
    2. Select Build > Jobs and find the job.
    3. To view the job log, select the job status.