Esegui e scala i runner GitHub self-hosted sui pool di worker Cloud Run

Questo tutorial mostra come utilizzare i runner GitHub con hosting autonomo nei pool di worker per eseguire i workflow definiti nel repository GitHub e scalare il pool di worker con la scalabilità automatica delle metriche esterne di Cloud Run (CREMA).

Informazioni sui runner GitHub con hosting autonomo

In un workflow di GitHub Actions, i runner sono le macchine che eseguono i job. Ad esempio, un runner può clonare il repository localmente, installare il software di test ed eseguire comandi che valutano il codice.

Puoi utilizzare i runner con hosting autonomo per eseguire GitHub Actions sulle istanze del pool di worker di Cloud Run. Questo tutorial mostra come scalare automaticamente un pool di runner in base al numero di job in esecuzione e non pianificati.

Obiettivi

In questo tutorial, imparerai a:

• Aggiungere runner GitHub con hosting autonomo per supportare un repository GitHub e creare secret di Secret Manager per archiviare in modo sicuro token e secret.

• Eseguire il deployment di un pool di worker di Cloud Run in Cloud Run e utilizzare il pool di worker per accettare i job da GitHub Actions.

• Eseguire il deployment del servizio CREMA di scalabilità automatica per scalare il pool di worker.

• Testare il servizio CREMA verificando i log.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Cloud Build
• Artifact Registry
• Secret Manager
• Cloud Run

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi Google Cloud utenti potrebbero avere diritto a una prova senza costi.

Prima di iniziare

Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Abilita le API Cloud Run, Secret Manager, Parameter Manager, Artifact Registry e Cloud Build.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilita le API

2. Installa e inizializza gcloud CLI.
3. Aggiorna i componenti:

   gcloud components update

4. Imposta le seguenti variabili di configurazione per CREMA utilizzate in questo tutorial:

   PROJECT_ID=PROJECT_ID
   CREMA_SERVICE_ACCOUNT_NAME=crema-service-account@$PROJECT_ID.iam.gserviceaccount.com
   CREMA_REPO_NAME=crema
   AR_REGION=us-central1

   Sostituisci PROJECT_ID con l'ID del tuo Google Cloud progetto.
