Skip to main content

Diese Version von GitHub Enterprise Server wurde eingestellt am 2024-07-09. Es wird keine Patch-Freigabe vorgenommen, auch nicht für kritische Sicherheitsprobleme. Für bessere Leistung, verbesserte Sicherheit und neue Features aktualisiere auf die neueste Version von GitHub Enterprise Server. Wende dich an den GitHub Enterprise-Support, um Hilfe zum Upgrade zu erhalten.

Informationen zum Actions Runner Controller

Sie können deine eigenen Runner hosten und die Umgebung anpassen, die für die Ausführung von Aufträgen in deinen GitHub Actions-Workflows verwendet wird.

Rechtliche Hinweise

Informationen zum Actions Runner Controller

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.

Das folgende Diagramm veranschaulicht die Architektur des Runnerskalierungsmodus von ARC für die automatische Skalierung.

Hinweis: Informationen zum Anzeigen des folgenden Diagramms in einer größeren Größe finden Sie in der Dokumentation zum Modus für die automatische Skalierung von Runnerskalierungsgruppen im Actions Runner Controller-Repository.

Diagramm, das den ScaleSet-Modus für die automatische Skalierung von Runnern von ARC zeigt.

  1. Actions Runner Controller wird mithilfe der angegebenen Helm-Diagramme installiert, und der Controller-Manager-Pod wird im angegebenen Namespace bereitgestellt. Eine neue AutoScalingRunnerSet-Ressource wird über die bereitgestellten Helm-Diagramme oder eine angepasste Manifestdatei bereitgestellt. Der AutoScalingRunnerSet-Controller ruft die GitHub-APIs auf, um die Runnergruppen-ID abzurufen, zu der die Runnerskalierungsgruppe gehört.
  2. Der AutoScalingRunnerSet-Controller ruft die APIs einmal mehr auf, um entweder eine Runnerskalierungsgruppe im GitHub Actions-Dienst abzurufen oder zu erstellen, bevor die Runner ScaleSet-Listenerressource erstellt wird.
  3. Ein Runner ScaleSet-Listenerpod wird vom AutoScalingListener-Controller bereitgestellt. In diesem Pod stellt die Listeneranwendung eine Verbindung mit dem GitHub Actions-Dienst her, um sich zu authentifizieren und eine lange HTTPS-Abfrageverbindung herzustellen. Der Listener bleibt im Leerlauf, bis er eine Job Available-Nachricht vom GitHub Actions-Dienst empfängt.
  4. Wenn eine Workflowausführung aus einem Repository ausgelöst wird, sendet der Dienst GitHub Actions einzelne Auftragsausführungen an die Runner oder Runnerskalierungsgruppen, wobei der runs-on-Schlüssel mit dem Namen der Runnerskalierungsgruppe oder Bezeichnungen von selbstgehosteten Runnern übereinstimmt.
  5. Wenn der Runner ScaleSet-Listener die Nachricht Job Available empfängt, überprüft er, ob auf die gewünschte Anzahl hochskaliert werden kann. Wenn dies möglich ist, bestätigt der Runner ScaleSet-Listener die Nachricht.
  6. Der Runner ScaleSet-Listener verwendet ein Dienstkonto und eine an dieses Konto gebundene Rolle, um einen HTTPS-Aufruf über die Kubernetes-APIs auszuführen, um die kurzlebige RunnerSet-Ressource mit der Anzahl der gewünschten Replikate zu patchen.
  7. Die Ephemeral RunnerSet-Ressource versucht, neue Runner zu erstellen, und der EphemeralRunner-Controller fordert ein JIT-Konfigurationstoken (Just-in-Time) an, um diese Runner zu registrieren. Der Controller versucht, Runnerpods zu erstellen. Wenn der Status des Pods failed ist, führt der Controller bis zu fünf Mal einen Wiederholungsversuch durch. Nach 24 Stunden hebt der Dienst GitHub Actions die Zuweisung des Auftrags auf, wenn kein Runner ihn akzeptiert.
  8. Nachdem der Runnerpod erstellt wurde, verwendet die Runneranwendung im Pod das JIT-Konfigurationstoken, um sich beim Dienst GitHub Actions zu registrieren. Anschließend wird eine weitere lange HTTPS-Abrufverbindung hergestellt, um die Auftragsdetails abzurufen, die für die Ausführung erforderlich sind.
  9. Der Dienst GitHub Actions bestätigt die Runnerregistrierung und sendet die Auftragsausführungsdetails.
  10. Während der gesamten Ausführung des Auftrags kommuniziert der Runner kontinuierlich die Protokolle und den Status Auftragsausführung zurück an den GitHub Actions-Dienst.
  11. Wenn der Runner seinen Auftrag erfolgreich abgeschlossen hat, überprüft der EphemeralRunner-Controller im GitHub Actions-Dienst, ob Runner gelöscht werden können. Wenn dies möglich ist, löscht das kurzlebige RunnerSet den Runner.

