Creare ed eseguire job batch utilizzando Terraform e Cloud Scheduler

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

Terraform è uno strumento open source che consente di eseguire il provisioning e 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.

Anche se Terraform non dispone 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 job batch in Terraform.

Obiettivi

Crea una directory Terraform e un file di configurazione che definisca un cron job di Cloud Scheduler che crea job batch.
Eseguire il deployment della configurazione Terraform per eseguire il cron job.
Verifica che il cron job crei job batch.
Aggiorna la configurazione Terraform per mettere in pausa il cron job in modo che interrompa la creazione di job batch.

Costi

In questo documento, utilizzi 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 essere idonei per una prova gratuita.

Una volta completate le attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la pagina Pulizia.

Prima di iniziare

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.

In fondo a questa pagina viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. L'inizializzazione della sessione può richiedere alcuni secondi.
Shell locale

Per utilizzare un ambiente di sviluppo locale, segui questi passaggi:
1. Installa Google Cloud CLI.
2. Per initialize gcloud CLI, esegui questo comando:
```
gcloud init
```
3. Installa Terraform.
Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
- Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
  Replace PROJECT_ID with a name for the Google Cloud project you are creating.
- Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
  Replace PROJECT_ID with your Google Cloud project name.
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Abilita le API 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

Assicurati che il progetto abbia almeno un account di servizio con le autorizzazioni necessarie per questo tutorial.

Nota: se utilizzi un nuovo progetto, questo passaggio non è obbligatorio a meno che la tua organizzazione non impedisca la concessione automatica dei ruoli per gli account di servizio predefiniti. Per impostazione predefinita, all'account di servizio predefinito di Compute Engine viene concesso automaticamente il ruolo IAM Editor (roles/editor), che dispone già di tutte le autorizzazioni necessarie per questo tutorial.

In particolare, puoi utilizzare lo stesso account di servizio o due account di servizio separati per concedere le seguenti autorizzazioni:
- Consenti al cron job di creare job batch e collegare l'account di servizio per questi job.
- Consenti ai job batch di creare e accedere alle risorse necessarie per l'esecuzione.
Per assicurarti che gli account di servizio per questo tutorial dispongano delle autorizzazioni necessarie per utilizzare Terraform al fine di creare job batch tramite un cron job di Cloud Scheduler, chiedi all'amministratore di concedere agli account di servizio per questo tutorial i seguenti ruoli IAM:
- Account di servizio per il cron job di Cloud Scheduler:
  - Editor job batch (roles/batch.jobsEditor) nel progetto
  - Utente account di servizio (roles/iam.serviceAccountUser) nell'account di servizio per i job batch (anche se si tratta di un account)
- Account di servizio per i job batch:
  - Reporter agente batch (roles/batch.agentReporter) nel progetto
  - Writer log (roles/logging.logWriter) sul progetto
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

L'amministratore potrebbe anche essere in grado di concedere agli account di servizio per questo tutorial le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Assicurati di disporre delle autorizzazioni necessarie per questo tutorial.

Nota: se hai creato questo progetto, questo passaggio non è obbligatorio. In qualità di creatore del progetto, ti viene concesso automaticamente il ruolo IAM Proprietario (roles/owner), che dispone già di tutte le autorizzazioni necessarie per questo tutorial.

In particolare, devi disporre delle autorizzazioni per:
- Crea un cron job e collega l'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 cron job di Cloud Scheduler, chiedi all'amministratore di concederti i ruoli IAM seguenti:
- Utente account di servizio (roles/iam.serviceAccountUser) sull'account di servizio per il cron job di Cloud Scheduler
- Amministratore Cloud Scheduler (roles/cloudscheduler.admin) nel progetto
- Editor job batch (roles/batch.jobsEditor) nel progetto
- Visualizzatore log (roles/logging.viewer) sul progetto

Crea la directory Terraform e il file di configurazione

Crea una directory per Terraform e un file di configurazione che definisca le risorse da creare o aggiornare utilizzando Terraform. Il file di configurazione di esempio per questo tutorial definisce un cron job di 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.

