Definir instâncias mínimas (serviços)

Nesta página, descrevemos como ativar instâncias inativas para seu serviço usando as configurações mínimas de instâncias.

Para serviços do Cloud Run, o Cloud Run por padrão balança no número de instâncias com base no número de solicitações recebidas. No entanto, se o serviço requer latência reduzida, especialmente ao escalonar de zero instâncias ativas, é possível alterar esse comportamento padrão especificando um número mínimo de instâncias de contêiner a serem mantidas em modo de espera e prontas para atender a solicitações. Consulte as dicas gerais de desenvolvimento para mais detalhes sobre essa otimização.

O Cloud Run remove instâncias que não estão atendendo solicitações (inativas). Com o número mínimo de instâncias definido, o Cloud Run mantém pelo menos o número mínimo de instâncias em execução, mesmo que elas não estejam atendendo solicitações. As instâncias ativas acima do número min-instances podem ficar inativas se não estiverem recebendo solicitações.

Por exemplo, se min-instances for 10 e o número de instâncias ativas for 0, o número de instâncias inativas será 10. Quando o número de instâncias ativas aumenta para 6, o número de instâncias inativas diminui para 4.

Como aplicar instâncias mínimas no nível de serviço em comparação com o nível de revisão

É possível configurar instâncias mínimas no nível de serviço ou de revisão. O Google recomenda que você aplique instâncias mínimas no nível de serviço e evite combinar instâncias mínimas no nível de serviço e de revisão.

Se você aplicar instâncias mínimas no nível da revisão, as configurações entrarão em vigor após a implantação da revisão. Se você aplicar esse recurso no nível de serviço, a configuração entrará em vigor sem precisar implantar uma nova revisão.

Revisões marcadas e instâncias mínimas no nível de serviço

As revisões marcadas são iniciadas, mas só contam para as instâncias mínimas no nível de serviço se fizerem parte de uma divisão de tráfego.

Faturamento

As instâncias que permanecem em execução com o recurso de instâncias mínimas geram custos de faturamento. Como essas cobranças são muito previsíveis, o Google recomenda a compra de um desconto por compromisso de uso.

Instâncias mínimas e CPU sempre alocada

Configure a CPU para que ela seja sempre alocada se você precisar de CPU fora das solicitações.

Reinicializações de instâncias mínimas

É possível reiniciar as instâncias mínimas a qualquer momento.

Revisões e instâncias mínimas

Quando as instâncias mínimas são definidas no nível de serviço, elas são distribuídas para todas as revisões que veiculam tráfego proporcionalmente à divisão de tráfego.

Quando o mínimo de instâncias é definido no nível da revisão, elas são iniciadas sempre que a revisão é referenciada em uma divisão de tráfego (mesmo em 0%) ou tem uma tag de tráfego atribuída.

Funções exigidas

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

Desenvolvedor do Cloud Run (roles/run.developer) no serviço Cloud Run
Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço

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 as APIs do Google 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.

Como definir e atualizar instâncias mínimas no nível de serviço

Por padrão, as instâncias de contêiner têm instâncias mínimas no nível de serviço desativadas, com uma configuração de 0. É possível alterar esse padrão usando o console do Google Cloud, a CLI do Google Cloud ou um arquivo YAML:

Console

No console do Google Cloud, acesse o Cloud Run:

Acessar o Cloud Run
Se você estiver configurando um novo serviço, clique em Implantar contêiner e selecione Serviço 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 Min instâncias no canto superior direito do painel de detalhes.
Localize o formulário Escalonamento automático de serviços.
- No campo Número mínimo de instâncias, especifique o valor de instâncias de contêiner a serem mantidas quentes e prontas para receber solicitações.
Clique em Criar para um novo serviço ou em Implantar para um serviço atual.

gcloud

Atualize o service-min-instances para um determinado serviço usando o seguinte comando:

gcloud run services update SERVICE --service-min-instances MIN-VALUE

Substitua:

SERVICE pelo nome do serviço;
MIN-VALUE pelo número de instâncias de contêiner a serem mantidas quentes e prontas para receber solicitações. Especifique default para limpar qualquer configuração mínima de instância.

Como alternativa, é possível definir service-min-instances durante a implantação usando o comando:

gcloud run deploy --image IMAGE_URL --service-min-instances MIN-VALUE

Substituir

IMAGE_URL por 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 tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
MIN-VALUE pelo número de instâncias de contêiner a serem mantidas quentes e prontas para receber solicitações. Especifique default para limpar qualquer configuração mínima de instância.

