Actions Runner Controller

À propos de Actions Runner Controller

Actions Runner Controller (ARC) est un opérateur Kubernetes qui orchestre et met à l’échelle des exécuteurs auto-hébergés pour GitHub Actions. Pour plus d'informations, consultez Modèle d’opérateur dans la documentation de Kubernetes.

Avec ARC, vous pouvez créer des groupes identiques d’exécuteurs qui sont automatiquement mis à l’échelle en fonction du nombre de flux de travail en cours d’exécution dans votre référentiel, organisation ou entreprise. Étant donné que les exécuteurs contrôlés peuvent être éphémères et basés sur des conteneurs, les nouvelles instances de l’exécuteur peuvent effectuer un scale-up ou un scale-down rapide et propre. Pour plus d’informations sur la mise à l’échelle automatique, consultez Référence des exécuteurs auto-hébergés.

Le diagramme suivant illustre l’architecture du mode de mise à l’échelle automatique des exécuteurs d'ARC.

1. Actions Runner Controller est installé à l’aide des charts fournis par Helm, et le pod du gestionnaire de contrôleur est déployé dans le namespace spécifié. Une nouvelle ressource AutoScalingRunnerSet est déployée via les charts Helm fournis ou un fichier manifeste personnalisé. Le contrôleur AutoScalingRunnerSet appelle les API de GitHub pour récupérer l’ID de groupe d’exécuteurs auquel appartient le groupe d’exécuteurs identiques.
2. Le contrôleur AutoScalingRunnerSet appelle les API une fois de plus pour récupérer ou créer un groupe d’exécuteurs identiques dans le service GitHub Actions avant de créer la ressource Écouteur de groupe d’exécuteurs identiques.
3. Un pod Écouteur de groupe d’exécuteurs identiques est déployé par le contrôleur AutoScalingListener. Dans ce pod, l’application de l’écouteur se connecte au service GitHub Actions pour s’authentifier et établir une longue connexion d’interrogation HTTPS. L’écouteur reste inactif tant qu’il n’a pas reçu un message du service GitHub Actions.
4. Lorsqu'un flux de travail est déclenché à partir d'un référentiel, le service GitHub Actions distribue les exécutions des tâches individuelles aux exécuteurs ou ensembles d'exécuteurs dont la clé correspond au nom de l'ensemble d'exécuteurs ou aux étiquettes des exécuteurs auto-hébergés.
5. Lorsque l’Écouteur de groupe d’exécuteurs identiques reçoit le message , il vérifie s’il peut effectuer un scale-up jusqu’au nombre souhaité. S’il le peut, l’Écouteur de groupe d’exécuteurs identiques accuse réception du message.
6. L’Écouteur de groupe d’exécuteurs identiques utilise un compte de service et un rôle lié à ce compte pour effectuer un appel HTTPS via les API Kubernetes afin de corriger la ressource Groupe d’exécuteurs éphémère avec le nombre de réplicas souhaités.
7. Le RunnerSet éphémère tente de créer de nouveaux runners et le contrôleur EphemeralRunner demande un jeton de configuration Just-in-Time (JIT) pour inscrire ces runners. Le contrôleur tente de créer des pods d’exécuteur. Si l’état du pod est , le contrôleur retente jusqu’à 5 fois. Passé 24 heures, le service GitHub Actions annule l’affectation du travail si aucun exécuteur ne l’accepte.
8. Une fois le pod d’exécuteur créé, l’application d’exécuteur dans le pod utilise le jeton de configuration JIT pour s’inscrire auprès du service GitHub Actions. Elle établit ensuite une autre longue connexion d’interrogation HTTPS pour recevoir les détails du travail qu’elle doit exécuter.
9. Le service GitHub Actions accuse réception de l’inscription de l’exécuteur et distribue les détails de l’exécution du travail.
10. Tout au long de l’exécution du travail, l’exécuteur communique en continu les journaux et l’état de l’exécution du travail au service GitHub Actions.
11. Lorsque l’exécuteur termine correctement son travail, le contrôleur EphemeralRunner vérifie avec le service GitHub Actions pour voir si l’exécuteur peut être supprimé. S’il le peut, le Groupe d’exécuteurs éphémère supprime l’exécuteur.

Composants de Actions Runner Controller

ARC se compose d’un ensemble de ressources, dont certaines sont créées spécifiquement pour ARC. Un déploiement ARC applique ces ressources à un cluster Kubernetes. Ensuite, il crée un ensemble de pods qui contiennent les conteneurs de vos exécuteurs auto-hébergés. Avec ARC, GitHub peut traiter ces conteneurs de runners comme des runners auto-hébergés et leur allouer des tâches en fonction des besoins.

Chaque ressource déployée par ARC reçoit un nom composé des éléments suivants :

• Un nom d'installation, que vous spécifiez lorsque vous installez le chart Helm.
• Suffixe d'identification de la ressource, qui est une chaîne de caractères identifiant le type de ressource. Cette valeur n'est pas configurable.

Ressources déployées par

Ressources déployées par

À propos des ressources personnalisées

ARC se compose de plusieurs définitions de ressources personnalisées (CRD). Pour plus d’informations sur les ressources personnalisées, consultez Ressources personnalisées dans la documentation de Kubernetes. Vous trouverez la liste des définitions de ressources personnalisées utilisées pour ARC dans les définitions de schéma d’API suivantes.

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

Étant donné que les ressources personnalisées sont des extensions de l’API Kubernetes, elles ne sont pas disponibles dans une installation Kubernetes par défaut. Vous devez installer ces ressources personnalisées pour utiliser ARC. Pour plus d’informations sur l’installation de ces ressources personnalisées, consultez « AUTOTITLE ».

Une fois les ressources personnalisées installées, vous pouvez déployer ARC dans votre cluster Kubernetes. Pour plus d’informations sur le déploiement d’ARC, consultez « AUTOTITLE ».

À propos de l’image conteneur de l’exécuteur

GitHub maintient une image de conteneur d’exécution minimale. Une nouvelle image sera publiée avec chaque version des fichiers binaires de l’exécuteur. L’image la plus récente aura la version des fichiers binaires de l’exécuteur et en tant que balises.

Cette image contient la quantité minimale de packages nécessaires pour le runtime du conteneur et les fichiers binaires de l’exécuteur. Pour installer des logiciels supplémentaires, vous pouvez créer votre propre image de l’exécuteur. Vous pouvez utiliser l’image de l’exécuteur d’ARC comme base ou utilisez les actions d’installation correspondantes. Par exemple, actions/setup-java pour Java ou actions/setup-node pour Node.

Vous pouvez trouver la définition de l'image de l'exécuteur ARC dans ce Dockerfile. Pour afficher l’image de base actuelle, vérifiez la ligne dans le Dockerfile de l'image de l'exécuteur, puis cherchez cette balise dans le référentiel .

Par exemple, si la ligne dans le Dockerfile de l’image de l’exécuteur est , vous pouvez trouver l’image de base dans .

Création de votre propre image de l’exécuteur

Vous pouvez créer votre propre image de runner qui répond à vos besoins. Votre image de l’exécuteur doit remplir les conditions suivantes.

• Utilisez une image de base qui peut exécuter l’application de l’exécuteur auto-hébergé. Consultez AUTOTITLE.

• Le fichier binaire de l’exécuteur doit être placé sous et lancé à l’aide de .

• Si vous utilisez le mode Kubernetes, les crochets du conteneur de l’exécuteur doivent être placés sous .

Vous pouvez utiliser l'exemple de Dockerfile suivant pour commencer à créer votre propre image de 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

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

Les logiciels installés dans l’image de l’environnement d'exécution ARC

L’image du runner ARC est fournie avec les logiciels suivants :

• Fichiers binaires de l’exécuteur
• Crochets du conteneur de l’exécuteur
• Docker (requis pour le mode Docker dans Docker)

Pour plus d’informations, consultez Fichier Docker de l’image de l’exécuteur d’ARC dans le référentiel Actions.

Ressources et publications

ARC est publié sous la forme de deux graphiques Helm et d’une image conteneur. Les graphiques Helm sont publiés uniquement en tant que packages OCI (Open Container Initiative). ARC ne fournit pas de tarballs ou de référentiels Helm via GitHub Pages.

Les dernières versions des graphiques Helm d’ARC et de l’image conteneur sont disponibles sur GitHub Packages :

• Graphique Helm
• Graphique Helm
• Image conteneur

L’image de runner prise en charge est publiée sous la forme d’une image conteneur distincte, disponible sur GitHub Packages.

Mentions légales

Certaines parties ont été adaptées à partir de https://github.com/actions/actions-runner-controller/ sous la licence Apache-2.0 :

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.

Étapes suivantes

Lorsque vous êtes prêt à utiliser ARC pour exécuter des flux de travail, consultez AUTOTITLE.

Vous ne pouvez pas utiliser d’étiquettes supplémentaires pour cibler les exécuteurs créés par ARC. Vous pouvez uniquement utiliser le nom d’installation du groupe identique d’exécuteurs que vous avez spécifié pendant l’installation ou en définissant la valeur du champ runnerScaleSetName dans votre fichier values.yaml. Celles-ci sont utilisées comme « étiquette unique » à utiliser comme cible runs-on. Consultez AUTOTITLE.

Vous pouvez mettre à l’échelle les exécuteurs de manière statique ou dynamique en fonction de vos besoins. Consultez AUTOTITLE.