Implantar um serviço, job ou pool de workers do Cloud Run

Este documento descreve como implantar seus aplicativos, incluindo serviços, jobs e pools de workers do Cloud Run. Os pools de workers do Cloud Run estão em pré-lançamento.

O Cloud Deploy permite implantar cargas de trabalho baseadas em contêineres em qualquer serviço do Cloud Run, job ou pool de workers. Todos os recursos do Cloud Deploy são compatíveis quando você implanta em destinos do Cloud Run para serviços ou pools de workers do Cloud Run, mas as implantações de canary não são compatíveis com jobs do Cloud Run.

Este documento descreve as três principais configurações que você precisa concluir para implantar no Cloud Run:

Limitações

Antes de começar

Criar a configuração de destino

O destino pode ser configurado no YAML do pipeline de entrega ou em um arquivo separado. Além disso, é possível configurar mais de um destino no mesmo arquivo.

Os destinos precisam ser definidos no mesmo projeto e região que o pipeline de entrega. No entanto, os serviços, jobs ou pools de workers em que os destinos são implantados podem estar em projetos e regiões diferentes, desde que a conta de serviço tenha acesso a esses projetos.

Na definição de destino, crie uma seção run para identificar o local em que o serviço do Cloud Run será criado.

A sintaxe para especificar o serviço, job ou pool de workers do Cloud Run na definição de destino é a seguinte:

run:
 location: projects/[project_name]/locations/[region_name]

Esse identificador de recurso usa os seguintes elementos:

  • project_name é o nome do Google Cloud projeto em que o serviço, job ou pool de workers do Cloud Run será criado.

    Faça isso para cada destino. Recomendamos um projeto diferente para cada serviço, job ou pool de workers do Cloud Run. Se você quiser mais de um serviço, job ou pool de workers no mesmo projeto, use perfis do Skaffold no arquivo de configuração skaffold.yaml.

  • region_name é a região em que o serviço, job ou pool de workers será criado. O serviço, job ou pool de workers pode estar em qualquer região compatível com o Cloud Run.

Confira a seguir um exemplo de configuração de destino, definindo o serviço, job ou pool de workers do Cloud Run a ser criado:

      apiVersion: deploy.cloud.google.com/v1
      kind: Target
      metadata:
       name: dev
      description: development service
      run:
       location: projects/my-app/locations/us-central1

É possível definir esse destino dentro de uma definição de pipeline de entrega do Cloud Deploy ou separadamente. De qualquer forma, é necessário registrar o destino antes de criar a versão para implantar o serviço, job ou pool de workers do Cloud Run.

Criar a configuração do Skaffold

Confira a seguir um exemplo skaffold.yaml de arquivo para uma implantação do Cloud Run:

apiVersion: skaffold/v4beta7
kind: Config
metadata: 
  name: cloud-run-application
manifests:
  rawYaml:
  - service.yaml
deploy:
  cloudrun: {}

Neste arquivo skaffold.yaml...

  • manifests.rawYaml fornece os nomes das definições de serviço do Cloud Run.

    Neste exemplo, service.yaml é o arquivo que define um serviço do Cloud Run que o Skaffold vai implantar. Esse nome de arquivo pode ser qualquer coisa, mas, por convenção, é service.yaml para um serviço, job.yaml para um job e workerpool.yaml para um pool de workers.

  • A seção deploy especifica como você quer que o manifesto seja implantado, especificamente, o projeto e o local. deploy é obrigatório.

    Recomendamos que você deixe o {} vazio. O Cloud Deploy preenche isso durante a renderização, com base no projeto e no local da definição de destino.

    No entanto, para o desenvolvimento local, é possível fornecer valores aqui. No entanto, o Cloud Deploy sempre usa o projeto e o local da definição de destino, independentemente de os valores serem fornecidos aqui.

Criar as definições de serviço do Cloud Run

Para criar uma definição de serviço do Cloud Run, é possível criar uma manualmente ou copiar uma de um serviço atual. Ambos são descritos nesta seção.

Opção 1: criar um novo service.yaml do Cloud Run

O service.yaml define o serviço do Cloud Run. Ao criar uma versão, o Skaffold usa essa definição para implantar o serviço.

Confira um exemplo simplificado:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: [SERVICE_NAME]
spec:
 template:
  spec:
   containers:
   - image: [IMAGE_PATH]

