Criar jobs

Nesta página, descrevemos como criar e atualizar jobs do Cloud Run usando uma imagem de contêiner atual. Ao contrário de um serviço do Cloud Run, que detecta e atende a solicitações, um job do Cloud Run só executa as tarefas e sai quando termina. Um job não detecta nem exibe solicitações.

Depois de criar ou atualizar um job, é possível fazer o seguinte:

Execute o job individualmente, de acordo com uma programação ou como parte de um fluxo de trabalho.
É possível substituir parâmetros configurados para um job ao executá-lo.
É possível gerenciar execuções de jobs individuais e visualizar os registros de execução.

É possível estruturar um job como uma única tarefa ou como várias tarefas independentes (até 10.000) que podem ser executadas em paralelo. Cada tarefa executa uma instância do contêiner e pode ser configurada para tentar novamente em caso de falha. Cada tarefa está ciente do índice, que é armazenado na variável de ambiente CLOUD_RUN_TASK_INDEX. A contagem geral de tarefas é armazenada na variável de ambiente CLOUD_RUN_TASK_COUNT. Se você estiver processando dados em paralelo, o código vai ser responsável por determinar qual tarefa processa qual subconjunto de dados.

É possível definir tempos limite em tarefas e especificar o número de novas tentativas em caso de falha de tarefas. Se alguma tarefa exceder o número máximo de novas tentativas, ela será marcada como falha e a execução do job será marcada como falha depois que todas as tarefas tiverem sido executadas.

Por padrão, cada tarefa é executada por no máximo 10 minutos: é possível alterar esse tempo para um tempo mais curto ou um tempo mais longo de até 24 horas. Para isso, altere a configuração de tempo limite da tarefa.

Não há tempo limite explícito para uma execução de job: a execução do job será concluída depois que todas as tarefas forem concluídas.

Os jobs usam o ambiente de execução de segunda geração.

Funções exigidas

Para receber as permissões necessárias para criar jobs 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 job do 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 job do Cloud Run interagir com APIs do Google Cloud, como 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.

Registros e imagens de contêiner compatíveis

É possível usar diretamente imagens de contêiner armazenadas no Artifact Registry ou no Docker Hub (em inglês). O Google recomenda o uso do Artifact Registry.

É possível usar imagens de contêiner de outros registros públicos ou privados (como JFrog Artifactory, Nexus ou GitHub Container Registry), configurando um repositório remoto do Artifact Registry.

Considere apenas o Docker Hub para implantar imagens de contêiner conhecidas, como Imagens oficiais do Docker ou Imagens do OSS patrocinadas pelo Docker. Para maior disponibilidade, o Google recomenda implantar essas imagens do Docker Hub usando um repositório remoto do Artifact Registry.

Criar um novo job

É possível criar um novo job usando o console do Google Cloud, a CLI do Google Cloud, o YAML ou o Terraform.

Console

Para criar um novo job:

No console do Google Cloud, acesse a página do Cloud Run:

Acessar o Cloud Run
Clique em Implantar contêiner e selecione Job para mostrar o formulário Criar job.
1. No formulário, especifique a imagem do contêiner que contém o código do job ou selecione uma opção em uma lista de contêineres implantados anteriormente.
2. O nome do job é gerado automaticamente a partir da imagem do contêiner. É possível editar ou alterar o nome do job conforme necessário. Não é possível alterar o nome de um job depois que ele é criado.
3. Selecione a região onde você quer que o job esteja localizado. O seletor de região destaca regiões com o menor impacto de carbono.
4. Especifique o número de tarefas que você quer executar no job. Todas as tarefas precisam ser bem-sucedidas para que o job seja concluído. Por padrão, as tarefas são executadas em paralelo.
Clique em Contêiner(s), volumes, rede, segurança para definir outras propriedades do job.
- Em "Capacidade da tarefa":
1. No menu suspenso Memória, especifique a quantidade de memória necessária. O padrão é o mínimo necessário, 512 MiB.
2. No menu CPU, especifique a quantidade de CPU necessária. O padrão é o mínimo necessário, 1 CPU.
3. Em Tempo limite da tarefa, especifique o período máximo em segundos em que a tarefa pode ser executada (até 24 horas). Cada tarefa precisa ser concluída nesse período. O padrão é 10 minutos (600 segundos).
4. Em Número de novas tentativas por tarefa com falha, especifique o número de novas tentativas em caso de falhas de tarefa. O padrão é três novas tentativas.
- Em "Paralelismo", faça o seguinte:
  1. Na maioria dos casos, é possível selecionar Executar o máximo possível de tarefas simultaneamente.
  2. Se você precisar definir um limite menor devido a restrições de escalonamento nos recursos acessados pelo job, selecione Limitar o número máximo de tarefas simultâneas e especifique o número de tarefas simultâneas no campo Limite de paralelismo personalizado.
