Gerir serviços do Cloud Run

Esta página descreve a criação de um serviço e a visualização de informações sobre um serviço.

Cada serviço tem um URL run.app único e permanente que não se altera ao longo do tempo à medida que implementa novas revisões. As funções implementadas no Cloud Run também são tratadas como um serviço e é-lhes atribuído um endereço run.app. O domínio permanente do serviço consiste no nome do serviço e num hash.

Funções necessárias

Para receber as autorizações de que precisa para gerir serviços e revisões do Cloud Run, peça ao seu administrador para lhe conceder a função de IAM de programador do Cloud Run (roles/run.developer) no seu serviço do Cloud Run.

Para ver uma lista de funções e autorizações de IAM associadas ao Cloud Run, consulte os artigos Funções de IAM do Cloud Run e Autorizações de IAM do Cloud Run. Se o seu serviço do Cloud Run interage com Google Cloud APIs, como as bibliotecas cliente da Google Cloud, consulte o guia de configuração da identidade do serviço. Para mais informações sobre a atribuição de funções, consulte as autorizações de implementação e faça a gestão do acesso.

Crie um serviço

Cria um novo serviço implementando uma imagem de contentor no mesmo pela primeira vez. A implementação de um novo serviço tem mais instruções.

Veja a lista de serviços no seu projeto

Pode ver uma lista dos serviços disponíveis no seu projeto através da Google Cloud consola ou da linha de comandos gcloud:

Consola

Para ver a lista de serviços:

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Examine a lista de serviços apresentada para o seu projeto:

    lista de serviços

gcloud

Para listar os serviços no seu projeto:

gcloud run services list

Tenha em atenção que cada serviço tem um URL associado.

Pode filtrar esta lista por propriedades da definição de serviço, como uma etiqueta atribuída.

Cloud Code

Para ver a lista de serviços com o Cloud Code, leia os guias do explorador do Cloud Run para IntelliJ e Visual Studio Code.

Bibliotecas cliente

Para ver a lista de serviços a partir do código:

API REST

Para ver a lista de serviços no seu projeto, envie um pedido HTTP GET para o ponto final service da API Cloud Run Admin.

Por exemplo, usar curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services

Substituir:

  • ACCESS_TOKEN com uma chave de acesso válida para uma conta que tenha as autorizações da IAM para ver serviços. Por exemplo, se tiver sessão iniciada no gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
  • REGION com a Google Cloud região do serviço.
  • PROJECT-ID com o Google Cloud ID do projeto.

Veja a lista de funções no seu projeto

Pode ver uma lista das funções disponíveis no seu projeto através da Google Cloud consola:

Consola

Para filtrar funções na sua lista de serviços:

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Examine a lista de serviços apresentada para o seu projeto:

    lista de serviços

  3. Selecione Filtrar serviços > Tipo de implementação > Função.

    Se implementou anteriormente a sua função através da API Cloud Functions v2, a coluna Implementado por mostra Cloud Functions.

Copie um serviço

Pode fazer uma cópia de um serviço existente através da Google Cloud consola ou do YAML. Pode alterar o que quiser na cópia, incluindo o nome e a região.

Consola

Para copiar um serviço:

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Selecione o serviço a copiar na lista de serviços apresentada para o seu projeto:

    lista de serviços

    1. Clique em Copiar.

    2. Na página de cópia do serviço, defina ou altere os valores que quer alterar, como a região, etc. Se mantiver a mesma região, tem de indicar um novo nome para o serviço.

    3. Clique em Criar para fazer uma cópia e implementá-la com o novo nome do serviço.

YAML

  1. Se estiver a criar um novo serviço, ignore este passo. Se estiver a atualizar um serviço existente, transfira a respetiva configuração YAML:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Faça as alterações de configuração desejadas ao serviço.

     apiVersion: serving.knative.dev/v1
     kind: Service
     metadata:
       annotations:
         ...
       name: SERVICE
       ...
     spec:
       template:
         metadata:
           annotations:
           ...
           name: REVISION
    
    • Se não estiver a implementar a cópia numa região diferente, substitua SERVICE pelo nome que quer usar para a cópia. Se estiver a implementar a cópia numa região diferente, pode usar o nome antigo.
    • Substitua REVISION por um novo nome de revisão ou elimine-o (se estiver presente). Se fornecer um novo nome de revisão, este tem de cumprir os seguintes critérios:
      • Começa com SERVICE-
      • Contém apenas letras minúsculas, números e -
      • Não termina com um -
      • Não exceder 63 carateres
  3. Copie o serviço através do seguinte comando:

    gcloud run services replace service.yaml

    Use a flag --region para implementar a cópia numa região diferente.

Veja mais detalhes sobre um serviço

Para ver mais detalhes sobre um serviço:

Consola

Para ver os detalhes de um serviço:

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Clique no serviço pretendido na lista de serviços apresentada para o seu projeto para abrir a vista de detalhes do serviço.

gcloud

Para ver detalhes sobre um serviço:

gcloud run services describe SERVICE
Substitua SERVICE pelo nome do serviço.

Pode usar a flag --format para formatar a saída. Por exemplo, como YAML:

gcloud run services describe SERVICE --region REGION --format yaml

Substituir:

  • SERVICE com o nome do serviço.
  • REGION com a Google Cloud região do serviço.

Pode usar --format export para exportar como YAML sem etiquetas ou estado gerados automaticamente:

gcloud run services describe SERVICE --region REGION --format export

