29 GitLab Runner: Die Execution-Engine

GitLab Runner ist die Execution-Engine von GitLab CI/CD – die Software, die tatsächlich Jobs ausführt. Während GitLab Server Pipelines orchestriert, clont Runner Code, führt Commands aus, reportet Results, und uploaded Artifacts. Ohne Runner keine CI/CD.

Dieses Kapitel erklärt Runner-Architektur, die verschiedenen Runner-Typen (Shared, Specific, Group), Executor-Typen (Shell, Docker, Kubernetes, etc.), Installation und Registration, Konfiguration, und Performance-Optimierung.

29.1 Runner-Architektur: Wie funktioniert ein Runner?

29.1.1 Runner als separate Komponente

Wichtig: Runner sind nicht Teil des GitLab-Servers. Sie sind separate Prozesse/VMs/Container, die irgendwo laufen (eigene Server, Cloud, Developer-Laptop).

Kommunikation:

Flow im Detail:

1. Polling: Runner pollt GitLab API regelmäßig (jede Sekunde)

GET /api/v4/jobs/request
Authorization: Runner token

2. Job Assignment: GitLab matcht verfügbare Jobs mit Runner (basierend auf Tags)

{
  "id": 456,
  "name": "test-job",
  "stage": "test",
  "ref": "main",
  "commands": ["npm install", "npm test"],
  "variables": {...}
}

3. Job Execution: - Runner clont Repository von Gitaly - Runner startet Executor (Shell, Docker, K8s) - Executor führt Commands aus - Stdout/Stderr wird gestreamt zu GitLab

4. Result Reporting:

{
  "id": 456,
  "state": "success",
  "trace": "$ npm install\nadded 1347 packages\n$ npm test\n✓ all tests passed",
  "artifacts": "artifacts.zip"
}

29.1.2 Runner-Registrierung

Registrierung verbindet Runner mit GitLab-Instanz.

Process: 1. Runner generiert Registration-Request 2. GitLab verifiziert Registration-Token 3. GitLab erstellt Runner-Eintrag in DB 4. GitLab gibt Authentication-Token zurück 5. Runner speichert Token in config.toml

Nach Registrierung: Runner pollt kontinuierlich für Jobs.

29.2 Runner-Typen

29.2.1 1. Shared Runners

Definition: Verfügbar für alle Projekte in GitLab-Instanz.

GitLab.com: GitLab stellt kostenlose Shared Runners bereit: - Linux (Docker-Executor) - Windows (Docker-Executor) - macOS (Shell-Executor)

Self-Managed: Admin installiert und registriert Shared Runner.

Vorteile: - Sofort verfügbar (keine Installation) - Keine Maintenance (von GitLab managed) - Autoscaling (auf GitLab.com)

Nachteile: - Shared Resources (kann langsamer sein bei hoher Last) - Limits (CI/CD Minuten auf GitLab.com) - Weniger Kontrolle (Fixed Configuration)

Sichtbar in: Settings → CI/CD → Runners → Available shared runners

29.2.2 2. Specific Runners

Definition: Registriert für spezifisches Projekt.

Use Case: Projekt braucht spezielle Hardware/Software: - GPU für ML-Training - Large Memory für Compilation - Spezifische Software (alte Linux-Version, proprietäre Tools) - Security (Runner in isoliertem Netzwerk)

Registration:

# Auf Runner-Maschine
gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token PROJECT_TOKEN \
  --description "My GPU Runner" \
  --tag-list "gpu,cuda" \
  --executor docker \
  --docker-image ubuntu:22.04

Token: Settings → CI/CD → Runners → Specific runners → Registration token

Vorteile: - Volle Kontrolle (eigene Hardware) - Keine Limits (unbegrenzte CI/CD Minuten) - Custom Configuration

Nachteile: - Maintenance (Updates, Monitoring) - Kosten (eigene Hardware/Cloud-Instanzen)

29.2.3 3. Group Runners

Definition: Verfügbar für alle Projekte in einer Gruppe.

Use Case: Organization hat mehrere Projekte mit gemeinsamen Requirements: - Alle Frontend-Projekte nutzen selben Runner - Alle Backend-Projekte nutzen selben Runner

