Criar e gerenciar instâncias do Cloud Run

Nesta página, descrevemos como criar e gerenciar instâncias singleton do Cloud Run endereçáveis individualmente. Ao contrário dos serviços do Cloud Run que são escalonados com base no tráfego de entrada, uma instância é um contêiner de computação dedicado que você gerencia manualmente usando transições de ciclo de vida (criar, parar, iniciar, atualizar, excluir).

Regiões compatíveis

As instâncias do Cloud Run podem ser criadas em qualquer uma das regiões compatíveis, exceto nas seguintes regiões:

  • europe-west1
  • us-central1
  • us-east1

Antes de começar

  1. Configure um novo projeto para o Cloud Run, conforme descrito na página de configuração.

  2. Ative a API Cloud Run Admin:

    gcloud services enable run.googleapis.com

  3. Atualize os componentes gcloud para a versão mais recente:

    gcloud components update

  4. Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

Funções exigidas

Para receber as permissões necessárias para configurar e implantar instâncias 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 a instância do Cloud Run interagir 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.

Criar uma instância

É possível implantar uma imagem de contêiner para criar uma nova instância. Se você não fornecer um nome, um será gerado automaticamente.

gcloud

Para criar uma instância do Cloud Run usando o comando gcloud beta run instances create:

gcloud beta run instances create INSTANCE_NAME \
    --image IMAGE_URL \
    --region REGION

Para criar uma instância do Cloud Run usando o comando gcloud beta run instances deploy:

gcloud beta run instances deploy INSTANCE_NAME \
    --image IMAGE_URL \
    --region REGION

Substitua:

  • INSTANCE_NAME: o nome da instância que você está criando. O nome da instância precisa ser exclusivo no projeto e na região. Não é possível criar uma instância com o mesmo nome de uma instância ou serviço do Cloud Run.
  • IMAGE_URL: uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/instances:latest.
  • REGION: a região Google Cloud em que você está executando a instância, por exemplo europe-west1.

Bibliotecas de cliente

Para criar uma nova instância usando código:

API REST

Para criar uma instância do Cloud Run, envie uma solicitação HTTP POST para o endpoint instances.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "containers": [{
      "image": "IMAGE_URL",
      "ports": [{"containerPort": PORT}]
    }],
    "ingress": "INGRESS_TRAFFIC_ALL",
    "invokerIamDisabled": true,
    "timeout": "3600s"
  }' \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances?instance_id=INSTANCE_NAME"

Substitua:

  • IMAGE_URL: o URL da imagem do contêiner.
  • PORT: a porta em que o contêiner detecta.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • REGION: a Google Cloud região da sua implantação.
  • INSTANCE_NAME: o nome da nova instância.

Depois de criar uma instância, ela recebe um URL do Cloud Run com o seguinte formato:

https://INSTANCE_NAME-PROJECT_NUMBER.REGION.run.app

Atualizar uma instância

Quando você atualiza uma instância, como a imagem do contêiner, a porta ou as variáveis de ambiente, ela é reiniciada.

gcloud

Para atualizar uma instância do Cloud Run usando o comando gcloud beta run instances update:

gcloud beta run instances update INSTANCE_NAME \
    --image NEW_IMAGE_URL \
    --region REGION

Para atualizar uma instância do Cloud Run usando o comando gcloud beta run instances deploy:

gcloud beta run instances deploy INSTANCE_NAME \
    --image IMAGE_URL \
    --region REGION

API REST

Para atualizar uma configuração de instância do Cloud Run na API, envie uma solicitação HTTP PATCH para o endpoint do URI da instância.

curl -H "Content-Type: application/json" \
  -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{template: {containers: [{image: "IMAGE_URL"}]}}' \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME"

Interromper uma instância

Use o comando ou método de interrupção para interromper uma instância do Cloud Run em execução.

gcloud

Para interromper uma instância:

gcloud beta run instances stop INSTANCE_NAME \
    --region REGION

Bibliotecas de cliente

Para interromper uma instância em execução usando o código:

API REST

Para interromper uma instância, envie uma solicitação HTTP POST com o decorador :stop:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME:stop"

Iniciar ou reiniciar uma instância

Use o comando ou método "start" para iniciar uma instância interrompida ou forçar uma reinicialização em uma instância atual.

gcloud

Para iniciar ou reiniciar uma instância:

gcloud beta run instances start INSTANCE_NAME \
    --region REGION

Bibliotecas de cliente

Para iniciar uma instância interrompida usando o código:

API REST

Para iniciar uma instância, envie uma solicitação HTTP POST com o decorador :start:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME:start"

Ver a lista de instâncias no projeto

É possível conferir todas as instâncias ativas e inativas no seu projeto.

gcloud

Para listar as instâncias em uma região específica:

gcloud beta run instances list \
    --region REGION

Substitua REGION pela Google Cloud região em que você está executando a instância.

Bibliotecas de cliente

Para listar instâncias ativas e inativas no código:

API REST

Para recuperar uma lista de instâncias, envie uma solicitação HTTP GET:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances"

Exibir detalhes da instância

Use o comando ou método "describe" para ver detalhes da configuração e o status atual.

gcloud

Para descrever uma instância:

gcloud beta run instances describe INSTANCE_NAME \
    --region REGION

Bibliotecas de cliente

Para conferir os detalhes e o status da configuração da instância no código:

API REST

Para descrever uma instância, envie uma solicitação HTTP GET:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME"

Excluir uma instância

Exclua uma instância para remover permanentemente a configuração, os metadados, o mapeamento de URL direto público e as funções de identidade do seu projeto.

gcloud

Para excluir uma instância:

gcloud beta run instances delete INSTANCE_NAME \
    --region REGION

Bibliotecas de cliente

Para excluir uma instância do código:

API REST

Para excluir uma instância, envie uma solicitação HTTP DELETE:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME"

A seguir