À propos d’Actions Runner Controller

Mentions légales

À 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 « Mise à l’échelle automatique avec des exécuteurs auto-hébergés ».

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

1. Actions Runner Controller est installé à l’aide des charts Helm fournis, et le pod de gestionnaire de contrôleur est déployé dans l’espace de noms 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 Job Available du service GitHub Actions.
4. Lorsqu’une exécution de workflow est déclenchée à partir d’un dépôt, le service GitHub Actions distribue des exécutions de travaux individuelles aux exécuteurs ou aux groupes d’exécuteurs identiques où la clé runs-on correspond au nom du groupe d’exécuteurs identiques ou aux étiquettes des exécuteurs auto-hébergés.
5. Lorsque l’Écouteur de groupe d’exécuteurs identiques reçoit le message Job Available, 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 Groupe d’exécuteurs éphémère tente de créer de nouveaux exécuteurs et le contrôleur EphemeralRunner demande un jeton de configuration juste-à-temps (JIT) pour inscrire ces exécuteurs. Le contrôleur tente de créer des pods d’exécuteur. Si l’état du pod est failed, 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 d’exécuteurs comme des exécuteurs auto-hébergés et leur allouer des travaux en fonction des besoins.

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

• Un nom d'installation, qui est le nom d'installation que vous spécifiez lorsque vous installez la carte 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 gha-runner-scale-set-controller

Ressources déployées par gha-runner-scale-set

À 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 « Démarrage rapide avec Actions Runner Controller ».

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 « Déploiement de groupes identiques d’exécuteurs avec Actions Runner Controller ».

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

GitHub maintient une image conteneur d’exécuteur 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 latest 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. Pour instance, actions/setup-java pour Java ou actions/setup-node pour Node.

Vous trouverez la définition de l’image de l’exécuteur d’ARC dans ce fichier Docker et la définition de l’image de base dans ce fichier Docker.

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

Vous pouvez créer votre propre image de l’exécuteur 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é. Pour plus d’informations, consultez « À propos des exécuteurs auto-hébergés ».
• Le fichier binaire de l’exécuteur doit être placé sous /home/runner/ et lancé à l’aide de /home/runner/run.sh.
• Si vous utilisez le mode Kubernetes, les crochets du conteneur de l’exécuteur doivent être placés sous /home/runner/k8s.

Vous pouvez utiliser l’exemple de fichier Docker suivant pour commencer à créer votre propre image de l’exécuteur.

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

Exécution de flux de travail

Une fois l’installation et la configuration terminées, vous pouvez utiliser ARC pour exécuter des exécutions de flux de travail. Un flux de travail peut être créé dans le même référentiel que celui qui peut cibler un exécuteur auto-hébergé créé par ARC. Pour plus d’informations sur le ciblage des flux de travail à exécuter sur des exécuteurs auto-hébergés, consultez « Utilisation d’exécuteurs auto-hébergés dans un workflow ».

Utilisation d’exécuteurs ARC dans un flux de travail

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. Pour plus d’informations, consultez « Utilisation d’exécuteurs Actions Runner Controller dans un flux de travail ».

Mise à l’échelle des exécuteurs

Vous pouvez mettre à l’échelle les exécuteurs de manière statique ou dynamique en fonction de vos besoins. Pour plus d’informations, consultez « Déploiement de groupes identiques d’exécuteurs avec Actions Runner Controller ».

Logiciels installés dans l’image de l’exécuteur ARC

L’image de l’exécuteur 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 versions

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 référentiels tarballs ou Helm via GitHub Pages.

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

• gha-runner-scale-set-controllerGraphique Helm
• gha-runner-scale-setGraphique Helm
• gha-runner-scale-set-controllerImage conteneur

L’image d’exécuteur prise en charge est publiée sous la forme d’une image conteneur distincte, disponible sur actions-runner 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.