Per creare una directory e un nuovo file di configurazione Terraform (.tf) all'interno di quella directory, digita il seguente comando, quindi premi Enter:
```
mkdir terraform && cd terraform && cat > main.tf
```
Questo comando crea la directory terraform, apre la directory e inizia a definire un nuovo file di configurazione main.tf nella riga successiva.

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_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
    }
  }
}

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto del progetto.
PROJECT_NUMBER: il numero di progetto del tuo progetto.
CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL: l'indirizzo email dell'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 dell'account di servizio 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 cron job che contatta il metodo API per creare un job batch.

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 del tuo progetto per verificare che Terraform abbia creato correttamente il cron job batch-job-invoker.

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.

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

terraform plan

L'output è simile al seguente, che mostra che il piano prevede la creazione del 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.

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 precedente comando terraform plan, tranne per il fatto che termina con un prompt 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.
```

Per verificare che il cron job 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_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: '...'

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

Verifica che il cron job crei un job batch

Verifica che il cron job batch-job-invoker stia creando correttamente job batch.

Attendi 5 minuti affinché il cron job venga eseguito automaticamente oppure attivalo immediatamente:
```
gcloud scheduler jobs run batch-job-invoker --location us-central1
```
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 mettere in pausa il cron job

Dopo aver ottenuto il numero desiderato di job batch, aggiorna ed esegui il deployment della configurazione Terraform per mettere in pausa il cron job batch-job-invoker. Se vuoi aggiornare altre proprietà del cron job o dei job batch futuri, viene applicato lo stesso processo.

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

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

terraform plan

L'output è simile al seguente, che indica 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.

Per applicare il piano di aggiornamento del cron job batch-job-invoker, segui questi passaggi:

Inserisci questo comando:
```
terraform apply
```
L'output è simile al precedente comando terraform plan, tranne per il fatto che termina con un prompt di conferma.

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.

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_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: '...'

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

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:
- L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività in questo documento, quando lo elimini elimini anche qualsiasi altro lavoro svolto nel progetto.
- Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.
Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.
Elimina un progetto Google Cloud:
```
gcloud projects delete PROJECT_ID
```
Vai alla directory padre, quindi elimina la directory Terraform e tutti i suoi file.
```
cd .. && rm -r terraform
```

Elimina singole risorse

Elimina il cron job batch-job-invoker.

Nota: per questo tutorial, il modo più semplice è utilizzare il seguente comando terraform destroy, che elimina tutte le risorse gestite dal file di configurazione Terraform. Tuttavia, se un file di configurazione Terraform contiene altre risorse che non vuoi eliminare, aggiorna la configurazione Terraform.
```
terraform destroy
```
Per eliminare tutti i job batch da questo tutorial, segui questi passaggi:
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 che devi 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.
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. In particolare, hai utilizzato i seguenti account di servizio:
- CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL: l'account di servizio per Cloud Scheduler.
- BATCH_SERVICE_ACCOUNT_EMAIL: l'account di servizio per Batch.
Se hai creato due account di servizio distinti, ripeti questo passaggio.
Vai alla directory padre, quindi elimina la directory Terraform e tutti i suoi file.
```
cd .. && rm -r terraform
```

Passaggi successivi

Scopri di più sull'utilizzo di Terraform con Google Cloud:
- Documentazione di Terraform per Google Cloud
- Documentazione di Google Cloud per Terraform
Scopri di più sui cron job di Cloud Scheduler.
Scopri di più sui job batch.

Creare ed eseguire job batch utilizzando Terraform e Cloud Scheduler

Obiettivi

Costi

Prima di iniziare

Cloud Shell

Shell locale

Crea la directory Terraform e il file di configurazione

Esegui il deployment della configurazione Terraform per creare il cron job

Verifica che il cron job crei un job batch

Aggiorna la configurazione Terraform per mettere in pausa il cron job

Esegui la pulizia

Elimina il progetto

Elimina singole risorse

Passaggi successivi