Creare job

Questa pagina descrive come creare e aggiornare i job Cloud Run da un'immagine container esistente. A differenza di un servizio Cloud Run, che ascolta e gestisce le richieste, un job Cloud Run esegue solo le proprie attività ed esce al termine. Un job non ascolta né gestisce le richieste.

Dopo aver creato o aggiornato un job, puoi:

• Esegui il job una tantum, in base a una pianificazione o nell'ambito di un flusso di lavoro.
• Puoi eseguire l'override dei parametri configurati per un job quando lo esegui.
• Puoi gestire le esecuzioni di singoli job e visualizzare i log di esecuzione.

Puoi strutturare un job come una singola attività o come più attività indipendenti (fino a 10.000) che possono essere eseguite in parallelo. Ogni compito esegue un'istanza di contenitore e può essere configurato per riprovare in caso di errore. Ogni attività è consapevole del proprio indice, che viene memorizzato nella variabile di ambienteCLOUD_RUN_TASK_INDEX. Il conteggio complessivo delle attività viene memorizzato nella variabile di ambiente CLOUD_RUN_TASK_COUNT. Se stai elaborando dati in parallelo, è compito del tuo codice determinare quale attività gestisce quale sottoinsieme di dati.

Puoi impostare i timeout per le attività e specificare il numero di nuovi tentativi in caso di fallimento. Se un'attività supera il numero massimo di nuovi tentativi, viene contrassegnata come non riuscita e l'esecuzione del job viene contrassegnata come non riuscita dopo l'esecuzione di tutte le attività.

Per impostazione predefinita, ogni attività viene eseguita per un massimo di 10 minuti: puoi impostare un periodo di tempo più breve o più lungo fino a 168 ore (7 giorni). Il supporto per i timeout superiori a 24 ore è disponibile in Anteprima. Modificando l'impostazione del timeout delle attività.

Non è previsto un timeout esplicito per un'esecuzione di job: al termine di tutte le attività, l'esecuzione del job è completata.

I job utilizzano l'ambiente di esecuzione di seconda generazione.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare job Cloud Run, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Cloud Run Developer (roles/run.developer) nel job Cloud Run
• Utente account di servizio (roles/iam.serviceAccountUser) nell'identità di servizio

Per un elenco dei ruoli e delle autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il tuo job Cloud Run si interfaccia con le API Google Cloud, come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per ulteriori informazioni sulla concessione dei ruoli, consulta le autorizzazioni di deployment e gestisci l'accesso.

Immagini e registry dei container supportati

Puoi utilizzare direttamente le immagini container archiviate in Artifact Registry o Docker Hub. Google consiglia di utilizzare Artifact Registry.

Puoi utilizzare immagini container di altri registri pubblici o privati (come JFrog Artifactory, Nexus o GitHub Container Registry) configurando un repository remoto Artifact Registry.

Ti consigliamo di utilizzare Docker Hub solo per il deployment di immagini container popolari come le immagini ufficiali Docker o le immagini OSS sponsorizzate da Docker. Per una maggiore disponibilità, Google consiglia di eseguire il deployment di queste immagini di Docker Hub tramite un repository remoto Artifact Registry.

Crea un nuovo job

Puoi creare un nuovo job utilizzando la console Google Cloud, Google Cloud CLI, YAML o Terraform.

Console

Per creare un nuovo job:

1. Nella console Google Cloud, vai alla pagina Cloud Run:

   Vai a Cloud Run

2. Fai clic su Esegui il deployment del contenitore e seleziona Job per visualizzare il modulo Crea job.

   1. Nel modulo, specifica l'immagine del contenitore contenente il codice del job o seleziona un'opzione da un elenco di container di cui è stato eseguito il deployment in precedenza.
   2. Il nome del job viene generato automaticamente dall'immagine del contenitore. Puoi modificare o cambiare il nome del job in base alle esigenze. Il nome di un job non può essere modificato dopo la creazione.
   3. Seleziona la regione in cui vuoi che si trovi il job. Il selettore di regioni evidenzia le regioni con impatto sul carbonio più basso.
   4. Specifica il numero di attività da eseguire nel job. Affinché il job riesca, tutte le attività devono avere esito positivo. Per impostazione predefinita, le attività vengono eseguite in parallelo.

