Escalonamento manual

Nesta página, descrevemos como escalonar seu serviço manualmente. Ele também fornece instruções para um caso de uso comum: mudar a contagem de instâncias com base em uma programação usando jobs do Cloud Scheduler e a API Cloud Run Admin.

Visão geral

Por padrão, o Cloud Run faz o escalonamento horizontal automático para um número máximo especificado ou padrão de instâncias, dependendo do tráfego e da utilização da CPU. No entanto, em alguns casos de uso, talvez seja necessário definir um número específico de instâncias usando o escalonamento manual.

Com o escalonamento manual, é possível definir uma contagem específica de instâncias, independente do tráfego ou da utilização, sem precisar fazer uma nova implantação. Tudo isso oferece a opção de escrever sua própria lógica de escalonamento usando um sistema externo. Consulte Escalonamento com base em programação para um exemplo.

Configurações mínimas e máximas no nível da revisão e escalonamento manual

Se você definir o escalonamento manual para o serviço, as configurações de instâncias mínimas e máximas no nível da revisão serão ignoradas.

Divisão de tráfego para escalonamento manual

A lista a seguir descreve como as instâncias são alocadas ao dividir o tráfego com escalonamento manual. Isso inclui o comportamento de revisões somente com tag de tráfego.

  • Durante uma divisão de tráfego, cada revisão recebe instâncias proporcionalmente, com base na divisão de tráfego, semelhante à divisão de tráfego com instâncias mínimas no nível de serviço.

  • Se o número de revisões que recebem tráfego exceder a contagem manual de instâncias, algumas revisões não terão instâncias. O tráfego enviado a essas revisões receberá o mesmo erro que se elas estivessem desativadas.

  • Para todas as revisões que recebem tráfego em uma divisão de tráfego, as instâncias mínimas e máximas no nível da revisão são desativadas.

  • Se uma revisão estiver ativa apenas devido a tags de tráfego:

    • Se o número mínimo de instâncias no nível da revisão estiver definido, o número especificado de instâncias será iniciado, mas não será contabilizado na contagem total de instâncias manuais do serviço. A revisão não será escalonada automaticamente.
    • Se o número mínimo de instâncias no nível da revisão não estiver definido, a revisão será escalonada para no máximo uma instância, em resposta ao tráfego enviado para o URL da tag.

Comportamento de faturamento usando o escalonamento manual

Ao usar o escalonamento manual, o comportamento de faturamento é semelhante ao do recurso instâncias mínimas.

Ou seja, com o escalonamento manual e o faturamento baseado em instâncias, as instâncias inativas escalonadas manualmente são faturadas como instâncias ativas.

Se você usar o escalonamento manual com faturamento com base em solicitações, as instâncias inativas escalonadas manualmente serão cobradas como instâncias mínimas inativas. Para detalhes completos sobre faturamento, consulte a página de preços.

Funções exigidas

Para receber as permissões necessárias para implantar os serviços do Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se o serviço do Cloud Run interage com APIsGoogle Cloud , como as bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.

Configurar o escalonamento manual

É possível configurar o modo de escalonamento usando o console Google Cloud , a Google Cloud CLI, o arquivo YAML ou a API ao criar um serviço ou atualizar uma revisão:

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Se você estiver configurando um novo serviço, clique em Implantar contêiner para mostrar o formulário Criar serviço. Se você estiver configurando um serviço atual, clique nele para exibir o painel de detalhes e, em seguida, clique no ícone de caneta ao lado de Escalonamento no canto superior direito do painel de detalhes.

  3. Localize o formulário Escalonamento de serviço (para um novo serviço) ou o formulário Editar escalonamento para um serviço atual.

    imagem

    No campo Número de instâncias, especifique o número de instâncias de contêiner para o serviço.

  4. Clique em Criar para um novo serviço ou em Salvar para um serviço atual.

gcloud

Para especificar o escalonamento de um novo serviço, use o comando deploy:

gcloud run deploy SERVICE \
    --scaling=INSTANCE_COUNT \
    --image IMAGE_URL

Substitua:

  • SERVICE: o nome do serviço.
  • INSTANCE_COUNT: o número de instâncias do serviço. Isso define o serviço para escalonamento manual. Especifique um valor de 0 para desativar o serviço. Especifique um valor de auto para usar o comportamento padrão de escalonamento automático do Cloud Run.
  • IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

Especifique o escalonamento de um serviço usando o seguinte comando de atualização:

gcloud run services update SERVICE \
   --scaling=INSTANCE_COUNT

YAML

  1. Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Atualize os atributos scalingMode e manualInstanceCount:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
  run.googleapis.com/scalingMode: MODE
  run.googleapis.com/manualInstanceCount: INSTANCE_COUNT

    Substitua:

    • SERVICE: o nome do seu serviço do Cloud Run
    • MODE: manual para escalonamento manual ou automatic para o comportamento de escalonamento automático padrão do Cloud Run.
    • INSTANCE_COUNT: o número de instâncias que você está escalonando manualmente para o serviço. Especifique um valor de 0 para desativar o serviço.

  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run services replace service.yaml

