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.

Permissões do IAM necessárias para criar e executar

Para usar os jobs do Cloud Run, você precisa ter um destes papéis:

Administrador do Cloud Run com permissões totais para criar/atualizar/excluir e executar jobs
Invocador do Cloud Run para executar jobs
Leitor do Cloud Run para visualizar e listar jobs

Se você estiver configurando um papel personalizado, use estas permissões:

run.jobs.{create/update/run/delete/get/list/getIamPolicy/setIamPolicy}
run.executions.{get/list/delete}
run.tasks.{get/list}

run.jobs.run permite que um usuário execute um job, iniciando uma nova execução. Não existe uma permissão run.executions.create separada: a única maneira de criar uma execução é ao executar um job.

Registros e imagens de contêiner compatíveis

É possível usar imagens de contêiner armazenadas no Artifact Registry, Container Registry (Obsoleto) ou or Docker Hub. O Google recomenda o uso do Artifact Registry.

É possível usar apenas os seguintes tipos de imagens de contêiner:

Imagens de contêiner armazenadas no mesmo projeto em que você está criando o job ou o serviço
Imagens de contêiner de outros projetos do Google Cloud (desde que as permissões corretas do IAM estejam definidas).
Imagens de contêiner públicas do Artifact Registry, Container Registry ou Docker Hub.

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.

Se você estiver armazenando imagens de contêiner em outro tipo de registro de contêiner, siga as instruções em Como implantar imagens de registros não compatíveis.

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:

Acesse o Cloud Run
Clique na guia Jobs.
Clique em Criar job para exibir 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 suspenso, 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 na caixa de texto 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.

Linha de comando

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" {
  provider     = google-beta
  name         = "cloud-run-job"
  location     = "us-central1"
  launch_stage = "BETA"

  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 (Madrid)
europe-west1 (Bélgica) Baixo CO_₂
europe-west4 (Países Baixos)
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)
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)
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:

Acesse o Cloud Run
Clique na guia Jobs para exibir a lista de jobs.
Clique no job desejado para exibir a página Detalhes do job.
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 conforme desejado:
- 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 suspenso, 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 na caixa de texto 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.

Linha de comando

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

Execute o comando:

gcloud run jobs update JOB_NAME

Substituir

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: