Escalonar automaticamente pools de workers com métricas externas

Nesta página, descrevemos como escalonar automaticamente pools de workers do Cloud Run usando métricas externas orientadas a eventos. O escalonamento automático de métricas externas do Cloud Run (CREMA, na sigla em inglês) ativa essa funcionalidade usando o escalonamento automático orientado por eventos baseado no Kubernetes (KEDA, na sigla em inglês) para escalonar cargas de trabalho com base em fontes de eventos externos.

Para conferir os escalonadores compatíveis e a compatibilidade com o Cloud Run, consulte Escalonamento automático de métricas externas do Cloud Run (CREMA) na documentação do Google Cloud GitHub.

Sobre o serviço de escalonador automático

Para fazer o escalonamento automático de pools de workers, implante o serviço de escalonamento automático do CREMA no Cloud Run. Esse serviço realiza as seguintes ações:

Faz pesquisas em fontes de eventos externos, como tópicos do Apache Kafka ou o GitHub Runner Scaler.
Calcula a contagem de instâncias necessárias com base na configuração YAML.
Atualiza automaticamente a contagem de instâncias do pool de workers.

Antes de começar

Verifique se você configurou um novo projeto para o Cloud Run conforme descrito na página de configuração.

Ative as APIs Artifact Registry, Cloud Build, Cloud Run Admin, Secret Manager e Parameter Manager:

gcloud services enable artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    run.googleapis.com \
    secretmanager.googleapis.com \
    parametermanager.googleapis.com

Configure uma carga de trabalho orientada a eventos ou baseada em solicitações, como executores do GitHub ou Apache Kafka. Para verificar se a origem da sua carga de trabalho é compatível, consulte a lista de compatibilidade do CREMA na documentação do Google Cloud GitHub.
Consulte a calculadora de preços para estimar os custos. Você recebe cobranças pelo serviço de escalonamento do Cloud Run com base na frequência com que aciona o escalonamento.

Funções exigidas