YAML

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
```
Atualize o atributo run.googleapis.com/minScale:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/minScale: 'MIN_INSTANCE'
```
Substitua:
- SERVICE pelo nome do serviço do Cloud Run;
- MIN-INSTANCE pelo número de instâncias a serem mantidas quentes e prontas para receber solicitações.
Crie ou atualize o serviço usando o seguinte comando:
```
gcloud run services replace service.yaml
```

Bibliotecas de cliente

Para atualizar instâncias mínimas de nível de serviço para seu serviço a partir do código:

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": { "minInstanceCount": MIN-VALUE }}' \
https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE?update_mask=scaling.minInstanceCount

Substitua:

ACCESS_TOKEN por 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.
MIN-VALUE pelo número de instâncias de contêiner a serem mantidas quentes e prontas para receber solicitações.
SERVICE pelo nome do serviço;
REGION pela região do Google Cloud do serviço.
PROJECT-ID pelo ID do projeto do Google Cloud.

Mostrar instâncias mínimas no nível de serviço

Para ver as configurações mínimas de instâncias mínimas no nível de serviço atuais do serviço do Cloud Run:

Console

No console do Google Cloud, acesse o Cloud Run:

Acessar o Cloud Run
Clique no serviço de seu interesse para abrir o painel Detalhes do serviço.
A configuração atual é mostrada no canto superior direito do painel de detalhes do serviço, ao lado de Mínimo de instâncias.

gcloud

Use o comando a seguir:
```
gcloud run services describe SERVICE
```
Localize o valor de Instâncias mínimas no nível de serviço: na configuração retornada.

Como definir e atualizar instâncias mínimas no nível de revisão

Qualquer mudança na configuração leva à criação de uma nova revisão. As próximas revisões também receberão automaticamente essa configuração, a menos que você faça atualizações explícitas para alterá-la.

Por padrão, as instâncias de contêiner têm min-instances desativado, com uma configuração de 0. É possível alterar esse padrão usando o console do Google Cloud, a CLI do Google Cloud ou um arquivo YAML ao criar um novo serviço ou implantar uma nova revisão:

Console

No console do Google Cloud, acesse o Cloud Run:

Acessar o Cloud Run
Clique em Implantar contêiner e selecione Serviço para configurar um novo serviço. Se você estiver configurando um serviço atual, clique nele e em Editar e implantar nova revisão.
Ao configurar um novo serviço, preencha a página inicial de configurações de serviço conforme preferir e clique em Contêineres, volumes, redes e segurança para expandir essa página.
Clique na guia Contêiner.
- No campo Número mínimo de instâncias, especifique o valor de instâncias de contêiner a serem mantidas quentes e prontas para receber solicitações.
Clique em Criar ou Implantar.

gcloud

É possível atualizar o valor de min-instance de um determinado serviço usando o seguinte comando:

gcloud run services update SERVICE --min-instances MIN-VALUE

Substitua:

SERVICE pelo nome do serviço;
MIN-VALUE pelo número de instâncias de contêiner a serem mantidas quentes e prontas para receber solicitações. Especifique default para limpar qualquer configuração mínima de instância.

Também é possível definir min-instance durante a implantação usando este comando:

gcloud run deploy --image IMAGE_URL --min-instances MIN-VALUE

Substitua:

IMAGE_URL por 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 tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
MIN-VALUE pelo número de instâncias de contêiner a serem mantidas quentes e prontas para receber solicitações. Especifique default para limpar qualquer configuração mínima de instância.

YAML

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
```
Atualize o atributo autoscaling.knative.dev/minScale::
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/minScale: 'MIN-INSTANCE'
      name: REVISION
```
Substitua:
- SERVICE pelo nome do serviço do Cloud Run;
- MIN-INSTANCE pelo número de instâncias a serem mantidas quentes e prontas para receber solicitações.
- REVISION por um novo nome de revisão ou excluí-lo (se houver). Se você fornecer um novo nome de revisão, ele precisará atender aos seguintes critérios:
  - Começa com SERVICE-
  - Contém apenas letras minúsculas, números e -
  - Não termina com um -
  - Não excede 63 caracteres
Crie ou atualize o serviço usando o seguinte comando:
```
gcloud run services replace service.yaml
```

Terraform

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

