Neste tutorial, explicamos como usar o Terraform para criar e executar jobs do lote com um cron job do Cloud Scheduler.
O Terraform é uma ferramenta de código aberto que permite provisionar e gerenciar a infraestrutura especificando o estado desejado nos arquivos de configuração. Esses arquivos podem ser tratados como código e armazenados em sistemas de controle de versões, como o GitHub.
O Terraform não tem recursos para o Batch, mas este tutorial mostra como usá-lo para criar jobs do Batch. Especificamente, é possível usar o Terraform para programar e executar um cron job do Cloud Scheduler que segmente a API Batch para criar e executar jobs do Batch. O Cloud Scheduler é um serviço do Google Cloud que permite programar cron jobs automaticamente e oferece suporte ao Terraform.
Este tutorial é destinado a usuários do Batch que já gerenciam a infraestrutura com o Terraform e querem incorporar jobs do Batch ao Terraform.
Objetivos
- Criar um diretório do Terraform e um arquivo de configuração para definir um cron job do Cloud Scheduler que crie jobs do Batch.
- Implante a configuração do Terraform para executar o cron job.
- Verifique se o cron job cria jobs em lote.
- Atualize a configuração do Terraform para pausar o cron job para que ele pare de criar jobs do Batch.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.
Antes de começar
-
Prepare seu ambiente de desenvolvimento, o Cloud Shell ou um shell local:
Cloud Shell
Para usar um terminal on-line com a CLI gcloud e o Terraform já configurados, ative o Cloud Shell.
Na parte inferior da página, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. A inicialização da sessão pode levar alguns segundos.
Shell local
Para usar um ambiente de desenvolvimento local, siga estas etapas:
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- Instale o Terraform.
-
Crie ou selecione um projeto do Google Cloud.
-
Crie um projeto do Google Cloud:
gcloud projects create PROJECT_ID
Substitua
PROJECT_ID
por um nome para o projeto do Google Cloud que você está criando. -
Selecione o projeto do Google Cloud que você criou:
gcloud config set project PROJECT_ID
Substitua
PROJECT_ID
pelo nome do projeto do Google Cloud.
-
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Ative as APIs Batch, Compute Engine, Cloud Logging, Cloud Scheduler, and Resource Manager:
gcloud services enable batch.googleapis.com
compute.googleapis.com logging.googleapis.com cloudscheduler.googleapis.com cloudresourcemanager.googleapis.com -
Verifique se o projeto tem pelo menos uma conta de serviço com as permissões necessárias para este tutorial.
Especificamente, é possível usar a mesma conta de serviço ou duas contas de serviço separadas para conceder as seguintes permissões:
- Permita que o cron job crie jobs do Batch e anexe a conta de serviço aos jobs do Batch.
- Permita que os jobs do Batch criem e acessem os recursos necessários para serem executados.
Para garantir que as conta de serviço deste tutorial tenham as permissões necessárias para usar o Terraform na criação de jobs do Batch com um cron job do Cloud Scheduler, peça ao administrador para conceder às conta de serviço para este tutorial os seguintes papéis do IAM:
-
Conta de serviço do cron job do Cloud Scheduler:
-
Editor de jobs em lote (
roles/batch.jobsEditor
) no projeto -
Usuário da conta de serviço (
roles/iam.serviceAccountUser
) na conta de serviço para jobs do Batch (mesmo que seja em si)
-
Editor de jobs em lote (
-
Conta de serviço para os jobs do Batch:
-
Relatório do agente em lote (
roles/batch.agentReporter
) no projeto -
Gravador de registros (
roles/logging.logWriter
) no projeto
-
Relatório do agente em lote (
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Talvez o administrador também possa conceder as conta de serviço deste tutorial as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
-
Verifique se você tem as permissões necessárias para este tutorial.
Especificamente, você precisa de permissões para fazer o seguinte:
- Crie um cron job e anexe a conta de serviço a ele.
- Visualizar e excluir o cron job e os jobs em lote.
Para receber as permissões necessárias para usar o Terraform na criação de jobs do Batch com um cron job do Cloud Scheduler, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Usuário da conta de serviço (
roles/iam.serviceAccountUser
) na conta de serviço do cron job do Cloud Scheduler -
Administrador do Cloud Scheduler (
roles/cloudscheduler.admin
) no projeto -
Editor de jobs em lote (
roles/batch.jobsEditor
) no projeto -
Visualizador de registros (
roles/logging.viewer
) no projeto
crie o diretório e o arquivo de configuração do Terraform
Crie um diretório para o Terraform e um arquivo de configuração
que defina os recursos que você quer criar ou atualizar usando o Terraform.
O arquivo de configuração de exemplo deste tutorial define um cron job do Cloud Scheduler chamado batch-job-invoker
.
Quando ativado, o cron job batch-job-invoker
é executado a cada cinco minutos para criar uma nova instância do job em lote
definido.
Para criar um diretório e um novo arquivo de configuração do Terraform (
.tf
) dentro desse diretório, digite o seguinte comando e pressioneEnter
:mkdir terraform && cd terraform && cat > main.tf
Esse comando cria o diretório
terraform
, leva você até ele e começa a definir um novo arquivo de configuraçãomain.tf
na próxima linha.Copie e cole a seguinte configuração do Terraform:
# define variables variable "project_id" { type = string description = "The project name to use." default = "PROJECT_ID" } variable "project_number" { type = string description = "The project number to use." default = "PROJECT_NUMBER" } variable "region" { type = string description = "The region where resources are created." default = "us-central1" } variable "cloud_scheduler_service_account_email" { type = string description = "The service account email." default = "CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL" } variable "batch_service_account_email" { type = string description = "The service account email." default = "BATCH_SERVICE_ACCOUNT_EMAIL" } # define a Cloud Scheduler cron job which triggers Batch jobs resource "google_cloud_scheduler_job" "batch-job-invoker" { paused = false # this cron job is enabled name = "batch-job-invoker" project = var.project_id region = var.region schedule = "*/5 * * * *" # when enabled, run every 5 minutes time_zone = "America/Los_Angeles" attempt_deadline = "180s" retry_config { max_doublings = 5 max_retry_duration = "0s" max_backoff_duration = "3600s" min_backoff_duration = "5s" } # when this cron job runs, create and run a Batch job http_target { http_method = "POST" uri = "https://batch.googleapis.com/v1/projects/${var.project_number}/locations/${var.region}/jobs" headers = { "Content-Type" = "application/json" "User-Agent" = "Google-Cloud-Scheduler" } # Batch job definition body = base64encode(<<EOT { "taskGroups":[ { "taskSpec": { "runnables":{ "script": { "text": "echo Hello world! This job was created using Terraform and Cloud Scheduler." } } } } ], "allocationPolicy": { "serviceAccount": { "email": "${var.batch_service_account_email}" } }, "labels": { "source": "terraform_and_cloud_scheduler_tutorial" }, "logsPolicy": { "destination": "CLOUD_LOGGING" } } EOT ) oauth_token { scope = "https://www.googleapis.com/auth/cloud-platform" service_account_email = var.cloud_scheduler_service_account_email } } }
Substitua:
PROJECT_ID
: o ID do projeto.PROJECT_NUMBER
: o número do projeto.CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL
: o endereço de e-mail da conta de serviço que você preparou para o cron job do Cloud Scheduler.Por exemplo, para usar a conta de serviço padrão do Compute Engine, especifique o seguinte:
PROJECT_NUMBER-compute@developer.gserviceaccount.com
BATCH_SERVICE_ACCOUNT_EMAIL
: o endereço de e-mail da conta de serviço que você preparou para os jobs do Batch.Por exemplo, para usar a conta de serviço padrão do Compute Engine, especifique o seguinte:
PROJECT_NUMBER-compute@developer.gserviceaccount.com
Essa configuração do Terraform define algumas variáveis de entrada e um cron job que entra em contato com o método da API para criar um job do Batch.
Para salvar e fechar o arquivo, pressione
Ctrl+D
(ouCommand+D
no macOS).
Implantar a configuração do Terraform para criar o cron job
Implante a configuração do Terraform inicializando-o, gerando as alterações planejadas e aplicando-as. Depois de implantar a configuração do Terraform, você pode descrever os recursos no seu projeto para verificar se
o Terraform criou com sucesso o cron job batch-job-invoker
.
Inicialize o Terraform no diretório:
terraform init
O resultado será assim:
... Terraform has been successfully initialized! You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure. All Terraform commands should now work. If you ever set or change modules or backend configuration for Terraform, rerun this command to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary.
Gere o plano de execução do Terraform com base no estado atual do projeto e no arquivo de configuração:
terraform plan
A saída é semelhante à seguinte, que mostra que o plano é criar o cron job
batch-job-invoker
:Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + create Terraform will perform the following actions: # google_cloud_scheduler_job.batch-job-invoker will be created + resource "google_cloud_scheduler_job" "batch-job-invoker" { + id = (known after apply) + name = "batch-job-invoker" + paused = false + project = "PROJECT_ID" + region = "us-central1" + schedule = "*/5 * * * *" + state = (known after apply) + time_zone = "America/Los_Angeles" + http_target { + body = "..." + headers = { + "Content-Type" = "application/json" + "User-Agent" = "Google-Cloud-Scheduler" } + http_method = "POST" + uri = "https://batch.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/jobs" + oauth_token { + scope = "https://www.googleapis.com/auth/cloud-platform" + service_account_email = "CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL" } } + retry_config { + max_backoff_duration = "3600s" + max_doublings = 5 + max_retry_duration = "0s" + min_backoff_duration = "5s" + retry_count = (known after apply) } } Plan: 1 to add, 0 to change, 0 to destroy. ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.
Para aplicar o plano e criar o cron job
batch-job-invoker
, siga estas etapas:Digite este comando:
terraform apply
A saída é semelhante ao comando
terraform plan
anterior, mas termina com um prompt de confirmação.Para confirmar e aplicar o plano, insira
yes
.O resultado será assim:
google_cloud_scheduler_job.batch-job-invoker: Creating... google_cloud_scheduler_job.batch-job-invoker: Creation complete after 0s [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker] Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
Para verificar se o cron job
batch-job-invoker
existe e está ativado, descreva-o:gcloud scheduler jobs describe batch-job-invoker --location us-central1
O resultado será assim:
attemptDeadline: 180s httpTarget: body: ... headers: Content-Type: application/json User-Agent: Google-Cloud-Scheduler httpMethod: POST oauthToken: scope: https://www.googleapis.com/auth/cloud-platform serviceAccountEmail: CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL uri: https://batch.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/jobs lastAttemptTime: '...' name: projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker retryConfig: maxBackoffDuration: 3600s maxDoublings: 5 maxRetryDuration: 0s minBackoffDuration: 5s schedule: '*/5 * * * *' scheduleTime: '...' state: ENABLED status: {} timeZone: America/Los_Angeles userUpdateTime: '...'
Na saída, verifique se o campo
state
está definido comoENABLED
.
Verificar se o cron job cria um job em lote
Verifique se o cron job batch-job-invoker
está criando jobs em lote corretamente.
Aguarde cinco minutos para que o cron job seja executado automaticamente ou acione a execução imediata do cron job:
gcloud scheduler jobs run batch-job-invoker --location us-central1
Liste os jobs em lote que foram criados pelo cron job
batch-job-invoker
:gcloud batch jobs list \ --filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" \ --sort-by ~createTime
- A flag
--filter labels.source=\"terraform_and_cloud_scheduler_tutorial\"
filtra a lista para incluir apenas jobs do Batch que têm um rótulo com a chavesource
e o valorterraform_and_cloud_scheduler_tutorial
. - A flag
--sort-by ~createTime
classifica a lista da mais recente à mais antiga.
- A flag
Atualizar a configuração do Terraform para pausar o cron job
Depois que você tiver o número desejado de jobs do Batch, atualize e implante a configuração do Terraform para pausar o cron job batch-job-invoker
. Se você quiser atualizar outras propriedades do
cron job ou futuros jobs do Batch,
o mesmo processo será aplicado.
Atualize o arquivo de configuração do Terraform para pausar o cron job definindo o campo
paused
comotrue
:sed -i 's/paused = false # this cron job is enabled/paused = true # this cron job is paused/g' main.tf
Gere o plano de execução do Terraform com base no estado atual do projeto e no arquivo de configuração:
terraform plan
A saída é semelhante à seguinte, que mostra que o plano é atualizar o valor do campo
paused
defalse
paratrue
:google_cloud_scheduler_job.batch-job-invoker: Refreshing state... [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker] Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: ~ update in-place Terraform will perform the following actions: # google_cloud_scheduler_job.batch-job-invoker will be updated in-place ~ resource "google_cloud_scheduler_job" "batch-job-invoker" { id = "projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker" name = "batch-job-invoker" ~ paused = false -> true # (6 unchanged attributes hidden) ~ http_target { ~ headers = { + "User-Agent" = "Google-Cloud-Scheduler" # (1 unchanged element hidden) } # (3 unchanged attributes hidden) # (1 unchanged block hidden) } # (1 unchanged block hidden) } Plan: 0 to add, 1 to change, 0 to destroy. ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.
Para aplicar o plano de atualização do cron job
batch-job-invoker
, siga estas etapas:Digite este comando:
terraform apply
A saída é semelhante ao comando
terraform plan
anterior, mas termina com um prompt de confirmação.Para confirmar e aplicar o plano, insira
yes
.O resultado será assim:
google_cloud_scheduler_job.batch-job-invoker: Modifying... [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker] google_cloud_scheduler_job.batch-job-invoker: Modifications complete after 1s [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker] Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
Para verificar se o cron job
batch-job-invoker
está pausado, descreva-o:gcloud scheduler jobs describe batch-job-invoker --location us-central1
O resultado será assim:
attemptDeadline: 180s httpTarget: body: ... headers: Content-Type: application/json User-Agent: Google-Cloud-Scheduler httpMethod: POST oauthToken: scope: https://www.googleapis.com/auth/cloud-platform serviceAccountEmail: CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL uri: https://batch.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/jobs lastAttemptTime: '...' name: projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker retryConfig: maxBackoffDuration: 3600s maxDoublings: 5 maxRetryDuration: 0s minBackoffDuration: 5s schedule: '*/5 * * * *' scheduleTime: '...' state: PAUSED status: {} timeZone: America/Los_Angeles userUpdateTime: '...'
Na saída, verifique se o campo
state
está definido comoPAUSED
.
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Excluir o projeto
Exclua um projeto do Google Cloud:
gcloud projects delete PROJECT_ID
Acesse o diretório pai e exclua o diretório do Terraform e todos os arquivos dele.
cd .. && rm -r terraform
Excluir recursos individuais
Exclua o cron job
batch-job-invoker
.terraform destroy
Para excluir todos os jobs do Batch deste tutorial, siga estas etapas:
Liste todos os jobs em lote que foram criados pelo cron job
batch-job-invoker
:gcloud batch jobs list \ --filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" \ --sort-by ~createTime
Registre o nome de cada job que você precisa excluir.
Excluir um job do Batch deste tutorial:
gcloud batch jobs delete JOB_NAME --location us-central1
Substitua
JOB_NAME
pelo nome de um job em lote.Repita essa etapa para todos os jobs em lote.
Se você criou uma conta de serviço para este tutorial, exclua-a:
gcloud iam service-accounts delete SERVICE_ACCOUNT_EMAIL
Substitua
SERVICE_ACCOUNT_EMAIL
pelo endereço de e-mail de uma conta de serviço que você criou para este tutorial. Ou seja, você usou as seguintes contas de serviço:CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL
: a conta de serviço do Cloud Scheduler.BATCH_SERVICE_ACCOUNT_EMAIL
: a conta de serviço do Batch.
Se você criou duas contas de serviço separadas, repita esta etapa.
Acesse o diretório pai e exclua o diretório do Terraform e todos os arquivos dele.
cd .. && rm -r terraform
A seguir
- Saiba mais sobre como usar o Terraform com o Google Cloud:
- Saiba mais sobre os cron jobs do Cloud Scheduler.
- Saiba mais sobre os jobs em lote.