Démarrage rapide avec Actions Runner Controller

Essayez Actions Runner Controller en 5 minutes.

Dans cet article

Mentions légales

Introduction

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

Vous pouvez configurer ARC sur Kubernetes en utilisant Helm, puis créer et exécuter un workflow qui utilise des groupes identiques d’exécuteurs. Pour plus d’informations sur les groupes identiques d’exécuteurs, consultez « Déploiement de groupes identiques d’exécuteurs avec Actions Runner Controller ».

Prérequis

Pour utiliser ARC, veillez à disposer des éléments suivants.

  • Un cluster Kubernetes

    • Pour un environnement cloud managé, vous pouvez utiliser AKS. Pour plus d’informations, consultez Azure Kubernetes Service dans la documentation Azure.

    • Pour une configuration locale, vous pouvez utiliser minikube ou kind. Pour plus d’informations, consultez minikube start dans la documentation de minikube et kind dans la documentation de kind.

      Remarque : Les clusters OpenShift ne sont pas pris en charge actuellement.

  • Helm 3

  • Bien qu’il ne soit pas nécessaire de déployer ARC, nous vous recommandons de vous assurer que vous avez implémenté un moyen de collecter et de conserver les journaux issus du contrôleur, des écouteurs et des exécuteurs éphémères avant de déployer ARC dans des flux de travail de production.

Installation d’Actions Runner Controller

  1. Pour installer l’opérateur et les définitions de ressources personnalisées (CRD) dans votre cluster, procédez comme suit.

    1. Dans votre chart Helm, mettez à jour la valeur NAMESPACE avec l’emplacement où vous souhaitez que vos pods d’opérateur soient créés. Cet espace de noms doit autoriser l’accès au serveur d’API Kubernetes.
    2. Installez le chart Helm.

    L’exemple suivant installe la dernière version du chart. Pour installer une version spécifique, vous pouvez passer l’argument --version avec la version du chart que vous souhaitez installer. Vous trouverez la liste des versions dans le Registre de conteneurs GitHub.

    Bash
    NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

    Pour obtenir d’autres options de configuration de Helm, consultez values.yaml dans la documentation d’ARC.

  2. Pour permettre à ARC de s’authentifier auprès de GitHub, générez un personal access token (classic). Pour plus d’informations, consultez « Authentification auprès de l’API GitHub ».

Configuration d’un groupe identique d’exécuteurs

  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. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».

    • Mettez à jour la valeur NAMESPACE avec l’emplacement où vous souhaitez que les pods d’exécuteur soient créés.

    • Définissez 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 souhaitez installer. Vous trouverez la liste des versions dans le Registre de conteneurs GitHub.

      Remarque :

      • 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é. Pour plus d’informations, consultez « Déploiement de groupes identiques d’exécuteurs avec 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 la documentation d’ARC.

  2. À partir de votre terminal, exécutez la commande suivante pour vérifier votre installation.

    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-runners     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 tout a été installé correctement, l’état des pods s’affiche comme En cours d’exécution.

    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 groupes identiques d’exécuteurs

Vous allez maintenant créer et exécuter un workflow test simple qui utilise les exécuteurs de groupes identiques d’exécuteurs.

  1. Dans un dépôt, créez un workflow similaire à l’exemple suivant. La valeur runs-on doit correspondre au nom d’installation Helm que vous avez utilisé lorsque vous avez installé l’ensemble d’exécuteurs pouvant se mettre à l’échelle automatiquement.

    Pour plus d’informations sur l’ajout de workflows dans un dépôt, consultez « Démarrage rapide pour GitHub Actions ».

    YAML
    name: Actions Runner Controller Demo
on:
  workflow_dispatch:

jobs:
  Explore-GitHub-Actions:
    # You need to use the INSTALLATION_NAME from the previous step
    runs-on: arc-runner-set
    steps:
    - run: echo "🎉 This job uses runner scale set runners!"

  2. Une fois que vous avez ajouté le workflow dans votre dépôt, déclenchez-le manuellement. Pour plus d’informations, consultez « Exécution manuelle d’un workflow ».

  3. Pour afficher les pods d’exécuteur en cours de création pendant l’exécution du workflow, exécutez la commande suivante à partir de votre terminal.

    Bash
    kubectl get pods -n arc-runners

    Une sortie réussie ressemble à ce qui suit.

    NAMESPACE     NAME                                                  READY   STATUS    RESTARTS      AGE
arc-runners   arc-runner-set-rmrgw-runner-p9p5n                     1/1     Running   0             21s

Étapes suivantes

Actions Runner Controller peut vous aider à gérer efficacement vos exécuteurs GitHub Actions. Prêt à vous lancer ? Voici quelques ressources utiles pour aller plus loin avec ARC :

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.