Ga naar hoofdinhoud

🏃‍♂️ GitHub Actions Runner Controller (ARC)

Overzicht​

Bij Brixion gebruiken we GitHub Actions Runner Controller (ARC) om self-hosted runners te beheren op Kubernetes. Dit systeem zorgt voor automatische schaling van runners op basis van de vraag en maakt gebruik van onze aangepaste Docker images voor consistente build-omgevingen.

Hoe het werkt​

Architectuur​

  • Controller: Beheert de lifecycle van runner sets
  • Runner Sets: Groepen van runners die automatisch schalen
  • Container Mode: Docker-in-Docker (DinD) voor geïsoleerde builds
  • Custom Images: Gebruik van ghcr.io/brixion/github-runner:latest

Automatische schaling​

  • Runners worden automatisch opgestart wanneer jobs in de queue staan
  • Runners worden automatisch afgesloten na voltooiing van jobs
  • Kostenefficiënt door alleen resources te gebruiken wanneer nodig

Vereisten​

Voordat je begint, zorg ervoor dat je de volgende tools hebt geïnstalleerd:

  • Go programming language
  • Helm (Kubernetes package manager)
  • kind (Kubernetes in Docker)
  • kubectl (Kubernetes CLI)

Stap-voor-stap installatie​

Stap 1: Dependencies installeren​

# Go installeren
sudo snap install go --classic

# Helm installeren
curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
sudo apt-get install apt-transport-https --yes
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm

# kind installeren
sudo apt install kind

# kubectl installeren
sudo snap install kubectl --classic

Stap 2: Kubernetes cluster opzetten​

# Maak een nieuwe kind cluster aan
kind create cluster --name actions-runner

Stap 3: ARC Controller installeren​

# Installeer de Actions Runner Controller
NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

Stap 4: GitHub authenticatie configureren​

GitHub App aanmaken (Aanbevolen)​

Volg de stappen die hier zijn beschreven om te authenticeren met een GitHub App: https://docs.github.com/en/actions/tutorials/use-actions-runner-controller/authenticate-to-the-api#authenticating-arc-with-a-github-app

⚠️ Veiligheid: Commit de private key nooit in je repository of values.yaml. Gebruik een van de onderstaande veilige methoden:

# Maak een secret aan met je GitHub App credentials
kubectl create secret generic github-app-credentials \
  --namespace arc-systems \
  --from-literal=github_app_id='123456' \
  --from-literal=github_app_installation_id='654321' \
  --from-file=github_app_private_key=./private-key.pem

# Upgrade de controller om het secret te gebruiken
helm upgrade arc \
    --namespace arc-systems \
    --set githubConfigSecret='github-app-credentials' \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

Stap 5: Runner Set installeren​

info

De INSTALLATION_NAME die je hier kiest wordt automatisch de tag die je moet gebruiken in workflows bij runs-on. Het is niet mogelijk om meerdere tags toe te voegen aan een runner set. Kies daarom een duidelijke en herkenbare naam.

# Configuratie variabelen
INSTALLATION_NAME="brixion-runners"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/brixion"

# Runner set installeren
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set containerMode.type=dind \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

# Maak ook hier de secret aan
kubectl create secret generic github-app-credentials \
  --namespace "${NAMESPACE}" \
  --from-literal=github_app_id='123456' \
  --from-literal=github_app_installation_id='654321' \
  --from-file=github_app_private_key=./private-key.pem

Stap 6: Custom configuratie toepassen​

Values bestand aanmaken​

Maak een values.yaml bestand aan met de volgende inhoud:

githubConfigUrl: 'https://github.com/brixion'
githubConfigSecret: github-app-credentials
# githubConfigSecret:
#   github_app_id: "123456"
#   github_app_installation_id: "654321"
#   github_app_private_key: |
#      -----BEGIN RSA PRIVATE KEY-----
#      ********
#      -----END RSA PRIVATE KEY-----
template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/brixion/github-runner:latest
        command:
          ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
        volumeMounts:
          - name: dind-externals
            mountPath: /home/runner/tmpDir
    
    containers:
      - name: runner
        image: ghcr.io/brixion/github-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
      
      - name: dind
        image: docker:dind
        args:
          - dockerd
          - --host=unix:///var/run/docker.sock
          - --group=$(DOCKER_GROUP_GID)
        env:
          - name: DOCKER_GROUP_GID
            value: "123"
        securityContext:
          privileged: true
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

namespaceOverride: ''

Configuratie toepassen​

# Runner set upgraden met custom configuratie
RUNNER_SET_NAME="brixion-runners"
NAMESPACE="arc-runners"

helm upgrade "${RUNNER_SET_NAME}" \
  --namespace "${NAMESPACE}" \
  -f values.yaml \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Verificatie​

Status controleren​

# Alle Helm releases bekijken
helm list -A

# Pods in het arc-systems namespace controleren
kubectl get pods -n arc-systems

# Pods in het arc-runners namespace controleren
kubectl get pods -n arc-runners

Logs bekijken​

# Controller logs
kubectl logs -n arc-systems -l app.kubernetes.io/name=gha-runner-scale-set-controller

# Runner logs
kubectl logs -n arc-runners -l app.kubernetes.io/name=gha-runner-scale-set

Gebruik in GitHub Actions​

Om de self-hosted runners te gebruiken in je GitHub Actions workflows, specificeer je de juiste runs-on label:

name: Example Workflow
on: [push]

jobs:
  build:
    runs-on: brixion-runners  # Gebruik je runner set naam
    steps:
      - uses: actions/checkout@v4
      - name: Run build
        run: echo "Running on self-hosted runner!"

Configuratie aanpassen​

Runner resources wijzigen​

Bewerk je values.yaml om resource limits in te stellen:

template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/brixion/github-runner:latest
        resources:
          requests:
            memory: "1Gi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "1000m"

Scaling configureren​

# Minimum en maximum aantal runners
minRunners: 0
maxRunners: 10

# Scaling gedrag
template:
  spec:
    containers:
      - name: runner
        env:
          - name: RUNNER_SCALE_SET_NAME
            value: brixion-runners

Voordelen​

  • Kostenefficiënt: Alleen actieve runners gebruiken resources
  • Schaalbaarheid: Automatische schaling op basis van vraag
  • Consistentie: Gebruik van aangepaste Docker images
  • Isolatie: Elke job draait in een schone omgeving
  • Flexibiliteit: Eenvoudig aan te passen configuratie

Troubleshooting​

Runners starten niet op​

  1. Controleer of je GitHub token de juiste permissions heeft
  2. Verificeer of de GitHub config URL correct is
  3. Bekijk de controller logs voor foutmeldingen

Docker builds falen​

  1. Controleer of de DinD container correct is geconfigureerd
  2. Verificeer of de privileged security context is ingesteld
  3. Controleer volume mounts tussen containers

Geen runners beschikbaar​

  1. Controleer of de runner set correct is geregistreerd in GitHub
  2. Verificeer scaling configuratie
  3. Bekijk runner logs voor startup problemen
tip

Voor uitgebreide troubleshooting, raadpleeg de officiële ARC documentatie.

Onderhoud​

Updates uitvoeren​

# Controller updaten
helm upgrade arc \
    --namespace arc-systems \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

# Runner set updaten
helm upgrade brixion-runners \
    --namespace arc-runners \
    -f values.yaml \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Monitoring​

  • Gebruik kubectl top pods om resource gebruik te monitoren
  • Configureer alerts voor failed pods of scaling events
  • Monitor GitHub Actions queue voor optimale scaling