Actions Runner Controller-Komponenten

ARC besteht aus einer Reihe von Ressourcen, von denen einige speziell für ARC erstellt werden. Eine ARC-Bereitstellung wendet diese Ressourcen auf einen Kubernetes-Cluster an. Nach der Anwendung wird eine Gruppe von Pods erstellt, die die Container deiner selbstgehosteten Runner enthalten. Mit dem ARC kann GitHub diese Runnercontainer als selbstgehostete Runner behandeln und ihnen nach Bedarf Aufträge zuordnen.

Jede Ressource, die von ARC bereitgestellt wird, erhält einen Namen bestehend aus:

  • einem Installationsnamen, bei dem es sich um den Installationsnamen handelt, den Sie beim Installieren des Helm-Diagramms angeben.
  • einem Ressourcenidentifikationssuffix, bei dem es sich um eine Zeichenfolge handelt, die den Ressourcentyp identifiziert. Dieser Wert ist nicht konfigurierbar.

Hinweis: Unterschiedliche Versionen von Kubernetes weisen unterschiedliche Längenbeschränkungen für Namen von Ressourcen auf. Der Längengrenzwert für den Ressourcennamen wird berechnet, indem die Länge des Installationsnamens und die Länge des Ressourcenidentifikationssuffixs addiert werden. Wenn der Ressourcenname länger als die reservierte Länge ist, wird ein Fehler angezeigt.

Von gha-runner-scale-set-controller bereitgestellte Ressourcen

VorlageRessourcentypNameReservierte LängeBeschreibungHinweise
deployment.yamlBereitstellungINSTALLATION_NAME-gha-rs-controller18Die Ressource, auf der Controller-Manager ausgeführt wirdDie von dieser Ressource erstellten Pods weisen das ReplicaSet-Suffix und das Pod-Suffix auf.
serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-controller18Dies wird erstellt, wenn serviceAccount.create in values.yaml auf "true" festgelegt wird.Der Name kann in values.yaml angepasst werden.
manager_cluster_role.yamlClusterRoleINSTALLATION_NAME-gha-rs-controller18ClusterRole für den Controller-ManagerDies wird erstellt, wenn der Wert flags.watchSingleNamespace leer ist.
manager_cluster_role_binding.yamlClusterRoleBindingINSTALLATION_NAME-gha-rs-controller18ClusterRoleBinding für den Controller-ManagerDies wird erstellt, wenn der Wert flags.watchSingleNamespace leer ist.
manager_single_namespace_controller_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-single-namespace35Rolle für den Controller-ManagerDies wird erstellt, wenn der Wert flags.watchSingleNamespace festgelegt wird.
manager_single_namespace_controller_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace35RoleBinding für den Controller-ManagerDies wird erstellt, wenn der Wert flags.watchSingleNamespace festgelegt wird.
manager_single_namespace_watch_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41Rolle für den Controller-Manager für den konfigurierten NamespaceDies wird erstellt, wenn der Wert flags.watchSingleNamespace festgelegt wird.
manager_single_namespace_watch_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41RoleBinding für den Controller-Manager für den konfigurierten NamespaceDies wird erstellt, wenn der Wert flags.watchSingleNamespace festgelegt wird.
manager_listener_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-listener26Rolle für den Listener.Dies wird immer erstellt.
manager_listener_role_binding.yaml RoleBindingINSTALLATION_NAME-gha-rs-controller-listener26RoleBinding für den ListenerDies wird immer erstellt und bindet die Listenerrolle an das Dienstkonto, das entweder von serviceaccount.yaml erstellt oder mit values.yaml konfiguriert wird.