API REST

Para atualizar as instâncias mínimas no nível do serviço de um determinado serviço, envie uma solicitação HTTP PATCH para o endpoint service da API Cloud Run Admin.

Por exemplo, usando curl:

    curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -X PATCH \
    -d '{"scaling":{"manualInstanceCount":MANUAL_INSTANCE_COUNT }}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE?update_mask=scaling.manualInstanceCount

Substitua:

  • ACCESS_TOKEN: um token de acesso válido para uma conta com as permissões do IAM para atualizar um serviço. Por exemplo, se você fez login em gcloud, é possível recuperar um token de acesso usando gcloud auth print-access-token. Em uma instância de contêiner do Cloud Run, é possível recuperar um token de acesso por meio do servidor de metadados da instância de contêiner.
  • MANUAL_INSTANCE_COUNT: o número de instâncias do serviço. Isso define o serviço para escalonamento manual. Especifique um valor de 0 para desativar o serviço.
  • SERVICE: o nome do serviço.
  • REGION: a região Google Cloud em que o serviço está implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Para mudar o modo de escalonamento de manual para automático, envie uma solicitação PATCH ao endpoint service da API Cloud Run Admin e defina o campo scalingMode como AUTOMATIC.

Por exemplo, execute o seguinte comando curl:

      curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      -X PATCH \
      -d '{"launchStage":"BETA","scaling":{"scalingMode": "AUTOMATIC","manualInstanceCount":null}}' \
      https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE?update_mask=launchStage,scaling.scalingMode,scaling.manualInstanceCount

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Adicione o seguinte a um recurso google_cloud_run_v2_service na configuração do Terraform:
resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE_NAME"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }
  scaling {
    scaling_mode = "MANUAL"
    manual_instance_count = "INSTANCE_COUNT"
  }
}

Substitua:

  • SERVICE_NAME: o nome do seu serviço do Cloud Run.
  • REGION: a Google Cloud região. Por exemplo, europe-west1.
  • IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
  • INSTANCE_COUNT: o número de instâncias que você está escalonando manualmente para o serviço. Esse número de instâncias é dividido entre todas as revisões com tráfego especificado com base na porcentagem de tráfego que elas estão recebendo.

Ver a configuração de escalonamento do serviço

Para conferir as instâncias de configuração de escalonamento do serviço do Cloud Run:

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique no serviço de seu interesse para abrir o painel Detalhes do serviço.

  3. A configuração de escalonamento atual é mostrada no canto superior direito do painel de detalhes do serviço, depois do rótulo Escalonamento, ao lado do ícone de caneta.

gcloud

Use o comando a seguir para conferir a configuração de escalonamento atual do serviço:

gcloud run services describe SERVICE

SERVICE pelo nome do serviço;

Procure o campo Scaling: Manual (Instances: ) perto da parte de cima do texto retornado pelo describe.

YAML

Use o comando a seguir para baixar a configuração YAML do serviço:

gcloud run services describe SERVICE --format export > service.yaml

A configuração de escalonamento está contida nos atributos scalingMode e manualInstanceCount.

Desativar um serviço

Quando você desativa um serviço, todas as solicitações em processamento são concluídas. No entanto, outras solicitações para o URL do serviço vão falhar com um erro Service unavailable ou Service disabled.

As solicitações para revisões de serviço que estão ativas apenas devido a tags de tráfego não são afetadas porque essas revisões não são desativadas.

Para desativar um serviço, defina o escalonamento como zero. É possível desativar um serviço usando o console Google Cloud , a Google Cloud CLI, um arquivo YAML ou a API:

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique no serviço que você quer desativar para exibir o painel de detalhes e, em seguida, clique no ícone de caneta ao lado de Escalonamento no canto superior direito do painel de detalhes.

  3. Localize o formulário Editar escalonamento e selecione Escalonamento manual.

    imagem

    No campo Número de instâncias, insira o valor 0 (zero).

  4. Clique em Salvar.

gcloud

Para desativar um serviço, use o seguinte comando para definir o escalonamento como zero:

gcloud run services update SERVICE --scaling=0

SERVICE pelo nome do serviço;

YAML

  1. Faça o download da configuração YAML do serviço:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Defina o atributo manualInstanceCount como zero (0):

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
  run.googleapis.com/scalingMode: manual
  run.googleapis.com/manualInstanceCount: `0`

    Substitua SERVICE pelo nome do serviço do Cloud Run.

  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run services replace service.yaml

API REST

Para desativar um serviço, envie uma solicitação HTTP PATCH ao endpoint service da API Cloud Run Admin.

Por exemplo, usando curl:

    curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -X PATCH \
    -d '{"scaling":{"manualInstanceCount":0 }}' \
    https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE?update_mask=scaling.manualInstanceCount