Em que:

  • [SERVICE_NAME] é um nome para esse serviço do Cloud Run.

  • [IMAGE_PATH] aponta para a imagem ou imagens do contêiner que você está implantando com esse serviço.

Opção 2: copiar um service.yaml de um serviço atual usando o Google Cloud console

É possível criar um serviço usando o Google Cloud console ou usar um já existente, e copiar o service.yaml dele.

Para acessar o service.yaml usando a Google Cloud CLI:

gcloud run services describe [service_name] --format=export

Para acessar o service.yaml do Google Cloud console:

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

  2. Selecione o serviço atual cuja definição você quer usar.

Ou crie um novo e selecione-o. Quando você seleciona o serviço, a página de detalhes do serviço é mostrada:

Página de detalhes do serviço ConsoleGoogle Cloud , mostrando a guia YAML

  1. Selecione a guia YAML.

  2. Clique em Editar e copie o conteúdo do YAML para um novo arquivo chamado service.yaml no seu sistema de arquivos, para que o Skaffold possa usá-lo ao criar uma versão.

Criar as definições de job do Cloud Run

Para implantar uma definição de job do Cloud Run, é possível criar uma manualmente ou copiar uma de um job atual. Ambos são descritos nesta seção.

Os jobs não são necessariamente executados após serem implantados pelo Cloud Deploy. Isso é diferente dos serviços, que são aplicativos em execução depois de implantados. A forma como um job é invocado depende do próprio job.

Opção 1: criar um novo job.yaml do Cloud Run

O job.yaml define o job do Cloud Run. Ao criar uma versão, o Skaffold usa essa definição para implantar o job.

Confira um exemplo simplificado:

apiVersion: run.googleapis.com/v1
kind: Job
metadata:
 name: [JOB_NAME]
spec:
  template:
  spec:
   containers:
   - image: [IMAGE_PATH]

Em que:

  • [JOB_NAME] é um nome para esse job do Cloud Run.

  • [IMAGE_PATH] aponta para a imagem do contêiner que você está implantando para esse job.

Opção 2: copiar um job.yaml de um job atual usando o Google Cloud console

É possível criar um job usando o Google Cloud console ou usar um já existente, e copiar o job.yaml dele.

Para acessar o job.yaml usando a Google Cloud CLI:

gcloud run jobs describe [job_name] --format=export

Para acessar o job.yaml do Google Cloud console:

  1. No Google Cloud console, acesse a página Jobs do Cloud Run.

  2. Selecione o job atual cuja definição você quer usar.

Ou crie um novo e selecione-o. Quando você seleciona o job, a página de detalhes do job é mostrada:

Página de detalhes do job ConsoleGoogle Cloud mostrando a guia YAML

  1. Selecione a guia YAML.

  2. Clique em Editar e copie o conteúdo do YAML para um novo arquivo chamado job.yaml no seu sistema de arquivos, para que o Skaffold possa usá-lo ao criar uma versão.

Criar as definições de pool de workers do Cloud Run (pré-lançamento)

Para implantar uma definição de pool de workers do Cloud Run, é possível criar uma manualmente ou copiar uma de um pool de workers atual. Ambos são descritos nesta seção.

Opção 1: criar um novo workerpool.yaml do Cloud Run

O workerpool.yaml define o pool de workers do Cloud Run. Ao criar uma versão, o Skaffold usa essa definição para implantar o pool de workers.

Confira um exemplo simplificado:

apiVersion: run.googleapis.com/v1
kind: WorkerPool
metadata:
 name: [WORKERPOOL_NAME]
 annotations:
  run.googleapis.com/launch-stage: BETA
spec:
  template:
   spec:
    containers:
    - image: [IMAGE_PATH]

Em que:

  • [WORKERPOOL_NAME] é um nome para esse pool de workers do Cloud Run.

  • [IMAGE_PATH] aponta para a imagem do contêiner que você está implantando para esse pool de workers.

Opção 2: copiar um workerpool.yaml de um pool de workers atual usando o Google Cloud console

É possível criar um pool de workers usando o Google Cloud console ou usar um já existente, e copiar o workerpool.yaml dele.

Para acessar o workerpool.yaml usando a Google Cloud CLI:

gcloud beta run worker-pools describe [workerpool_name] --format=export

Para acessar o workerpool.yaml do Google Cloud console:

  1. No Google Cloud console, acesse a página Pools de workers do Cloud Run.

  2. Selecione o pool de workers atual cuja definição você quer usar.