Registration: Wie Specific, aber auf Group-Level (Group → Settings → CI/CD → Runners)

Vorteile: - Shared zwischen Projekten (effizient) - Zentral managed (Update einmal, gilt für alle)

29.2.4 Runner-Typen: Vergleich

Aspekt	Shared	Specific	Group
Verfügbar für	Alle Projekte	Ein Projekt	Alle Projekte in Group
Registration	Admin (Instance-Level)	Project-Maintainer	Group-Owner
Token	Instance Registration Token	Project Registration Token	Group Registration Token
Kosten	Free (mit Limits)	Eigene Hardware	Eigene Hardware
Kontrolle	Niedrig	Hoch	Hoch
Use Case	Standard CI/CD	Spezielle Hardware	Team-shared Resources

29.3 Executor-Typen

Executor definiert wie Job ausgeführt wird.

29.3.1 1. Shell Executor

Definition: Commands laufen direkt auf Runner-OS.

Setup:

gitlab-runner register \
  --executor shell

Job-Execution:

test:
  script:
    - npm install  # Läuft direkt auf Runner-Maschine
    - npm test

Working Directory: /home/gitlab-runner/builds/$PROJECT_ID/

Vorteile: - Schnell (kein Container-Overhead) - Einfach (keine Docker-Installation nötig) - Direkter Zugriff auf Runner-Filesystem

Nachteile: - Keine Isolation (Job kann Runner-System modifizieren) - Cleanup nötig (Files bleiben nach Job) - Dependencies manuell installieren

Use Case: Legacy-Projekte, spezielle Hardware (GPU direkt), Performance-kritisch.

Security-Concern: Jobs können potentiell Runner kompromittieren.

29.3.2 2. Docker Executor (Empfohlen)

Definition: Jeder Job läuft in fresh Docker-Container.

Setup:

gitlab-runner register \
  --executor docker \
  --docker-image alpine:latest

Job-Execution:

test:
  image: node:18-alpine  # Job-spezifisches Image
  script:
    - npm install
    - npm test

Was passiert: 1. Runner pulled node:18-alpine Image 2. Runner startet Container 3. Container clont Repository 4. Commands laufen in Container 5. Container wird destroyed

Vorteile: - Isolation: Jeder Job in fresh Environment - Reproduzierbar: Gleiche Image → gleiche Results - Clean: Kein Cleanup nötig (Container destroyed) - Flexibel: Verschiedene Images per Job

Nachteile: - Docker-Installation nötig auf Runner - Overhead (Image pull, Container start) - Privileged-Mode für Docker-in-Docker

Use Case: Standard CI/CD, meiste Projekte.

Docker-in-Docker (für Jobs, die selbst Docker nutzen):

build:
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker build -t myapp .

29.3.3 3. Kubernetes Executor

Definition: Jobs laufen als Kubernetes-Pods.

Setup:

gitlab-runner register \
  --executor kubernetes \
  --kubernetes-host https://k8s-cluster.example.com \
  --kubernetes-namespace gitlab-runner

config.toml:

[[runners]]
  name = "k8s-runner"
  url = "https://gitlab.com/"
  token = "abc123"
  executor = "kubernetes"
  [runners.kubernetes]
    host = "https://k8s-cluster.example.com"
    namespace = "gitlab-runner"
    image = "alpine:latest"
    cpu_request = "100m"
    memory_request = "128Mi"
    cpu_limit = "1"
    memory_limit = "1Gi"
    service_cpu_request = "50m"
    service_memory_request = "64Mi"

Job-Execution:

test:
  image: node:18-alpine
  script:
    - npm test

Was passiert: 1. Runner erstellt Pod in Kubernetes 2. Pod pulled Image 3. Pod führt Commands aus 4. Pod wird deleted

Vorteile: - Cloud-Native: Nutzt K8s-Autoscaling - Isolation: Jeder Job in separate Pod - Resource-Limits: CPU/Memory per Job kontrollierbar - Hochskalierbar: Hunderte Jobs parallel

Nachteile: - Kubernetes-Cluster nötig - Komplexe Configuration - Overhead (Pod creation)

Use Case: Cloud-Native-Projects, large-scale CI/CD.

29.3.4 4. Docker Machine Executor (Deprecated, aber erwähnenswert)