Substitua:

  • ACCESS_TOKEN: um token de acesso válido para uma conta com as permissões do IAM para atualizar um serviço. Por exemplo, se você fez login em gcloud, é possível recuperar um token de acesso usando gcloud auth print-access-token. Em uma instância de contêiner do Cloud Run, é possível recuperar um token de acesso por meio do servidor de metadados da instância de contêiner.
  • SERVICE: o nome do serviço.
  • REGION: a região Google Cloud em que o serviço está implantado.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Terraform

Para desativar um serviço, defina o atributo manual_instance_count como zero (0):

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE_NAME"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
    }
  }
  scaling {
    scaling_mode = "MANUAL"
    manual_instance_count = "0"
  }
}

Substitua:

  • SERVICE_NAME: o nome do seu serviço do Cloud Run.
  • REGION: a Google Cloud região. Por exemplo, europe-west1.
  • IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

Exemplo de escalonamento com base em programação

Um caso de uso comum do escalonamento manual é mudar a contagem de instâncias com base em uma programação predefinida. Neste exemplo, usamos o Cloud Scheduler para programar dois jobs, cada um deles invocando a API Cloud Run Admin para escalonar o número de instâncias. O primeiro job do Cloud Scheduler define o escalonamento manual do serviço para um número especificado de instâncias durante o horário comercial (9h às 17h, de segunda a sexta-feira). O segundo job define o serviço para reduzir escala vertical para um número especificado de instâncias durante o horário de folga.

Neste exemplo, usamos o guia de início rápido do Cloud Run por simplicidade, mas é possível usar um serviço de sua escolha.

Para configurar o escalonamento manual com base em programação:

  1. Implante o serviço usando o seguinte comando:

    gcloud run deploy SERVICE \
   --image=us-docker.pkg.dev/cloudrun/container/hello \
   --region=REGION \
   --project PROJECT_ID

    Substitua:

    • SERVICE: o nome do serviço do Cloud Run.
    • REGION: a região em que o serviço do Cloud Run é implantado.
    • PROJECT_ID: o ID do projeto do Google Cloud .

  2. Configure o serviço para escalonamento manual em 10 instâncias usando o seguinte comando:

    gcloud run services update SERVICE \
   --region=REGION \
   --scaling=10

  3. Crie um job do Cloud Scheduler que faça escalonamento manual para um número especificado de instâncias de serviço durante o horário comercial:

    gcloud scheduler jobs create http hello-start-instances \
  --location=REGION \
  --schedule="0 9 * * MON-FRI" \
  --time-zone=America/Los_Angeles \
  --uri=https://run.googleapis.com/v2/projects/PROJECT_ID/
  locations/REGION/services/hello?update_mask=launchStage,scaling.manualInstanceCount \
  --headers=Content-Type=application/json,X-HTTP-Method-Override=PATCH \
  --http-method=PUT \
  --message-body='{"scaling":{"manualInstanceCount":INSTANCE_COUNT}}' \
  --oauth-service-account-email=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua:

    • REGION: a região em que o serviço do Cloud Run é implantado.
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • INSTANCE_COUNT: o número de instâncias para escalonar. Por exemplo, 10.
    • PROJECT_NUMBER: o número do projeto Google Cloud .

    Esse comando cria um job do Cloud Scheduler que faz uma chamada HTTP para a API Cloud Run Admin, definindo o número de instâncias como o número especificado. O exemplo usa a conta de serviço padrão do Compute Engine PROJECT_NUMBER-compute@developer.gserviceaccount.com para os jobs do Cloud Scheduler. Você pode usar qualquer conta de serviço que tenha permissões para atualizar serviços do Cloud Run.

  4. Crie um job do Cloud Scheduler que reduza manualmente as instâncias de serviço durante o horário de folga:

    gcloud scheduler jobs create http hello-stop-instances \
  --location=REGION \
  --schedule="0 17 * * MON-FRI" \
  --time-zone=America/Los_Angeles \
  --uri=https://run.googleapis.com/v2/projects/PROJECT_ID/
  locations/REGION/services/hello?update_mask=launchStage,scaling.manualInstanceCount \
  --headers=Content-Type=application/json,X-HTTP-Method-Override=PATCH \
  --http-method=PUT \
  --message-body='{"scaling":{"manualInstanceCount":INSTANCE_COUNT}}' \
  --oauth-service-account-email=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua:

    • REGION: a região em que o serviço do Cloud Run é implantado.
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • INSTANCE_COUNT: o número de instâncias para escalonar. Para desativar o serviço, defina como 0.
    • PROJECT_NUMBER: o número do projeto Google Cloud .

    Esse comando cria um job do Cloud Scheduler que faz uma chamada HTTP para a API Cloud Run Admin, definindo instâncias de escalonamento manual para o número de instâncias especificado. Definir as instâncias como zero desativa o serviço, mas não os jobs do Cloud Scheduler. Esses jobs continuam sendo executados e vão redefinir (e reativar) o serviço para um número maior de instâncias conforme programado.