Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 14: Runner auf Kubernetes mit ARC

Ziel: Actions Runner Controller (ARC) im k3s installieren, eine Runner Scale Set für dein Repository anlegen und zusehen, wie für jeden Job ein frischer Runner-Pod entsteht und danach verschwindet. · Dauer: ca. 75 min · Voraussetzung: Tag 13

Briefing

  • Der Runner von Tag 5 ist langlebig: Jeder Job sieht die Spuren des vorigen. ARC startet stattdessen für jeden Job einen ephemeren Runner-Pod, der nach dem Job gelöscht wird.
  • Zwei Helm-Charts: der Controller (einmal pro Cluster) und eine Runner Scale Set (eine pro Repository, Organisation oder Runner-Typ).
  • Ein Listener-Pod hält die Verbindung zu GitHub. Kommt ein Job, startet der Controller einen Runner-Pod – zwischen minRunners und maxRunners.
  • Der Name der Scale Set ist das Label: runs-on: arc-notes.
 github.com ◄── Listener (arc-systems) ── Controller ──► Runner-Pod (arc-runners)
   Job runs-on: arc-notes ─────────────────────────────► startet, 1 Job, weg

Drill 1: Helm und der Controller

mkdir -p ~/gha-lab/helm
cd ~/gha-lab/helm
curl -fsSLO https://get.helm.sh/helm-v4.3.1-linux-amd64.tar.gz
tar xzf helm-v4.3.1-linux-amd64.tar.gz
mv linux-amd64/helm ~/.local/bin/
helm version --short

Erwartet:

v4.3.1+gc0d08d0

Der Controller kommt als OCI-Chart aus GHCR:

helm install arc --namespace arc-systems --create-namespace \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \
  --version 0.15.1
kubectl -n arc-systems get pods

Erwartet (nach einigen Sekunden):

NAME                                     READY   STATUS    RESTARTS   AGE
arc-gha-rs-controller-557d5846d4-bbnnn   1/1     Running   0          32s

Davor meldet Helm Pulled: … und STATUS: deployed.

  • oci://ghcr.io/…: Helm holt Charts direkt aus einer OCI-Registry, ganz ohne helm repo add.
  • Der Controller bringt die Custom Resources mit: AutoscalingRunnerSet, EphemeralRunnerSet, EphemeralRunner.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Eine Runner Scale Set

Die Scale Set braucht Zugang zu GitHub. Im Lab nimmst du den Token von gh – er landet als Secret im Cluster, nicht auf dem Bildschirm:

kubectl create namespace arc-runners
kubectl -n arc-runners create secret generic gh-token \
  --from-literal=github_token="$(gh auth token)"

Erwartet:

namespace/arc-runners created
secret/gh-token created

Die Einstellungen der Scale Set kommen in eine Values-Datei:

cat > ~/gha-lab/arc-notes.yaml <<'EOF'
githubConfigUrl: https://github.com/OWNER/notes-actions
githubConfigSecret: gh-token
minRunners: 0
maxRunners: 2
EOF
sed -i "s/OWNER/$(gh api user --jq .login)/" ~/gha-lab/arc-notes.yaml
helm install arc-notes --namespace arc-runners -f ~/gha-lab/arc-notes.yaml \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
  --version 0.15.1
kubectl -n arc-systems get pods

Erwartet (nach einigen Sekunden):

NAME                                     READY   STATUS    RESTARTS   AGE
arc-gha-rs-controller-557d5846d4-bbnnn   1/1     Running   0          65s
arc-notes-7b89bf7c-listener              1/1     Running   0          28s
  • Der Release-Name arc-notes wird zum Label für runs-on.
  • minRunners=0: Ohne Jobs läuft kein einziger Runner-Pod, nur der Listener.
  • Der Listener steht im Namespace des Controllers, die Runner-Pods kommen nach arc-runners.

GitHub kennt die Scale Set jetzt als Runner – ohne einzelne Runner:

cd ~/gha-lab/notes-actions
gh api repos/{owner}/{repo}/actions/runners --jq '.runners[] | .name + " " + .status'

Erwartet:

gha-vm online

Nur der Runner von Tag 5. Eine Scale Set meldet sich erst mit einem Runner, wenn ein Job kommt.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ein Job auf ARC

cat > .github/workflows/arc.yml <<'EOF'
name: arc
on: workflow_dispatch

permissions:
  contents: read

jobs:
  wo:
    runs-on: arc-notes
    steps:
      - name: Wo bin ich?
        run: |
          echo "Host: $(hostname)"
          echo "Spur: $(cat /tmp/spur 2>/dev/null || echo keine)"
          echo "$GITHUB_RUN_ID" > /tmp/spur
EOF
git add .github
git commit -qm "arc: Job auf dem Runner Scale Set"
git push -q
gh workflow run arc.yml
kubectl -n arc-runners get pods

Erwartet (wenige Sekunden nach dem Start):

NAME                     READY   STATUS              RESTARTS   AGE
arc-notes-runner-hn98k   0/1     ContainerCreating   0          13s

Beim ersten Mal lädt k3s das Runner-Image (rund 1 GB) – das dauert. Sobald der Lauf fertig ist:

kubectl -n arc-runners get pods

Erwartet:

No resources found in arc-runners namespace.

Der Pod ist weg. Was hat der Job gesehen?

gh run view <ID> --log | grep -E 'Z (Host|Spur):'

Erwartet (Zeitstempel gekürzt):

wo  Wo bin ich? ... Host: arc-notes-runner-hn98k
wo  Wo bin ich? ... Spur: keine

Ein zweiter Lauf:

gh workflow run arc.yml

Sobald er fertig ist, mit der neuen ID:

gh run view <ID> --log | grep -E 'Z (Host|Spur):'

Erwartet:

wo  Wo bin ich? ... Host: arc-notes-runner-76kz5
wo  Wo bin ich? ... Spur: keine

Anderer Pod, keine Spur – anders als ~/gha-lab/laeufe.txt an Tag 5.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Skalieren

Drei Läufe auf einmal, aber höchstens zwei Runner:

gh workflow run arc.yml
gh workflow run arc.yml
gh workflow run arc.yml
sleep 20
kubectl -n arc-runners get ephemeralrunners

Erwartet (Namen gekürzt):

NAME                     GITHUB CONFIG URL                      RUNNERID   PHASE     ...
arc-notes-runner-8kjzm   https://github.com/<du>/notes-actions  5          Running   ...
arc-notes-runner-sc96k   https://github.com/<du>/notes-actions  6          Running   ...
gh run list --workflow arc.yml --limit 3 --json status --jq '.[].status'

Erwartet (je nach Zeitpunkt):

queued
completed
completed

Der neueste Lauf steht oben: Er wartet, bis ein Runner frei wird. Die beiden anderen waren hier schon fertig – kurze Jobs sind schnell. maxRunners begrenzt, wie viel vom Cluster ARC belegt.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

helm list -A

Erwartet (gekürzt):

NAME             NAMESPACE   REVISION  UPDATED ...  STATUS    CHART
arc              arc-systems 1         2026-11-...  deployed  gha-runner-scale-set-cont...
arc-notes        arc-runners 1         2026-11-...  deployed  gha-runner-scale-set-0.15.1
gateway-api-crd  kube-system 1         2026-11-...  deployed  gateway-api-crd-1.6.103

gateway-api-crd bringt k3s selbst mit.

kubectl get autoscalingrunnersets -A

Erwartet:

NAMESPACE     NAME        MINIMUM RUNNERS   MAXIMUM RUNNERS   PHASE
arc-runners   arc-notes   0                 2                 Running
gh run list --workflow arc.yml --limit 5 --json conclusion --jq '.[].conclusion'

Erwartet:

success
success
success
success
success

Challenge

Der erste Job nach einer Pause wartet, bis ein Pod startet. Halte einen Runner warm, ohne die Scale Set neu zu installieren. Prüfe, dass ohne Job ein Runner-Pod läuft.

Hinweis: minRunners in ~/gha-lab/arc-notes.yaml, dann helm upgrade mit derselben Datei.

Lösung

sed -i 's/^minRunners: 0/minRunners: 1/' ~/gha-lab/arc-notes.yaml
helm upgrade arc-notes --namespace arc-runners -f ~/gha-lab/arc-notes.yaml \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
  --version 0.15.1 >/dev/null
sleep 30
kubectl -n arc-runners get pods

Erwartet:

NAME                     READY   STATUS    RESTARTS   AGE
arc-notes-runner-xk6g8   1/1     Running   0          35s

Der warme Runner nimmt den nächsten Job sofort an – danach startet ARC einen neuen warmen Runner. Zurück auf null:

sed -i 's/^minRunners: 1/minRunners: 0/' ~/gha-lab/arc-notes.yaml
helm upgrade arc-notes --namespace arc-runners -f ~/gha-lab/arc-notes.yaml \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
  --version 0.15.1 >/dev/null

--reuse-values --set minRunners=1 wäre kürzer, scheitert aber mit Helm 4 an diesem Chart (incompatible types for comparison). Eine Values-Datei ist ohnehin besser: Sie gehört ins Git, und jeder sieht, was eingestellt ist.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • GitHub App statt Token: In Produktion meldet sich ARC mit einer GitHub App an (github_app_id, github_app_installation_id, github_app_private_key). Ihre Rechte sind enger, sie hängt an keiner Person, und ihre Tokens laufen nach einer Stunde ab.
  • Container in Jobs: Jobs, die selbst Container bauen, brauchen containerMode dind (Docker im Pod, privilegiert) oder kubernetes (jeder Step ein eigener Pod). Beides will gut abgewogen sein – privilegierte Pods sind ein Risiko.
  • Ressourcen: Ein Runner-Pod ohne Grenzen nimmt sich, was er kriegt. Über template.spec im Chart bekommen Runner resources, nodeSelector und tolerations – z. B. eigene Nodes nur für CI.
  • Viele Scale Sets: Eine Scale Set pro Runner-Typ (arc-klein, arc-gpu) oder pro Organisation; die Namen sind die Labels in runs-on.