Ou crie um novo e selecione-o. Quando você seleciona o pool de workers, a página de detalhes do pool de workers é mostrada:

Página de detalhes do pool de workers consoleGoogle Cloud , mostrando a guia YAML

  1. Selecione a guia YAML.

  2. Copie o conteúdo do YAML para um novo arquivo chamado workerpool.yaml no seu sistema de arquivos, para que o Skaffold possa usá-lo ao criar uma versão.

Como tudo funciona em conjunto

Agora que você tem a definição de serviço, job ou pool de workers do Cloud Run, a configuração skaffold.yaml e a definição de destino do Cloud Deploy , e registrou o destino como um recurso do Cloud Deploy, é possível invocar o pipeline de entrega para criar uma versão e avançá-la na progressão de destinos definidos no pipeline.

O guia de início rápido Implantar um app no Cloud Run usando o Cloud Deploy mostra tudo isso em ação.

Comportamento dos serviços em revisões

Ao reimplantar um serviço, a nova revisão é baseada no service.yaml recém-implantado. Nada sobre a revisão anterior é mantido, a menos que seja o mesmo no YAML recém-implantado. Por exemplo, se houver configurações ou rótulos na revisão anterior que não estão no novo YAML, essas configurações ou rótulos estarão ausentes da nova revisão.

Como acionar jobs do Cloud Run

Depois de implantar um job, é possível acioná-lo conforme descrito na documentação do Cloud Run.

Como implantar serviços, jobs e pools de workers do Cloud Run em vários projetos

Se você precisar implantar serviços, jobs ou pools de workers que estão em projetos diferentes, sua conta de serviço de execução precisará de permissão para acessar os projetos em que esses serviços, jobs ou pools de workers estão definidos.

Consulte Conta de serviço de execução do Cloud Deploy e Papéis e permissões do Identity and Access Management para mais informações.

Como implantar o Cloud Run functions

O Cloud Run functions cria o código-fonte sempre que uma função é implantada. Por isso, cada ambiente de execução de destino no pipeline pode receber um artefato ligeiramente diferente. Isso é contrário às práticas recomendadas no Cloud Deploy. Em vez disso, sugerimos que você use um serviço do Cloud Run diretamente. Isso permite criar um único artefato e promovê-lo em todos os ambientes.

  1. Faça o check-in do service.yaml para a função do Cloud Run.

    Para fazer isso, execute o comando a seguir:

    gcloud run services describe FUNCTION_NAME \
--format=export \
--region=REGION \
--project=PROJECT

  2. Remova as seguintes anotações, se presentes:

    • run.googleapis.com/build-base-image
    • run.googleapis.com/build-name
    • run.googleapis.com/build-source-location
    • run.googleapis.com/build-enable-automatic-updates

  3. Substitua o valor em spec.spec.containers.image por IMAGE_TAG.

  4. Crie o pipeline de entrega e os destinos, com o serviço do Cloud Run como destino.

  5. Separe a etapa de build da etapa de implantação no processo de CI. Em vez de usar a Google Cloud CLI para implantar a função, substitua-a pelas seguintes etapas:

    1. Crie a função em um contêiner usando o Cloud Build:

      gcloud builds submit --pack image=REGION-docker.pkg.dev/PROJECT/cloud-run-source-deploy/IMAGE_NAME \
--project=PROJECT \
--region=REGION

    2. Crie uma versão usando o Cloud Deploy:

      gcloud deploy releases create RELEASE_NAME \
--project=DEPLOY_PROJECT \
--region=REGION \
--delivery-pipeline=DELIVERY_PIPELINE \
--images=IMAGE_TAG=REGION-docker.pkg.dev/PROJECT/cloud-run-source-deploy/IMAGE_NAME

      Neste comando...

      • RELEASE_NAME é um nome que será atribuído à versão. O nome precisa ser exclusivo entre todas as versões desse pipeline de entrega.

      • DEPLOY_PROJECT é o ID do projeto em que você criou o pipeline de implantação.

      • DELIVERY_PIPELINE é o nome do pipeline de entrega que gerenciará a implantação dessa versão por meio da progressão de destinos. Esse nome precisa corresponder ao name campo na definição do pipeline.

      • REGION é o nome da região em que você está criando a versão, por exemplo, us-central1. Obrigatório.

      • IMAGE_NAME é o nome que você deu à imagem na etapa anterior, quando criou a função.

A seguir