Execute e dimensione executores do GitHub com alojamento próprio em pools de trabalhadores do Cloud Run

Este tutorial mostra como usar executores do GitHub autoalojados em pools de trabalhadores para executar os fluxos de trabalho definidos no seu repositório do GitHub e dimensionar o seu pool de trabalhadores com o dimensionamento automático de métricas externas do Cloud Run (CREMA).

Acerca dos executores do GitHub autoalojados

Num fluxo de trabalho do GitHub Actions, os executores são as máquinas que executam tarefas. Por exemplo, um runner pode clonar o seu repositório localmente, instalar software de testes e, em seguida, executar comandos que avaliam o seu código.

Pode usar executores com alojamento próprio para executar ações do GitHub em instâncias do conjunto de trabalhadores do Cloud Run. Este tutorial mostra-lhe como dimensionar automaticamente um conjunto de executores com base no número de tarefas em execução e não agendadas.

Objetivos

Neste tutorial, vai:

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação sem custo financeiro.

Antes de começar

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

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

  7. Instale e inicialize a CLI gcloud.
  8. Atualize os componentes: 
    gcloud components update
  9. Defina as seguintes variáveis de configuração para o CREMA usado neste 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
     Substitua PROJECT_ID pelo ID do seu Google Cloud projeto.
  10. Incorre em custos pelo seu serviço de escalabilidade do Cloud Run com base na frequência com que aciona a escalabilidade. Para mais informações, estime os custos com a calculadora de preços.

    11. Funções necessárias

    Para receber as autorizações de que precisa para concluir o tutorial, peça ao seu administrador para lhe conceder as seguintes funções de IAM no seu projeto:

    Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

    Precisa de autorização para editar as definições num repositório do GitHub para configurar os executores autoalojados. O repositório pode ser propriedade do utilizador ou de uma organização.

    O GitHub recomenda a utilização de executores autoalojados apenas com repositórios privados.

    Crie uma conta de serviço personalizada

    Este tutorial usa uma conta de serviço personalizada com as autorizações mínimas necessárias para usar os recursos aprovisionados. Para configurar a conta de serviço, faça o seguinte:

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

Adicione executores do GitHub autoalojados

Para adicionar executores do GitHub autoalojados, siga as instruções para adicionar executores autoalojados na documentação do GitHub.

Identifique o repositório do GitHub

Neste tutorial, a variável GITHUB_REPO representa o nome do repositório. Esta é a parte do nome que encontra após o nome do domínio para repositórios de utilizadores pessoais e repositórios de organizações. Por exemplo:

  • Se o URL do seu domínio for https://github.com/myuser/myrepo, o GITHUB_REPO é myuser/myrepo.
  • Se o URL do seu domínio for https://github.com/mycompany/ourrepo, o GITHUB_REPO é mycompany/ourrepo.

Crie uma chave de acesso

Crie um token de acesso do GitHub para adicionar e remover dinamicamente executores através da interação com o repositório selecionado. Para criar um token de acesso no GitHub e guardá-lo no Secret Manager, siga estes passos:

  1. Certifique-se de que tem sessão iniciada na sua conta do GitHub.
  2. Navegue para a página Settings > Developer Settings > Personal Access Tokens > Tokens (classic) do GitHub.
  3. Clique em Gerar novo token e selecione Gerar novo token (clássico).
  4. Para o âmbito do token, selecione a caixa de verificação repo.
  5. Clique em Gerar token.
  6. Copie o símbolo gerado.

Para mais informações sobre tokens de acesso, consulte os requisitos de autenticação na documentação do GitHub.

Crie um segredo para o seu token de acesso através do Secret Manager

Pegue no token secreto que criou no passo anterior e armazene-o no Secret Manager. Para definir autorizações de acesso, siga estes passos:

  1. Crie o Secret no Secret Manager:

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

    Substitua GITHUB_TOKEN pelo valor que copiou do GitHub.

  2. Conceda a função roles/secretmanager.secretAccessor à sua conta de serviço personalizada para aceder ao segredo recém-criado:

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

Implemente um grupo de trabalhadores

Crie um conjunto de trabalhadores do Cloud Run para processar ações do GitHub. Este conjunto vai usar uma imagem baseada na imagem actions/runner criada pelo GitHub. Para implementar um conjunto de trabalhadores, siga estes passos:

  1. Clone o repositório de exemplo para o seu computador local para obter o exemplo de código para utilização:

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

  2. Altere para o diretório que contém o código de exemplo do Cloud Run:

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

  3. Implemente o grupo de trabalhadores:

    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

    Substitua o seguinte:

    • WORKER_POOL_NAME: o nome do conjunto de trabalhadores
    • WORKER_POOL_LOCATION: a região do grupo de trabalhadores
    • GITHUB_REPO: o nome do repositório do GitHub

    Se for a primeira vez que usa implementações de origem do Cloud Run neste projeto, o Cloud Run pede-lhe que crie um repositório do Artifact Registry predefinido.

Compreenda o exemplo de código

O conjunto de trabalhadores está configurado com um Dockerfile baseado na imagem actions/runner criada pelo 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"]

Este script auxiliar é executado quando o contentor é iniciado, registando-se no repositório configurado como uma instância efémera, através de um token que cria.

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

Use o grupo de trabalhadores para aceitar tarefas das ações do GitHub

A sua instância do worker pool está pronta para aceitar tarefas das ações do GitHub.

Se o seu repositório ainda não tiver ações do GitHub, siga as instruções no início rápido para criar o seu primeiro fluxo de trabalho.

Se o seu repositório tiver ações do GitHub, verifique se concluiu a configuração do executável autoalojado invocando uma ação do GitHub no seu repositório.

