Crea ed esegui job batch utilizzando Terraform e Cloud Scheduler

Questo tutorial spiega come utilizzare Terraform per creare ed eseguire job Batch utilizzando un cron job Cloud Scheduler.

Terraform è uno strumento open source che consente di eseguire il provisioning e di gestire l'infrastruttura specificando lo stato desiderato nei file di configurazione. Questi file possono essere trattati come codice e archiviati in sistemi di controllo della versione come GitHub.

Sebbene Terraform non disponga di risorse per Batch, questo tutorial mostra come utilizzare Terraform per creare job Batch. In particolare, puoi utilizzare Terraform per pianificare ed eseguire un cron job di Cloud Scheduler che ha come target l'API Batch per creare ed eseguire job Batch. Cloud Scheduler è un servizio Google Cloud che consente di pianificare automaticamente i cron job e supporta Terraform.

Questo tutorial è destinato agli utenti di Batch che gestiscono già l'infrastruttura con Terraform e vogliono incorporare i job Batch in Terraform.

Obiettivi

  • Crea una directory Terraform e un file di configurazione che definisce un cron job Cloud Scheduler che crea job Batch.
  • Esegui il deployment della configurazione Terraform per eseguire il cron job.
  • Verifica che il job cron crei job Batch.
  • Aggiorna la configurazione Terraform per mettere in pausa il cron job in modo che smetta di creare job Batch.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.

Prima di iniziare

  1. Prepara l'ambiente di sviluppo, Cloud Shell o una shell locale:

    Cloud Shell

    Per utilizzare un terminale online con gcloud CLI e Terraform già configurati, attiva Cloud Shell.

    Nella parte inferiore di questa pagina viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. L'inizializzazione della sessione può richiedere alcuni secondi.

    Shell locale

    Per utilizzare un ambiente di sviluppo locale:

    1. Installa Google Cloud CLI.

    2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    3. Per inizializzare gcloud CLI, esegui questo comando: 

      gcloud init
    4. Installa Terraform.

  2. Crea o seleziona un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Creare un progetto Google Cloud :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

  3. Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

  4. Abilita le API Batch, Compute Engine, Cloud Logging, Cloud Scheduler e Resource Manager:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli. 

    gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com cloudscheduler.googleapis.com cloudresourcemanager.googleapis.com

  5. Assicurati che il tuo progetto abbia almeno un service account con le autorizzazioni richieste per questo tutorial.

    In particolare, puoi utilizzare lo stesso account di servizio o due service account separati per concedere le seguenti autorizzazioni:

    • Consenti al job cron di creare job Batch e collegare ilaccount di serviziot per i job Batch.
    • Consenti ai job Batch di creare e accedere alle risorse necessarie per l'esecuzione.

    Per assicurarti che i account di servizio per questo tutorial dispongano delle autorizzazioni necessarie per utilizzare Terraform per creare job Batch tramite un job cron di Cloud Scheduler, chiedi all'amministratore di concedere i seguenti ruoli IAaccount di serviziocount per questo tutorial:

    • Service account per il cron job Cloud Scheduler:
    • Service account per i job batch:

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    L'amministratore potrebbe anche essere in grado di concedere ai account di servizio per questo tutorial le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

  6. Assicurati di disporre delle autorizzazioni necessarie per questo tutorial.

    In particolare, devi disporre delle autorizzazioni per eseguire le seguenti operazioni:

    • Crea un cron job e collega il account di servizio per il cron job.
    • Visualizza ed elimina il cron job e i job batch.

    Per ottenere le autorizzazioni necessarie per utilizzare Terraform per creare job Batch tramite un job cron di Cloud Scheduler, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Crea la directory e il file di configurazione Terraform

Crea una directory per Terraform e un file di configurazione che definisce le risorse da creare o aggiornare utilizzando Terraform. Il file di configurazione di esempio per questo tutorial definisce un cron job Cloud Scheduler denominato batch-job-invoker. Quando è abilitato, il cron job batch-job-invoker viene eseguito ogni 5 minuti per creare una nuova istanza del job Batch definito.

  1. Per creare una directory e un nuovo file di configurazione Terraform (.tf) al suo interno, digita il comando seguente e poi premi Enter:

    mkdir terraform && cd terraform && cat > main.tf

    Questo comando crea la directory terraform, ti porta al suo interno e inizia a definire un nuovo file di configurazione main.tf nella riga successiva.

  2. Copia e incolla la seguente configurazione 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_id}/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
    }
  }
}

    Sostituisci quanto segue:

    • PROJECT_ID: l' ID progetto del tuo progetto.
    • PROJECT_NUMBER: il numero di progetto del tuo progetto.

    • CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio che hai preparato per il cron job di Cloud Scheduler.

      Ad esempio, per utilizzare l'account di servizio predefinito di Compute Engine, specifica quanto segue:

      PROJECT_NUMBER-compute@developer.gserviceaccount.com

    • BATCH_SERVICE_ACCOUNT_EMAIL: l'indirizzo email delaccount di serviziot che hai preparato per i job batch.

      Ad esempio, per utilizzare l'account di servizio predefinito di Compute Engine, specifica quanto segue:

      PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Questa configurazione Terraform definisce alcune variabili di input e un job cron che contatta il metodo API per creare un job Batch.

  3. Per salvare e chiudere il file, premi Ctrl+D (o Command+D su macOS).

Esegui il deployment della configurazione Terraform per creare il cron job

Esegui il deployment della configurazione Terraform inizializzando Terraform, generando le modifiche pianificate e applicandole. Dopo aver eseguito il deployment della configurazione Terraform, puoi descrivere le risorse nel tuo progetto per verificare che Terraform abbia creato correttamente il job cron batch-job-invoker.

  1. Inizializza Terraform nella directory:

    terraform init

    L'output è simile al seguente:

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

  2. Genera il piano di esecuzione Terraform in base allo stato attuale del tuo progetto e al file di configurazione:

    terraform plan

    L'output è simile al seguente, che mostra che il piano prevede di creare il 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_ID/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.

  3. Per applicare il piano per creare il cron job batch-job-invoker, segui questi passaggi:

    1. Inserisci questo comando:

      terraform apply

      L'output è simile al comando terraform plan precedente, tranne che termina con una richiesta di conferma.

    2. Per confermare e applicare il piano, inserisci yes.

      L'output è simile al seguente:

      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.

  4. Per verificare che il job cron batch-job-invoker esista e sia abilitato, descrivilo:

    gcloud scheduler jobs describe batch-job-invoker --location us-central1

    L'output è simile al seguente:

    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_ID/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: '...'

    Nell'output, verifica che il campo state sia impostato su ENABLED.

Verifica che il job cron crei un job Batch

Verifica che il cron job batch-job-invoker crei correttamente i job batch.

  1. Attendi 5 minuti che il cron job venga eseguito automaticamente o attiva l'esecuzione immediata del cron job:

    gcloud scheduler jobs run batch-job-invoker --location us-central1

  2. Elenca i job Batch creati dal cron job batch-job-invoker:

    gcloud batch jobs list \
--filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" \
--sort-by ~createTime
    • Il flag --filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" filtra l'elenco in modo da includere solo i job batch che hanno un'etichetta con la chiave source e il valore terraform_and_cloud_scheduler_tutorial.
    • Il flag --sort-by ~createTime ordina l'elenco dal più recente al meno recente.

Aggiorna la configurazione Terraform per sospendere il cron job

Una volta raggiunto il numero desiderato di job Batch, aggiorna ed esegui il deployment della configurazione Terraform per mettere in pausa il job cron batch-job-invoker. Se vuoi aggiornare altre proprietà del cron job o dei batch job futuri, si applica lo stesso processo.

  1. Aggiorna il file di configurazione Terraform per mettere in pausa il cron job impostando il campo paused su true:

    sed -i 's/paused           = false # this cron job is enabled/paused           = true # this cron job is paused/g' main.tf

  2. Genera il piano di esecuzione Terraform in base allo stato attuale del tuo progetto e al file di configurazione:

    terraform plan

    L'output è simile al seguente, che mostra che il piano prevede di aggiornare il valore del campo paused da false a true:

    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.

  3. Per applicare il piano per aggiornare il job cron batch-job-invoker, segui questi passaggi:

    1. Inserisci questo comando:

      terraform apply

      L'output è simile al comando terraform plan precedente, tranne che termina con una richiesta di conferma.

    2. Per confermare e applicare il piano, inserisci yes.

      L'output è simile al seguente:

      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.

  4. Per verificare che il cron job batch-job-invoker sia in pausa, descrivilo:

    gcloud scheduler jobs describe batch-job-invoker --location us-central1

    L'output è simile al seguente:

    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_ID/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: '...'

    Nell'output, verifica che il campo state sia impostato su PAUSED.

Esegui la pulizia

Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

  1. Elimina un progetto Google Cloud :

    gcloud projects delete PROJECT_ID

  2. Vai alla directory principale, quindi elimina la directory Terraform e tutti i relativi file.

    cd .. && rm -r terraform

Elimina singole risorse

  1. Elimina il cron job batch-job-invoker.

    terraform destroy

  2. Per eliminare tutti i job Batch di questo tutorial:

    1. Elenca tutti i job Batch creati dal cron job batch-job-invoker:

      gcloud batch jobs list \
--filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" \
--sort-by ~createTime

      Registra il nome di ogni job da eliminare.

    2. Elimina un job batch da questo tutorial:

      gcloud batch jobs delete JOB_NAME --location us-central1

      Sostituisci JOB_NAME con il nome di un job Batch.

      Ripeti questo passaggio per tutti i job batch.

  3. Se hai creato un account di servizio per questo tutorial, eliminalo:

    gcloud iam service-accounts delete SERVICE_ACCOUNT_EMAIL

    Sostituisci SERVICE_ACCOUNT_EMAIL con l'indirizzo email di un account di servizio che hai creato per questo tutorial. ovvero hai utilizzato i seguenti service account:

    • CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL: il account di servizio per Cloud Scheduler.
    • BATCH_SERVICE_ACCOUNT_EMAIL: il account di servizio per Batch.

    Se hai creato due service account separati, ripeti questo passaggio.

  4. Vai alla directory principale, quindi elimina la directory Terraform e tutti i relativi file.

    cd .. && rm -r terraform

Passaggi successivi