À propos des groupes identiques d’exécuteurs
Les groupes identiques d’exécuteurs sont un groupe d’exécuteurs homogènes qui peuvent être affectés à des travaux de GitHub Actions. Le nombre d’exécuteurs actifs appartenant à un groupe identique d’exécuteurs peut être contrôlé par des solutions d’exécuteurs qui se mettent à l’échelle automatiquement comme Actions Runner Controller (ARC).
Vous pouvez utiliser des groupes d’exécuteurs pour gérer les groupes identiques d’exécuteurs. Comme pour les exécuteurs auto-hébergés, vous pouvez ajouter des groupes identiques d’exécuteurs à des groupes d’exécuteurs existants. Toutefois, les groupes identiques d’exécuteurs ne peuvent appartenir qu’à un seul groupe d’exécuteurs à la fois et ne peuvent se voir attribuer qu’une seule étiquette. Pour plus d’informations sur les groupes d’exécuteurs, consultez « Gestion de l’accès aux exécuteurs auto-hébergés à l’aide de groupes ».
Pour affecter des travaux à un groupe identique d’exécuteurs, vous devez configurer votre workflow de manière à ce qu’il référence le nom du groupe identique d’exécuteurs. Pour plus d’informations, consultez « Utilisation d’exécuteurs Actions Runner Controller dans un flux de travail ».
Déploiement d’un groupe identique d’exécuteurs
Pour déployer un groupe identique d’exécuteurs, vous devez avoir ARC prêt à s’exécuter. Pour plus d’informations, consultez « Démarrage rapide avec Actions Runner Controller ».
Vous pouvez déployer des groupes identiques d’exécuteurs avec les charts Helm d’ARC ou en déployant les manifestes nécessaires. L’utilisation des charts Helm d’ARC est la méthode recommandée, en particulier si vous n’avez pas d’expérience préalable avec ARC.
Remarques :
- Comme meilleure pratique de sécurité, créez les pods de votre exécuteur dans un espace de noms différent de l’espace de noms contenant les pods de votre opérateur.
- Comme meilleure pratique de sécurité, créez des secrets Kubernetes et transmettez les références des secrets. La transmission de vos secrets en texte brut via l’interface CLI peut présenter un risque de sécurité.
- Nous vous recommandons d’exécuter les charges de travail de production de manière isolée. Les workflows GitHub Actions sont conçus pour exécuter du code arbitraire, et l’utilisation d’un cluster Kubernetes partagé pour les charges de travail de production peut présenter un risque de sécurité.
- Vérifiez que vous avez implémenté un moyen de collecter et de conserver les journaux du contrôleur, des écouteurs et des exécuteurs éphémères.
-
Pour configurer votre groupe identique d’exécuteurs, exécutez la commande suivante dans votre terminal en utilisant les valeurs de votre configuration ARC.
Lorsque vous exécutez la commande, gardez les points suivants à l’esprit.
-
Mettez à jour la valeur
INSTALLATION_NAME
en faisant bien attention. Vous utiliserez le nom de l’installation comme valeur deruns-on
dans vos workflows. -
Mettez à jour la valeur
NAMESPACE
avec l’emplacement où vous souhaitez que les pods d’exécuteur soient créés. -
Définissez la valeur
GITHUB_CONFIG_URL
avec l’URL de votre dépôt, organisation ou entreprise. Il s’agit de l’entité à laquelle les exécuteurs appartiendront. -
Cet exemple de commande installe la dernière version du chart Helm. Pour installer une version spécifique, vous pouvez passer l’argument
--version
avec la version du chart que vous voulez installer. Vous trouverez la liste des versions dans le dépôtactions-runner-controller
.Bash INSTALLATION_NAME="arc-runner-set" NAMESPACE="arc-runners" GITHUB_CONFIG_URL="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>" GITHUB_PAT="<PAT>" helm install "${INSTALLATION_NAME}" \ --namespace "${NAMESPACE}" \ --create-namespace \ --set githubConfigUrl="${GITHUB_CONFIG_URL}" \ --set githubConfigSecret.github_token="${GITHUB_PAT}" \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
INSTALLATION_NAME="arc-runner-set" NAMESPACE="arc-runners" GITHUB_CONFIG_URL="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>" GITHUB_PAT="<PAT>" helm install "${INSTALLATION_NAME}" \ --namespace "${NAMESPACE}" \ --create-namespace \ --set githubConfigUrl="${GITHUB_CONFIG_URL}" \ --set githubConfigSecret.github_token="${GITHUB_PAT}" \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
Pour obtenir d’autres options de configuration de Helm, consultez
values.yaml
dans le référentiel ARC.
-
-
Pour vérifier votre installation, exécutez la commande suivante dans votre terminal.
Bash helm list -A
helm list -A
Le résultat ressemble à ce qui suit.
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION arc arc-systems 1 2023-04-12 11:45:59.152090536 +0000 UTC deployed gha-runner-scale-set-controller-0.4.0 0.4.0 arc-runner-set arc-systems 1 2023-04-12 11:46:13.451041354 +0000 UTC deployed gha-runner-scale-set-0.4.0 0.4.0
-
Pour vérifier le pod de gestionnaire, exécutez la commande suivante dans votre terminal.
Bash kubectl get pods -n arc-systems
kubectl get pods -n arc-systems
Si l’installation a réussi, les pods affichent l’état
Running
.NAME READY STATUS RESTARTS AGE arc-gha-runner-scale-set-controller-594cdc976f-m7cjs 1/1 Running 0 64s arc-runner-set-754b578d-listener 1/1 Running 0 12s
Si votre installation n’a pas réussi, consultez « Résolution des erreurs d’Actions Runner Controller » pour obtenir des informations de dépannage.
Utilisation des options de configuration avancées
ARC offre plusieurs options de configuration avancées.
Configuration du nom du groupe identique d’exécuteurs
Remarque : Les noms de groupes identiques d’exécuteurs sont uniques au sein du groupe d’exécuteurs auquel ils appartiennent. Si vous voulez déployer plusieurs groupes identiques d’exécuteurs portant le même nom, ils doivent appartenir à différents groupes d’exécuteurs.
Pour configurer le nom du groupe identique d’exécuteurs, vous pouvez définir un INSTALLATION_NAME
ou définir la valeur de runnerScaleSetName
dans votre copie du fichier values.yaml
.
## The name of the runner scale set to create, which defaults to the Helm release name
runnerScaleSetName: "my-runners"
Veillez à passer le fichier values.yaml
dans votre commande helm install
. Pour plus d’informations, consultez la documentation Installation de Helm.
Choix des destinations des exécuteurs
Les groupes identiques d’exécuteurs peuvent être déployés au niveau du dépôt, de l’organisation ou de l’entreprise.
Remarque : Vous pouvez déployer des groupes identiques d’exécuteurs au niveau de l’entreprise seulement si vous utilisez une authentification par personal access token (classic).
Pour déployer des groupes identiques d’exécuteurs à un niveau spécifique, définissez la valeur de githubConfigUrl
dans votre copie du fichier values.yaml
sur l’URL de votre dépôt, organisation ou entreprise.
L’exemple suivant montre comment configurer ARC pour ajouter des exécuteurs à octo-org/octo-repo
.
githubConfigUrl: "http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>"
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Utilisation d’une GitHub App pour l’authentification
Si vous n’utilisez pas d’exécuteurs au niveau de l’entreprise, vous pouvez utiliser des GitHub Apps pour vous authentifier auprès de l’API GitHub. Pour plus d’informations, consultez « Authentification auprès de l’API GitHub ».
Remarque : Étant donné le risque de sécurité associé à l’exposition de votre clé privée en texte brut dans un fichier sur disque, nous vous recommandons de créer un secret Kubernetes et de passer la référence à la place.
Vous pouvez créer un secret Kubernetes ou spécifier des valeurs dans votre fichier values.yaml
.
Option 1 : Créer un secret Kubernetes (recommandé)
Une fois que vous avez créé votre GitHub App, créez un secret Kubernetes et passez la référence à ce secret dans votre copie du fichier values.yaml
.
Remarque : créez le secret dans le même espace de noms que celui où le graphique gha-runner-scale-set
est installé. Dans cet exemple, l’espace de noms est arc-runners
, de sorte correspondre à la documentation de démarrage rapide. Pour plus d’informations, consultez « Démarrage rapide avec Actions Runner Controller ».
kubectl create secret generic pre-defined-secret \
--namespace=arc-runners \
--from-literal=github_app_id=123456 \
--from-literal=github_app_installation_id=654321 \
--from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'
Dans votre copie du fichier values.yaml
, passez le nom du secret en tant que référence.
githubConfigSecret: pre-defined-secret
Option 2 : Spécifier des valeurs dans votre fichier values.yaml
Vous pouvez également spécifier les valeurs de app_id
, installation_id
et private_key
dans votre copie du fichier values.yaml
.
## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API.
## You can choose to use a GitHub App or a personal access token (classic)
githubConfigSecret:
## GitHub Apps Configuration
## IDs must be strings, use quotes
github_app_id: "123456"
github_app_installation_id: "654321"
github_app_private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
HkVN9...
...
-----END RSA PRIVATE KEY-----
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Gestion de l’accès avec des groupes d’exécuteurs
Vous pouvez utiliser des groupes d’exécuteurs pour contrôler quelles organisations ou quels dépôts ont accès à vos groupes identiques d’exécuteurs. Pour plus d’informations sur les groupes d’exécuteurs, consultez « Gestion de l’accès aux exécuteurs auto-hébergés à l’aide de groupes ».
Pour ajouter un groupe identique d’exécuteurs à un groupe d’exécuteurs, vous devez déjà avoir un groupe d’exécuteurs. Définissez ensuite la propriété runnerGroup
dans votre copie du fichier values.yaml
. L’exemple suivant ajoute un groupe identique d’exécuteurs au groupe d’exécuteurs Octo-Group.
runnerGroup: "Octo-Group"
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Configuration d’un proxy sortant
Pour forcer le trafic HTTP du contrôleur et des exécuteurs à passer par votre proxy sortant, définissez les propriétés suivantes dans votre chart Helm.
proxy:
http:
url: http://proxy.com:1234
credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
https:
url: http://proxy.com:1234
credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
noProxy:
- example.com
- example.org
ARC prend en charge l’utilisation de proxys anonymes ou authentifiés. Si vous utilisez des proxys authentifiés, vous devez définir la valeur credentialSecretRef
pour référencer un secret Kubernetes. Vous pouvez créer un secret avec vos informations d’identification de proxy avec la commande suivante.
Remarque : créez le secret dans le même espace de noms que celui où le graphique gha-runner-scale-set
est installé. Dans cet exemple, l’espace de noms est arc-runners
, de sorte correspondre à la documentation de démarrage rapide. Pour plus d’informations, consultez « Démarrage rapide avec Actions Runner Controller ».
kubectl create secret generic proxy-auth \ --namespace=arc-runners \ --from-literal=username=proxyUsername \ --from-literal=password=proxyPassword \
kubectl create secret generic proxy-auth \
--namespace=arc-runners \
--from-literal=username=proxyUsername \
--from-literal=password=proxyPassword \
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Définition du nombre maximal et minimal d’exécuteurs
Les propriétés maxRunners
et minRunners
vous fournissent un éventail d’options pour personnaliser votre configuration ARC.
Remarque : ARC ne prend pas en charge les configurations maximale et minimale planifiées. Vous pouvez utiliser une tâche cronjob ou toute autre solution de planification pour mettre à jour la configuration selon une planification.
Exemple : Nombre non délimité d’exécuteurs
Si vous commentez à la fois les propriétés maxRunners
et minRunners
, ARC effectue un scale-up jusqu’au nombre de travaux attribués au groupe identique d’exécuteurs et effectue un scale-down à 0 s’il n’y a aucun travail actif.
## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0
## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
# minRunners: 0
Exemple : Nombre minimal d’exécuteurs
Vous pouvez définir la propriété minRunners
sur n’importe quel nombre et ARC s’assurera qu’il y a toujours le nombre spécifié d’exécuteurs actifs et disponibles pour s’occuper des travaux assignés au groupe identique d’exécuteurs.
## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0
## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20
Exemple : Définir le nombre maximal et minimal d’exécuteurs
Dans cette configuration, Actions Runner Controller effectue un scale-up jusqu’à un maximum de 30
exécuteurs et un scale-down à 20
exécuteurs quand les travaux sont terminés.
Remarque : La valeur de minRunners
ne peut jamais dépasser celle de maxRunners
, sauf si maxRunners
est commenté.
## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 30
## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20
Exemple : Vidage de la file d’attente des travaux
Dans certains scénarios, vous voudrez probablement vider la file d’attente des travaux pour résoudre un problème ou effectuer une maintenance sur votre cluster. Si vous définissez les deux propriétés sur 0
, Actions Runner Controller ne crée pas de pod d’exécuteur lorsque de nouveaux travaux sont disponibles et attribués.
## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 0
## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0
Certificats TLS personnalisés
Remarque : Si vous utilisez une image d’exécuteur personnalisée qui n’est pas basée sur la distribution Debian
, les instructions suivantes ne fonctionnent pas.
Certains environnements demandent des certificats TLS signés par une autorité de certification personnalisée. Étant donné que les certificats d’autorité de certification personnalisés ne sont pas regroupés avec les conteneurs de contrôleur ou d’exécuteur, vous devez les injecter dans leur magasin de confiance respectif.
githubServerTLS:
certificateFrom:
configMapKeyRef:
name: config-map-name
key: ca.crt
runnerMountPath: /usr/local/share/ca-certificates/
Lorsque vous effectuez cette opération, veillez à utiliser le format PEM (Privacy Enhanced Mail) et vérifiez que l’extension de votre certificat est .crt
. Toutes les autres seront ignorées.
Le contrôleur exécute les actions suivantes.
- Crée un volume
github-server-tls-cert
contenant le certificat spécifié danscertificateFrom
. - Monte ce volume sur le chemin
runnerMountPath/<certificate name>
. - Définit la variable d’environnement
NODE_EXTRA_CA_CERTS
sur ce même chemin. - Définit la variable d’environnement
RUNNER_UPDATE_CA_CERTS
sur1
(à partir de la version2.303.0
, cela indique à l’exécuteur de recharger les certificats sur l’hôte).
ARC observe les valeurs définies dans le modèle de pod d’exécuteur et ne les remplace pas.
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Utilisation d’un registre de conteneurs privé
Avertissement : cette option de personnalisation Actions Runner Controller peut être en dehors de l’étendue de ce que Support GitHub peut être d’assistance et peut entraîner un comportement inattendu lorsqu’elle est configurée de manière incorrecte.
Pour plus d’informations sur ce que Support GitHub peut faire, consultez À propos du support pour Actions Runner Controller.
Pour utiliser un registre de conteneurs privé, vous pouvez copier l’image du contrôleur et l’image de l’exécuteur dans votre registre de conteneurs privé. Configurez ensuite les liens vers ces images et définissez les valeurs imagePullPolicy
et imagePullSecrets
.
Configuration de l’image du contrôleur
Vous pouvez mettre à jour votre copie du fichier values.yaml
et définir les propriétés image
comme suit.
image:
repository: "custom-registry.io/gha-runner-scale-set-controller"
pullPolicy: IfNotPresent
# Overrides the image tag whose default is the chart appVersion.
tag: "0.4.0"
imagePullSecrets:
- name: <registry-secret-name>
Le conteneur d’écouteur hérite de imagePullPolicy
, qui a été défini pour le contrôleur.
Configuration de l’image de l’exécuteur
Vous pouvez mettre à jour votre copie du fichier values.yaml
et définir les propriétés template.spec
comme suit.
template:
spec:
containers:
- name: runner
image: "custom-registry.io/actions-runner:latest"
imagePullPolicy: Always
command: ["/home/runner/run.sh"]
imagePullSecrets:
- name: <registry-secret-name>
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Mise à jour de la spécification du pod pour le pod d’exécuteur
Avertissement : cette option de personnalisation Actions Runner Controller peut être en dehors de l’étendue de ce que Support GitHub peut être d’assistance et peut entraîner un comportement inattendu lorsqu’elle est configurée de manière incorrecte.
Pour plus d’informations sur ce que Support GitHub peut faire, consultez À propos du support pour Actions Runner Controller.
Vous pouvez entièrement personnaliser la PodSpec du pod d’exécuteur et le contrôleur applique la configuration que vous spécifiez. Voici un exemple de spécification de pod.
template:
spec:
containers:
- name: runner
image: ghcr.io/actions/actions-runner:latest
command: ["/home/runner/run.sh"]
resources:
limits:
cpu: 500m
memory: 512Mi
securityContext:
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
capabilities:
add:
- NET_ADMIN
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Mise à jour de la spécification du pod pour le pod de l’écouteur
Avertissement : cette option de personnalisation Actions Runner Controller peut être en dehors de l’étendue de ce que Support GitHub peut être d’assistance et peut entraîner un comportement inattendu lorsqu’elle est configurée de manière incorrecte.
Pour plus d’informations sur ce que Support GitHub peut faire, consultez À propos du support pour Actions Runner Controller.
Vous pouvez personnaliser le PodSpec du pod d’écouteur et le contrôleur appliquera la configuration que vous avez spécifiée. Voici un exemple de spécification de pod.
Il est important de ne pas modifier la valeur de listenerTemplate.spec.containers.name
du conteneur d’écouteur. Sinon, la configuration que vous spécifiez sera appliquée à un nouveau conteneur side-car.
listenerTemplate:
spec:
containers:
# If you change the name of the container, the configuration will not be applied to the listener,
# and it will be treated as a side-car container.
- name: listener
securityContext:
runAsUser: 1000
resources:
limits:
cpu: "1"
memory: 1Gi
requests:
cpu: "1"
memory: 1Gi
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Utilisation du mode Docker-in-Docker ou Kubernetes pour les conteneurs
Avertissement : cette option de personnalisation Actions Runner Controller peut être en dehors de l’étendue de ce que Support GitHub peut être d’assistance et peut entraîner un comportement inattendu lorsqu’elle est configurée de manière incorrecte.
Pour plus d’informations sur ce que Support GitHub peut faire, consultez À propos du support pour Actions Runner Controller.
Si vous utilisez des travaux et des services de conteneur ou des actions de conteneur, la valeur containerMode
doit être définie sur dind
ou kubernetes
.
- Pour plus d’informations sur les travaux et services de conteneur, consultez « Exécution de travaux dans un conteneur ».
- Pour plus d’informations sur les actions de conteneur, consultez « Creating a Docker container action ».
Utilisation du mode Docker-in-Docker
Remarque : Le conteneur Docker-in-Docker nécessite un mode privilégié. Pour plus d’informations, consultez Configure a Security Context for a Pod or Container dans la documentation Kubernetes.
Par défaut, le conteneur dind
utilise l’image docker:dind
, qui exécute le démon Docker en tant que racine. Vous pouvez remplacer cette image par docker:dind-rootless
à condition de tenir compte des limitations connues et d’exécuter les pods en mode --privileged
. Pour savoir comment personnaliser la configuration de Docker-in-Docker, consultez « Personnalisation des modes de conteneur ».
Le mode Docker-in-Docker est une configuration qui vous permet d’exécuter Docker au sein d’un conteneur Docker. Dans cette configuration, pour chaque pod d’exécuteur créé, ARC crée les conteneurs suivants.
- Un conteneur
init
- Un conteneur
runner
- Un conteneur
dind
Pour activer le mode Docker-in-Docker, définissez la valeur containerMode.type
sur dind
comme suit.
containerMode:
type: "dind"
template.spec
est mis à jour avec la configuration par défaut suivante.
template:
spec:
initContainers:
- name: init-dind-externals
image: ghcr.io/actions/actions-runner:latest
command:
["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
volumeMounts:
- name: dind-externals
mountPath: /home/runner/tmpDir
containers:
- name: runner
image: ghcr.io/actions/actions-runner:latest
command: ["/home/runner/run.sh"]
env:
- name: DOCKER_HOST
value: unix:///var/run/docker.sock
volumeMounts:
- name: work
mountPath: /home/runner/_work
- name: dind-sock
mountPath: /var/run
- name: dind
image: docker:dind
args:
- dockerd
- --host=unix:///var/run/docker.sock
- --group=$(DOCKER_GROUP_GID)
env:
- name: DOCKER_GROUP_GID
value: "123"
securityContext:
privileged: true
volumeMounts:
- name: work
mountPath: /home/runner/_work
- name: dind-sock
mountPath: /var/run
- name: dind-externals
mountPath: /home/runner/externals
volumes:
- name: work
emptyDir: {}
- name: dind-sock
emptyDir: {}
- name: dind-externals
emptyDir: {}
Les valeurs dans template.spec
sont automatiquement injectées et ne peuvent pas être remplacées. Si vous souhaitez personnaliser cette configuration, vous devez annuler l’ensemble containerMode.type
, puis copier cette configuration et l’appliquer directement dans votre copie du fichier values.yaml
.
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Utilisation du mode Kubernetes
En mode Kubernetes, ARC utilise des hooks de conteneur d’exécuteur pour créer un pod dans le même espace de noms afin d’exécuter le service, le travail de conteneur ou l’action.
Prérequis
Le mode Kubernetes s’appuie sur des volumes persistants pour partager les détails des travaux entre le pod d’exécuteur et le pod de travail de conteneur. Pour plus d’informations, consultez Persistent Volumes dans la documentation Kubernetes.
Pour utiliser le mode Kubernetes, vous devez effectuer les opérations suivantes.
- Créer des volumes persistants disponibles pour les pods d’exécuteur à revendiquer.
- Utiliser une solution pour provisionner automatiquement des volumes persistants à la demande.
Pour les tests, vous pouvez utiliser une solution comme OpenEBS.
Configuration du mode Kubernetes
Pour activer le mode Kubernetes, définissez containerMode.type
sur kubernetes
dans votre fichier values.yaml
.
containerMode:
type: "kubernetes"
kubernetesModeWorkVolumeClaim:
accessModes: ["ReadWriteOnce"]
storageClassName: "dynamic-blob-storage"
resources:
requests:
storage: 1Gi
Pour obtenir d’autres options de configuration de Helm, consultez values.yaml
dans le référentiel ARC.
Remarque : Lorsque le mode Kubernetes est activé, les workflows qui ne sont pas configurés avec un travail de conteneur échouent avec une erreur semblable à :
Jobs without a job container are forbidden on this runner, please add a 'container:' to your job or contact your self-hosted runner administrator.
Pour permettre aux travaux sans conteneur de travail de s’exécuter, définissez ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
sur false
au niveau de votre conteneur d’exécuteur. Cela indique à l’exécuteur de désactiver cette vérification.
template:
spec:
containers:
- name: runner
image: ghcr.io/actions/actions-runner:latest
command: ["/home/runner/run.sh"]
env:
- name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
value: "false"
Personnalisation des modes de conteneur
Lorsque vous définissez containerMode
dans le fichier values.yaml
pour le graphique Helm gha-runner-scale-set
, vous pouvez utiliser l’une des valeurs suivantes :
dind
oukubernetes
En fonction de la valeur que vous définissez pour containerMode
, une configuration sera automatiquement injectée dans la section template
du fichier values.yaml
pour le graphique Helm gha-runner-scale-set
.
- Reportez-vous à la configuration de
dind
. - Reportez-vous à la configuration de
kubernetes
.
Pour personnaliser la spécification, mettez en commentaire ou supprimez containerMode
, et ajoutez la configuration que vous voulez dans la section template
.
Exemple : exécution de dind-rootless
Avant de décider d’exécuter dind-rootless
, assurez-vous de connaître les limitations connues.
## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg
githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller"
## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret
## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5
## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0
runnerGroup: "my-custom-runner-group"
## name of the runner scale set to create. Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"
## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
spec:
initContainers:
- name: init-dind-externals
image: ghcr.io/actions/actions-runner:latest
command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
volumeMounts:
- name: dind-externals
mountPath: /home/runner/tmpDir
- name: init-dind-rootless
image: docker:dind-rootless
command:
- sh
- -c
- |
set -x
cp -a /etc/. /dind-etc/
echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
echo 'runner:x:1001:' >> /dind-etc/group
echo 'runner:100000:65536' >> /dind-etc/subgid
echo 'runner:100000:65536' >> /dind-etc/subuid
chmod 755 /dind-etc;
chmod u=rwx,g=rx+s,o=rx /dind-home
chown 1001:1001 /dind-home
securityContext:
runAsUser: 0
volumeMounts:
- mountPath: /dind-etc
name: dind-etc
- mountPath: /dind-home
name: dind-home
containers:
- name: runner
image: ghcr.io/actions/actions-runner:latest
command: ["/home/runner/run.sh"]
env:
- name: DOCKER_HOST
value: unix:///var/run/docker.sock
volumeMounts:
- name: work
mountPath: /home/runner/_work
- name: dind-sock
mountPath: /var/run
- name: dind
image: docker:dind-rootless
args:
- dockerd
- --host=unix:///var/run/docker.sock
securityContext:
privileged: true
runAsUser: 1001
runAsGroup: 1001
volumeMounts:
- name: work
mountPath: /home/runner/_work
- name: dind-sock
mountPath: /var/run
- name: dind-externals
mountPath: /home/runner/externals
- name: dind-etc
mountPath: /etc
- name: dind-home
mountPath: /home/runner
volumes:
- name: work
emptyDir: {}
- name: dind-externals
emptyDir: {}
- name: dind-sock
emptyDir: {}
- name: dind-etc
emptyDir: {}
- name: dind-home
emptyDir: {}
Comprendre runner-container-hooks
Lorsque l’exécuteur détecte une exécution de flux de travail qui utilise un travail de conteneur, un conteneur de service ou une action Docker, il appelle runner-container-hooks pour créer un nouveau pod. L’exécuteur s’appuie sur runner-container-hooks pour appeler les API Kubernetes et créer un nouveau pod dans le même espace de noms que le pod d’exécuteur. Ce nouveau pod sera utilisé pour exécuter le travail de conteneur, le conteneur de service ou l’action Docker. Pour plus d'informations, consultez le dépôt runner-container-hooks
.
Configuration des extensions de hook
À partir de la version 0.4.0 d’ARC, runner-container-hooks prend en charge les extensions de hook. Vous pouvez les utiliser pour configurer le pod créé par runner-container-hooks. Par exemple, vous pouvez utiliser une extension de hook pour définir un contexte de sécurité pour le pod. Les extensions de hook vous permettent de spécifier un fichier YAML qui est utilisé pour mettre à jour le PodSpec du pod créé par runner-container-hooks.
Il existe deux options pour configurer les extensions de hook.
- Stocker dans votre image d’exécuteur personnalisée. Vous pouvez stocker le PodSpec dans un fichier YAML n’importe où dans votre image d’exécuteur personnalisée. Pour plus d’informations, consultez « À propos d’Actions Runner Controller ».
- Stocker dans un ConfigMap. Vous pouvez créer un ConfigMap avec le PodSpec et monter ce ConfigMap dans le conteneur d’exécuteur. Pour plus d’informations, consultez ConfigMaps dans la documentation Kubernetes.
Remarque : Avec les deux options, vous devez définir la variable d’environnement ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE
dans la spécification du conteneur d’exécuteur pour qu’elle pointe vers le chemin du fichier YAML monté dans le conteneur d’exécuteur.
Exemple : Utilisation d’un ConfigMap pour définir securityContext
Créez un ConfigMap dans le même espace de noms que les pods d’exécuteur. Par exemple :
apiVersion: v1
kind: ConfigMap
metadata:
name: hook-extension
namespace: arc-runners
data:
content: |
metadata:
annotations:
example: "extension"
spec:
containers:
- name: "$job" # Target the job container
securityContext:
runAsUser: 1000
- Les champs
.metadata.labels
etmetadata.annotations
seront ajoutés tels quels, sauf si leurs clés sont réservées. Vous ne pouvez pas remplacer les champs.metadata.name
etmetadata.namespace
. - La majorité des champs de PodSpec sont appliqués à partir du modèle spécifié et remplacent les valeurs transmises par le fichier
values.yaml
de votre graphique Helm. - Si vous spécifiez des volumes supplémentaires, ils seront ajoutés aux volumes par défaut spécifiés par l’exécuteur.
- Les
spec.containers
sont fusionnés en fonction des noms qui leur sont attribués.- Si le nom du conteneur est
$job
:- Les champs
spec.containers.name
etspec.containers.image
sont ignorés. - Les champs
spec.containers.env
,spec.containers.volumeMounts
etspec.containers.ports
sont ajoutés à la spécification de conteneur par défaut créée par le hook. - Les autres champs sont appliqués tels qu’ils ont été fournis.
- Les champs
- Si le nom du conteneur n’est pas
$job
, les champs seront ajoutés tels quels à la définition du pod.
- Si le nom du conteneur est
Activation des métriques
Note : Les métriques pour ARC sont disponibles à partir de la version gha-runner-scale-set-0.5.0.
ARC peut émettre des métriques sur vos exécuteurs, vos travaux et le temps consacré à l’exécution de vos flux de travail. Les métriques peuvent être utilisées pour identifier la congestion, surveiller l’intégrité de votre déploiement ARC, visualiser les tendances d’utilisation, optimiser la consommation des ressources, parmi de nombreux autres cas d’utilisation. Les métriques sont émises par les pods contrôleur-manager et écouteurs au format Prometheus. Pour plus d’informations, consultez les formats Exposition dans la documentation Prometheus.
Pour activer les métriques pour ARC, configurez la metrics
propriété dans le fichier values.yaml
du gha-runner-scale-set-controller
graphique.
Voici un exemple de configuration.
metrics:
controllerManagerAddr: ":8080"
listenerAddr: ":8080"
listenerEndpoint: "/metrics"
Note : Si metrics:
l’objet n’est pas fourni ou est commenté, les indicateurs suivants sont appliqués aux pods du gestionnaire de contrôleur et de l’écouteur avec des valeurs vides : --metrics-addr
, --listener-metrics-addr
, --listener-metrics-endpoint
. Cela désactive les métriques pour ARC.
Une fois ces propriétés configurées, vos pods de contrôleur et d’écouteur émettent des métriques via l’écouteurEndpoint lié aux ports que vous spécifiez dans votre fichier values.yaml
. Dans l’exemple ci-dessus, le point de terminaison est /metrics
et le port est :8080
. Vous pouvez utiliser ce point de terminaison pour récupérer des métriques à partir de vos pods contrôleur-manager et écouteur.
Pour désactiver les métriques, mettez à jour votre fichier values.yaml
en supprimant ou en commentant l’objet metrics:
et ses propriétés.
Métriques disponibles pour ARC
Le tableau suivant présente les métriques émises par les pods du gestionnaire de contrôleur et de l’écouteur.
Note : les métriques émises par le contrôleur-manager concernent le runtime du contrôleur et ne sont pas détenues par GitHub.
Propriétaire | Métrique | Type | Description |
---|---|---|---|
controller-manager | gha_controller_pending_ephemeral_runners | jauge | Nombre d’exécuteurs éphémères dans un état en attente |
controller-manager | gha_controller_running_ephemeral_runners | jauge | Nombre d’exécuteurs éphémères dans un état en cours d’exécution |
controller-manager | gha_controller_failed_ephemeral_runners | jauge | Nombre d’exécuteurs éphémères dans un état d’échec |
controller-manager | gha_controller_running_listeners | jauge | Nombre d’écouteurs dans un état en cours d’exécution |
listener | gha_assigned_jobs | jauge | Nombre de projets affectés au groupe identique de l’exécuteur |
listener | gha_running_jobs | jauge | Nombre de projets en cours d’exécution ou mis en file d’attente à exécuter |
listener | gha_registered_runners | jauge | Nombre d’exécuteurs inscrits par le groupe identique de l’exécuteur |
listener | gha_busy_runners | jauge | Nombre d’exécuteurs inscrits en cours d’exécution d’un projet |
listener | gha_min_runners | jauge | Nombre minimal d’exécuteurs configurés pour le groupe identique de l’exécuteur |
listener | gha_max_runners | jauge | Nombre maximal d’exécuteurs configurés pour le groupe identique de l’exécuteur |
listener | gha_desired_runners | jauge | Nombre d’exécuteurs souhaités (objectif scale up/scale down) par le groupe identique de l’exécuteur |
listener | gha_idle_runners | jauge | Nombre d’exécuteurs inscrits qui n’exécutent pas un projet |
listener | gha_started_jobs_total | counter | Nombre total de projets démarrés depuis que l’écouteur est devenu prêt [1] |
listener | gha_completed_jobs_total | counter | Nombre total de projets terminés depuis que l’écouteur est devenu prêt [1] |
listener | gha_job_startup_duration_seconds | histogram | Nombre de secondes passées en attente de tâche de workflow pour démarrer sur l’exécuteur détenu par le groupe identique de l’exécuteur |
listener | gha_job_execution_duration_seconds | histogram | Nombre de secondes passées à exécuter des tâches de workflow par le groupe identique de l’exécuteur |
[1]: Listener metrics that have the counter type are reset when the listener pod restarts.
Utiliser ARC avec Dependabot et code scanning
Vous pouvez utiliser Actions Runner Controller pour créer des exécuteurs dédiés pour votre instance GitHub Enterprise Server que Dependabot peut utiliser pour sécuriser et maintenir les dépendances utilisées dans les référentiels de votre entreprise. Pour plus d’informations, consultez « Gestion des exécuteurs auto-hébergés pour les mises à jour Dependabot dans votre entreprise ».
Vous pouvez aussi utiliser ARC CodeQL pour identifier les vulnérabilités et les erreurs dans votre code. Pour plus d’informations, consultez « À propos de l’analyse du code avec CodeQL ». Si vous utilisez déjà code scanning et que vous souhaitez configurer un groupe identique d’exécuteurs pour utiliser la configuration par défaut, définissez INSTALLATION_NAME=code-scanning
. Pour plus d’informations sur l’installation par défaut code scanning, consultez « Définition de la configuration par défaut pour l’analyse du code ».
Actions Runner Controller n’utilise pas plusiuers étiquettes pour router les tâches vers des groupes identiques d’exécuteurs spécifiques. Au lieu de cela, pour désigner un groupe identique d’exécuteurs pour les mises à jour de Dependabot ou code scanning avec CodeQL, utilisez un nom d’installation descriptif dans votre graphique Helm, comme dependabot
ou code-scanning
. Vous pouvez ensuite attribuer la valeur runs-on
dans vos workflows au nom de l’installation en tant qu’étiquette unique, et utiliser le groupe identique d’exécuteurs désigné pour les mises à jour Dependabot ou les tâches code scanning.
Si vous utilisez la configuration par défaut pour code scanning, l’analyse recherche automatiquement un groupe identique d’exécuteur avec le nom d’installation code-scanning
.
L’action Dependabot est utilisée pour exécuter les mises à jour de Dependabot via GitHub Actions. Cette action nécessite Docker comme dépendance. Pour cette raison, vous pouvez utiliser seulement Actions Runner Controller avec Dependabot quand le mode Docker-in-Docker (DinD) est activé. Pour plus d’informations, consultez « Gestion des exécuteurs auto-hébergés pour les mises à jour Dependabot dans votre entreprise » et « Déploiement de groupes identiques d’exécuteurs avec Actions Runner Controller ».
Mise à niveau d’ARC
Étant donné que Helm ne prend pas en charge la mise à niveau ou la suppression des CRD, il n’est pas possible d’utiliser Helm pour mettre à niveau ARC. Pour plus d’informations, consultez Définitions de ressources personnalisées dans la documentation Helm. Pour mettre à niveau ARC vers une version plus récente, vous devez effectuer les étapes suivantes.
- Désinstallez toutes les installations de
gha-runner-scale-set
. - Attendez que les ressources soient nettoyées.
- Désinstallez ARC.
- S’il existe une modification des CRD entre la version actuellement installée et la version mise à jour, supprimez tous les CRD associés au groupe d’API
actions.github.com
. - Réinstallez ARC.
Pour plus d’informations, consultez « Déploiement d’un groupe identique d’exécuteurs ».
Si vous souhaitez mettre à niveau ARC mais que vous craignez des temps d’arrêt, vous pouvez déployer ARC dans une configuration de haute disponibilité afin de garantir que les exécuteurs sont toujours disponibles. Pour plus d’informations, consultez « Haute disponibilité et basculement automatique ».
Remarque :
La transition de la version d’ARC prise en charge par la communauté vers la version prise en charge par GitHub constitue un changement architectural important. La version prise en charge par GitHub nécessite une refonte de nombreux composants d’ARC. Il ne s’agit pas d’une mise à niveau de logiciel mineure. Pour ces raisons, nous recommandons de tester d’abord les nouvelles versions dans un environnement intermédiaire qui correspond à votre environnement de production. Cela garantira la stabilité et la fiabilité de la configuration avant de la déployer en production.
Déploiement d’une image canary
Vous pouvez tester les fonctionnalités avant qu’elles ne soient publiées en utilisant des versions canary de l’image du conteneur controller-manager. Les images canary sont publiées avec le format de balise canary-SHORT_SHA
. Pour plus d’informations, consultez gha-runner-scale-set-controller
sur le Container registry.
Remarques :
- Vous devez utiliser les graphiques Helm dans votre système de fichiers local.
- Vous ne pouvez pas utiliser les graphiques Helm publiés.
- Mettez à jour le
tag
dans le fichier gha-runner-scale-set-controllervalues.yaml
en :canary-SHORT_SHA
- Mettez à jour le champ
appVersion
dans le fichierChart.yaml
pourgha-runner-scale-set
en :canary-SHORT_SHA
- Réinstallez ARC en utilisant le graphique Helm et les fichiers
values.yaml
mis à jour.
Haute disponibilité et basculement automatique
ARC peut être déployé dans une configuration à haute disponibilité (active/active). Si vous avez deux clusters Kubernetes distincts déployés dans des régions distinctes, vous pouvez déployer ARC dans les deux clusters et configurer des groupes identiques d’exécuteurs pour qu’ils utilisent le même runnerScaleSetName
. Pour ce faire, chaque groupe identique de l’exécuteur doit être affecté à un groupe d’exécuteurs distinct. Par exemple, vous pouvez avoir deux groupes identiques d’exécuteurs nommés chacunarc-runner-set
, à condition qu’un groupe identique de l’exécuteur appartient à runner-group-A
et que l’autre groupe identique de l’exécuteur appartient à runner-group-B
. Pour plus d’informations sur l’affectation de groupes identiques d’exécuteurs à des groupes d’exécuteurs, consultez « Gestion de l’accès aux exécuteurs auto-hébergés à l’aide de groupes ».
Si les deux groupes identiques de l’exécuteur sont en ligne, les projets qui leur sont attribués sont distribués arbitrairement (course d’affectation). Vous ne pouvez pas configurer l’algorithme d’attribution de projet. Si l’un des clusters tombe en panne, le groupe identique de l’exécuteur dans l’autre cluster continue d’acquérir des projets normalement sans aucune intervention ni modification de configuration.
Utilisation d’ARC dans les organisations
Une seule installation d’Actions Runner Controller vous permet de configurer un ou plusieurs groupes identiques d’exécuteurs. Ces groupes identiques d’exécuteurs peuvent être inscrits dans un dépôt, une organisation ou une entreprise. Vous pouvez également utiliser des groupes d’exécuteurs pour contrôler les limites des autorisations de ces groupes identiques d’exécuteurs.
Il est recommandé de créer un espace de noms unique pour chaque organisation. Vous pouvez également créer un espace de noms pour chaque groupe d’exécuteurs ou chaque groupe identique d’exécuteurs. Vous pouvez installer autant de groupes identiques d’exécuteurs que nécessaire dans chaque espace de noms. Vous bénéficierez ainsi des niveaux d’isolation les plus élevés et améliorerez votre sécurité. Vous pouvez utiliser des GitHub Apps pour l’authentification et définir des autorisations granulaires pour chaque groupe identique d’exécuteurs.
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.