Se a sua ação do GitHub não usar executores autoalojados, altere a tarefa da ação do GitHub do valor runs-on para self-hosted.

Depois de configurar uma ação para usar os executores autoalojados, execute a ação.

Confirme que a ação é concluída com êxito na interface do GitHub.

Implemente o serviço CREMA do redimensionador automático

Implementou um trabalhador no seu conjunto original, o que permite o processamento de uma ação de cada vez. Consoante a sua utilização da integração contínua (CI), pode ter de dimensionar o seu conjunto para processar um afluxo de trabalho a realizar.

Depois de implementar o conjunto de trabalhadores com um executor do GitHub ativo, configure o escalador automático do CREMA para aprovisionar instâncias de trabalhadores com base no estado da tarefa na fila de ações.

Esta implementação ouve um evento workflow_job. Quando cria uma tarefa de fluxo de trabalho, esta aumenta o número de trabalhadores e, assim que a tarefa é concluída, diminui novamente. Não dimensiona o conjunto além do número máximo de instâncias que configurar e dimensiona para zero quando todas as tarefas em execução estiverem concluídas.

Pode adaptar o CREMA com base nas suas cargas de trabalho.

Configure o redimensionador automático

Este tutorial usa o Parameter Manager para armazenar o ficheiro de configuração YAML para o CREMA.

  1. Crie um parâmetro no Gestor de parâmetros para armazenar versões de parâmetros para o CREMA:

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

  2. Crie um ficheiro YAML, my-crema-config.yaml no diretório principal para definir a configuração do redimensionador automático:

    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

    Substitua o seguinte:

    • PROJECT_ID: o Google Cloud ID do projeto
    • WORKER_POOL_NAME: o nome do conjunto de trabalhadores que implementou
    • GITHUB_RUNNER: o nome do executor do GitHub que configurou
    • REPOSITORY_OWNER: o proprietário do repositório do GitHub
    • REPOSITORY_NAME: o nome do repositório do GitHub

  3. Carregue o ficheiro YAML local como uma nova versão de parâmetros:

    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

Conceda autorizações adicionais à sua conta de serviço personalizada

Para dimensionar o conjunto de trabalhadores especificado na configuração YAML, conceda as seguintes autorizações na conta de serviço personalizada:

  1. Conceda à sua conta de serviço do CREMA autorização para ler a partir do Parameter Manager:

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

  2. Conceda à sua conta de serviço do CREMA a função roles/run.developer no conjunto de trabalhadores:

    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"

    Substitua WORKER_POOL_NAME pelo nome do conjunto de trabalhadores.

  3. Conceda à sua conta de serviço do CREMA autorização para escrever métricas:

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

  4. Conceda à sua conta de serviço do CREMA a função de utilizador da conta de serviço:

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

Implemente o serviço para dimensionar as suas cargas de trabalho

Para implementar o serviço de forma a dimensionar o conjunto de trabalhadores, execute o seguinte comando com uma imagem de contentor pré-criada:

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"

Crie um valor secreto do webhook

Para criar um valor secreto para aceder ao webhook do GitHub, faça o seguinte:

  1. Crie um segredo do Gestor Secreto para gerir o acesso ao seu webhook do GitHub.

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

    Substitua WEBHOOK_SECRET por um valor de string arbitrário.

  2. Conceda acesso ao segredo à conta de serviço do escalador automático:

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

Crie um webhook do GitHub

Para criar o webhook do GitHub, siga estes passos:

  1. Certifique-se de que tem sessão iniciada na sua conta do GitHub.
  2. Navegue para o seu repositório do GitHub.
  3. Clique em Definições.
  4. Em Código e automatização, clique em Webhooks.
  5. Clique em Adicionar webhook.

  6. Introduza os seguintes dados:

    1. Em URL de carga útil, introduza o URL do serviço CREMA do Cloud Run que implementou, my-crema-service.
    2. Para Tipo de conteúdo, selecione application/json.
    3. Em Segredo, introduza o valor WEBHOOK_SECRET que criou anteriormente.
    4. Para a validação de SSL, selecione Ativar validação de SSL.
    5. Em Que eventos quer acionar este webhook?, selecione Permitir-me selecionar eventos individuais.
    6. Na seleção de eventos, selecione Tarefas de fluxo de trabalho. Desmarque qualquer outra opção.
    7. Clique em Adicionar webhook.

Teste o seu serviço CREMA

Para verificar se o serviço de escalamento automático está a funcionar corretamente, consulte o separador Registos do serviço do Cloud Run.

Deve ver os seguintes registos nos registos do seu serviço sempre que as métricas são atualizadas:

Cada mensagem de registo é etiquetada com o componente que a emitiu.

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

Limpar

Para evitar custos adicionais na sua conta Google Cloud , elimine todos os recursos que implementou com este tutorial.

Elimine o projeto

Se criou um novo projeto para este tutorial, elimine-o. Se usou um projeto existente e precisa de o manter sem as alterações que adicionou neste tutorial, elimine os recursos que criou para o tutorial.

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

  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.

Elimine recursos de tutoriais

  1. Elimine o serviço do Cloud Run que implementou neste tutorial. Os serviços do Cloud Run não incorrem em custos até receberem pedidos.

    Para eliminar o seu serviço do Cloud Run, execute o seguinte comando:

    gcloud run services delete SERVICE-NAME

    Substitua SERVICE-NAME pelo nome do seu serviço.

    Também pode eliminar serviços do Cloud Run a partir da Google Cloud consola.

  2. Remova a configuração da região predefinida gcloud que adicionou durante a configuração do tutorial:

     gcloud config unset run/region

  3. Remova a configuração do projeto:

     gcloud config unset project

  4. Elimine outros Google Cloud recursos criados neste tutorial:

O que se segue?