Skip to main content

À propos d’Actions Runner Controller

Vous pouvez héberger vos propres exécuteurs et personnaliser l’environnement utilisé pour exécuter les travaux dans vos workflows GitHub Actions.

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.

Remarque : Pour voir le diagramme suivant en plus grand, consultez la documentation sur le mode de mise à l’échelle automatique de groupes d’exécuteurs identiques dans le dépôt Actions Runner Controller.

Diagramme montrant le 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 lors de l’installation du graphique Helm ;
  • un suffixe d’identification de ressource, qui est une chaîne qui identifie le type de ressource. Cette valeur n'est pas configurable.

Remarque : différentes versions de Kubernetes ont des limites de longueur différentes pour les noms de ressources. La limite de longueur du nom de la ressource est calculée en ajoutant la longueur du nom d’installation et la longueur du suffixe d’identification de la ressource. Si le nom de la ressource est supérieur à la longueur réservée, une erreur s’affiche.

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

ModèleType de ressourceNomLongueur réservéeDescriptionNotes
deployment.yamlDéploiementINSTALLATION_NAME-gha-rs-controller18Ressource exécutant le controller-managerLes pods créés par cette ressource comportent les suffixes ReplicaSet et Pod.
serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-controller18Cet élément est créé si la valeur de serviceAccount.create dans values.yaml est définie sur true.Le nom peut être personnalisé dans values.yaml
manager_cluster_role.yamlClusterRoleINSTALLATION_NAME-gha-rs-controller18ClusterRole pour le gestionnaire de contrôleursCet élément est créé si la valeur de flags.watchSingleNamespace est vide.
manager_cluster_role_binding.yamlClusterRoleBindingINSTALLATION_NAME-gha-rs-controller18ClusterRoleBinding pour le gestionnaire de contrôleursCet élément est créé si la valeur de flags.watchSingleNamespace est vide.
manager_single_namespace_controller_role.yamlRôleINSTALLATION_NAME-gha-rs-controller-single-namespace35Rôle pour le gestionnaire de contrôleursCet élément est créé si la valeur de flags.watchSingleNamespace est définie.
manager_single_namespace_controller_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace35RoleBinding pour le gestionnaire de contrôleursCet élément est créé si la valeur de flags.watchSingleNamespace est définie.
manager_single_namespace_watch_role.yamlRôleINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41Rôle pour le gestionnaire de contrôleurs pour l’espace de noms configuréCet élément est créé si la valeur de flags.watchSingleNamespace est définie.
manager_single_namespace_watch_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41RoleBinding pour le gestionnaire de contrôleurs pour l’espace de noms configuréCet élément est créé si la valeur de flags.watchSingleNamespace est définie.
manager_listener_role.yamlRôleINSTALLATION_NAME-gha-rs-controller-listener26Rôle pour l'écouteurCet élément est systématiquement créé.
manager_listener_role_binding.yaml RoleBindingINSTALLATION_NAME-gha-rs-controller-listener26RoleBinding pour l’écouteurCet élément est systématiquement créé et lie le rôle d’écouteur au compte de service, qui est créé par serviceaccount.yaml ou configuré avec values.yaml.

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

ModèleType de ressourceNomLongueur réservéeDescriptionNotes
autoscalingrunnerset.yamlAutoscalingRunnerSetINSTALLATION_NAME0Ressource de niveau supérieur fonctionnant avec des groupes identiquesLa longueur maximale du nom est de 45 caractères.
no_permission_service_account.yamlServiceAccountINSTALLATION_NAME-gha-rs-no-permission21Compte de service monté sur le conteneur d’exécuteurCet élément est créé si le mode conteneur n’est pas « kubernetes » et que template.spec.serviceAccountName n’est pas spécifié.
githubsecret.yamlSecretINSTALLATION_NAME-gha-rs-github-secret20Secret contenant les valeurs nécessaires pour s’authentifier auprès de l’API GitHubCet élément est créée si githubConfigSecret est un objet. Si une chaîne est fournie, ce secret ne sera pas créé.
manager_role.yamlRôleINSTALLATION_NAME-gha-rs-manager15Rôle fourni au gestionnaire pour qu’il puisse rapprocher les ressources de l’espace de noms du jeu d’exécuteurs de mise à l’échelle automatiqueCet élément est systématiquement créé.
manager_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-manager15Liaison manager_role au compte de service manager.Cet élément est systématiquement créé.
kube_mode_role.yamlRôleINSTALLATION_NAME-gha-rs-kube-mode17Rôle fournissant les autorisations nécessaires pour le hookCet élément est créé lorsque le mode conteneur est défini sur « kubernetes » et que template.spec.serviceAccount n’est pas fourni.
kube_mode_serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-kube-mode17Compte de service lié au pod d’exécuteur.Cet élément est créé lorsque le mode conteneur est défini sur « kubernetes » et que template.spec.serviceAccount n’est pas fourni.

À 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.

É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.

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

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

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 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. 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 :

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 :

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.

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.