Como opção, defina outras configurações nas guias apropriadas:
Quando terminar a configuração, clique em Criar para criar o job no Cloud Run.
Para executar o job, consulte Executar jobs ou executar jobs em uma programação.

gcloud

Para usar a linha de comando, você precisa já ter configurado a CLI gcloud.

Para criar um novo job:

Execute o comando:

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS

Outra possibilidade é usar o comando de implantação:

gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS

Substitua JOB_NAME pelo nome do job que você quer criar. É possível omitir esse parâmetro, mas será solicitado o nome do job se você omiti-lo.
IMAGE_URL por uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest;

Como alternativa, substitua OPTIONS por qualquer uma das seguintes opções:

Opção	Descrição
`--tasks`	Aceita números inteiros maiores ou iguais a 1. o padrão é 1; o máximo é de 10.000. Cada tarefa recebe as variáveis de ambiente `CLOUD_RUN_TASK_INDEX` com um valor entre 0 e o número de tarefas menos 1, além de `CLOUD_RUN_TASK_COUNT`, que é o número de tarefas
`--max-retries`	O número de novas tentativas de uma tarefa com falha. Quando uma tarefa falha além desse limite, todo o job é marcado como falha. Por exemplo, se for definida como 1, uma tarefa com falha será repetida por duas tentativas, no total de duas tentativas. o padrão é 3; Aceita números inteiros de 0 a 10.
`--task-timeout`	Aceita uma duração como "2s". O padrão é 10 minutos; máximo é de 24 horas.
`--parallelism`	O número máximo de tarefas que podem ser executadas em paralelo. Por padrão, as tarefas serão iniciadas o mais rápido possível em paralelo. Consulte Paralelismo para ver o intervalo de valores.
`--execute-now`	Se definido, imediatamente após a criação do job, uma execução de job será iniciada. Isso equivale a chamar `gcloud run jobs create` seguido de `gcloud run jobs execute`.

Além das opções acima, você define também outras configurações, como variáveis de ambiente ou limites de memória.

Para ver uma lista completa das opções disponíveis ao criar um job, consulte a documentação da linha de comando gcloud run jobs create.

Aguarde a conclusão da criação do job. Você verá uma mensagem de conclusão bem-sucedida.
Para executar o job, consulte Executar jobs ou executar jobs em uma programação.

YAML

É possível armazenar a especificação do job em um arquivo YAML e implantá-la usando a CLI gcloud.