3. Fai clic su Container, volumi, networking, sicurezza per impostare proprietà aggiuntive del job.

   • In Capacità dell'attività:
   1. Nel menu Memoria, specifica la quantità di memoria richiesta. Il valore predefinito è il valore minimo richiesto, 512 MiB.
   2. Nel menu CPU, specifica la quantità di CPU richiesta. Il valore predefinito è il valore minimo richiesto, 1 CPU.

   3. In Timeout attività, specifica il periodo di tempo massimo in secondi durante il quale l'attività può essere eseguita, fino a 168 ore (7 giorni). Il supporto per i timeout superiori a 24 ore è disponibile in Anteprima. Ogni attività deve essere completata entro questo periodo di tempo. Il valore predefinito è 10 minuti (600 secondi).

   4. In Numero di nuovi tentativi per attività non riuscita, specifica il numero di nuovi tentativi in caso di errori nelle attività. Il valore predefinito è 3 tentativi.

   • In Parallelismo:

     1. Nella maggior parte dei casi puoi selezionare Esegui contemporaneamente il maggior numero di attività possibile.
     2. Se devi impostare un limite inferiore a causa di vincoli di scalabilità sulle risorse a cui accede il job, seleziona Limita il numero massimo di attività simultanee e specifica il numero di attività simultanee nel campo Limite di parallelismo personalizzato.

4. (Facoltativo) Configura altre impostazioni nelle schede appropriate:

   • Configurazione del contenitore
   • Limiti della CPU
   • Limiti di memoria
   • Secret
   • Variabili di ambiente
   • Etichette
   • Service account
   • Connessioni Cloud SQL
   • Connettività VPC

5. Al termine della configurazione del job, fai clic su Crea per creare il job in Cloud Run.

6. Per eseguire il job, consulta Eseguire job o Eseguire job in base a una pianificazione.

gcloud

Per utilizzare la riga di comando, devi aver già configurato gcloud CLI.

Per creare un nuovo job:

1. Esegui il comando:

   gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS

   In alternativa, utilizza il comando di deployment:

   gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS

   • Sostituisci JOB_NAME con il nome del job che vuoi creare. Puoi omettere questo parametro, ma se lo fai ti verrà chiesto il nome del job.
   • Sostituisci IMAGE_URL con un riferimento all'immagine del container, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.

   • Se vuoi, sostituisci OPTIONS con una delle seguenti opzioni:

     Opzione	Descrizione
     --tasks	Accetta numeri interi maggiori o uguali a 1. Il valore predefinito è 1; il valore massimo è 10.000. A ogni attività vengono fornite le variabili di ambiente CLOUD_RUN_TASK_INDEX con un valore compreso tra 0 e il numero di attività meno 1, oltre a CLOUD_RUN_TASK_COUNT, che è il numero di attività
     --max-retries	Il numero di volte in cui viene eseguito un nuovo tentativo per un'attività non riuscita. Se un'attività non riesce oltre questo limite, l'intero job viene contrassegnato come non riuscito. Ad esempio, se impostato su 1, verrà tentato un nuovo tentativo per un'attività non riuscita una volta, per un totale di due tentativi. Il valore predefinito è 3. Accetta numeri interi da 0 a 10.
     --task-timeout	Accetta una durata come "2s". Il valore predefinito è 10 minuti; il massimo è 168 ore (7 giorni). Il supporto per i timeout superiori a 24 ore è disponibile in Anteprima.
     --parallelism	Il numero massimo di attività che possono essere eseguite in parallelo. Per impostazione predefinita, le attività verranno avviate il più rapidamente possibile in parallelo. Consulta la sezione Parallelismi per conoscere l'intervallo di valori.
     --execute-now	Se impostato, viene avviata un'esecuzione del job immediatamente dopo la creazione del job. Equivalente a chiamare gcloud run jobs create seguito da gcloud run jobs execute.

     Oltre alle opzioni sopra indicate, puoi specificare anche altre configurazioni, ad esempio variabili di ambiente o limiti di memoria.

     Per un elenco completo delle opzioni disponibili durante la creazione di un job, consulta la documentazione della riga di comando gcloud run jobs create.

2. Attendi il completamento della creazione del job. Al termine dell'operazione, verrà visualizzato un messaggio di conferma.

3. Per eseguire il job, consulta Eseguire job o Eseguire job in base a una pianificazione.

YAML

Puoi memorizzare la specifica del job in un file YAML ed eseguirne il deployment utilizzando la gcloud CLI.

1. Crea un nuovo file job.yaml con i seguenti contenuti:

   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
     name: JOB
   spec:
     template:
       spec:
         template:
           spec:
             containers:
             - image: IMAGE

   Sostituisci

   • JOB con il nome del job Cloud Run. I nomi dei job devono contenere massimo 49 caratteri e devono essere univoci per regione e progetto.
   • IMAGE con l'URL dell'immagine del container del job.

   Puoi anche specificare ulteriori configurazioni, come variabili di ambiente o limiti di memoria.

2. Esegui il deployment del nuovo job utilizzando il seguente comando:

   gcloud run jobs replace job.yaml

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

Per creare un nuovo job Cloud Run, utilizza la risorsa google_cloud_run_v2_job e modifica il file main.tf come mostrato nel seguente snippet.

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

Librerie client

Per creare un job dal codice:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

API REST

Per creare un job, invia una richiesta HTTP POST all'endpoint jobs dell'API Cloud Run Admin.

Ad esempio, utilizzando 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

Sostituisci:

• ACCESS_TOKEN con un token di accesso valido per un account che possiede le autorizzazioni IAM per creare job. Ad esempio, se hai eseguito l'accesso a gcloud, puoi recuperare un token di accesso utilizzando gcloud auth print-access-token. All'interno di un'istanza container Cloud Run, puoi recuperare un token di accesso utilizzando il server di metadati dell'istanza container.
• JOB_NAME con il nome del job che vuoi creare.
• IMAGE_URL con l'URL dell'immagine del contenitore del job, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.
• REGION con la regione Google Cloud del job.
• PROJECT_ID con l'ID progetto Google Cloud.

Località Cloud Run

Cloud Run è un servizio a livello di regione, il che significa che l'infrastruttura che gestisce i tuoi servizi Cloud Run si trova in una regione specifica ed è gestita da Google in modo da essere disponibile in modo ridondante in tutte le zone all'interno della regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità è uno dei fattori principali per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. In genere puoi selezionare la regione più vicina ai tuoi utenti, ma devi prendere in considerazione la posizione degli altri prodotti Google Cloud utilizzati dal servizio Cloud Run. L'utilizzo combinato dei prodotti Google Cloud in più località può influire sulla latenza e sul costo del servizio.

Cloud Run è disponibile nelle seguenti regioni:

Soggetto ai prezzi di Livello 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• asia-south1 (Mumbai, India)
• europe-north1 (Finlandia) Bassi livelli di CO₂
• europe-southwest1 (Madrid) Basso livello di CO₂
• europe-west1 (Belgio) Bassi livelli di CO₂
• europe-west4 (Paesi Bassi) Bassi livelli di CO₂
• europe-west8 (Milano)
• europe-west9 (Parigi) Bassi livelli di CO₂
• me-west1 (Tel Aviv)
• us-central1 (Iowa) Bassi livelli di CO₂
• us-east1 (Carolina del Sud)
• us-east4 (Virginia del Nord)
• us-east5 (Columbus)
• us-south1 (Dallas) Bassi livelli di CO₂
• us-west1 (Oregon) Basso livello di CO₂

Soggetto ai prezzi di Livello 2

• africa-south1 (Johannesburg)
• asia-east2 (Hong Kong)
• asia-northeast3 (Seul, Corea del Sud)
• asia-southeast1 (Singapore)
• asia-southeast2 (Giacarta)
• asia-south2 (Delhi, India)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Varsavia, Polonia)
• europe-west10 (Berlino) Bassi livelli di CO₂
• europe-west12 (Torino)
• europe-west2 (Londra, Regno Unito) Bassi livelli di CO₂
• europe-west3 (Francoforte, Germania) Bassi livelli di CO₂
• europe-west6 (Zurigo, Svizzera) Bassi livelli di CO₂
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) Bassi livelli di CO₂
• northamerica-northeast2 (Toronto) Bassi livelli di CO₂
• southamerica-east1 (San Paolo, Brasile) Bassi livelli di CO₂
• southamerica-west1 (Santiago, Cile) Bassi livelli di CO₂
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

Se hai già creato un servizio Cloud Run, puoi visualizzare la regione nella dashboard di Cloud Run nella console Google Cloud.

Ok

Quando crei un nuovo job, l'agente di servizio Cloud Run deve essere in grado di accedere al contenitore, il che accade per impostazione predefinita.

Aggiornare un job esistente

La modifica di qualsiasi impostazione di configurazione richiede l'aggiornamento del job, anche se l'immagine del contenitore non viene modificata. Tieni presente che per le impostazioni non modificate, continueranno a essere utilizzate le impostazioni precedenti.

Puoi aggiornare un job esistente utilizzando la console Google Cloud, Google Cloud CLI, YAML o Terraform.

Console

Per aggiornare un job esistente:

1. Nella console Google Cloud, vai alla pagina Cloud Run:

   Vai a Cloud Run

2. Fai clic sulla scheda Job per visualizzare l'elenco dei job.

3. Fai clic sul job per visualizzare la pagina Dettagli job.

4. Fai clic su Modifica.

5. Se hai apportato modifiche al codice del job, specifica il nuovo digest dell'immagine del contenitore.

6. Se necessario, modifica il numero di attività nel job.

7. Se vuoi, fai clic su Container, volumi, networking, sicurezza per aggiornare eventuali proprietà aggiuntive del job:

   • In Capacità dell'attività:
   1. Nel menu Memoria, specifica la quantità di memoria richiesta. Il valore predefinito è il valore minimo richiesto, 512 MiB.
   2. Nel menu CPU, specifica la quantità di CPU richiesta. Il valore predefinito è il valore minimo richiesto, 1 CPU.
   3. In Timeout attività, specifica il periodo di tempo massimo in secondi durante il quale l'attività può essere eseguita, fino a 168 ore (7 giorni). Il supporto per i timeout superiori a 24 ore è disponibile in Anteprima. Ogni attività deve essere completata entro questo periodo di tempo. Il valore predefinito è 10 minuti (600 secondi).
   4. In Numero di nuovi tentativi per attività non riuscita, specifica il numero di nuovi tentativi in caso di errori nelle attività. Il valore predefinito è 3 tentativi.

   • In Parallelismo:

     1. Nella maggior parte dei casi puoi selezionare Esegui contemporaneamente il maggior numero di attività possibile.
     2. Se devi impostare un limite inferiore a causa di vincoli di scalabilità sulle risorse a cui accede il job, seleziona Limita il numero di attività simultanee e specifica il numero massimo di attività simultanee nel campo Limite di parallelismo personalizzato.

8. (Facoltativo) Configura altre impostazioni nelle schede appropriate:

   • Configurazione del contenitore
   • Limiti della CPU
   • Limiti di memoria
   • Secret
   • Variabili di ambiente
   • Etichette
   • Service account
   • Connessioni Cloud SQL
   • Connettività VPC

9. Al termine della configurazione del job, fai clic su Salva per creare il job in Cloud Run e attendi il completamento della creazione.

10. Per eseguire il job, consulta Eseguire job o Eseguire job in base a una pianificazione.

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. Esegui il comando:

   gcloud run jobs update JOB_NAME

   Sostituisci:

   • JOB_NAME con il nome del job da aggiornare.

   • Se vuoi, puoi sostituire OPTIONS con le seguenti opzioni:

     Opzione	Descrizione
     --tasks	Accetta numeri interi uguali o superiori a 1. Il valore predefinito è 1; il valore massimo è 10.000. A ogni attività vengono fornite le variabili di ambiente CLOUD_RUN_TASK_INDEX con un valore compreso tra 0 e il numero di attività meno 1, oltre a CLOUD_RUN_TASK_COUNT, che è il numero di attività
     --max-retries	Il numero di volte in cui viene eseguito un nuovo tentativo per un'attività non riuscita. Se un'attività non riesce oltre questo limite, l'intero job viene contrassegnato come non riuscito. Ad esempio, se impostato su 1, verrà tentato un nuovo tentativo per un'attività non riuscita una volta, per un totale di due tentativi. Il valore predefinito è 3. Accetta numeri interi da 0 a 10.
     --task-timeout	Accetta una durata come "2s". Il valore predefinito è 10 minuti; il massimo è 168 ore (7 giorni). Il supporto per i timeout superiori a 24 ore è disponibile in Anteprima.
     --parallelism	Il numero massimo di attività che possono essere eseguite in parallelo. Per impostazione predefinita, le attività verranno avviate il più rapidamente possibile, in parallelo. Consulta la sezione Parallelismi per conoscere l'intervallo di valori.

   Oltre alle opzioni sopra indicate, puoi impostare altre impostazioni di configurazione facoltative:

   • Configurazione del contenitore
   • Limiti della CPU
   • Limiti di memoria
   • Secret
   • Variabili di ambiente
   • Etichette
   • Service account
   • Connessioni Cloud SQL
   • Connessione VPC

   Per un elenco completo delle opzioni disponibili durante la creazione di un job, consulta la documentazione della riga di comando gcloud run jobs create.

3. Attendi il completamento dell'aggiornamento del job. Al termine, viene visualizzato un messaggio di operazione riuscita simile al seguente:

   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. Per eseguire il job, consulta Eseguire job o Eseguire job in base a una pianificazione.

YAML

Attenzione: le istruzioni riportate di seguito sostituiscono la configurazione del job esistente con quella specificata nel file YAML. Pertanto, se utilizzi YAML per apportare modifiche, devi evitare di utilizzare anche la console Google Cloud o gcloud CLI per apportare modifiche alla configurazione perché possono essere sovrascritte quando utilizzi YAML.

Se devi scaricare o visualizzare la configurazione di un job esistente, utilizza il seguente comando per salvare i risultati in un file YAML:

gcloud run jobs describe JOB --format export > job.yaml

Da un file YAML di configurazione del job, modifica gli attributi secondari spec.template come preferisci per aggiornare le impostazioni di configurazione, quindi esegui nuovamente il deployment:

1. Aggiorna la configurazione del job esistente:

   gcloud run jobs replace job.yaml

2. Per eseguire il job, consulta Eseguire job o Eseguire job in base a una pianificazione.

Terraform

Apporta modifiche alla configurazione del job nel file main.tf utilizzando il comando terraform apply. Sono disponibili istruzioni dettagliate su Terraform per:

• Parallelismi
• Numero massimo di nuovi tentativi
• Timeout

Per ulteriori informazioni, consulta le opzioni della riga di comando terraform apply.

Librerie client

Per aggiornare un job esistente dal codice:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

API REST

Per aggiornare un job, invia una richiesta HTTP PATCH all'endpoint jobs dell'API Cloud Run Admin.

Ad esempio, utilizzando 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

Sostituisci:

• ACCESS_TOKEN con un token di accesso valido per un account che possieda le autorizzazioni IAM per aggiornare i job. Ad esempio, se hai eseguito l'accesso a gcloud, puoi recuperare un token di accesso utilizzando gcloud auth print-access-token. All'interno di un'istanza container Cloud Run, puoi recuperare un token di accesso utilizzando il server di metadati dell'istanza container.
• JOB_NAME con il nome del job da aggiornare.
• IMAGE_URL con l'URL dell'immagine del contenitore del job, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.
• REGION con la regione Google Cloud del job.
• PROJECT_ID con l'ID progetto Google Cloud.

Codice di esempio

Per esempi di codice che mostrano job semplici, consulta le guide rapide specifiche per lingua.

Passaggi successivi

Dopo aver creato o aggiornato un job, puoi:

• Eseguire un job
• Eseguire un job in base a una pianificazione
• Gestire i job
• Gestire le esecuzioni dei job
• Visualizzare i log dei job
• Monitorare il rendimento dei job
• Impostare limiti di memoria
• Imposta le variabili di ambiente