Déploiement de groupes identiques d’exécuteurs avec Actions Runner Controller

Mentions légales

À 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 pas avoir d’étiquettes qui leur soient attribuées. 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.

1. 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 de runs-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ôt actions-runner-controller.

     Bash

     INSTALLATION_NAME="arc-runner-set"
     NAMESPACE="arc-runners"
     GITHUB_CONFIG_URL="https://github.com/<your_enterprise/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.

2. Pour vérifier votre installation, exécutez la commande suivante dans votre terminal.

   Bash

   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
   

3. Pour vérifier le pod de gestionnaire, exécutez la commande suivante dans votre terminal.

   Bash

   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

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.

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: "https://github.com/octo-ent/octo-org/octo-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 ».

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.

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.

  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.

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 runners the auto scaling runner set will scale down to.
# minRunners: 0

Exemple : Nombre minimal d’exécuteurs

Vous pouvez définir la propriété minRunners sur n’importe quel nombre et ARC s’assure qu’il y a tout le temps au moins ce nombre d’exécuteurs actifs et disponibles pour s’occuper des travaux attribué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 runners the auto scaling runner set will scale down to.
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.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 30

## minRunners is the min number of runners the auto scaling runner set will scale down to.
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 runners the auto scaling runner set will scale down to.
minRunners: 0

Certificats TLS personnalisés

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é dans certificateFrom.
• 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 sur 1 (à partir de la version 2.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 du mode Docker-in-Docker ou Kubernetes pour les conteneurs

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

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", "-v", "/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:///run/docker/docker.sock
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/docker
          readOnly: true
    - name: dind
      image: docker:dind
      args:
        - dockerd
        - --host=unix:///run/docker/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: /run/docker
        - name: dind-externals
          mountPath: /home/runner/externals
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}

Vous ne pouvez pas remplacer ces valeurs entrées automatiquement. 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.

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.

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, vous devez indiquer à l’exécuteur de désactiver cette condition. Vous pouvez le faire en paramétrant ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER sur false dans votre conteneur d’exécuteur :

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"

Utilisation d’un registre de conteneurs privé

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"]

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

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.

Activation des métriques

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"

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.

[1]: Listener metrics that have the counter type are reset when the listener pod restarts.

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.