Também pode usar a flag --format para obter o URL do serviço:

gcloud run services describe SERVICE --region REGION --format='value(status.url)'

Cloud Code

Para ver os detalhes de um serviço com o Cloud Code, leia os guias do explorador do Cloud Run para IntelliJ e Visual Studio Code.

Para mais detalhes sobre as revisões de serviços, consulte o artigo Gerir revisões.

Bibliotecas cliente

Para ver detalhes sobre um serviço a partir do código:

API REST

Para ver detalhes sobre um serviço, envie um pedido HTTP GET para o ponto final service da API Cloud Run Admin.

Por exemplo, usar curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE-NAME

Substituir:

  • ACCESS_TOKEN com uma chave de acesso válida para uma conta que tenha as autorizações do IAM para ver os detalhes do serviço. Por exemplo, se tiver sessão iniciada no gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
  • SERVICE-NAME com o nome do serviço.
  • REGION com a Google Cloud região do serviço.
  • PROJECT-ID com o Google Cloud ID do projeto.

Desative um serviço existente

Para obter as autorizações de que precisa para desativar um serviço e uma revisão do Cloud Run existentes, peça ao seu administrador para lhe conceder a função de IAM administrador do Cloud Run (roles/run.admin) no seu projeto.

Quando desativa um serviço, todos os pedidos que estão a ser processados são concluídos. No entanto, quaisquer pedidos adicionais ao URL do serviço vão falhar com um erro Service unavailable ou Service disabled.

Os pedidos de revisões de serviços que só estão ativos devido a etiquetas de tráfego não são afetados porque essas revisões não estão desativadas.

Para desativar um serviço, define o dimensionamento como zero. Pode desativar um serviço através da Google Cloud consola, da CLI Google Cloud, do ficheiro YAML ou da API:

Consola

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Clique no serviço que quer desativar para apresentar o respetivo painel de detalhes e, de seguida, clique no ícone de caneta junto a Ajuste de escala na parte superior direita do painel de detalhes.

  3. Localize o formulário Editar dimensionamento e selecione Dimensionamento manual.

    imagem

    No campo com a etiqueta Número de instâncias, introduza o valor 0 (zero).

  4. Clique em Guardar.

gcloud

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

gcloud run services update SERVICE --scaling=0

Substitua SERVICE pelo nome do seu serviço.

YAML

  1. Transfira a configuração YAML do seu 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 seu serviço do Cloud Run.

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

    gcloud run services replace service.yaml

API REST

Para desativar um serviço, envie um PATCHpedido HTTP para o ponto final da API Cloud Run Admin service.

Por exemplo, usar 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 o seguinte:

  • ACCESS_TOKEN: um token de acesso válido para uma conta que tenha as autorizações de IAM para atualizar um serviço. Por exemplo, se tiver sessão iniciada em gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
  • SERVICE: o nome do serviço.
  • REGION: a Google Cloud região na qual o serviço é implementado.
  • PROJECT_ID: o Google Cloud ID do projeto.

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 o seguinte:

  • 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 do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se usar o Artifact Registry, o repositório REPO_NAMEtem de já estar criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

Elimine os serviços existentes

As seguintes considerações aplicam-se à eliminação de um serviço:

  • A eliminação de um serviço elimina todos os recursos relacionados com este serviço, incluindo todas as revisões deste serviço, quer estejam a publicar tráfego ou não.
  • A eliminação de um serviço não remove automaticamente as imagens de contentores do Artifact Registry. Para eliminar imagens de contentores usadas pelas revisões eliminadas do Artifact Registry, consulte o artigo Eliminar imagens.
  • A eliminação de um serviço com um ou mais acionadores do Eventarc não elimina automaticamente estes acionadores. Para eliminar os acionadores, consulte o artigo Gerir acionadores.
  • Após a eliminação, o serviço permanece visível na Google Cloud consola e na interface de linha de comandos até a eliminação estar totalmente concluída. No entanto, não pode atualizar o serviço.
  • A eliminação de um serviço é permanente: não existe a opção de anular ou restaurar. No entanto, se, após eliminar um serviço, implementar um novo serviço com o mesmo nome na mesma região, este terá o mesmo URL do ponto final.

Consola

Para eliminar um serviço:

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Localize o serviço que quer eliminar na lista de serviços e clique na caixa de verificação para o selecionar.

  3. Clique em ELIMINAR. Esta ação elimina todas as revisões do serviço.

gcloud

Para eliminar um serviço, use o comando:

gcloud run services delete SERVICE --region REGION

Substituir

  • SERVICE com o nome do seu serviço.
  • REGION com a Google Cloud região do serviço.

Bibliotecas cliente

Para eliminar um serviço a partir do código:

API REST

Para eliminar um serviço, envie um pedido HTTP DELETE para o ponto final service da API Admin do Cloud Run.

Por exemplo, usar curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X DELETE \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE-NAME

Substituir:

  • ACCESS_TOKEN com uma chave de acesso válida para uma conta que tenha as autorizações do IAM para eliminar um serviço. Por exemplo, se tiver sessão iniciada no gcloud, pode obter um token de acesso através de gcloud auth print-access-token. A partir de uma instância de contentor do Cloud Run, pode obter um token de acesso através do servidor de metadados da instância de contentor.
  • SERVICE-NAME com o nome do serviço.
  • REGION com a Google Cloud região do serviço.
  • PROJECT-ID com o Google Cloud ID do projeto.