Skip to content

KIT GitLab Runner - KGR

Quick Start 🚀

Are you new to runners? You can start using CI/CD in GitLab by following steps:

  • You are going to need .gitlab-ci.yml file in your repository and enable runner.
  • To create the file proceed as follows: Your-repository->Build->Pipeline editor->Configure pipeline->Commit changes
  • If it is running, hurray! Otherwise go to settings->CI/CD->Runners and check if Enable instance runners for this project is on.
  • For more information refer to official GitLab documentation and this documentation regarding specific configuration at KIT

Introduction

GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline. A runner is a process that can run on any computer and process pending jobs. A distinction must be made between “shared”, “group” and "project" runners. A specific runner only serves for certain projects, a group runner is dedicated to process only jobs associated to projects in a group, and shared runners are available to all groups and projects in a GitLab instance. You can find available runner type in the project settings Settings -> CI/CD -> Runners.

PLEASE NOTE🗒️: The runners are already in released with all planned features. They are upgraded without any versions, so despite the persistence of settings is high up in the priority changes, the runner service is further developed, maintained and growing.

Runner types at KIT:

  • instance (shared) runners
  • project and group runners

The project and group runner in KIT only serves jobs for a group or a project. On the other hand the instance runners are shared with everyone. In case of the project runner, the runner can be used for all projects and subgroups inside of that group.

Runner specification

The GitLab-Runner is installed on a Kubernetes-Tanzu-Cluster in the VMware infrastructure and ready to process jobs/tasks in a container.

Available runners overview

KGR1 runners

  • Platform: Kubernetes
  • Timeout: 1 hour
Name/tag Concurrency Cores Memory Disk
kgr1-instance-mini 20 (high) 0.5 - 0.5 1.6 - 2 4 - 13
kgr1-instance-standard 16 (high) 1 - 1 2.8 - 3.7 10 - 26
kgr1-instance-experimental (medium)
kgr1-instance-extraordinary 1 (low) 4 - 6 44 - 45 44 - 92

KGR2 runners

  • Platform: Docker
  • Timeout: 1 hour
Name/tag Concurrency Cores Memory Disk
kgr2-instance-hugedisk 1 (low) 1 - 2 8 128

Overview explanation

If sizes are in format lower-upper - lower size in the range is guaranteed, the upper number is the Resource limit. Terms explanation: - Concurrency: how many jobs can this runner process (always in separated environments for each user/project/job) - Timeout: Maximal duration of the job - Cores: Available cores of the runner for one job - Memory: Available memory of the runner for one job (in GiB) - Disk: Available disk space of the runner for one job (in GiB)

EXPERIMENTAL - EDGE RUNNER RELEASE ⚠️: You can freely use experimental runner as well. It leads the setup of standard runner. So you can expect similar specification but with experimental configuration/features. Because this runners specification is not stable, it wont be as extensively documented.

NOTE 🗒: - For project/group runners the standard size is used by default (on demand the size or number of runners can be adjusted for project runners). - We do design our infrastructure to support specified configuration, however the parallelizability and immediate availability can not be guaranteed. The fact on how mny runners will run for you depends on many factors like, usage by other users, decision of workload and job planning algorithms, etc.

OS - Choosing Linux Distribution

IMPORTANT 🗒️: We do support only linux.

Use image variable to specify the runner. If you don't specify it, the runner will use Ubuntu.

We recommend following two images:

  • ubuntu:latest" - default image if not specified otherwise
  • alpine:latest - lightweight linux image, that is recommended if you want to keep more resources for your builds, scripts, etc.

If those images do not suit your needs you can choose others like: debian:latest, centos:latest, fedora:latest, archlinux:latest, opensuse/leap:latest...

NOTE🗒: Not every version might be available, check before or use the specified version or latest if available.

CI/CD configuration files examples

Example of .gitlab-ci.yml - hello world

hello_world:
  # using tagged runner with tag "eager-blackbear-0"
  tags:
    - "kgr1-instance-standard"

  # specifying stage 
  # (most common stage and order is build->test->deploy)
  stage: build

  # if image not specified then the default is used
  # default: image: "gitlab/gitlab-runner:ubuntu"

  # specifying the commands to be run by the runner
  script:
    - echo "Hello world"

Example of .gitlab-ci.yml - extension

build_the_script:
  tags:
    - "eager-blackbear-0"
  stage: build
  image: "gitlab/gitlab-runner:ubuntu"

  script:
    - echo "print(42)" > get_answer.py 

  # using artifact to pass script to next stage 
  artifacts:
    paths:
      - get_answer.py


test_the_script:
  tags:
    - "eager-blackbear-0"
  stage: test
  image: "gitlab/gitlab-runner:ubuntu"

  script:
    - apt update
    - apt install python3 -y
    - if [ "$(python3 get_answer.py)" == "42" ]; then echo 'Answer is correct'; else echo 'Answer is NOT correct'; fi

Runner with a tag and variables

A tag can be used to control which jobs can be executed on which runners and for which sub-group or specific projects. If tags have been assigned to a job, it will only run on a runner with the appropriate tags.

In the .gitlab-ci.yml file, use CI/CD variables with tags for dynamic runner selection: 

    variables:
      KIT_KUBERNETES_RUNNER: kit-öjwenadnh64$s82gowß3urhnßü1nvwß1nvsa

      job:
        tags:
          - docker
          - $KIT_KUBERNETES_RUNNER
        script:
          - echo "Hello runner selector feature"

Tag of KIT runner

Specify the tag of the runner in tags sequence if you need to specify the runner to be used: 

tags:
  - "kgr-instance-extraordinary"

Variables

Sensitive variables such as tokens or passwords should be stored in the settings in the user interface, preferably not in the .gitlab-ci.yml file. You can define CI/CD variables in the UI Settings -> CI/CD -> Variables.

alt text

Security

When setting up your runners, you should pay attention to the security and protection of confidential data. Any user who has the access rights to the project can also execute arbitrary but unverified commands. When you are setting up your runner, you must ensure that no confidential information is accessible to ungranted user. Particularly for using shared runners, it should be noticed that the runner's private authentication token could be readable and the runner could be imitated by another machine.

Rate-Limit

To ensure a continuous service for all users, projects and groups, each project can start a maximum of 5 pipelines per minute. If this is not sufficient in your case, please write us a ticket with a brief explanation why more simultaneous pipelines need to be active in your project.

Specific needs

If you have specific needs for a runner with a good reason you can contact us with the ticket and write your request.

GitLab Documentation