O recurso google_cloud_run_v2_service a seguir especifica um número mínimo de instâncias de 1 em template.scaling. Substitua 1 pelo número mínimo de instâncias.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-min-instances"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    scaling {
      # Min instances
      min_instance_count = 1
    }
  }
}

Exibir configurações mínimas de instâncias no nível da revisão

Para ver as configurações mínimas atuais de instâncias mínimas no nível da revisão para o serviço do Cloud Run:

Console

No console do Google Cloud, acesse o Cloud Run:

Acessar o Cloud Run
Clique no serviço de seu interesse para abrir a página Detalhes do serviço.
Clique na guia Revisões.
No painel de detalhes à direita, a configuração de instâncias mínimas no nível da revisão está listada na guia Contêiner.

gcloud

Use o comando a seguir:
```
gcloud run services describe SERVICE
```
Localize a configuração de instâncias mínimas no nível da revisão na configuração retornada.

Como usar instâncias mínimas ou máximas no nível de serviço e de revisão

A tabela a seguir mostra o comportamento se você combinar instâncias mínimas no nível de serviço e instâncias mínimas ou máximas no nível da revisão:

Configuração	Comportamento
As instâncias mínimas de nível de serviço e de revisão estão definidas.	O valor efetivo da revisão é o maior valor entre as instâncias mínimas no nível da revisão e as instâncias mínimas no nível de serviço.
As instâncias mínimas no nível de serviço e o máximo de instâncias no nível da revisão estão definidos.	O valor efetivo da revisão é o menor número de instâncias máximas no nível de revisão e instâncias mínimas de nível de serviço. Isso é válido mesmo que o número máximo de instâncias no nível da revisão impeça que o serviço atinja o número de instâncias configuradas para esse nível mínimo.

Como usar instâncias mínimas de nível de serviço com divisão de tráfego

Se você usar a divisão de tráfego, as instâncias mínimas de nível de serviço serão divididas entre as revisões com base na proporção dessa divisão. Por exemplo, se o mínimo de instâncias no nível de serviço for igual a 10, uma divisão de tráfego de 50/50 alocará cinco instâncias mínimas no nível de serviço para cada revisão.

A tabela a seguir mostra exemplos de cenários de configuração:

Amostra de caso de uso	Exemplo de configuração	Comportamento resultante
Nenhuma configuração no nível da revisão	Mínimo de instâncias de nível de serviço: 10 Instâncias mínimas da revisão A: 0 Instância mínima da revisão B: 0 Divisão de tráfego: 60/40	A revisão A recebe seis instâncias de instâncias mínimas no nível de serviço proporcionais à divisão de tráfego. A revisão B recebe quatro instâncias de instâncias mínimas no nível de serviço proporcionais à divisão de tráfego.
Receber mais do que o mínimo de instâncias no nível de serviço devido ao mínimo de instâncias no nível da revisão	Mínimo de instâncias de nível de serviço: 10 Mínimo de instâncias da revisão A: 6 Instância mínima da revisão B: 0 Divisão de tráfego: 50/50	A revisão A recebe seis instâncias de instâncias mínimas no nível da revisão. A revisão B recebe cinco instâncias de instâncias mínimas no nível de serviço proporcionais à divisão de tráfego. Isso excede as instâncias mínimas no nível de serviço e é intencional.
Receber menos que o mínimo de instâncias no nível de serviço devido ao máximo de instâncias no nível de revisão.	Mínimo de instâncias de nível de serviço: 10 Instâncias mínimas da revisão A: 0 Máximo de instâncias da revisão A: 3 Instância mínima da revisão B: 0 Divisão de tráfego: 50/50	A revisão A recebe três instâncias das instâncias mínimas no nível de serviço geradas pela divisão de tráfego, mas está limitada às instâncias máximas no nível da revisão. A revisão B recebe cinco instâncias das instâncias mínimas no nível de serviço proporcionais à divisão do tráfego. Isso resulta em oito instâncias de nível de serviço, já que duas são perdidas devido ao máximo de instâncias da revisão A no nível da revisão.
O número mínimo de instâncias no nível de serviço é maior que o número de revisões na divisão de tráfego e há uma quantidade fracionária de instâncias proporcional à divisão de tráfego	Instâncias mínimas de nível de serviço: 3 Instâncias mínimas da revisão A: 0 Instância mínima da revisão B: 0 A revisão B é a primeira na seção de tráfego da configuração de serviço. Divisão de tráfego: 50/50	A revisão A recebe uma instância mínima, e a revisão B recebe duas instâncias mínimas. O número de instâncias do serviço é 3.