Exécuter et mettre à l'échelle des exécuteurs GitHub auto-hébergés sur des pools de nœuds de calcul Cloud Run

Ce tutoriel explique comment utiliser des exécuteurs GitHub auto-hébergés sur des pools de nœuds de calcul pour exécuter les workflows définis dans votre dépôt GitHub et mettre à l'échelle votre pool de nœuds de calcul avec l'autoscaling des métriques externes Cloud Run (CREMA).

À propos des exécuteurs GitHub auto-hébergés

Dans un workflow GitHub Actions, les exécuteurs sont les machines qui exécutent les tâches. Par exemple, un exécuteur peut cloner votre dépôt localement, installer un logiciel de test, puis exécuter des commandes qui évaluent votre code.

Vous pouvez utiliser des exécuteurs auto-hébergés pour exécuter des actions GitHub sur des instances de pool de nœuds de calcul Cloud Run. Ce tutoriel explique comment mettre automatiquement à l'échelle un pool d'exécuteurs en fonction du nombre de tâches en cours d'exécution et non planifiées.

Objectifs

Au cours de ce tutoriel, vous allez :

Coûts

Dans ce document, vous utilisez les composants facturables de suivants Google Cloud:

Obtenez une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Avant de commencer

  1. Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Activez les API Cloud Run, Secret Manager, Parameter Manager, Artifact Registry et Cloud Build.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer les API

  7. Installez et initialisez gcloud CLI.
  8. Mettez à jour les composants : 
    gcloud components update
  9. Définissez les variables de configuration suivantes pour CREMA utilisées dans ce tutoriel : 
    PROJECT_ID=PROJECT_ID
CREMA_SERVICE_ACCOUNT_NAME=crema-service-account@$PROJECT_ID.iam.gserviceaccount.com
CREMA_REPO_NAME=crema
AR_REGION=us-central1
     Remplacez PROJECT_ID par l'ID de votre Google Cloud projet.
  10. Les frais de votre service de scaling Cloud Run sont facturés en fonction de la fréquence à laquelle vous déclenchez le scaling. Pour en savoir plus, estimez les coûts à l'aide du simulateur de coût.

Rôles requis

Pour obtenir les autorisations nécessaires pour suivre le tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Vous devez disposer de l'autorisation de modifier les paramètres d'un dépôt GitHub pour configurer les exécuteurs auto-hébergés. Le dépôt peut appartenir à un utilisateur ou à une organisation.

GitHub recommande d'utiliser des exécuteurs auto-hébergés uniquement avec des dépôts privés.

Créer un compte de service personnalisé

Ce tutoriel utilise un compte de service personnalisé avec les autorisations minimales requises pour utiliser les ressources provisionnées. Pour configurer le compte de service, procédez comme suit :

gcloud iam service-accounts create crema-service-account \
  --display-name="CREMA Service Account"

Ajouter des exécuteurs GitHub auto-hébergés

Pour ajouter des exécuteurs GitHub auto-hébergés, suivez les instructions de la section Ajouter des exécuteurs auto-hébergés dans la documentation GitHub.

Identifier le dépôt GitHub

Dans ce tutoriel, la variable GITHUB_REPO représente le nom du dépôt. Il s'agit de la partie du nom que vous trouvez après le nom de domaine pour les dépôts d'utilisateurs personnels et les dépôts d'organisation. Exemple :

  • Si l'URL de votre domaine est https://github.com/myuser/myrepo, le GITHUB_REPO est myuser/myrepo.
  • Si l'URL de votre domaine est https://github.com/mycompany/ourrepo, le GITHUB_REPO est mycompany/ourrepo.

Créer un jeton d'accès