Para receber as permissões necessárias para escalonar automaticamente seu pool de trabalhadores, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Administrador do repositório do Artifact Registry (roles/artifactregistry.repoAdmin)
Editor do Cloud Build (roles/cloudbuild.builds.editor)
Administrador do Cloud Run (roles/run.admin)
Criar contas de serviço (roles/iam.serviceAccountCreator)
Administrador do Secret Manager (roles/secretmanager.admin)
Usuário da conta de serviço (roles/iam.serviceAccountUser)
Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
Administrador de armazenamento (roles/storage.admin)
Administrador do Parameter Manager (roles/parametermanager.admin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar uma conta de serviço personalizada

Crie uma conta de serviço personalizada com as permissões mínimas necessárias para usar os recursos provisionados exigidos pela sua carga de trabalho. Para configurar a conta de serviço, faça o seguinte:

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

Substitua CREMA_SERVICE_ACCOUNT por um nome para sua conta de serviço personalizada, por exemplo, crema-service-account. Esse comando cria uma conta de serviço que segue o formato crema-service-account@example-project.iam.gserviceaccount.com.

Criar o arquivo de configuração do CREMA

Para definir a lógica de escalonamento, crie um arquivo de configuração YAML no diretório raiz. Esse arquivo instrui o serviço CREMA sobre quais fontes externas monitorar, como autenticar com os recursos e quais pools de trabalhadores escalonar.

Exemplo de YAML

O exemplo a seguir mostra o arquivo de configuração para escalonar um pool de trabalhadores do Cloud Run (example-workerpool) usando as métricas do GitHub Runner. Ele usa um secret do Secret Manager chamado github_runner_token para autenticar com o GitHub e ler as métricas.

  apiVersion: crema/v1
  kind: CremaConfig
  metadata:
    name: gh-demo
  spec:
    triggerAuthentications:
      - metadata:
          name: github-trigger-auth
        spec:
          gcpSecretManager:
            secrets:
              - parameter: personalAccessToken
                id: github_runner_token
                version: latest
    scaledObjects:
      - spec:
          scaleTargetRef:
            name: projects/example-project/locations/us-central1/workerpools/example-workerpool
          triggers:
            - type: github-runner
              name: example-runner
              metadata:
                owner: repo-owner
                runnerScope: repo
                repos: repo-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
        pollingInterval: 10

A configuração YAML usa os seguintes parâmetros de alto nível:

triggerAuthentications: determina como o CREMA autentica o serviço externo, como usando um token armazenado no Secret Manager.
scaledObjects: define o mapeamento entre seu pool de workers do Cloud Run e o recurso de métrica externa. Esse parâmetro inclui:
- scaleTargetRef: os serviços do Cloud Run ou pools de worker a serem escalonados.
- triggers: a métrica externa específica usada para escalonamento. Se a fonte de métricas externa exigir autenticação, defina o campo authenticationRef para especificar um dos objetos TriggerAuthentications de credenciais.
pollingInterval: controla o intervalo (em segundos) em que o CREMA atualiza as métricas. Se você omitir esse parâmetro, o CREMA não fará pesquisas automáticas, e será necessário acionar uma verificação de escalonamento manualmente usando uma solicitação POST ao serviço.

Para mais informações sobre como definir métricas de configuração básicas e avançadas, consulte Referência de configuração na documentação do Google Cloud GitHub.

Para conferir a lista completa de definições de configuração dos seus escalonadores compatíveis, consulte Escalonadores na documentação do KEDA.

Armazenar sua configuração do CREMA no Gerenciador de parâmetros

Para armazenar versões de parâmetros para o serviço de escalonamento automático do CREMA, siga estas etapas:

Crie um parâmetro no Gerenciador de parâmetros:

gcloud parametermanager parameters create PARAMETER_ID --location=global  --parameter-format=YAML

Substitua PARAMETER_ID pelo nome do seu parâmetro.

Faça upload do arquivo YAML local como uma nova versão de parâmetro:
```
gcloud parametermanager parameters versions create PARAMETER_VERSION \
  --location=global \
  --parameter=PARAMETER_ID \
  --payload-data-from-file=LOCAL_YAML_CONFIG_FILE
```
Substitua:
- PARAMETER_VERSION: o ID que você quer atribuir à versão do parâmetro, por exemplo, 1.
- LOCAL_YAML_CONFIG_FILE: o caminho para o arquivo de configuração YAML.

Para mais informações, consulte Criar um parâmetro.

Conceder outras permissões à sua conta de serviço do CREMA

Para escalonar o pool de workers especificado na configuração YAML, conceda as seguintes permissões na conta de serviço personalizada:

Conceda à sua conta de serviço do CREMA permissão para ler do Gerenciador de parâmetros:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:CREMA_SERVICE_ACCOUNT_NAME \
  --role="roles/parametermanager.parameterViewer"
```
Substitua:
- PROJECT_ID: o ID do seu projeto do Google Cloud .
- CREMA_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço do CREMA.
Conceda à conta de serviço do CREMA o papel roles/run.developer no pool de workers. Isso permite que o serviço CREMA modifique a contagem de instâncias do pool de workers em resposta à mudança de métricas:
```
WORKER_POOL_NAME=WORKER_POOL_NAME
WORKER_POOL_REGION=WORKER_POOL_REGION
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: o nome do pool de workers.
- WORKER_POOL_REGION: a região do pool de workers.

Conceda à sua conta de serviço do CREMA permissão para gravar métricas:

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

Conceda à sua conta de serviço do CREMA o função do usuário da conta de serviço:

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

Implante o serviço para escalonar suas cargas de trabalho

Para implantar o serviço e escalonar o pool de workers, execute o seguinte comando com uma imagem de contêiner pré-criada:

gcloud beta run deploy SERVICE_NAME\
  --image=us-central1-docker.pkg.dev/cloud-run-oss-images/crema-v1/autoscaler:1.0 \
  --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=projects/PROJECT_ID/locations/PARAMETER_REGION/parameters/PARAMETER_ID/versions/PARAMETER_VERSION,OUTPUT_SCALER_METRICS=True"

Substitua:

SERVICE_NAME: o nome do serviço de escalonador automático.
SERVICE_REGION: a região do serviço.
CREMA_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço do CREMA.
PROJECT_ID: o ID do seu projeto do Google Cloud .
PARAMETER_REGION, PARAMETER_ID e PARAMETER_VERSION: valores que você armazenou no Gerenciador de parâmetros.

Também é possível implantar o serviço CREMA usando uma imagem de contêiner personalizada criada com base no código-fonte usando o Cloud Build.

Testar seu serviço do CREMA

Para verificar se o serviço de escalonamento automático está funcionando corretamente, confira a guia Registros do serviço do Cloud Run.

Os seguintes registros vão aparecer nos registros do serviço sempre que as métricas forem atualizadas:

Cada mensagem de registro é rotulada 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 ...

A seguir

Saiba como usar executores do GitHub autohospedados em pools de trabalhadores para executar os fluxos de trabalho definidos no seu repositório do GitHub e escalonar seu pool de trabalhadores com o CREMA.
Saiba mais sobre os pools de workers do Cloud Run.