5. Ti vengono addebitati costi per il servizio di scalabilità di Cloud Run in base alla frequenza con cui attivi la scalabilità. Per ulteriori informazioni, stima i costi con il calcolatore prezzi.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare il tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Amministratore repository Artifact Registry (roles/artifactregistry.repoAdmin)
• Editor Cloud Build (roles/cloudbuild.builds.editor)
• Cloud Run Admin (roles/run.admin)
• Create Service Accounts (roles/iam.serviceAccountCreator)
• Amministratore Secret Manager (roles/secretmanager.admin)
• Utente Service Account (roles/iam.serviceAccountUser)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Storage Admin (roles/storage.admin)
• Amministratore Parameter Manager (roles/parametermanager.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Nota: i ruoli di base IAM potrebbero contenere anche le autorizzazioni per completare il tutorial. Non devi concedere ruoli di base in un ambiente di produzione, ma puoi concederli in un ambiente di sviluppo o di test.

Per configurare i runner con hosting autonomo, devi disporre dell'autorizzazione per modificare le impostazioni di un repository GitHub. Il repository può essere di proprietà dell'utente o di un'organizzazione.

GitHub consiglia di utilizzare i runner con hosting autonomo solo con repository privati.

Crea un account di servizio personalizzato

Questo tutorial utilizza un account di servizio personalizzato con le autorizzazioni minime richieste per utilizzare le risorse di cui è stato eseguito il provisioning. Per configurare il account di servizio, procedi nel seguente modo:

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

Aggiungi runner GitHub con hosting autonomo

Per aggiungere runner GitHub con hosting autonomo, segui le istruzioni riportate in Aggiungere runner con hosting autonomo nella documentazione di GitHub.

Identifica il repository GitHub

In questo tutorial, la variabile GITHUB_REPO rappresenta il nome del repository. Questa è la parte del nome che trovi dopo il nome di dominio sia per i repository degli utenti personali sia per i repository delle organizzazioni. Ad esempio:

• Se l'URL del dominio è https://github.com/myuser/myrepo, il GITHUB_REPO è myuser/myrepo.
• Se l'URL del dominio è https://github.com/mycompany/ourrepo, il GITHUB_REPO è mycompany/ourrepo.

Crea token di accesso

Crea un token di accesso GitHub per aggiungere e rimuovere dinamicamente i runner interagendo con il repository selezionato. Per creare un token di accesso su GitHub e salvarlo in Secret Manager:

1. Assicurati di aver eseguito l'accesso al tuo account GitHub.
2. Vai alla pagina Impostazioni > Impostazioni sviluppatore > Token di accesso personale > Token (classico) di GitHub.
3. Fai clic su Genera nuovo token e seleziona Genera nuovo token (classico).
4. Per l'ambito del token, seleziona la casella di controllo repo.
5. Fai clic su Genera token.
6. Copia il token generato.

Per ulteriori informazioni sui token di accesso, consulta Requisiti di autenticazione in documentazione di GitHub.

Crea un secret per il token di accesso utilizzando Secret Manager

Prendi il token secret creato nel passaggio precedente e archivialo in Secret Manager. Per impostare le autorizzazioni di accesso:

1. Crea il secret in Secret Manager:

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

   Sostituisci GITHUB_TOKEN con il valore che hai copiato da GitHub.

2. Concedi il ruolo roles/secretmanager.secretAccessor al tuo account di servizio personalizzato per accedere al secret appena creato:

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

Esegui il deployment di un pool di worker

Crea un pool di worker di Cloud Run per elaborare GitHub Actions. Questo pool utilizzerà un'immagine basata sull'immagine actions/runner creata da GitHub. Per eseguire il deployment di un pool di worker:

1. Clona il repository di esempio sulla tua macchina locale per recuperare l'esempio di codice da utilizzare:

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

2. Passa alla directory che contiene il codice campione di Cloud Run:

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

3. Esegui il deployment del pool di worker:

   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
   

   Sostituisci quanto segue:

   • WORKER_POOL_NAME: il nome del pool di worker
   • WORKER_POOL_LOCATION: la regione del pool di worker
   • GITHUB_REPO: il nome del repository GitHub

   Se è la prima volta che utilizzi i deployment di origine di Cloud Run in questo progetto, Cloud Run ti chiede di creare un repository Artifact Registry predefinito.

Comprendi l'esempio di codice

Il pool di worker è configurato con un Dockerfile basato sull'immagine actions/runner creata da 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"]

Questo script helper viene eseguito all'avvio del container e si registra nel repository configurato come istanza effimera, utilizzando un token che crei.

# 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 $!

Utilizza il pool di worker per accettare i job da GitHub Actions

L'istanza del pool di worker è pronta per accettare i job da GitHub Actions.

Se il tuo repository non ha ancora GitHub Actions, segui le istruzioni riportate nella guida rapida per creare il tuo primo workflow.

Se il tuo repository ha GitHub Actions, verifica di aver completato la configurazione del runner con hosting autonomo richiamando un'azione GitHub sul repository.

Se la tua azione GitHub non utilizza runner con hosting autonomo, modifica il job di GitHub Actions dal valore runs-on a self-hosted.

Dopo aver configurato un'azione per utilizzare i runner con hosting autonomo, esegui l'azione.

Verifica che l'azione venga completata correttamente nell'interfaccia di GitHub.

Esegui il deployment del servizio CREMA di scalabilità automatica

Hai eseguito il deployment di un worker nel pool originale, che consente di elaborare un'azione alla volta. A seconda dell'utilizzo dell'integrazione continua (CI), potresti dover scalare il pool per gestire un afflusso di lavoro da svolgere.

Dopo aver eseguito il deployment del pool di worker con un runner GitHub attivo, configura il gestore della scalabilità automatica CREMA per eseguire il provisioning delle istanze worker in base allo stato del job nella coda delle azioni.

Questa implementazione è in attesa di un workflow_job evento. Quando crei un job del workflow, il pool di worker viene sottoposto a scale up e, al termine del job, viene sottoposto di nuovo a scale down. Il pool non verrà scalato oltre il numero massimo di istanze configurato e verrà scalato a zero al termine di tutti i job in esecuzione.

Puoi adattare CREMA in base ai tuoi carichi di lavoro.

Configura il gestore della scalabilità automatica

Questo tutorial utilizza il Parameter Manager per archiviare il file di configurazione YAML per CREMA.

1. Crea un parametro in Parameter Manager per archiviare le versioni dei parametri per CREMA:

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

2. Crea un file YAML, my-crema-config.yaml, nella directory principale per definire la configurazione del gestore della scalabilità automatica:

   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
   
   

   Sostituisci quanto segue:

   • PROJECT_ID: l' Google Cloud ID progetto
   • WORKER_POOL_NAME: il nome del pool di worker di cui hai eseguito il deployment
   • GITHUB_RUNNER: il nome del runner GitHub che hai configurato
   • REPOSITORY_OWNER: il proprietario del repository GitHub
   • REPOSITORY_NAME: il nome del repository GitHub

3. Carica il file YAML locale come nuova versione del parametro:

   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
   

Concedi autorizzazioni aggiuntive al tuo account di servizio personalizzato

Per scalare il pool di worker specificato nella configurazione YAML, concedi le seguenti autorizzazioni all'account di servizio personalizzato:

1. Concedi al tuo account di servizio CREMA l'autorizzazione per leggere da Parameter Manager:

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

2. Concedi al tuo account di servizio CREMA il ruolo roles/run.developer nel pool di worker:

   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"
   

   Sostituisci WORKER_POOL_NAME con il nome del pool di worker.

3. Concedi al tuo account di servizio CREMA l'autorizzazione per scrivere le metriche:

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

4. Concedi al tuo account di servizio CREMA il ruolo Utente account di servizio:

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

Esegui il deployment del servizio per scalare i carichi di lavoro

Per eseguire il deployment del servizio per scalare il pool di worker, esegui il comando seguente con un'immagine container predefinita:

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"

Testa il servizio CREMA

Per verificare che il servizio di scalabilità automatica funzioni correttamente, controlla la scheda Log del servizio Cloud Run.

Dovresti visualizzare i seguenti log nei log del servizio ogni volta che le metriche vengono aggiornate:

Ogni messaggio di log è etichettato con il componente che lo ha emesso.

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

Libera spazio

Per evitare addebiti aggiuntivi al tuo Google Cloud account, elimina tutte le risorse di cui hai eseguito il deployment con questo tutorial.

Elimina il progetto

Se hai creato un nuovo progetto per questo tutorial, eliminalo. Se hai utilizzato un progetto esistente e devi conservarlo senza le modifiche aggiunte in questo tutorial, elimina le risorse create per il tutorial.

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella Google Cloud console, vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Elimina le risorse del tutorial

1. Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial. I servizi Cloud Run non comportano costi finché non ricevono richieste.

   Per eliminare il servizio Cloud Run, esegui questo comando:

   gcloud run services delete SERVICE-NAME

   Sostituisci SERVICE-NAME con il nome del tuo servizio.

   Puoi eliminare i servizi Cloud Run anche dalla Google Cloud console.

2. Rimuovi la configurazione della regione predefinita di gcloud che hai aggiunto durante la configurazione del tutorial:

    gcloud config unset run/region
   

3. Rimuovi la configurazione del progetto:

    gcloud config unset project
   

4. Elimina le altre Google Cloud risorse create in questo tutorial:

   • Elimina il pool di worker di Cloud Run
   • Elimina l'immagine container del servizio da Artifact Registry.
   • Elimina l'account di servizio crema-service-account@PROJECT_ID.iam.gserviceaccount.com
   • Elimina i secret in Secret Manager
   • Elimina i parametri in Parameter Manager

Passaggi successivi

• Scopri di più sui pool di worker di Cloud Run.
• Esplora altre demo, tutorial ed esempi di Cloud Run.
• Esegui il deployment del servizio CREMA utilizzando un'immagine container personalizzata creata dal codice sorgente con Cloud Build.