Crie um novo arquivo job.yaml com este conteúdo:
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
```
Substituir
- JOB pelo nome do job do Cloud Run. Os nomes dos jobs precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto.
- IMAGE pelo URL da imagem do contêiner do job.
Também é possível definir outras configurações, como variáveis de ambiente ou limites de memória.
Implante o novo job usando este comando:
```
gcloud run jobs replace job.yaml
```

Terraform

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

Para criar um novo job do Cloud Run, use o recurso google_cloud_run_v2_job e modifique seu arquivo main.tf, conforme mostrado no snippet a seguir.

resource "google_cloud_run_v2_job" "default" {
  name     = "cloud-run-job"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    template {
      containers {
        image = "us-docker.pkg.dev/cloudrun/container/job:latest"
      }
    }
  }
}

Bibliotecas de cliente

Para criar um job com base no código, siga estas etapas:

API REST

Para criar um job, envie uma solicitação HTTP POST para o endpoint jobs da API Cloud Run Admin.

Por exemplo, usando curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '{template: {template: {containers: [{image: "IMAGE_URL"}]}}}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs?jobId=JOB_NAME

Substitua:

ACCESS_TOKEN por um token de acesso válido para uma conta com as permissões do IAM para criar jobs. Por exemplo, se você fez login no 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.
JOB_NAME pelo nome do job que você quer criar.
IMAGE_URL pelo URL da imagem do contêiner do job. Por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
REGION pela região do Google Cloud do job.
PROJECT_ID pelo ID do projeto do Google Cloud.

Locais do Cloud Run

O Cloud Run é regional, o que significa que a infraestrutura que executa seus serviços do Cloud Run está localizada em uma região específica e é gerenciada pelo Google para estar disponível de maneira redundante em todas as zonas da região.

Atender aos seus requisitos de latência, disponibilidade ou durabilidade são os principais fatores para selecionar a região em que seus serviços do Cloud Run são executados. Geralmente, é possível selecionar a região mais próxima de seus usuários, mas considere a localização dos outros produtos do Google Cloud usados pelo serviço do Cloud Run. O uso de produtos do Google Cloud em vários locais pode afetar a latência e o custo do serviço.

O Cloud Run está disponível nas regiões a seguir:

Sujeitas aos preços do nível 1

asia-east1 (Taiwan)
asia-northeast1 (Tóquio)
asia-northeast2 (Osaka)
europe-north1 (Finlândia) Baixo CO₂
europe-southwest1 (Madri) Baixo CO₂
europe-west1 (Bélgica) Baixo CO₂
europe-west4 (Países Baixos) Baixo CO₂
europe-west8 (Milão)
europe-west9 (Paris) Baixo CO₂
me-west1 (Tel Aviv)
us-central1 (Iowa) Baixo CO₂
us-east1 (Carolina do Sul)
us-east4 (Norte da Virgínia)
us-east5 (Columbus)
us-south1 (Dallas) Baixo CO₂
us-west1 (Oregon) Baixo CO₂

Sujeitas aos preços do nível 2

africa-south1 (Johannesburgo)
asia-east2 (Hong Kong)
asia-northeast3 (Seul, Coreia do Sul)
asia-southeast1 (Singapura)
asia-southeast2 (Jacarta)
asia-south1 (Mumbai, Índia)
asia-south2 (Déli, Índia)
australia-southeast1 (Sydney)
australia-southeast2 (Melbourne)
europe-central2 (Varsóvia, Polônia)
europe-west10 (Berlim) Baixo CO₂
europe-west12 (Turim)
europe-west2 (Londres, Reino Unido) Baixo CO₂
europe-west3 (Frankfurt, Alemanha) Baixo CO₂
europe-west6 (Zurique, Suíça) Baixo CO₂
me-central1 (Doha)
me-central2 (Damã)
northamerica-northeast1 (Montreal) Baixo CO₂
northamerica-northeast2 (Toronto) Baixo CO₂
southamerica-east1 (São Paulo, Brasil) Baixo CO₂
southamerica-west1 (Santiago, Chile) Baixo CO₂
us-west2 (Los Angeles)
us-west3 (Salt Lake City)
us-west4 (Las Vegas)

Se você já criou um serviço do Cloud Run, é possível visualizar a região no painel do Cloud Run no console do Google Cloud.

Quando você cria um novo job, o agente de serviço do Cloud Run precisa ser capaz de acessar o contêiner, o que é o caso por padrão.

Atualizar um job

Para alterar as definições de configuração, é necessário atualizar o job, mesmo que não haja alterações na imagem do contêiner. Para as configurações inalteradas, as configurações anteriores continuam sendo usadas.

É possível atualizar um job que já existe usando o console do Google Cloud, a CLI do Google Cloud, o YAML ou o Terraform.

Console

Para atualizar um job:

No console do Google Cloud, acesse a página do Cloud Run:

Acessar o Cloud Run
Clique na guia Jobs para exibir a lista de jobs.
Clique no job para exibir a página de detalhes.
Clique em Editar.
Se você fez alterações no código do job, especifique o novo resumo de imagem do contêiner.
Se necessário, mude o número de tarefas no job.
Se quiser, clique em Contêiner(s), volumes, rede, segurança para atualizar outras propriedades do job:
- Em "Capacidade da tarefa":
1. No menu suspenso Memória, especifique a quantidade de memória necessária. O padrão é o mínimo necessário, 512 MiB.
2. No menu CPU, especifique a quantidade de CPU necessária. O padrão é o mínimo necessário, 1 CPU.
3. Em Tempo limite da tarefa, especifique o período máximo em segundos em que a tarefa pode ser executada (até 24 horas). Cada tarefa precisa ser concluída nesse período. O padrão é 10 minutos (600 segundos).
4. Em Número de novas tentativas por tarefa com falha, especifique o número de novas tentativas em caso de falhas de tarefa. O padrão é três novas tentativas.
- Em "Paralelismo", faça o seguinte:
  1. Na maioria dos casos, é possível selecionar Executar o máximo possível de tarefas simultaneamente.
  2. Se você precisar definir um limite menor devido a restrições de escalonamento nos recursos acessados pelo job, selecione Limitar o número de tarefas simultâneas e especifique o número de tarefas simultâneas no campo Limite de paralelismo personalizado.
Como opção, defina outras configurações nas guias apropriadas:
Quando terminar de configurar o job, clique em Salvar para criar o job no Cloud Run e aguarde a criação.
Para executar o job, consulte Executar jobs ou executar jobs em uma programação.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Execute o comando:

gcloud run jobs update JOB_NAME

Substitua:

JOB_NAME pelo nome do job que você quer atualizar.

Se quiser, substitua OPTIONS pelas seguintes opções:

Opção	Descrição
`--tasks`	Aceita números inteiros iguais ou maiores que 1. o padrão é 1; o máximo é de 10.000. Cada tarefa recebe as variáveis de ambiente `CLOUD_RUN_TASK_INDEX` com um valor entre 0 e o número de tarefas menos 1, além de `CLOUD_RUN_TASK_COUNT`, que é o número de tarefas
`--max-retries`	O número de novas tentativas de uma tarefa com falha. Quando uma tarefa falha além desse limite, todo o job é marcado como falha. Por exemplo, se for definida como 1, uma tarefa com falha será repetida por duas tentativas, no total de duas tentativas. O padrão é `3`. Aceita números inteiros de 0 a 10.
`--task-timeout`	Aceita uma duração como "2s". O padrão é 10 minutos; máximo é de 24 horas.
`--parallelism`	O número máximo de tarefas que podem ser executadas em paralelo. Por padrão, as tarefas serão iniciadas o mais rápido possível em paralelo. Consulte Paralelismo para ver o intervalo de valores.

Além das opções acima, você pode definir outras configurações opcionais:

Para ver uma lista completa das opções disponíveis ao criar um job, consulte a documentação da linha de comando gcloud run jobs create.

Aguarde a conclusão da atualização do job. Após a conclusão, será exibida uma mensagem semelhante a esta:

Job [JOB_NAME] has been successfully updated.
View details about this job by running `gcloud run jobs describe JOB_NAME`.
See logs for this execution at: https://console.cloud.google.com/logs/viewer?project=PROJECT_ID&resource=cloud_run_revision/service_name/JOB_NAME

Para executar o job, consulte Executar jobs ou executar jobs em uma programação.

YAML

Se você precisar fazer o download ou visualizar a configuração de um job que já existe, use o comando a seguir para salvar os resultados em um arquivo YAML:

gcloud run jobs describe JOB --format export > job.yaml

Em um arquivo YAML de configuração do job, modifique todos os atributos filhos spec.template conforme preferir para atualizar as configurações e reimplante:

Atualize a configuração do job que já existe:
```
gcloud run jobs replace job.yaml
```
Para executar o job, consulte Executar jobs ou executar jobs em uma programação.

Terraform

Faça alterações na configuração do job no arquivo main.tf usando o comando terraform apply. As instruções detalhadas do Terraform estão disponíveis para:

Para mais informações, consulte as opções de linha de comando terraform apply.

Bibliotecas de cliente

Para atualizar um job atual a partir do código, siga estas etapas:

API REST

Para atualizar um job, envie uma solicitação HTTP PATCH para o endpoint jobs da API Cloud Run Admin.

Por exemplo, usando curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X PATCH \
  -d '{template: {template: {containers: [{image: "IMAGE_URL"}]}}}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB_NAME

Substitua:

ACCESS_TOKEN por um token de acesso válido para uma conta com as permissões do IAM para atualizar jobs. Por exemplo, se você fez login no 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.
JOB_NAME pelo nome do job que você quer atualizar.
IMAGE_URL pelo URL da imagem do contêiner do job. Por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
REGION pela região do Google Cloud do job.
PROJECT_ID pelo ID do projeto do Google Cloud.

Código de amostra

Para exemplos de código que mostram jobs simples, consulte os guias de início rápido específicos para linguagens.

A seguir

O que fazer depois de criar ou atualizar um job: