What is GitLab Runner?

Posted on January 17, 2025

CNCF projects highlighted in this post

Ambassador post by Natalia Granato, CNCF Ambassador

GitLab Runner is an open-source application that runs jobs defined in your GitLab CI/CD pipelines. It can be installed on different platforms, including virtual machines, bare-metal servers, and Kubernetes.

Registering the Runner in Your Projects

After deploying GitLab Runner on Kubernetes, you need to register the runner in your projects so it can execute jobs.

1. Go to the Settings > CI/CD section of your project in GitLab.
2. Expand the Runners section.
3. Click on Register a runner.
4. Copy the displayed registration token.
5. Run the following command on your Kubernetes cluster, replacing YOUR_REGISTRATION_TOKEN with the copied token:
   sh kubectl exec -it gitlab-runner-gitlab-runner-XXXXX-XXXXX -- gitlab-runner register \ --non-interactive \ --url https://gitlab.example.com/ \ --registration-token YOUR_REGISTRATION_TOKEN \ --executor kubernetes

Deploying GitLab Runner on Kubernetes Using Helm

To install GitLab Runner on Kubernetes using Helm, follow these steps:

1. Add the Helm repository: helm repo add gitlab https://charts.gitlab.io/
2. Update the repositories: helm repo update
3. Install GitLab Runner:
   sh helm install gitlab-runner gitlab/gitlab-runner \ --set gitlabUrl=https://gitlab.example.com/ \ --set runnerRegistrationToken=YOUR_REGISTRATION_TOKEN
   Replace https://gitlab.example.com/ with your GitLab URL.
   Replace YOUR_REGISTRATION_TOKEN with the runner registration token obtained in the CI/CD section of your GitLab project.

Key Points in the values.yaml Configuration File

Rules (rules)

This section defines permissions for accessing Kubernetes resources.

• resources: Lists the Kubernetes resources the runner can access, such as configmaps, pods, pods/attach, secrets, and services.
• verbs: Actions that can be performed on the above resources, like get, list, watch, create, patch, update, and delete.
• apiGroups: Specifies API groups in Kubernetes. Here, it’s empty (''), indicating the core API group.
• resources: Lists specific resources of the above API group, such as pods/exec.
• verbs: Actions allowed for the pods/exec resource, such as create, patch, and delete.

Runners (runners)

Defines the runner configuration.

• cache: Cache configuration, currently empty ({}).
• config: Runner configuration in TOML format.
• runners.kubernetes: Configuration specific to Kubernetes runners.
  • image: Container image to use (ubuntu:20.04).
  • wait_for_services_timeout: Timeout for waiting on services (-1 indicates infinite).
  • privileged: Enables privileged mode for the container (true).
  • allow_privilege_escalation: Allows privilege escalation (true).
  • image_pull_secrets: Specifies secrets for pulling container images (aws-ecr).
• configPath: Configuration path, currently empty ('').
• name: Runner name (globalweb-gitlab-runner).
• privileged: Indicates privileged execution (true).
• runUntagged: Indicates whether to run untagged jobs (true).
• tags: Tags associated with the runner (docker, share_cache, share_cache1, amd64).

Secrets (secrets)

List of secrets, currently empty ([]).

SecurityContext (securityContext)

Security configurations for the containers.

• allowPrivilegeEscalation: Permission for privilege escalation (false).
• capabilities: Container capabilities.
• drop: Capabilities to be removed (ALL).
• privileged: Indicates if the container is privileged (false).
• readOnlyRootFilesystem: Indicates if the root filesystem is read-only (false).
• runAsNonRoot: Indicates if the container should run as a non-root user (true).

Other Key Configurations

• Service (service): Service settings. enabled: false, type: ClusterIP.
• SessionServer (sessionServer): Disabled by default (enabled: false).
• Termination Grace Period Seconds (terminationGracePeriodSeconds): Graceful termination timeout (3600 seconds).

Using the New Runner in GitLab CI Pipelines

To use the new runner in your GitLab CI pipelines, add the kubernetes tag to the job you want to execute on Kubernetes. For example:

build_image:
  stage: build
  image: alpine:latest
  tags:
    - kubernetes
  script:
    - echo "Building image..."

Kubernetes Doesn’t Use Docker as Container Runtime? Kaniko to the Rescue

Kubernetes doesn’t use Docker as its default container runtime, which can pose a challenge for CI/CD pipelines that depend on Docker for building images. Kaniko is a tool that allows building container images without Docker.

What is Kaniko and How Does it Work?

Kaniko is an open-source tool that builds container images from a Dockerfile inside a container or Kubernetes cluster. It works by extracting the base container filesystem, executing Dockerfile commands, and packaging the result into a container image.

Configuring Environment Variables in GitLab CI

To use Kaniko effectively, configure the necessary environment variables in GitLab CI. These variables include credentials for accessing your container registry and project-specific information.

Steps to Configure Environment Variables for Your Pipeline

1. Go to the Settings > CI/CD section of your GitLab project.
2. Expand the Variables section.
3. Add the following variables without the protected flag:

• AWS_REGION: Specifies the AWS region where resources will be managed.
• AWS_ACCESS_KEY_ID: AWS public access key for authentication.
• AWS_SECRET_ACCESS_KEY: AWS secret access key for authentication.
• REGISTRY: The container registry where Docker images are stored.

Example .gitlab-ci.yml for Building and Pushing Container Images with Kaniko

build:
  stage: build
  image:
    name: gcr.io/kaniko-project/executor:debug
    entrypoint: [""]
  script:
    - mkdir -p /kaniko/.docker
    - echo "{\"credsStore\":\"ecr-login\",\"credHelpers\":{\"$REGISTRY/portal-colaborador-hml\":\"ecr-login\"}}" > /kaniko/.docker/config.json
    - >-
      /kaniko/executor
      --context "${CI_PROJECT_DIR}" \
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile" \
      --build-arg AWS_REGION=$AWS_REGION \
      --build-arg AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
      --build-arg AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
      --destination "${REGISTRY}/portal-colaborador-hml:${CI_COMMIT_SHORT_SHA:0:5}"

  tags:
    - docker, share_cache, share_cache1, amd64
  only:
    - main
    - develop

Conclusion

Using GitLab Runner in conjunction with Kaniko on Kubernetes enables efficient and secure container image building and pushing without relying on Docker as a runtime. This configuration leverages Kubernetes’ power to scale and manage CI/CD builds, offering greater flexibility and performance in your pipelines.