Bereitstellen von Runner-Skalierungssets mit Actions Runner Controller

Bereitstellen eines Runner-Scale-Sets

ARC muss aktuell ausgeführt werden, damit du eine Runner-Skalierungsgruppe bereitstellen kannst. Weitere Informationen finden Sie unter Schnellstart für Actions Runner Controller.

Runner-Skalierungsgruppen können mit den Helm-Charts von ARC oder durch Bereitstellen der erforderlichen Manifeste bereitgestellt werden. Die Verwendung der Helm-Charts von ARC ist die bevorzugte Methode, insbesondere wenn du noch keine Erfahrung im Umgang mit ARC hast.

1. Führe den folgenden Befehl in deinem Terminal mit Werten aus deiner ARC-Konfiguration aus, um deine Runner-Skalierungsgruppe zu konfigurieren.

   Beachte beim Ausführen des Befehls folgende Punkte:

   • Aktualisiere den INSTALLATION_NAME-Wert mit Bedacht. Der Installationsname wird in deinen Workflows als Wert von runs-on genutzt.

   • Aktualisiere den NAMESPACE-Wert auf den Speicherort, an dem die Runnerpods erstellt werden sollen.

   • Lege den GITHUB_CONFIG_URL-Wert auf die URL deines Repositorys, deiner Organisation oder deines Unternehmens fest. Dies ist die Instanz, der die Läufer angehören.

   • Mit diesem Beispielbefehl wird die neueste Version des Helm-Charts installiert. Wenn du eine bestimmte Version installieren möchtest, kannst du das --version-Argument zusammen mit der Version des Charts übergeben, die du installieren möchtest. Die Liste der Releases finden Sie im actions-runner-controller-Repository.

     Bash

     INSTALLATION_NAME="arc-runner-set"
     NAMESPACE="arc-runners"
     GITHUB_CONFIG_URL="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>"
     GITHUB_PAT="<PAT>"
     helm install "${INSTALLATION_NAME}" \
         --namespace "${NAMESPACE}" \
         --create-namespace \
         --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
         --set githubConfigSecret.github_token="${GITHUB_PAT}" \
         oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
     

     Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

2. Führe den folgenden Befehl in deinem Terminal aus, um deine Installation zu überprüfen.

   Bash

   helm list -A
   

   Es sollte in etwa folgende Ausgabe angezeigt werden:

   NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                       APP VERSION
   arc             arc-systems     1               2023-04-12 11:45:59.152090536 +0000 UTC deployed        gha-runner-scale-set-controller-0.4.0       0.4.0
   arc-runner-set  arc-systems     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0
   

3. Führe den folgenden Befehl in deinem Terminal aus, um den Managerpod zu überprüfen.

   Bash

   kubectl get pods -n arc-systems
   

   War die Installation erfolgreich, zeigen die Pods den Status Running an.

   NAME                                                   READY   STATUS    RESTARTS   AGE
   arc-gha-runner-scale-set-controller-594cdc976f-m7cjs   1/1     Running   0          64s
   arc-runner-set-754b578d-listener                       1/1     Running   0          12s
   

Wenn die Installation nicht erfolgreich war, findest du weitere Informationen zur Problembehandlung unter Problembehandlung bei Actions Runner Controller-Fehlern.

Verwenden erweiterter Konfigurationsoptionen

ARC bietet eine Reihe von erweiterten Konfigurationsoptionen.

Konfigurieren des Namens der Runner-Skalierungsgruppe

Zur Konfiguration des Namens des Runner-Scale-Sets können Sie INSTALLATION_NAME definieren oder den Wert von runnerScaleSetName in Ihrer Kopie der values.yaml-Datei festlegen.

## The name of the runner scale set to create, which defaults to the Helm release name
runnerScaleSetName: "my-runners"

Vergewissere dich, dass du in deinem values.yaml-Befehl die Datei helm install übergibst. Weitere Informationen finden Sie in der Dokumentation zur Helm-Installation.

Auswählen von Runnerzielen

Runner-Skalierungsgruppen können auf Repository-, Organisations- oder Unternehmensebene bereitgestellt werden.

Lege den Wert von githubConfigUrl in deiner Kopie der values.yaml-Datei auf die URL deines Repositorys, deiner Organisation oder deines Unternehmens fest, um Runner-Skalierungsgruppen auf einer bestimmten Ebene bereitzustellen.

Das folgende Beispiel zeigt die Konfiguration von ARC, um octo-org/octo-repo Runner hinzuzufügen.

githubConfigUrl: "http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>"

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Nutzung der GitHub App zur Authentifizierung

Wenn Sie keine Runner auf Unternehmensebene verwenden, können Sie sich mit GitHub Apps bei der GitHub-API authentifizieren. Weitere Informationen finden Sie unter Authentifizieren von ARC für die GitHub-API.

Sie können entweder ein Kubernetes-Geheimnis erstellen oder Werte in der values.yaml-Datei angeben.

Option 1: Erstellen eines Kubernetes-Geheimnisses (empfohlen)

Nachdem du deine GitHub App erstellt hast, erstelle ein Kubernetes-Geheimnis, und übergib den Verweis zu diesem Geheimnis in deiner Kopie der values.yaml-Datei.

kubectl create secret generic pre-defined-secret \
  --namespace=arc-runners \
  --from-literal=github_app_id=123456 \
  --from-literal=github_app_installation_id=654321 \
  --from-file=github_app_private_key=private-key.pem

Übergib in deiner Kopie des values.yaml den Secret-Namen als Referenz.

githubConfigSecret: pre-defined-secret

Option 2: Angeben von Werten in deiner values.yaml-Datei

Alternativ können Sie in Ihrer Kopie der values.yaml-Datei die Werte von app_id, installation_id und private_key angeben.

## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API.
## You can choose to use a GitHub App or a personal access token (classic)
githubConfigSecret:
  ## GitHub Apps Configuration
  ## IDs must be strings, use quotes
  github_app_id: "123456"
  github_app_installation_id: "654321"
  github_app_private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    HkVN9...
    ...
    -----END RSA PRIVATE KEY-----

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Verwalten des Zugriffs mit Runner-Gruppen

Mit Runnergruppen können Sie steuern, welche Organisationen oder Repositorys Zugriff auf Ihre Runner-Skalierungssätze erhalten sollen. Weitere Informationen zu Runnergruppen findest du unter Verwalten des Zugriffs auf selbstgehostete Runner mithilfe von Gruppen.

Damit du einer Runnergruppe eine Runner-Skalierungsgruppe hinzufügen kannst, musst du bereits eine Runnergruppe erstellt haben. Anschließend legst du die Eigenschaft runnerGroup in deiner Kopie der values.yaml-Datei fest. Im folgenden Beispiel wird der Runnergruppe „Octo-Group“ eine Runner-Skalierungsgruppe hinzugefügt.

runnerGroup: "Octo-Group"

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Konfigurieren eines Proxys für ausgehenden Datenverkehr

Lege in deinem Helm-Chart die folgenden Eigenschaften fest, um zu erzwingen, dass der HTTP-Datenverkehr für den Controller und die Runner über den Proxy für ausgehenden Datenverkehr verläuft.

proxy:
  http:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  https:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  noProxy:
    - example.com
    - example.org

ARC unterstützt die Verwendung anonymer oder authentifizierter Proxys. Für authentifizierte Proxys musst du den Wert credentialSecretRef so festlegen, dass er auf ein Kubernetes-Geheimnis verweist. Mit dem folgenden Befehl kannst du ein Secret mit deinen Proxyanmeldeinformationen erstellen.

  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Festlegen der maximalen und minimalen Anzahl von Runnern

Die Eigenschaften maxRunners und minRunners bieten eine Reihe von Optionen, um dein ARC-Setup anzupassen.

Beispiel: Unbegrenzte Anzahl von Runnern

Wenn du die beiden Eigenschaften maxRunners und minRunners auskommentierst, führt ARC eine Hochskalierung bis zur Anzahl der Aufträge durch, die der Runner-Skalierungsgruppe zugewiesen sind bzw. skaliert herunter auf 0, wenn keine aktiven Aufträge vorhanden sind.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
# minRunners: 0

Beispiel: Mindestanzahl von Runnern

Sie können die minRunners-Eigenschaft auf eine beliebige Zahl festlegen und ARC sorgt dafür, dass immer die angegebene Anzahl von Runnern aktiv und verfügbar ist, um Aufträge zu übernehmen, die der eingestellten Runner-Skalierungsgruppe zugeordnet sind.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

Beispiel: Festlegen der maximalen und minimalen Anzahl von Runnern

In dieser Konfiguration führt Actions Runner Controller eine Hochskalierung auf maximal 30 Runner und nach Abschluss der Aufträge eine Herunterskalierung auf 20 Runner durch.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 30

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

Beispiel: Ausgleichen der Auftragswarteschlange

In bestimmten Szenarien möchten Sie möglicherweise die Auftragswarteschlange leeren, um ein Problem zu beheben oder um Ihren Cluster zu warten. Wenn du beide Eigenschaften auf 0 festlegst, erstellt Actions Runner Controller keine neuen Runnerpods, wenn neue Aufträge verfügbar und zugewiesen sind.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

Benutzerdefinierte TLS-Zertifikate

Einige Umgebungen erfordern TLS-Zertifikate, die von einer benutzerdefinierten Zertifizierungsstelle signiert sind. Da Zertifikate von benutzerdefinierten Zertifizierungsstellen nicht mit Controller- oder Runnercontainern gebündelt sind, musst du sie in die jeweiligen Vertrauensspeicher einfügen.

githubServerTLS:
  certificateFrom:
    configMapKeyRef:
      name: config-map-name
      key: ca.crt
  runnerMountPath: /usr/local/share/ca-certificates/

Stelle dabei sicher, dass du das PEM-Format (Privacy Enhanced Mail) verwendest und die Zertifikaterweiterung .crt lautet. Alles andere wird ignoriert.

Der Controller führt die folgenden Aktionen aus:

• Erstellen des Volumes github-server-tls-cert mit den in certificateFrom angegebenen Zertifikaten
• Einbinden dieses Volumes im Pfad runnerMountPath/<certificate name>
• Festlegen der Umgebungsvariable NODE_EXTRA_CA_CERTS auf denselben Pfad
• Festlegen der Umgebungsvariable RUNNER_UPDATE_CA_CERTS auf 1 (ab Version 2.303.0 wird der Runner angewiesen, Zertifikate auf dem Host neu zu laden)

ARC beobachtet die in der Runner-Pod-Vorlage festgelegten Werte und überschreibt sie nicht.

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Verwenden einer privaten Containerregistrierung

Wenn du eine private Containerregistrierung verwenden möchtest, kopiere das Controller- und das Runnerimage in deine private Containerregistrierung. Konfiguriere anschließend die Links zu diesen Images, und lege die Werte imagePullPolicy und imagePullSecrets fest.

Konfigurieren des Controller-Images

Aktualisiere deine Kopie der values.yaml-Datei, und lege die image-Eigenschaften wie folgt fest:

image:
  repository: "custom-registry.io/gha-runner-scale-set-controller"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: "0.4.0"

imagePullSecrets:
  - name: <registry-secret-name>

Der Listenercontainer erbt das für den Controller definierte imagePullPolicy-Element.

Konfigurieren des Runnerimages

Du kannst deine Kopie der Datei values.yaml aktualisieren und die template.spec-Eigenschaften festlegen, um den Runnerpod für deinen spezifischen Anwendungsfall zu konfigurieren.

Nachfolgend ein Beispiel für eine Konfiguration:

template:
  spec:
    containers:
      - name: runner
        image: "custom-registry.io/actions-runner:latest"
        imagePullPolicy: Always
        command: ["/home/runner/run.sh"]
    imagePullSecrets:
      - name: <registry-secret-name>

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Aktualisieren der Podspezifikation für den Runnerpod

Sie können die PodSpec des Runnerpods vollständig anpassen, und der Controller wird die von Ihnen angegebene Konfiguration anwenden. Der folgende Code ist ein Beispiel für eine Pod-Spezifikation.

template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
        securityContext:
          readOnlyRootFilesystem: true
          allowPrivilegeEscalation: false
          capabilities:
            add:
              - NET_ADMIN

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Aktualisierung der Pod-Spezifikation für den Listener-Pod

Sie können die PodSpec des Listener-Pods anpassen, und der Controller wird die von Ihnen angegebene Konfiguration übernehmen. Der folgende Code ist ein Beispiel für eine Podspezifikation.

listenerTemplate:
  spec:
    containers:
    # If you change the name of the container, the configuration will not be applied to the listener,
    # and it will be treated as a sidecar container.
    - name: listener
      securityContext:
        runAsUser: 1000
      resources:
        limits:
          cpu: "1"
          memory: 1Gi
        requests:
          cpu: "1"
          memory: 1Gi

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Verwenden des Docker-in-Docker- oder Kubernetes-Modus für Container

Wenn du Containeraufträge und -dienste oder Containeraktionen verwendest, musst du den Wert von containerMode auf dind oder kubernetes festlegen. Um einen benutzerdefinierten Containermodus zu verwenden, kommentiere containerMode aus oder entferne ihn, und füge im Abschnitt template die gewünschte Konfiguration hinzu. Weitere Informationen findest du unter Anpassen von Containermodi.

• Weitere Informationen zu Containeraufträgen und -diensten findest du unter Jobs in einem Container ausführen.
• Weitere Informationen zu Containeraktionen findest du unter Creating a Docker container action (Erstellen einer Docker-Containeraktion).

Verwenden des Docker-in-Docker-Modus

Mit der Konfiguration des Docker-in-Docker-Modus können Sie Docker in einem Docker-Container ausführen. In dieser Konfiguration erstellt ARC für jeden erstellten Runnerpod die folgenden Container:

• Einen init-Container
• Einen runner-Container
• Einen dind-Container

Lege containerMode.type wie folgt auf dind fest, um den Docker-in-Docker-Modus zu aktivieren.

containerMode:
  type: "dind"

          `template.spec` wird auf die folgende Standardkonfiguration aktualisiert.

Für Versionen von Kubernetes >= v1.29 wird der Sidecar-Container zum Ausführen des Docker-Daemons verwendet.

template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/actions/actions-runner:latest
        command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
        volumeMounts:
          - name: dind-externals
            mountPath: /home/runner/tmpDir
      - 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
        restartPolicy: Always
        startupProbe:
          exec:
            command:
              - docker
              - info
          initialDelaySeconds: 0
          failureThreshold: 24
          periodSeconds: 5
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
          - name: RUNNER_WAIT_FOR_DOCKER_IN_SECONDS
            value: "120"
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

Für Versionen von Kubernetes < v1.29 wird die folgende Konfiguration angewendet:

template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/actions/actions-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/actions/actions-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: {}

Die Werte in template.spec werden automatisch eingefügt und können nicht überschrieben werden. Wenn Sie dieses Setup anpassen möchten, müssen Sie die Konfiguration containerMode.type aufheben und dann diese Konfiguration kopieren und direkt in Ihrer Kopie der values.yaml Datei anwenden.

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Verwenden des Kubernetes-Modus

Im Kubernetes-Modus erstellt ARC mithilfe von Runnercontainerhooks einen neuen Pod im selben Namespace, um den Dienst, den Containerauftrag oder die Aktion auszuführen.

Voraussetzungen

Der Kubernetes-Modus unterstützt zwei Ansätze für die gemeinsame Nutzung von Job-Daten zwischen dem Runner Pod und dem Container Job Pod. Sie können persistente Volumes verwenden, die die empfohlene Option für Szenarien bleiben, die gleichzeitigen Schreibzugriff erfordern, oder Containerlebenszyklus-Hooks verwenden, um Auftragsdateisysteme zwischen Pods wiederherzustellen und zu exportieren, ohne sich auf RWX-Volumes zu verlassen. Der Lebenszyklus-Hook-Ansatz verbessert die Portabilität und Leistung durch nutzung des lokalen Speichers und ist ideal für Cluster ohne gemeinsam genutzten Speicher.

Konfigurieren des Kubernetes-Modus mit persistenten Volumes

Um den Kubernetes-Modus zu verwenden, müssen Sie persistente Volumes erstellen, die von den Runner-Pods beansprucht werden können, und eine Lösung verwenden, die diese Volumes bei Bedarf automatisch bereitstellt. Zu Testzwecken können Sie z. B. die Lösung OpenEBS nutzen.

In Ihrer values.yaml-Datei setzen Sie containerMode.type auf kubernetes, um den Kubernetes-Modus zu aktivieren.

containerMode:
  type: "kubernetes"
  kubernetesModeWorkVolumeClaim:
    accessModes: ["ReadWriteOnce"]
    storageClassName: "dynamic-blob-storage"
    resources:
      requests:
        storage: 1Gi

Weitere Helm-Konfigurationsoptionen findest du unter values.yaml im ARC-Repository.

Konfigurieren des Kubernetes-Modus mit Containerlebenszyklus-Hooks

Um den Kubernetes-Modus mithilfe von Containerlebenszyklus-Hooks zu aktivieren, setzen Sie containerMode.type auf kubernetes-novolume in der values.yaml-Datei.

containerMode:
  type: "kubernetes-novolume"

Problembehandlung beim Kubernetes-Modus

Ist der Kubernetes-Modus aktiviert, erzeugen Workflows, die nicht mit einem Containerauftrag konfiguriert sind, einen Fehler wie den folgenden:

Jobs without a job container are forbidden on this runner, please add a 'container:' to your job or contact your self-hosted runner administrator.

Damit Aufträge ohne Auftragscontainer ausgeführt werden können, legen Sie ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER auf false für den Runnercontainer fest. Dadurch wird der Runner angewiesen, diese Überprüfung zu deaktivieren.

  template:
    spec:
      containers:
        - name: runner
          image: ghcr.io/actions/actions-runner:latest
          command: ["/home/runner/run.sh"]
          env:
            - name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
              value: "false"

Anpassen von Containermodi

Wenn Sie die containerMode in der values.yaml-Datei für die gha-runner-scale-set-Helmchart festlegen, können Sie einen der folgenden Werte verwenden: * dind oder

• kubernetes

Je nachdem, welchen Wert Sie für das containerMode festlegen, wird automatisch eine Konfiguration in den template-Abschnitt der values.yaml-Datei für die gha-runner-scale-set-Helmchart eingefügt.

• Siehe dind-Konfiguration.
• Siehe kubernetes-Konfiguration.

Wenn Sie die Spezifikation anpassen möchten, müssen Sie containerMode auskommentieren oder entfernen bzw. die gewünschte Konfiguration im template-Abschnitt hinzufügen.

Beispiel: dind-rootless ausführen

Bevor Sie sich für die Ausführung von dind-rootless entscheiden, stellen Sie sicher, dass Sie die Einschränkungen kennen.

Für Versionen von Kubernetes >= v1.29 wird der Sidecar-Container zum Ausführen des Docker-Daemons verwendet.

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg
githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create. Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >> /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///run/user/1001/docker.sock
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      restartPolicy: Always
      startupProbe:
        exec:
          command:
            - docker
            - info
        initialDelaySeconds: 0
        failureThreshold: 24
        periodSeconds: 5
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

Für Versionen von Kubernetes < v1.29 kann die folgende Konfiguration angewendet werden:

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg
githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create. Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >> /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

Runner-Container-Hooks verstehen

Wenn der Runner einen Workflowrun erkennt, der einen Containerauftrag, einen Dienstcontainer oder eine Docker-Aktion verwendet, ruft er Runner-Container-Hooks auf, um einen neuen Pod zu erstellen. Der Runner nutzt Runner-Container-Hooks, um die Kubernetes-APIs aufzurufen und einen neuen Pod zu erstellen, der sich im selben Namespace wie der Runner-Pod befindet. Dieser neu erstellte Pod wird verwendet, um den Containerauftrag, den Dienstcontainer oder die Docker-Aktion auszuführen. Weitere Informationen finden Sie im runner-container-hooks-Repository.

Hook-Erweiterungen konfigurieren

Seit ARC Version 0.4.0 unterstützen Runner-Container-Hooks Erweiterungen für Hooks. Sie können diese verwenden, um den von Runner-Container-Hooks erstellten Pod zu konfigurieren. Sie können z. B. eine Hook-Erweiterung verwenden, um einen Sicherheitskontext auf dem Pod festzulegen. Hook-Erweiterungen ermöglichen es Ihnen, eine YAML-Datei anzugeben, die zum Aktualisieren der PodSpec des Pods verwendet wird, das von runner-container-hooks erstellt wurde.

Es gibt zwei Optionen zum Konfigurieren von Hook-Erweiterungen.

• Speichern Sie sie in Ihrem benutzerdefinierten Runner-Bild. Sie können die PodSpec in einer YAML-Datei an einer beliebigen Stelle in Ihrem benutzerdefinierten Runner-Bild speichern. Weitere Informationen finden Sie unter Actions Runner Controller (Steuerung für Aktionsläufer).
• Speichern Sie sie in einer ConfigMap. Sie können eine ConfigMap mit der PodSpec erstellen und diese ConfigMap im Runner-Container bereitstellen. Weitere Informationen finden Sie in der Kubernetes-Dokumentation unter ConfigMaps.

Beispiel: Verwenden von ConfigMap zum Festlegen von securityContext

Erstellen Sie eine ConfigMap im selben Namespace wie die Runner-Pods. Zum Beispiel:

apiVersion: v1
kind: ConfigMap
metadata:
  name: hook-extension
  namespace: arc-runners
data:
  content: |
    metadata:
      annotations:
        example: "extension"
    spec:
      containers:
        - name: "$job" # Target the job container
          securityContext:
            runAsUser: 1000

• Die .metadata.labels- und metadata.annotations-Felder werden so angefügt, wie sie sind, es sei denn, ihre Schlüssel sind reserviert. Sie können die .metadata.name- und metadata.namespace-Felder nicht außer Kraft setzen.
• Der Großteil der PodSpec-Felder wird aus der angegebenen Vorlage angewendet und überschreibt die von der values.yaml-Datei aus der Helm-Chart übergebenen Werte.
• Wenn Sie zusätzliche Volumes angeben, werden diese an die vom Runner angegebenen Standardvolumes angefügt.
• Die spec.containers werden basierend auf den ihnen zugewiesenen Namen zusammengeführt.
  • Wenn der Name des Blobcontainers $job ist:
    • … werden die spec.containers.name- und spec.containers.image-Felder ignoriert.
    • … werden die spec.containers.env-, spec.containers.volumeMounts- und spec.containers.ports-Felder an die durch den Hook erstellte Standard-Container-Spezifikation angehängt.
    • Die restlichen Felder werden wie angegeben angewendet.
  • Wenn der Name des Containers nicht $job lautet, werden die Felder der Pod-Definition wie folgt hinzugefügt:

Aktivieren von Metriken

ARC kann Metriken zu Ihren Runnern, Ihren Aufträgen und der für die Ausführung Ihrer Workflows aufgewendeten Zeit ausgeben. Metriken können verwendet werden, um Überlastungen zu identifizieren, die Integrität Ihrer ARC-Bereitstellung zu überwachen, Nutzungstrends zu visualisieren, den Ressourcenverbrauch zu optimieren und vieles mehr. Metriken werden vom Controller-Manager und Listener-Pods im Prometheus-Format ausgegeben. Weitere Informationen finden Sie in der Prometheus-Dokumentation unter Expositionsformate.

Um Metriken für ARC zu aktivieren, konfigurieren Sie die metrics-Eigenschaft in dervalues.yaml-Datei des gha-runner-scale-set-controller-Diagramms.

Hier eine beispielhafte Konfiguration.

metrics:
  controllerManagerAddr: ":8080"
  listenerAddr: ":8080"
  listenerEndpoint: "/metrics"

Nachdem diese Eigenschaften konfiguriert wurden, geben Ihre Controller-Manager- und Listener-Pods Metriken über den listenerEndpoint an die Ports aus, die Sie in Ihrer values.yaml-Datei angeben. Im obigen Beispiel ist /metrics der Endpunkt und der Port ist :8080. Sie können diesen Endpunkt verwenden, um Metriken von Ihrem Controller-Manager und Listener-Pods auszulesen.

Um Metriken zu deaktivieren, aktualisieren Sie Ihre values.yaml-Datei, indem Sie das Objekt und dessen metrics: Eigenschaften entfernen oder kommentieren.

Verfügbare Metriken für ARC:

Die folgende Tabelle zeigt die Metriken, die vom Controller-Manager und Listener-Pods ausgegeben werden.

          [1]: Listener metrics that have the counter type are reset when the listener pod restarts.

Verwenden von ARC mit Dependabot und code scanning

Sie können Actions Runner Controller verwenden, um dedizierte Runner für Ihre GitHub Enterprise Server-Instanz zu erstellen, damit Dependabot die Abhängigkeiten, die in den Repositories Ihres Unternehmens genutzt werden, absichern und verwalten kann. Weitere Informationen finden Sie unter Verwalten von selbstgehosteten Runnern für Dependabot-Updates in Ihrem Unternehmen.

Sie können auch ARC mit CodeQL verwenden, um Sicherheitsrisiken und Fehler in deinem Code zu identifizieren. Weitere Informationen finden Sie unter Informationen zu Codescans mit CodeQL. Wenn Sie bereits code scanning verwenden und ein Runner-Skalenset für die Verwendung des Standardsetups konfigurieren möchten, legen Sie INSTALLATION_NAME=code-scanning fest. Weitere Informationen zum code scanning-Standardsetup findest du unter Konfigurieren des Standardsetups für das Code-Scanning.

Actions Runner Controller verwendet keine mehrfachen Bezeichnungen, um Aufträge an bestimmte Runnerskalierungsgruppen weiterzuleiten. Um stattdessen einen Runner-Skalierungssatz für Dependabot-Updates oder code scanning mit CodeQL festzulegen, verwenden Sie einen beschreibenden Installationsnamen in deinem Helm-Diagramm, z. B. dependabot oder code-scanning. Anschließend kannst du den runs-on-Wert in deinen Workflows auf den Installationsnamen als einzelne Bezeichnung festlegen und den angegebenen Runner-Skalierungssatz für Dependabot-Updates oder code scanning-Aufträge verwenden.

Wenn du das Standard-Setup für code scanning verwendest, sucht die Analyse automatisch nach einem Runner Scale Set mit dem Installationsnamen code-scanning .

Upgraden von ARC

Da es keine Unterstützung für das Upgrade oder Löschen von CRDs mit Helm gibt, ist es nicht möglich, Helm zum Upgrade von ARC zu verwenden. Weitere Informationen finden Sie unter Benutzerdefinierte Ressourcendefinitionen in der Helm-Dokumentation. Um ARC auf eine neuere Version zu aktualisieren, müssen Sie die folgenden Schritte ausführen:

1. Deinstallieren Sie alle Installationen von gha-runner-scale-set.
2. Warten Sie, bis die Ressourcen bereinigt werden.
3. Deinstallieren Sie ARC.
4. Wenn sich CRDs in der upgegradeten Version gegenüber der aktuell installierten Version ändern, entfernen Sie alle CRDs, die der API-Gruppe actions.github.com zugeordnet sind.
5. Installieren Sie ARC erneut.

Weitere Informationen findest du unter Bereitstellen eines Runner-Skalierungssets.

Wenn Sie ARC aufrüsten möchten, sich aber Sorgen über Ausfallzeiten machen, können Sie ARC in einer Hochverfügbarkeitskonfiguration einsetzen, um sicherzustellen, dass die Runner immer verfügbar sind. Weitere Informationen findest du unter Hochverfügbarkeit und automatisches Failover.

Bereitstellen eines Canaryimages

Sie können Features testen, bevor sie veröffentlicht werden, indem Sie Canary-Versionen des Controller-Manager-Containerimages verwenden. Canaryimages werden im Tagformat canary-SHORT_SHA veröffentlicht. Weitere Informationen finden Sie unter gha-runner-scale-set-controller im Container registry.

1. Aktualisieren Sie die tag im gha-runner-scale-set-controller values.yaml die Datei auf: canary-SHORT_SHA
2. Aktualisieren Sie das Feld appVersion in der Chart.yaml-Datei für gha-runner-scale-set auf: canary-SHORT_SHA
3. Installieren Sie ARC mithilfe der aktualisierten Helm-Chart und der values.yaml-Dateien erneut.

Hochverfügbarkeit und automatisches Failover

ARC kann in einer Hochverfügbarkeitskonfiguration (aktiv-aktiv) bereitgestellt werden. Wenn Sie zwei unterschiedliche Kubernetes-Cluster in separaten Regionen bereitgestellt haben, können Sie ARC in beiden Clustern bereitstellen und Runner-Skalierungsgruppen so konfigurieren, dass sie dasselbe runnerScaleSetName verwenden. Um dies zu tun, muss jede Runner-Skalierungsgruppe einer bestimmten Runnergruppe zugewiesen werden. Sie können zum Beispiel zwei Runner-Skalierungsgruppen haben, die jeweils als arc-runner-set benannt sind, solange eine Runner-Skalierungsgruppe zu runner-group-A gehört und die andere Runner-Skalierungsgruppe zu runner-group-B gehört. Informationen über die Zuweisung von Runner Scale Sets zu Runner-Gruppen findest du unter Verwalten des Zugriffs auf selbstgehostete Runner mithilfe von Gruppen.

Wenn beide Runner-Skalierungsgruppen online sind, werden ihnen zugewiesene Aufträge willkürlich verteilt (Zuordnungsrennen). Sie können den Auftragszuweisungsalgorithmus nicht konfigurieren. Wenn eines der Cluster abläuft, übernimmt die im anderen Cluster festgelegte Runner-Skalierungsgruppe weiterhin Aufträge normal ohne Eingriff oder Konfigurationsänderung.

Organisationsübergreifendes Verwenden von ARC

Mit einer einzelnen Installation von Actions Runner Controller können Sie eine oder mehrere Runner-Skalierungsgruppen konfigurieren. Diese Runner-Skalensätze können in einem Repository, einer Organisation oder einem Unternehmen registriert werden. Mit Runner-Gruppen können Sie auch die Berechtigungsgrenzen dieser Runner-Skalierungssets steuern.

Es hat sich bewährt, für jede Organisation einen eindeutigen Namespace zu erstellen. Sie könnten auch für jede Runnergruppe oder jedes Runner-Skalierungsset einen Namespace erstellen. In jedem Namespace können so viele Runner-Skalierungsgruppen wie nötig installiert werden. Dadurch wird die Isolation maximal erhöht und die Sicherheit verbessert. Für die Authentifizierung können Sie GitHub Apps verwenden und präzise Berechtigungen für jede Runner-Skalierungsgruppe definieren.

Rechtliche Hinweise

Teile wurden von https://github.com/actions/actions-runner-controller/ unter der Apache-2.0-Lizenz übernommen:

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.