Definition: Dynamische VM-Creation für Jobs.

Idee: Runner erstellt VM on-demand (AWS EC2, DigitalOcean), führt Job aus, destroyed VM.

Status: Deprecated (Docker Machine project archived). Ersetzt durch Kubernetes Executor.

29.3.5 5. VirtualBox Executor

Definition: Jobs laufen in VirtualBox-VMs.

Use Case: Windows-CI/CD auf Linux-Runner, komplette Isolation.

Rarely used: Docker/Kubernetes sind besser.

29.3.6 6. Parallels Executor

Definition: Jobs laufen in Parallels-VMs (macOS).

Use Case: iOS/macOS-Builds.

Rarely used: Xcode Cloud oder macOS-Runner mit Shell-Executor sind üblicher.

29.3.7 7. SSH Executor

Definition: Runner connected zu remote Machine via SSH, führt Commands dort aus.

Use Case: Legacy-Server ohne Runner-Installation.

Configuration:

[[runners]]
  executor = "ssh"
  [runners.ssh]
    host = "remote-server.example.com"
    port = 22
    user = "gitlab-runner"
    identity_file = "/home/gitlab-runner/.ssh/id_rsa"

29.3.8 8. Custom Executor

Definition: Custom Script definiert, wie Job ausgeführt wird.

Use Case: Sehr spezielle Requirements (z.B. Job auf physical Device ausführen).

Configuration:

[[runners]]
  executor = "custom"
  [runners.custom]
    prepare_exec = "/path/to/prepare.sh"
    run_exec = "/path/to/run.sh"
    cleanup_exec = "/path/to/cleanup.sh"

29.3.9 Executor-Typen: Empfehlung

Executor	Empfohlen für	Pros	Cons
Docker	✅ Most Projects	Isolation, Reproduzierbar, Clean	Docker nötig
Kubernetes	✅ Cloud-Native, Scale	Autoscaling, Resource-Control	Komplex
Shell	Legacy, Special Hardware	Schnell, Einfach	Keine Isolation
VirtualBox	Windows auf Linux	Isolation	Langsam
SSH	Legacy ohne Runner	Remote-Execution	Unsicher
Custom	Very Special Cases	Maximum Flexibility	Komplex

Default-Empfehlung: Docker Executor.

29.4 Runner Installation

29.4.1 Linux (Ubuntu/Debian)

1. Repository hinzufügen:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

2. Install:

sudo apt-get install gitlab-runner

3. Verify:

gitlab-runner --version
# Output: Version:      16.6.0

29.4.2 Linux (Manual Binary)

1. Download:

sudo curl -L --output /usr/local/bin/gitlab-runner \
  "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"

2. Make executable:

sudo chmod +x /usr/local/bin/gitlab-runner

3. Create user:

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

4. Install and start service:

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

29.4.3 macOS

Homebrew:

brew install gitlab-runner
brew services start gitlab-runner

29.4.4 Windows

1. Download gitlab-runner-windows-amd64.exe

2. Install als Service:

.\gitlab-runner-windows-amd64.exe install
.\gitlab-runner-windows-amd64.exe start

29.4.5 Docker

Run Runner in Docker:

docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

Wichtig: /var/run/docker.sock mounted → Runner kann Docker-Containers starten (Docker-in-Docker).

29.5 Runner Registration

Registration verbindet Runner mit GitLab.

29.5.1 Interactive Registration

Command:

sudo gitlab-runner register

Prompts:

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.com/

Enter the registration token:
abc123xyz789  # Von GitLab UI (Settings → CI/CD → Runners)

Enter a description for the runner:
my-docker-runner

Enter tags for the runner (comma-separated):
docker,linux

Enter optional maintenance note for the runner:
Production Docker Runner

Enter an executor: custom, docker, parallels, shell, ssh, virtualbox, docker+machine, kubernetes:
docker

Enter the default Docker image (for example, ruby:2.7):
alpine:latest

Result: Runner registered, config.toml created.

29.5.2 Non-Interactive Registration

One-Liner:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "abc123xyz789" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "my-docker-runner" \
  --tag-list "docker,linux" \
  --run-untagged="false" \
  --locked="false"

Use Case: Automated Runner-Setup (Terraform, Ansible).

29.5.3 Registration Token finden

Project-Level:

Project → Settings → CI/CD → Runners → Specific runners
Registration token: abc123xyz789

Group-Level:

Group → Settings → CI/CD → Runners
Registration token: def456uvw012

Instance-Level (Admin only):

Admin Area → Overview → Runners
Registration token: ghi789rst345

29.6 Runner Configuration (`config.toml`)

Location: /etc/gitlab-runner/config.toml (Linux) oder ~/.gitlab-runner/config.toml

Structure:

concurrent = 4  # Max parallel jobs across all runners

check_interval = 3  # Polling interval (seconds)

[[runners]]
  name = "my-docker-runner"
  url = "https://gitlab.com/"
  token = "abc123xyz"
  executor = "docker"
  
  [runners.cache]
    Type = "s3"
    Shared = true
    [runners.cache.s3]
      ServerAddress = "s3.amazonaws.com"
      BucketName = "gitlab-runner-cache"
      BucketLocation = "eu-central-1"
  
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0

29.6.1 Wichtige Settings

Concurrency:

concurrent = 10  # Max 10 Jobs parallel über alle Runner

Per-Runner Concurrency:

[[runners]]
  limit = 5  # Dieser Runner max 5 Jobs parallel

Docker-Volumes:

[runners.docker]
  volumes = ["/cache", "/builds:/builds"]

Docker-Privileged (für Docker-in-Docker):

[runners.docker]
  privileged = true

Docker-Network:

[runners.docker]
  network_mode = "host"  # Oder "bridge", "none"

Resource-Limits (Kubernetes):

[runners.kubernetes]
  cpu_limit = "1"
  memory_limit = "1Gi"
  cpu_request = "100m"
  memory_request = "128Mi"

29.7 Tags und Job-Matching

Tags matchen Jobs zu Runnern.

29.7.1 Tags definieren (Runner)

Bei Registration:

gitlab-runner register --tag-list "docker,linux,x86"

In config.toml:

[[runners]]
  tags = ["docker", "linux", "x86"]

29.7.2 Tags nutzen (Job)

build:
  tags:
    - docker
    - linux
  script:
    - make build

test:gpu:
  tags:
    - gpu
    - cuda
  script:
    - python train_model.py

Matching-Regel: Job läuft auf Runner, der alle Tags hat.

Job build: Läuft auf Runner mit docker AND linux Tags. Job test:gpu: Läuft nur auf Runner mit gpu AND cuda Tags.

29.7.3 Untagged Jobs

Runner-Setting:

[[runners]]
  run_untagged = true  # Runner akzeptiert auch Jobs ohne Tags

Empfehlung: run_untagged = false für Specific Runners (vermeidet unerwartete Job-Execution).

29.8 Performance und Scaling

29.8.1 1. Concurrent Jobs erhöhen

concurrent = 20  # 20 Jobs parallel

Hardware-Requirement: CPU/Memory muss ausreichen. Docker: 20 parallel Container → 20 GB RAM+ empfohlen.

29.8.2 2. Cache nutzen

S3-Cache:

[runners.cache]
  Type = "s3"
  Shared = true
  [runners.cache.s3]
    ServerAddress = "s3.amazonaws.com"
    BucketName = "gitlab-runner-cache"
    BucketLocation = "us-east-1"
    AccessKey = "AKIAIOSFODNN7EXAMPLE"
    SecretKey = "wJalrXUtnFEMI/K7MDENG/bPxRfiCY"

Shared = true: Cache shared zwischen Runnern (effizient für Cluster).

29.8.3 3. Docker Image pre-pulling

Problem: Job wartet auf Image-Pull.

Lösung: Pre-pull häufig genutzte Images:

docker pull node:18-alpine
docker pull python:3.11-slim
docker pull openjdk:17-jdk-slim

Cron-Job:

0 2 * * * docker pull node:18-alpine
0 2 * * * docker pull python:3.11-slim

29.8.4 4. Kubernetes Autoscaling

Horizontal Pod Autoscaler:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: gitlab-runner
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: gitlab-runner
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Effekt: Wenn CPU-Utilization > 70%, scale up (bis 10 Pods).

29.9 Monitoring

29.9.1 Runner-Status

Command-Line:

gitlab-runner status
# Runtime platform: linux/amd64
# gitlab-runner: Service is running

gitlab-runner verify
# Verifying runner... is alive

Admin Area (GitLab UI):

Admin Area → Overview → Runners

Runner #123: my-docker-runner
Status: ✓ online
Last contact: 2 seconds ago
Tags: docker, linux
Jobs run: 1,234

29.9.2 Prometheus Metrics

Runner exportiert Metrics:

http://runner-host:9252/metrics

Wichtige Metrics:

gitlab_runner_jobs{state="running"}       # Aktuell laufende Jobs
gitlab_runner_jobs{state="waiting"}       # Wartende Jobs in Queue
gitlab_runner_job_duration_seconds        # Job-Duration
gitlab_runner_errors_total                # Errors

Grafana-Dashboard: Visualisiert Runner-Performance, Queue-Length, Error-Rate.

29.10 Troubleshooting

29.10.1 Problem 1: Runner offline

Symptom: Admin Area zeigt “offline” (grau).

Diagnose:

gitlab-runner status
# Service is not running

Fix:

sudo gitlab-runner start

29.10.2 Problem 2: Jobs hängen in “pending”

Symptom: Job startet nicht, Status “pending”.

Diagnose: - Kein Runner mit matching Tags: Job hat tags: [gpu], aber kein Runner hat gpu Tag. - Alle Runner busy: concurrent Limit erreicht, alle Runner beschäftigt.

Fix: - Tags matchen - concurrent erhöhen - Mehr Runner registrieren

29.10.3 Problem 3: Docker pull error

Symptom:

ERROR: Job failed: failed to pull image "myimage:latest"

Diagnose: Runner kann Image nicht pullen (nicht existiert, keine Permissions).

Fix: - Image existiert verifizieren - DOCKER_AUTH_CONFIG setzen (für private Registry)

29.10.4 Problem 4: “This job is stuck”

Symptom: Job zeigt “This job is stuck”.

Diagnose: Kein Runner verfügbar (alle offline, Tags matchen nicht).

Fix: Runner starten, Tags fixen.

29.11 Best Practices

1. Separate Runner für verschiedene Workloads:

Runner 1: Tags [docker, linux] → Standard CI/CD
Runner 2: Tags [gpu, cuda] → ML-Training
Runner 3: Tags [windows] → Windows-Builds

2. Docker Executor für meiste Projekte: Isolation, Reproduzierbarkeit.

3. Monitoring setup: Prometheus + Grafana für Runner-Health.

4. Cache mit S3: Shared Cache für mehrere Runner.

5. Regular Updates:

sudo apt-get update
sudo apt-get install gitlab-runner

6. Security: privileged = false wo möglich, run_untagged = false für Specific Runners.

7. Resource-Limits (Kubernetes): CPU/Memory Limits prevent resource-exhaustion.

29.12 Zusammenfassung

GitLab Runner ist die Execution-Engine, die Jobs ausführt:

Runner-Typen: - Shared: Für alle Projekte - Specific: Für ein Projekt - Group: Für alle Projekte in Group

Executor-Typen: - Docker: Empfohlen, Isolation, Reproduzierbar - Kubernetes: Cloud-Native, Autoscaling - Shell: Legacy, spezielle Hardware

Setup: - Installation (Package Manager, Binary, Docker) - Registration (Interactive oder Non-Interactive) - Configuration (config.toml)

Tags: Matchen Jobs zu Runnern

Performance: - Concurrent Jobs - Cache (S3) - Image Pre-Pulling - Autoscaling (Kubernetes)

Master Runner, und CI/CD wird von “waiting in queue” zu “instant execution at scale”.

29.13 Runner-Executor: Typen und Einsatzmöglichkeiten

Der GitLab Runner verwendet sogenannte Executors, um Jobs in verschiedenen Umgebungen auszuführen. Ein Executor bestimmt, wie und wo ein Job abgearbeitet wird, und bietet verschiedene Möglichkeiten, um sich an die Anforderungen des Projekts anzupassen.

29.13.1 Typen von Runner-Executors

Shell-Executor: Führt Jobs direkt im Terminal des Hosts aus. Einfach einzurichten, aber begrenzt in der Isolation und Portabilität.
Docker-Executor: Nutzt Container für jeden Job, was eine isolierte Umgebung bietet und die Portabilität erhöht.
Docker-Compose-Executor: Ermöglicht die Verwendung von mehreren Docker-Containern für komplexere Setups.
Kubernetes-Executor: Führt Jobs in Kubernetes-Pods aus, ideal für Cloud-native Anwendungen.
SSH-Executor: Verwendet SSH, um Jobs auf einem entfernten Server auszuführen.
Custom-Executor: Bietet die Möglichkeit, benutzerdefinierte Ausführungsumgebungen zu definieren.

29.13.2 Einsatzmöglichkeiten

Die Wahl des Executors hängt von den Anforderungen an Sicherheit, Portabilität, Isolierung und der zugrundeliegenden Infrastruktur ab:

Shell-Executor eignet sich für lokale Entwicklungsumgebungen.
Docker-Executor ist ideal für konsistente und portable Build-Umgebungen.
Kubernetes-Executor bietet die beste Skalierbarkeit und Integration für Cloud-basierte Projekte.

29.14 Einrichtung und Konfiguration von GitLab Runnern

Die Einrichtung und Konfiguration eines GitLab Runners ist ein entscheidender Schritt, um eine funktionierende CI/CD-Pipeline zu ermöglichen. Der GitLab Runner führt die in der .gitlab-ci.yml definierten Jobs aus und kann auf verschiedenen Umgebungen, wie physischen oder virtuellen Maschinen, installiert werden. GitLab bietet verschiedene Runner-Typen: Shared, Group und Project Runner.

29.14.1 Installation des GitLab Runners

Die Installation des GitLab Runners variiert je nach Betriebssystem. Die häufigsten Betriebssysteme für GitLab Runner sind Linux, Windows und macOS. Für die Installation auf Linux-Systemen wird üblicherweise das offizielle GitLab-Repository verwendet. Nachdem der Runner installiert ist, kann er als Dienst gestartet werden. Detaillierte Installationsanweisungen finden sich in der offiziellen GitLab-Dokumentation, und es gibt auch spezifische Optionen für die Installation in Kubernetes oder über Docker.

29.14.2 Runner registrieren

Nachdem der GitLab Runner installiert wurde, muss er bei einem GitLab-Projekt, einer Gruppe oder einer Instanz registriert werden. Dies geschieht über den Befehl gitlab-runner register. Hierbei wird der Runner mit dem GitLab Server verbunden und erhält einen Token, der die Authentifizierung sicherstellt. Bei der Registrierung können auch zusätzliche Parameter festgelegt werden, wie der Executor-Typ (z.B. Docker, Shell, Kubernetes) und spezifische Tags, die den Jobs zugewiesen werden.

29.14.3 Konfiguration über die `config.toml`-Datei

Die Konfiguration des GitLab Runners erfolgt hauptsächlich über die Datei config.toml. Diese Datei enthält verschiedene Einstellungen, die das Verhalten des Runners steuern, einschließlich der Anzahl paralleler Jobs, der Verzeichnisstruktur für Builds und anderer Parameter. Diese Datei kann nach der Installation auf dem Hostsystem angepasst werden, um den Anforderungen der Umgebung gerecht zu werden.

29.14.4 Timeout und Ressourcenlimits festlegen

Für eine bessere Kontrolle über die Ausführung von Jobs können maximale Zeitlimits für Jobs (Job Timeout) und Ressourcennutzungen festgelegt werden. Dies ist besonders wichtig in großen Projekten, um sicherzustellen, dass keine unendlich laufenden Jobs Ressourcen blockieren. Diese Einstellungen können sowohl auf Instanz-, Gruppen- als auch Projektebene angepasst werden.

29.14.5 Sicherheit und Zugriffskontrolle

GitLab ermöglicht es, Runner für bestimmte Branches oder Tags zu beschränken, um sicherzustellen, dass Jobs nur auf bestimmten Runnern ausgeführt werden. Außerdem können sogenannte geschützte Runner konfiguriert werden, die nur in geschützten Branches oder Umgebungen verwendet werden dürfen. Dies bietet eine zusätzliche Sicherheitsebene für kritische Umgebungen wie Produktion.

Weitere Details und Anleitungen zu spezifischen Konfigurationsmöglichkeiten finden sich in der GitLab-Dokumentation.

29.15 Best Practices für die Verwendung von GitLab Runnern

Die effiziente und sichere Verwendung von GitLab Runnern erfordert eine sorgfältige Konfiguration und Verwaltung. Durch die Anwendung bewährter Praktiken kann die Performance der CI/CD-Pipelines verbessert, die Sicherheit erhöht und eine optimale Nutzung der Ressourcen sichergestellt werden.

29.15.1 Wahl des richtigen Executors

Die Wahl des passenden Executors hat einen erheblichen Einfluss auf die Flexibilität und Effizienz der CI/CD-Pipeline. Die gängigsten Executor-Typen und ihre optimalen Einsatzbereiche:

Shell-Executor: Geeignet für einfache Setups ohne Virtualisierung. Allerdings bietet er keine Isolierung, daher ist er für Produktionsumgebungen weniger geeignet.
Docker-Executor: Der Docker-Executor bietet eine hohe Flexibilität, da jeder Job in einem eigenen Container läuft. Dies stellt sicher, dass die Umgebung sauber und reproduzierbar ist. Docker ist besonders nützlich für Build-Prozesse und Testumgebungen, die spezifische Abhängigkeiten benötigen.
Kubernetes-Executor: Ideal für Cloud-native Anwendungen und große Teams. Kubernetes-Executors bieten eine dynamische Skalierung der Runner-Umgebung und eine enge Integration in bestehende Cloud-Infrastrukturen.

Vermeide den Einsatz des Shell-Executors für komplexe oder sicherheitskritische Anwendungen, da dieser keine Isolierung zwischen den Jobs bietet.

29.15.2 Richtige Nutzung von Caching und Artefakten

Caching und Artefakte spielen eine zentrale Rolle bei der Performance-Optimierung von Pipelines. Durch die Verwendung von Caches können Zwischenschritte, wie das Herunterladen von Abhängigkeiten, gespeichert und in nachfolgenden Jobs wiederverwendet werden.

Beispiel für den Cache:

cache:
  paths:
    - node_modules/

Artefakte ermöglichen das Speichern von Build-Outputs, die von anderen Jobs in der Pipeline verwendet werden. Dies reduziert die Notwendigkeit, dieselben Dateien in jedem Job neu zu generieren.

Beispiel für Artefakte:

artifacts:
  paths:
    - dist/

Achte darauf, dass Caches und Artefakte nicht unnötig groß werden, da dies die Performance der Pipeline beeinträchtigen kann. Nutze spezifische Pfade und definiere klare Speicherzeiträume.

29.15.3 Effiziente Nutzung von Runners durch Tags

Durch den Einsatz von Runner-Tags können Jobs gezielt auf bestimmte Runner verteilt werden. Dies ist besonders nützlich, wenn verschiedene Runner-Typen für unterschiedliche Aufgaben vorgesehen sind (z.B. Docker-Runner für Builds, Shell-Runner für einfache Skript-Jobs).

Beispiel für den Einsatz von Tags:

job_name:
  tags:
    - docker

Es ist ratsam, Tags konsistent und eindeutig zu verwenden, um eine klare Zuordnung der Jobs zu den entsprechenden Runnern sicherzustellen.

29.15.4 Skalierbarkeit und Ressourcenoptimierung

Eine effiziente Nutzung der Ressourcen ist entscheidend, besonders bei großen Projekten mit vielen parallelen Pipelines. GitLab Runner bietet Optionen zur Skalierung, insbesondere durch den Einsatz von Docker- und Kubernetes-Executors. Mit Auto-Scaling können zusätzliche Runner je nach Bedarf hinzugefügt oder entfernt werden, um Lastspitzen abzufangen.

Für die Ressourcenoptimierung sollten Timeouts und Limits für Jobs gesetzt werden, um zu verhindern, dass Jobs zu lange oder unkontrolliert laufen:

job_name:
  timeout: 20m

29.15.5 Sicherheitsmaßnahmen implementieren

