Schnellstart für Actions Runner Controller

Rechtliche Hinweise

Einführung

Actions Runner Controller (ARC) ist ein Kubernetes-Operator, der selbstgehostete Runner für GitHub Actions orchestriert und skaliert. Weitere Informationen findest du in der Kubernetes-Dokumentation unter Operator-Muster.

Mit ARC kannst du Runner-Skalierungsgruppen erstellen, die basierend auf der Anzahl von Workflows, die in deinem Repository, deiner Organisation oder deinem Unternehmen ausgeführt werden, automatisch skaliert werden. Da kontrollierte Runner kurzlebig sein und auf Containern basieren können, können neue Runnerinstanzen schnell und sauber hoch- oder herunterskaliert werden. Weitere Informationen zur automatischen Skalierung findest du unter Automatische Skalierung mit selbstgehosteten Runnern.

Du kannst ARC in Kubernetes mithilfe von Helm einrichten und dann einen Workflow erstellen und ausführen, der Runner-Skalierungsgruppen verwendet. Weitere Informationen zu Runner-Skalierungsgruppennamen findest du unter Bereitstellen von Runner-Skalierungsgruppen mit Actions Runner Controller.

Voraussetzungen

Um ARC zu verwenden, stelle sicher, dass du über Folgendes verfügst.

• Ein Kubernetes-Cluster

  • Für eine verwaltete Cloudumgebung kannst du AKS verwenden. Weitere Informationen findest du unter Azure Kubernetes Service in der Azure-Dokumentation.

  • Für ein lokales Setup kannst du minikube oder kind verwenden. Weitere Informationen findest du unter minikube start in der minikube-Dokumentation und unter kind in der kind-Dokumentation.

    Hinweis: OpenShift-Cluster werden derzeit nicht unterstützt.

• Helm 3

  • Weitere Informationen findest du unter Installieren von Helm in der Helm-Dokumentation.

• Zwar ist es für die Bereitstellung von ARC nicht zwingend erforderlich, doch sollten Sie eine Methode zum Sammeln und Aufbewahren von Protokollen aus dem Controller, aus Listenern und kurzlebigen Runnern implementiert haben, ehe Sie ARC in Produktionsworkflows bereitstellen.

Installieren von Actions Runner Controller

1. Gehe wie folgt vor, um den Operator und die benutzerdefinierten Ressourcendefinitionen (CRDs) in deinem Cluster zu installieren.

   1. Aktualisiere in deinem Helm-Chart den NAMESPACE-Wert an der Position, wo deine Operatorpods erstellt werden sollen. Dieser Namespace muss den Zugriff auf den Kubernetes-API-Server ermöglichen.
   2. Installieren des Helm-Charts

   Im folgenden Beispiel wird die neueste Version des Charts installiert. Um eine bestimmte Version zu installieren, kannst du das --version-Argument zusammen mit der Version des Charts übergeben, das du installieren möchtest. Die Liste der Releases findest du im GitHub Container Registry.

   Bash

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

   Weitere Helm-Konfigurationsoptionen findest du unter values.yaml in der ARC-Dokumentation.

2. Um ARC die Authentifizierung bei GitHub zu ermöglichen, generiere ein personal access token. Weitere Informationen findest du unter Authentifizieren bei der GitHub-API.

Konfigurieren einer Runner-Skalierungsgruppe

1. Führe zum Konfigurieren deiner Runner-Skalierungsgruppe den folgenden Befehl in deinem Terminal mithilfe von Werten aus deiner ARC-Konfiguration aus.

   Beachte beim Ausführen des Befehls folgende Punkte:

   • Aktualisiere den INSTALLATION_NAME-Wert mit Bedacht. Verwende den Installationsnamen als Wert von runs-on in deinen Workflows. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

   • Aktualisiere den NAMESPACE-Wert am Speicherort, an dem die Runner-Pods erstellt werden sollen.

   • Lege GITHUB_CONFIG_URL auf die URL deines Repositorys, deiner Organisation oder deines Unternehmens fest. Dies ist die Entität, der die Runner angehören.

   • Mit diesem Beispielbefehl wird die neueste Version des Helm-Charts installiert. Um eine bestimmte Version zu installieren, kannst du das --version-Argument zusammen mit der Version des Charts übergeben, das du installieren möchtest. Die Liste der Releases findest du im GitHub Container Registry.

     Hinweis:

     • Als bewährte Sicherheitsmethode solltest du deine Runnerpods in einem anderen Namespace erstellen als dem, der deine Operatorpods enthält.
     • Erstelle als bewährte Sicherheitsmethode Kubernetes-Geheimnisse, und übergib die Geheimnisverweise. Die Übergabe deiner Geheimnisse im Nur-Text-Format über die CLI kann ein Sicherheitsrisiko darstellen. Weitere Informationen findest du unter Bereitstellen von Runner-Skalierungsgruppen mit Actions Runner Controller.
     Bash

     INSTALLATION_NAME="arc-runner-set"
     NAMESPACE="arc-runners"
     GITHUB_CONFIG_URL="https://github.com/<your_enterprise/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 in der ARC-Dokumentation.

2. Führe in deinem Terminal den folgenden Befehl 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-runners     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0
   

3. Um den Manager-Pod zu überprüfen, führe den folgenden Befehl in deinem Terminal aus.

   Bash

   kubectl get pods -n arc-systems
   

   Wenn alles erfolgreich installiert wurde, wird der Status der Pods als Wird ausgeführt angezeigt.

   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 von Runner-Skalierungsgruppen

Erstelle nun einen einfachen Testworkflow, der die Runner der Runner-Skalierungsgruppe verwendet, und führe Ihn aus.

1. Erstelle in einem Repository einen Workflow ähnlich dem folgenden Beispiel. Der runs-on-Wert sollte mit dem Helm-Installationsnamen übereinstimmen, den du beim Installieren der Runner für die automatische Skalierung verwendet hast.

   Weitere Informationen zum Hinzufügen eines Workflows zu einem Repository findest du unter Schnellstart für GitHub Actions.

   YAML

   name: Actions Runner Controller Demo
   on:
     workflow_dispatch:
   
   jobs:
     Explore-GitHub-Actions:
       # You need to use the INSTALLATION_NAME from the previous step
       runs-on: arc-runner-set
       steps:
       - run: echo "🎉 This job uses runner scale set runners!"
   

2. Nachdem du den Workflow deinem Repository hinzugefügt hast, löse den Workflow manuell aus. Weitere Informationen findest du unter Manuelles Ausführen eines Workflows.

3. Führe den folgenden Befehl über deinem Terminal aus, um die während der Ausführung des Workflows erstellten Runnerpods anzuzeigen.

   Bash

   kubectl get pods -n arc-runners
   

   Eine erfolgreiche Ausgabe ähnelt der folgenden.

   NAMESPACE     NAME                                                  READY   STATUS    RESTARTS      AGE
   arc-runners   arc-runner-set-rmrgw-runner-p9p5n                     1/1     Running   0             21s
   

Nächste Schritte

Actions Runner Controller kann dir helfen, deine GitHub Actions-Runner effizient zu verwalten. Willst du loslegen? Hier findest du einige hilfreiche Ressourcen für deine nächsten Schritte mit ARC:

• Detaillierte Informationen zur Authentifizierung findest du unter Authentifizieren bei der GitHub-API.
• Hilfe zur Verwendung von ARC-Runnern in deinen Workflows findest du unter Verwenden von Actions Runner Controller-Runnern in einem Workflow.
• Informationen zur Bereitstellung findest du unter Bereitstellen von Runner-Skalierungsgruppen mit Actions Runner Controller.

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.