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:

É 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:

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:

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

    Acessar o Cloud Run

  2. 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.
  3. 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.
  4. Como opção, defina outras configurações nas guias apropriadas:

  5. Quando terminar a configuração, clique em Criar para criar o job no Cloud Run.

  6. 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:

  1. 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.

  2. Aguarde a conclusão da criação do job. Você verá uma mensagem de conclusão bem-sucedida.

  3. 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.

  1. 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.

  2. 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) Ícone de folha Baixo CO2
  • europe-southwest1 (Madri) Ícone de folha Baixo CO2
  • europe-west1 (Bélgica) Ícone de folha Baixo CO2
  • europe-west4 (Países Baixos) Ícone de folha Baixo CO2
  • europe-west8 (Milão)
  • europe-west9 (Paris) Ícone de folha Baixo CO2
  • me-west1 (Tel Aviv)
  • us-central1 (Iowa) Ícone de folha Baixo CO2
  • us-east1 (Carolina do Sul)
  • us-east4 (Norte da Virgínia)
  • us-east5 (Columbus)
  • us-south1 (Dallas) Ícone de folha Baixo CO2
  • us-west1 (Oregon) Ícone de folha Baixo CO2

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) Ícone de folha Baixo CO2
  • europe-west12 (Turim)
  • europe-west2 (Londres, Reino Unido) Ícone de folha Baixo CO2
  • europe-west3 (Frankfurt, Alemanha) Ícone de folha Baixo CO2
  • europe-west6 (Zurique, Suíça) Ícone de folha Baixo CO2
  • me-central1 (Doha)
  • me-central2 (Damã)
  • northamerica-northeast1 (Montreal) Ícone de folha Baixo CO2
  • northamerica-northeast2 (Toronto) Ícone de folha Baixo CO2
  • southamerica-east1 (São Paulo, Brasil) Ícone de folha Baixo CO2
  • southamerica-west1 (Santiago, Chile) Ícone de folha Baixo CO2
  • 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:

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

    Acessar o Cloud Run

  2. Clique na guia Jobs para exibir a lista de jobs.

  3. Clique no job para exibir a página de detalhes.

  4. Clique em Editar.

  5. Se você fez alterações no código do job, especifique o novo resumo de imagem do contêiner.

  6. Se necessário, mude o número de tarefas no job.

  7. 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.
  8. Como opção, defina outras configurações nas guias apropriadas:

  9. Quando terminar de configurar o job, clique em Salvar para criar o job no Cloud Run e aguarde a criação.

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

gcloud

  1. 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.

  2. 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.

  3. 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
  4. 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:

  1. Atualize a configuração do job que já existe:

    gcloud run jobs replace job.yaml
  2. 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: