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
minRunnersundmaxRunners. - 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 --shortErwartet:
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 podsErwartet (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 ohnehelm 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 podsErwartet (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-noteswird zum Label fürruns-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 podsErwartet (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 podsErwartet:
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.ymlSobald 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 ephemeralrunnersErwartet (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 -AErwartet (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 -AErwartet:
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 podsErwartet:
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
containerModedind(Docker im Pod, privilegiert) oderkubernetes(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.specim Chart bekommen Runnerresources,nodeSelectorundtolerations– 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 inruns-on.