Von gha-runner-scale-set bereitgestellte Ressourcen

VorlageRessourcentypNameReservierte LängeBeschreibungHinweise
autoscalingrunnerset.yamlAutocalingRunnerSetINSTALLATION_NAME0Ressource auf oberster Ebene, die mit Skalierungssätzen arbeitetDie Länge ist auf 45 Zeichen beschränkt.
no_permission_service_account.yamlServiceAccountINSTALLATION_NAME-gha-rs-no-permission21Dienstkonto, das in den Runner-Container eingebunden istDies wird erstellt, wenn der Containermodus nicht "kubernetes" ist und template.spec.serviceAccountName nicht angegeben wird.
githubsecret.yamlGeheimnisINSTALLATION_NAME-gha-rs-github-secret20Geheimer Schlüssel, der Werte enthält, die für die Authentifizierung bei der GitHub-API erforderlich sind.Dies wird erstellt, wenn es sich bei githubConfigSecret um ein Objekt handelt. Wenn eine Zeichenfolge angegeben wird, wird dieser geheime Schlüssel nicht erstellt.
manager_role.yamlRoleINSTALLATION_NAME-gha-rs-manager15Rolle, die dem Manager bereitgestellt wird, um Ressourcen im Namespace des automatischen Runnersatzes in Einklang zu bringenDies wird immer erstellt.
manager_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-manager15Verknüpfung von manager_role mit dem Verwaltungsdienstkonto.Dies wird immer erstellt.
kube_mode_role.yamlRoleINSTALLATION_NAME-gha-rs-kube-mode17Rolle, die erforderliche Berechtigungen für den Hook bereitstellt.Dies wird erstellt, wenn der Containermodus auf "kubernetes" festgelegt ist und template.spec.serviceAccount nicht bereitgestellt wird.
kube_mode_serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-kube-mode17Dienstkonto, das an die Runner-Pod gebunden ist.Dies wird erstellt, wenn der Containermodus auf "kubernetes" festgelegt ist und template.spec.serviceAccount nicht bereitgestellt wird.

Informationen zu benutzerdefinierten Ressourcen

Der ARC besteht aus mehreren Definitionen benutzerdefinierter Ressourcen (Custom Resource Definitions, CRDs). Weitere Informationen zu benutzerdefinierten Ressourcen finden Sie unter Benutzerdefinierte Ressourcen in der Kubernetes-Dokumentation. Die Liste der Definitionen benutzerdefinierter Ressourcen, die für ARC verwendet werden, finden Sie in den folgenden API-Schemadefinitionen.

Da benutzerdefinierte Ressourcen Erweiterungen der Kubernetes-API sind, sind sie in einer Kubernetes-Standardinstallation nicht verfügbar. Du musst diese benutzerdefinierten Ressourcen installieren, um ARC verwenden zu können. Weitere Informationen zur Installation benutzerdefinierter Ressourcen finden Sie unter Schnellstart für Actions Runner Controller.

Nachdem die benutzerdefinierten Ressourcen installiert wurden, können Sie den ARC in deinem Kubernetes-Cluster bereitstellen. Weitere Informationen zur ARC-Bereitstellung finden Sie unter Bereitstellen von Runner-Skalierungsgruppen mit Actions Runner Controller.

Informationen zum Runnercontainerimage

GitHub verwaltet ein minimales Runnercontainerimage. Mit jedem Runnerbinärdateien-Release wird ein neues Image veröffentlicht. Das neueste Image enthält die Version der Runnerbinärdateien und latest als Tags.