Créez un jeton d'accès GitHub pour ajouter et supprimer dynamiquement des exécuteurs en interagissant avec le dépôt sélectionné. Pour créer un jeton d'accès sur GitHub et l'enregistrer dans Secret Manager, procédez comme suit :

  1. Assurez-vous d'être connecté à votre compte GitHub.
  2. Accédez à la page GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic) (Paramètres GitHub > Paramètres de développeur > Jetons d'accès personnels > Jetons (classiques)).
  3. Cliquez sur Generate new token (Générer un nouveau jeton), puis sélectionnez Generate new token (classic) (Générer un nouveau jeton (classique)).
  4. Pour le champ d'application du jeton, cochez la case repo.
  5. Cliquez sur Generate token (Générer le jeton).
  6. Copiez le jeton généré.

Pour en savoir plus sur les jetons d'accès, consultez Exigences d'authentification dans la documentation GitHub.

Créer un secret pour votre jeton d'accès à l'aide de Secret Manager

Prenez le jeton secret que vous avez créé à l'étape précédente et stockez-le dans Secret Manager. Pour définir les autorisations d'accès, procédez comme suit :

  1. Créez le secret dans Secret Manager :

    echo -n "GITHUB_TOKEN" | gcloud secrets create github_runner_token --data-file=-

    Remplacez GITHUB_TOKEN par la valeur que vous avez copiée depuis GitHub.

  2. Accordez le rôle roles/secretmanager.secretAccessor à votre compte de service personnalisé pour accéder au secret que vous venez de créer :

    gcloud secrets add-iam-policy-binding github_runner_token \
  --member "serviceAccount:$CREMA_SERVICE_ACCOUNT_NAME" \
  --role "roles/secretmanager.secretAccessor"

Déployer un pool de nœuds de calcul

Créez un pool de nœuds de calcul Cloud Run pour traiter les actions GitHub. Ce pool utilisera une image basée sur l'image actions/runner créée par GitHub. Pour déployer un pool de nœuds de calcul, procédez comme suit :

  1. Clonez l'exemple de dépôt sur votre ordinateur local pour récupérer l'exemple de code à utiliser :

    git clone https://github.com/GoogleCloudPlatform/cloud-run-samples

  2. Accédez au répertoire contenant l'exemple de code Cloud Run :

    cd cloud-run-samples/github-runner/worker-pool-container

  3. Déployez le pool de nœuds de calcul :

    gcloud run worker-pools deploy WORKER_POOL_NAME \
  --region us-central1 \
  --source . \
  --instances 1 \
  --set-env-vars GITHUB_REPO=GITHUB_REPO \
  --set-secrets GITHUB_TOKEN=github_runner_token:latest \
  --service-account $CREMA_SERVICE_ACCOUNT_NAME \
  --memory 2Gi \
  --cpu 4

    Remplacez les éléments suivants :

    • WORKER_POOL_NAME : nom du pool de nœuds de calcul
    • WORKER_POOL_LOCATION : région du pool de nœuds de calcul
    • GITHUB_REPO : le nom du dépôt GitHub

    Si vous utilisez des déploiements de source Cloud Run pour la première fois dans ce projet, Cloud Run vous invite à créer un dépôt Artifact Registry par défaut.

Comprendre l'exemple de code

Le pool de nœuds de calcul est configuré avec un fichier Dockerfile basé sur l'image actions/runner créée par GitHub :

FROM ghcr.io/actions/actions-runner:2.332.0

# Add scripts with right permissions.
USER root
# hadolint ignore=DL3045
COPY start.sh start.sh
RUN chmod +x start.sh

# Add start entrypoint with right permissions.
USER runner
ENTRYPOINT ["./start.sh"]

Ce script d'assistance s'exécute au démarrage du conteneur, s'enregistrant dans le dépôt configuré en tant qu'instance éphémère à l'aide d'un jeton que vous créez.

# Configure the current runner instance with URL, token and name.
mkdir /home/docker/actions-runner && cd /home/docker/actions-runner
echo "GitHub Repo: ${GITHUB_REPO_URL} for ${RUNNER_PREFIX}-${RUNNER_SUFFIX}"
./config.sh --unattended --url ${GITHUB_REPO_URL} --pat ${GH_TOKEN} --name ${RUNNER_NAME}

# Function to cleanup and remove runner from Github.
cleanup() {
   echo "Removing runner..."
   ./config.sh remove --unattended --pat ${GH_TOKEN}
}

# Trap signals.
trap 'cleanup; exit 130' INT
trap 'cleanup; exit 143' TERM

# Run the runner.
./run.sh & wait $!

Utiliser le pool de nœuds de calcul pour accepter les tâches des actions GitHub

Votre instance de pool de nœuds de calcul est prête à accepter les tâches des actions GitHub.

Si votre dépôt ne comporte pas encore d'actions GitHub, suivez les instructions du guide de démarrage rapide pour créer votre premier workflow.

Si votre dépôt comporte des actions GitHub, vérifiez que vous avez terminé la configuration de votre exécuteur auto-hébergé en appelant une action GitHub sur votre dépôt.

Si votre action GitHub n'utilise pas d'exécuteurs auto-hébergés, changez le travail de votre action GitHub de la valeur runs-on à self-hosted.

Une fois que vous avez configuré une action pour utiliser les exécuteurs auto-hébergés, exécutez l'action.

Vérifiez que l'action s'est terminée correctement dans l'interface GitHub.

Déployer le service d'autoscaling CREMA

Vous avez déployé un nœud de calcul dans votre pool d'origine, ce qui permet de traiter une action à la fois. En fonction de votre utilisation de l'intégration continue (CI), vous devrez peut-être mettre à l'échelle votre pool pour gérer un afflux de travail à effectuer.

Une fois que vous avez déployé le pool de nœuds de calcul avec un exécuteur GitHub actif, configurez l'autoscaler CREMA pour provisionner des instances de nœuds de calcul en fonction de l'état des tâches dans la file d'attente des actions.

Cette implémentation écoute un workflow_job événement. Lorsque vous créez une tâche de workflow, elle met à l'échelle le pool de nœuds de calcul, puis le réduit une fois la tâche terminée. Elle ne met pas à l'échelle le pool au-delà du nombre maximal d'instances que vous configurez et le réduit à zéro une fois toutes les tâches en cours d'exécution terminées.

Vous pouvez adapter CREMA en fonction de vos charges de travail.

Configurer l'autoscaler

Ce tutoriel utilise le Parameter Manager pour stocker le fichier de configuration YAML pour CREMA.

  1. Créez un paramètre dans Parameter Manager pour stocker les versions de paramètres pour CREMA :

    PARAMETER_ID=crema-config
PARAMETER_REGION=global
gcloud parametermanager parameters create $PARAMETER_ID --location=$PARAMETER_REGION --parameter-format=YAML

  2. Créez un fichier YAML, my-crema-config.yaml, dans le répertoire parent pour définir la configuration de l'autoscaler :

    apiVersion: crema/v1
kind: CremaConfig
metadata:
  name: gh-demo
spec:
  pollingInterval: 10
  triggerAuthentications:
    - metadata:
        name: github-trigger-auth
      spec:
        gcpSecretManager:
          secrets:
            - parameter: personalAccessToken
              id: github_runner_token
              version: latest
  scaledObjects:
    - spec:
        scaleTargetRef:
          name: projects/PROJECT_ID/locations/us-central1/workerpools/WORKER_POOL_NAME
        triggers:
          - type: github-runner
            name: GITHUB_RUNNER
            metadata:
              owner: REPOSITORY_OWNER
              runnerScope: repo
              repos: REPOSITORY_NAME
              targetWorkflowQueueLength: 1
            authenticationRef:
              name: github-trigger-auth
        advanced:
          horizontalPodAutoscalerConfig:
            behavior:
              scaleDown:
                stabilizationWindowSeconds: 10
                policies:
                  - type: Pods
                    value: 100
                    periodSeconds: 10
              scaleUp:
                stabilizationWindowSeconds: 10
                policies:
                  - type: Pods
                    value: 2
                    periodSeconds: 10

    Remplacez les éléments suivants :

    • PROJECT_ID : ID du Google Cloud projet
    • WORKER_POOL_NAME : nom du pool de nœuds de calcul que vous avez déployé
    • GITHUB_RUNNER : nom de l'exécuteur GitHub que vous avez configuré
    • REPOSITORY_OWNER : propriétaire du dépôt GitHub
    • REPOSITORY_NAME : nom du dépôt GitHub

  3. Importez votre fichier YAML local en tant que nouvelle version de paramètre :

    LOCAL_YAML_CONFIG_FILE=my-crema-config.yaml
PARAMETER_VERSION=1

gcloud parametermanager parameters versions create $PARAMETER_VERSION \
  --location=$PARAMETER_REGION \
  --parameter=$PARAMETER_ID \
  --payload-data-from-file=$LOCAL_YAML_CONFIG_FILE

Accorder des autorisations supplémentaires à votre compte de service personnalisé

Pour mettre à l'échelle le pool de nœuds de calcul que vous avez spécifié dans votre configuration YAML, accordez les autorisations suivantes sur le compte de service personnalisé :

  1. Accordez à votre compte de service CREMA l'autorisation de lire à partir de Parameter Manager :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CREMA_SERVICE_ACCOUNT_NAME" \
  --role="roles/parametermanager.parameterViewer"

  2. Attribuez le rôle roles/run.developer à votre compte de service CREMA sur le pool de nœuds de calcul :

    WORKER_POOL_NAME=WORKER_POOL_NAME
WORKER_POOL_REGION=us-central1
gcloud run worker-pools add-iam-policy-binding $WORKER_POOL_NAME \
  --region=$WORKER_POOL_REGION \
  --member="serviceAccount:$CREMA_SERVICE_ACCOUNT_NAME" \
  --role="roles/run.developer"

    Remplacez WORKER_POOL_NAME par le nom du pool de nœuds de calcul.

  3. Accordez à votre compte de service CREMA l'autorisation d'écrire des métriques :

     gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member="serviceAccount:$CREMA_SERVICE_ACCOUNT_NAME" \
   --role="roles/monitoring.metricWriter"

  4. Attribuez le rôle d'utilisateur de compte de service à votre compte de service CREMA :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CREMA_SERVICE_ACCOUNT_NAME" \
  --role="roles/iam.serviceAccountUser"

Déployer le service pour mettre à l'échelle vos charges de travail

Pour déployer le service afin de mettre à l'échelle votre pool de nœuds de calcul, exécutez la commande suivante avec une image de conteneur prédéfinie :

SERVICE_NAME=my-crema-service
SERVICE_REGION=us-central1

CREMA_CONFIG_PARAM_VERSION=projects/$PROJECT_ID/locations/$PARAMETER_REGION/parameters/$PARAMETER_ID/versions/$PARAMETER_VERSION
IMAGE=us-central1-docker.pkg.dev/cloud-run-oss-images/crema-v1/autoscaler:1.0

gcloud run deploy $SERVICE_NAME \
  --image=${IMAGE} \
  --region=${SERVICE_REGION} \
  --service-account="${CREMA_SERVICE_ACCOUNT_NAME}" \
  --no-allow-unauthenticated \
  --no-cpu-throttling \
  --base-image=us-central1-docker.pkg.dev/serverless-runtimes/google-24/runtimes/java25 \
  --labels=created-by=crema \
  --set-env-vars="CREMA_CONFIG=${CREMA_CONFIG_PARAM_VERSION},OUTPUT_SCALER_METRICS=True"

Tester votre service CREMA

Pour vérifier que votre service d'autoscaling fonctionne correctement, consultez l'onglet Journaux du service Cloud Run.

Les journaux suivants doivent s'afficher dans les journaux de votre service chaque fois que les métriques sont actualisées :

Chaque message de journal est libellé avec le composant qui l'a émis.

[INFO] [METRIC-PROVIDER] Starting metric collection cycle
[INFO] [METRIC-PROVIDER] Successfully fetched scaled object metrics ...
[INFO] [METRIC-PROVIDER] Sending scale request ...
[INFO] [SCALER] Received ScaleRequest ...
[INFO] [SCALER] Current instances ...
[INFO] [SCALER] Recommended instances ...

Libérer de l'espace

Pour éviter des frais supplémentaires sur votre Google Cloud compte, supprimez toutes les ressources que vous avez déployées avec ce tutoriel.

Supprimer le projet

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous devez le conserver sans les modifications que vous avez ajoutées dans ce tutoriel, supprimez les ressources que vous avez créées pour ce tutoriel.

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

  1. Dans la Google Cloud console, accédez à la page Gérer les ressources.

    Accéder à la page "Gérer les ressources"

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez Arrêter pour supprimer le projet.

Supprimer les ressources du tutoriel

  1. Supprimez le service Cloud Run que vous avez déployé dans ce tutoriel. Les services Cloud Run n'entraînent pas de coûts tant qu'ils ne reçoivent pas de requêtes.

    Pour supprimer votre service Cloud Run, exécutez la commande suivante :

    gcloud run services delete SERVICE-NAME

    Remplacez SERVICE-NAME par le nom du service.

    Vous pouvez également supprimer des services Cloud Run à partir de la Google Cloud console.

  2. Supprimez la configuration régionale gcloud par défaut que vous avez ajoutée lors de la configuration du tutoriel :

     gcloud config unset run/region

  3. Supprimez la configuration du projet :

     gcloud config unset project

  4. Supprimez les autres Google Cloud ressources créées dans ce tutoriel :

Étape suivante