Informationen zum Actions Runner Controller

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.

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.

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

Von gha-runner-scale-set bereitgestellte Ressourcen

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.

• actions.github.com/v1alpha1
• actions.summerwind.net/v1alpha1

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.

• Verwende ein Basisimage, das die selbstgehostete Runneranwendung ausführen kann. Weitere Informationen finden Sie unter Informationen zu selbstgehosteten Runnern.
• Die Runner-Binärdatei muss unter /home/runner/ platziert und mit /home/runner/run.shgestartet werden.
• Wenn Sie den Kubernetes-Modus verwenden, müssen die Runnercontainer-Hooks unter /home/runner/k8s platziert werden.

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

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

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:

• Runner-Binärdateien
• Runnercontainer-Hooks
• Docker (erforderlich für Docker-in-Docker-Modus)

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:

• gha-runner-scale-set-controllerHelm-Chart
• gha-runner-scale-setHelm-Chart
• gha-runner-scale-set-controllerContainerimage

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

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.