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

Anteprima — Cloud Run External Metrics Autoscaling (CREMA)

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Anteprima — Cloud Run worker pools

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Questo tutorial mostra come utilizzare i runner GitHub self-hosted nei pool di worker per eseguire i workflow definiti nel repository GitHub e scalare il pool di worker con Cloud Run External Metrics Autoscaling (CREMA).

Informazioni sui runner GitHub self-hosted

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

Puoi utilizzare i runner self-hosted per eseguire GitHub Actions sulle istanze del pool di worker 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:

• Aggiungi runner GitHub self-hosted per supportare un repository GitHub e crea secret di Secret Manager per archiviare in modo sicuro token e secret.

• Esegui il deployment di un pool di worker Cloud Run in Cloud Run e utilizza il pool di worker per accettare i job dalle azioni di GitHub.

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

• Testa 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 utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Prima di iniziare

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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. Enable the Cloud Run, Secret Manager, Parameter Manager, Artifact Registry, and Cloud Build APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

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 progetto Google Cloud .
5. I costi del servizio di scalabilità di Cloud Run vengono addebitati in base alla frequenza con cui attivi lo scaling. 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 tuo progetto:

• Amministratore repository Artifact Registry (roles/artifactregistry.repoAdmin)
• Editor Cloud Build (roles/cloudbuild.builds.editor)
• Cloud Run Admin (roles/run.admin)
• Crea service account (roles/iam.serviceAccountCreator)
• Amministratore Secret Manager (roles/secretmanager.admin)
• Utente Service Account (roles/iam.serviceAccountUser)
• Consumer Service Usage (roles/serviceusage.serviceUsageConsumer)
• Storage Admin (roles/storage.admin)
• Parameter Manager Admin (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 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 test.

Per configurare i runner self-hosted, 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 runner self-hosted 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:

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

Aggiungere runner GitHub con hosting autonomo

Per aggiungere runner GitHub self-hosted, segui le istruzioni riportate in Aggiunta di runner self-hosted 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 quelli dell'organizzazione. 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, segui questi passaggi:

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 maggiori informazioni sui token di accesso, consulta la sezione Requisiti di autenticazione nella documentazione di GitHub.

Crea un secret per il token di accesso utilizzando Secret Manager

Prendi il token segreto che hai 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 worker pool

Crea un pool di worker Cloud Run per elaborare le azioni di GitHub. 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 worker pool:

   gcloud beta 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 dell'origine Cloud Run in questo progetto, Cloud Run ti chiede di creare un repository Artifact Registry predefinito.

Comprendere il 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.330.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, registrandosi nel repository configurato come istanza effimera, utilizzando un token creato.

# 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 dalle azioni di GitHub

L'istanza del pool di worker è pronta per accettare i job dalle azioni di GitHub.

Se il tuo repository non ha ancora azioni GitHub, segui le istruzioni della guida rapida per creare il tuo primo flusso di lavoro.

Se il tuo repository ha azioni GitHub, verifica di aver completato la configurazione del runner self-hosted richiamando un'azione GitHub sul tuo repository.

Se l'azione GitHub non utilizza runner self-hosted, modifica il job dell'azione GitHub dal valore runs-on a self-hosted.

Dopo aver configurato un'azione per utilizzare i runner self-hosted, esegui l'azione.

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

Esegui il deployment del servizio di scalabilità automatica CREMA

Hai eseguito il deployment di un worker nel pool originale, il che consente l'elaborazione di 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 ascolto di un evento workflow_job. Quando crei un job del flusso di lavoro, il pool di worker viene scalato e, una volta completato il job, viene ridimensionato di nuovo. Non esegue lo scale up del pool oltre il numero massimo di istanze che configuri e lo riduce a zero quando tutti i job in esecuzione sono stati completati.

Puoi adattare CREMA in base ai tuoi workload.

Configura lo scalatore automatico

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

1. Crea un parametro in Gestore dei parametri 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 dello scalatore automatico:

   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 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 di lettura 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 beta 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 account di servizio CREMA l'autorizzazione a scrivere 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 questo comando 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 beta 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-22/runtimes/java21 \
  --labels=created-by=crema \
  --set-env-vars="CREMA_CONFIG=${CREMA_CONFIG_PARAM_VERSION},OUTPUT_SCALER_METRICS=True"

Crea il valore del secret webhook

Per creare un valore secret per accedere al webhook GitHub:

1. Crea un secret di Secret Manager per gestire l'accesso al webhook GitHub.

   echo -n "WEBHOOK_SECRET" | gcloud secrets create github_webhook_secret --data-file=-
   

   Sostituisci WEBHOOK_SECRET con un valore stringa arbitrario.

2. Concedi l'accesso al secret al account di servizio dello strumento di scalabilità automatica:

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

Crea webhook GitHub

Per creare il webhook GitHub:

1. Assicurati di aver eseguito l'accesso al tuo account GitHub.
2. Vai al tuo repository GitHub.
3. Fai clic su Impostazioni.
4. Nella sezione Codice e automazione, fai clic su Webhook.
5. Fai clic su Aggiungi webhook.

6. Inserisci quanto segue:

   1. In URL payload, inserisci l'URL del servizio Cloud Run CREMA che hai implementato, my-crema-service.
   2. Per Tipo di contenuti, seleziona application/json.
   3. In Secret, inserisci il valore WEBHOOK_SECRET che hai creato in precedenza.
   4. In Verifica SSL, seleziona Attiva verifica SSL.
   5. Per Quali eventi vuoi che attivino questo webhook?, seleziona Consenti la selezione di singoli eventi.
   6. Nella selezione degli eventi, seleziona Job del workflow. Deseleziona qualsiasi altra opzione.
   7. Fai clic su Aggiungi webhook.

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

Esegui la pulizia

Per evitare addebiti aggiuntivi al tuo account Google Cloud , elimina tutte le risorse che hai implementato 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 che hai aggiunto in questo tutorial, elimina le risorse che hai creato per il tutorial.

Il modo più semplice per eliminare la fatturazione è eliminare il progetto 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. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

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

   Puoi eliminare i servizi Cloud Run anche dalla consoleGoogle Cloud .

2. Rimuovi la configurazione della regione predefinita 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 worker pool Cloud Run
   • Elimina l'immagine container del servizio da Artifact Registry.
   • Elimina il account di servizio crema-service-account@PROJECT_ID.iam.gserviceaccount.com
   • Elimina i secret in Secret Manager
   • Eliminare i parametri in Parameter Manager

Passaggi successivi

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