Dieses Image enthält die geringste Menge an Paketen, die für die Containerruntime und die Runnerbinärdateien erforderlich sind. Um zusätzliche Software zu installieren, können Sie dein eigenes Runnerimage erstellen. Sie können das Runnerimage von ARC als Basis oder die entsprechenden Setupaktionen verwenden. Beispiel: actions/setup-java für Java oder actions/setup-node für Node.

Die Definition des ARC-Runnerimages finden Sie in dieser Dockerfile-Datei und die Definition des Basisimages in dieser Dockerfile-Datei.

Erstellen eines eigenen Runnerimages

Sie können ein eigenes Runnerimage erstellen, das deinen Anforderungen entspricht. Dein Runnerimage muss die folgenden Bedingungen erfüllen.

Sie können das folgende Dockerfile-Beispiel verwenden, um mit der Erstellung deines eigenen Runnerimages zu beginnen.

Dockerfile
FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build

# Replace value with the latest runner release version
# source: https://github.com/actions/runner/releases
# ex: 2.303.0
ARG RUNNER_VERSION=""
ARG RUNNER_ARCH="x64"
# Replace value with the latest runner-container-hooks release version
# source: https://github.com/actions/runner-container-hooks/releases
# ex: 0.3.1
ARG RUNNER_CONTAINER_HOOKS_VERSION=""

ENV DEBIAN_FRONTEND=noninteractive
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1

RUN apt update -y && apt install curl unzip -y

RUN adduser --disabled-password --gecos "" --uid 1001 runner \
    && groupadd docker --gid 123 \
    && usermod -aG sudo runner \
    && usermod -aG docker runner \
    && echo "%sudo   ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \
    && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers

WORKDIR /home/runner

RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \
    && tar xzf ./runner.tar.gz \
    && rm runner.tar.gz

RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \
    && unzip ./runner-container-hooks.zip -d ./k8s \
    && rm runner-container-hooks.zip

USER runner

Ausführen von Workflows

Nach Abschluss der Installation und Konfiguration können Sie mit dem ARC Workflowausführungen ausführen. Ein Workflow kann im selben Repository erstellt werden, das auf einen von ARC erstellten selbstgehosteten Runner ausgerichtet werden kann. Weitere Informationen zum Ausrichten von Workflows zur Ausführung auf selbstgehosteten Runnern finden Sie unter Verwenden von selbstgehosteten Runnern in einem Workflow.

Verwenden von ARC-Runnern in einem Workflow

Du kannst keine zusätzlichen Bezeichnungen für Ziel-Runner verwenden, die von ARC erstellt wurden. Du kannst nur den Installationsnamen der Runnerskalierungsgruppe verwenden, die du während der Installation angegeben hast, oder durch Definieren des Werts des runnerScaleSetName-Felds in deiner values.yaml-Datei. Diese werden als "einzelne Bezeichnung" verwendet, um sie als runs-on-Ziel zu verwenden. Weitere Informationen finden Sie unter Verwenden von Actions Runner Controller-Runnern in einem Workflow.

Skalieren von Runnern

Sie können Runner je nach deinen Anforderungen statisch oder dynamisch skalieren. Weitere Informationen finden Sie unter Bereitstellen von Runner-Skalierungsgruppen mit Actions Runner Controller.

Im ARC-Runnerimage installierte Software

Das ARC-Runnerimage ist mit der folgenden Software gebündelt:

Weitere Informationen finden Sie unter Dockerfile des ARC-Runnerimages im Actions-Repository.

Ressourcen und Versionen

ARC wird als zwei Helm-Charts und ein Containerimage veröffentlicht. Die Helm-Charts werden nur als OCI-Pakete (Open Container Initiative) veröffentlicht. ARC stellt keine Tarballs oder Helm-Repositorys über GitHub Pages bereit.

Die neuesten Versionen von ARC Helm-Charts und Containerimages finden Sie unter GitHub Packages:

Das unterstützte Runner-Image wird als separates Containerimage freigegeben, das Sie unter actions-runner in GitHub Packages. finden können.

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.