Sicherheit ist ein wesentlicher Aspekt bei der Arbeit mit GitLab Runnern. Zu den Best Practices gehören:

Geschützte Runner: Setze Runner nur für geschützte Branches und Tags ein, um sicherzustellen, dass nur geprüfter Code in sensiblen Umgebungen wie der Produktion ausgeführt wird.
Verwendung von Masked und Protected Variablen: Sensible Informationen wie API-Schlüssel sollten stets durch geschützte und maskierte Variablen übergeben werden, um sicherzustellen, dass sie nicht im Job-Log sichtbar sind.

Beispiel für geschützte Variablen:

variables:
  SECRET_API_KEY: "masked_key"
  protected: true

29.15.6 Überwachung und Protokollierung

Die Überwachung der Runner-Performance und die Protokollierung der Ausführung sind essenziell, um Engpässe und Fehler zu identifizieren. GitLab bietet umfangreiche Monitoring-Tools, die Runner-Logs und Metriken exportieren können, z.B. über Prometheus. Dies ermöglicht eine tiefgehende Analyse und Optimierung der Pipeline-Effizienz.

29 GitLab Runner: Die Execution-Engine

29.1 Runner-Architektur: Wie funktioniert ein Runner?

29.1.1 Runner als separate Komponente

29.1.2 Runner-Registrierung

29.2 Runner-Typen

29.2.1 1. Shared Runners

29.2.2 2. Specific Runners

29.2.3 3. Group Runners

29.2.4 Runner-Typen: Vergleich

29.3 Executor-Typen

29.3.1 1. Shell Executor

29.3.2 2. Docker Executor (Empfohlen)

29.3.3 3. Kubernetes Executor

29.3.4 4. Docker Machine Executor (Deprecated, aber erwähnenswert)

29.3.5 5. VirtualBox Executor

29.3.6 6. Parallels Executor

29.3.7 7. SSH Executor

29.3.8 8. Custom Executor

29.3.9 Executor-Typen: Empfehlung

29.4 Runner Installation

29.4.1 Linux (Ubuntu/Debian)

29.4.2 Linux (Manual Binary)

29.4.3 macOS

29.4.4 Windows

29.4.5 Docker

29.5 Runner Registration

29.5.1 Interactive Registration

29.5.2 Non-Interactive Registration

29.5.3 Registration Token finden

29.6 Runner Configuration (config.toml)

29.6.1 Wichtige Settings

29.7 Tags und Job-Matching

29.7.1 Tags definieren (Runner)

29.7.2 Tags nutzen (Job)

29.7.3 Untagged Jobs

29.8 Performance und Scaling

29.8.1 1. Concurrent Jobs erhöhen

29.8.2 2. Cache nutzen

29.8.3 3. Docker Image pre-pulling

29.8.4 4. Kubernetes Autoscaling

29.9 Monitoring

29.9.1 Runner-Status

29.9.2 Prometheus Metrics

29.10 Troubleshooting

29.10.1 Problem 1: Runner offline

29.10.2 Problem 2: Jobs hängen in “pending”

29.10.3 Problem 3: Docker pull error

29.10.4 Problem 4: “This job is stuck”

29.11 Best Practices

29.12 Zusammenfassung

29.13 Runner-Executor: Typen und Einsatzmöglichkeiten

29.13.1 Typen von Runner-Executors

29.13.2 Einsatzmöglichkeiten

29.14 Einrichtung und Konfiguration von GitLab Runnern

29.14.1 Installation des GitLab Runners

29.14.2 Runner registrieren

29.14.3 Konfiguration über die config.toml-Datei

29.14.4 Timeout und Ressourcenlimits festlegen

29.14.5 Sicherheit und Zugriffskontrolle

29.15 Best Practices für die Verwendung von GitLab Runnern

29.15.1 Wahl des richtigen Executors

29.15.2 Richtige Nutzung von Caching und Artefakten

29.15.3 Effiziente Nutzung von Runners durch Tags

29.15.4 Skalierbarkeit und Ressourcenoptimierung

29.15.5 Sicherheitsmaßnahmen implementieren

29.15.6 Überwachung und Protokollierung

29.6 Runner Configuration (`config.toml`)

29.14.3 Konfiguration über die `config.toml`-Datei