Creazione di job

Questa pagina descrive come creare e aggiornare 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 le proprie attività e si chiude solo al termine. Un job non rimane in ascolto 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 ne esegui uno.
• Puoi gestire le esecuzioni di singoli job e visualizzare i relativi log.

Puoi strutturare un job come singola o come più attività indipendenti (fino a 10.000 attività) che possono essere eseguite in parallelo. Ogni attività esegue un'istanza di container e può essere configurata per riprovare in caso di errore. Ogni attività è a conoscenza del proprio indice, che viene archiviato nella variabile di ambiente CLOUD_RUN_TASK_INDEX. Il conteggio complessivo delle attività viene archiviato nella variabile di ambiente CLOUD_RUN_TASK_COUNT. Se elabori i dati in parallelo, il tuo codice è responsabile di determinare quale attività gestisce quale sottoinsieme di dati.

Puoi impostare timeout sulle attività e specificare il numero di nuovi tentativi in caso di errore dell'attività. Se un'attività supera il numero massimo di nuovi tentativi, l'attività 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 modificare questa impostazione scegliendo un periodo di tempo più breve o più lungo, fino a 24 ore. Per farlo, modifica l'impostazione di timeout dell'attività.

Non esiste un timeout esplicito per l'esecuzione di un job: una volta completate 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:

• Sviluppatore Cloud Run (roles/run.developer) sul job Cloud Run
• Utente account di servizio (roles/iam.serviceAccountUser) sull'identità del 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 job Cloud Run si interfaccia con le API Google Cloud, ad esempio le librerie client di Cloud, consulta la guida alla configurazione dell'identità del servizio. Per ulteriori informazioni sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestire l'accesso.

Immagini e registri di 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 di Artifact Registry.

Ti consigliamo di prendere in considerazione solo Docker Hub per il deployment di immagini container popolari, come le immagini ufficiali Docker o le immagini Docker Sponsorizzate OSS. Per una maggiore disponibilità, Google consiglia di eseguire il deployment di queste immagini Docker Hub tramite un repository remoto di 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. Vai a Cloud Run

2. Fai clic sulla scheda Job.

3. Fai clic su Crea job per visualizzare il modulo Crea job.

   1. Nel modulo, specifica l'immagine container contenente il codice del job o seleziona da un elenco di container di cui è stato eseguito il deployment in precedenza.
   2. Il nome del job viene generato automaticamente dall'immagine container. Puoi modificare o cambiare il nome del job in base alle tue esigenze. Non è possibile modificare il nome di un job dopo la sua creazione.
   3. Seleziona la regione in cui vuoi collocare il job. Il selettore di regioni evidenzia le regioni con l'impatto più basso di anidride carbonica.
   4. Specifica il numero di attività che vuoi eseguire nel job. Tutte le attività devono avere esito positivo affinché il job abbia esito positivo. Per impostazione predefinita, le attività vengono eseguite in parallelo.

4. Fai clic su Container, volumi, networking, sicurezza per impostare altre proprietà del job.

   • Nella sezione Capacità attività:
   1. Nel menu a discesa Memoria, specifica la quantità di memoria richiesta. Il valore predefinito è il minimo richiesto, 512 MiB.
   2. Nel menu a discesa della CPU, specifica la quantità di CPU richiesta. Il valore predefinito è il minimo richiesto, 1 CPU.

   3. In Timeout attività, specifica il tempo massimo in secondi per cui l'attività può essere eseguita, fino a 24 ore. 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 tentativi in caso di errori delle attività. Il valore predefinito è 3 nuovi tentativi.

   • Con parallelismo:

     1. Nella maggior parte dei casi puoi selezionare Esegui il maggior numero possibile di attività contemporaneamente.
     2. Se devi impostare un limite inferiore a causa dei 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 nella casella di testo Limite di parallelismo personalizzato.

5. Facoltativamente, configura altre impostazioni nelle schede appropriate:

   • Configurazione container
   • Limiti della CPU
   • Limiti di memoria
   • Secret
   • Variabili di ambiente
   • Etichette
   • Account di servizio
   • Connessioni Cloud SQL
   • Connettività VPC

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

7. Per eseguire il job, vedi Eseguire job o eseguire i 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 ometti, ti verrà richiesto il nome del job.
   • Sostituisci IMAGE_URL con un riferimento all'immagine 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 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, insieme a CLOUD_RUN_TASK_COUNT, che è il numero di attività
     --max-retries	Il numero di volte in cui viene ripetuto un'attività non riuscita. Quando un'attività supera questo limite, l'intero job viene contrassegnato come non riuscito. Ad esempio, se il valore è impostato su 1, un'attività non riuscita verrà ripetuta una volta per un totale di due tentativi. Il valore predefinito è 3. Accetta numeri interi compresi tra 0 e 10.
     --task-timeout	Accetta una durata come "2 s". Il valore predefinito è 10 minuti; il massimo è 24 ore.
     --parallelism	Il numero massimo di attività che possono essere eseguite in parallelo. Per impostazione predefinita, le attività verranno avviate in parallelo il più rapidamente possibile. Fai riferimento a Parallelismo per conoscere l'intervallo di valori.
     --execute-now	Se impostato, subito dopo la creazione del job, viene avviata un'esecuzione del job. Equivale a chiamare gcloud run jobs create seguito da gcloud run jobs execute.

     Oltre alle opzioni precedenti, devi specificare anche altre configurazioni, come le variabili di ambiente o i limiti di memoria.

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

2. Attendi il completamento della creazione del job. Una volta completato, vedrai un messaggio di operazione riuscita.

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

YAML

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

1. Crea un nuovo file job.yaml con questi 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 tuo job Cloud Run. I nomi dei job devono contenere al massimo 49 caratteri e devono essere univoci per ogni regione e progetto.
   • IMAGE con l'URL dell'immagine container del job.

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

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

   gcloud run jobs replace job.yaml

Terraform

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

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

resource "google_cloud_run_v2_job" "default" {
  provider     = google-beta
  name         = "cloud-run-job"
  location     = "us-central1"
  launch_stage = "BETA"

  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, se utilizzi 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 dispone delle 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. Dall'interno di un'istanza di container Cloud Run, puoi recuperare un token di accesso utilizzando il server di metadati dell'istanza di container.
• JOB_NAME con il nome del job che vuoi creare.
• IMAGE_URL con l'URL dell'immagine container 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 è regionale, il che significa che l'infrastruttura che esegue i tuoi servizi Cloud Run si trova in una regione specifica ed è gestita da Google per essere disponibile in modo ridondante in tutte le zone all'interno della regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità sono fattori principali per la selezione della regione in cui vengono eseguiti i servizi Cloud Run. In genere puoi selezionare la regione più vicina ai tuoi utenti, ma devi considerare la località degli altri prodotti Google Cloud utilizzati dal tuo servizio Cloud Run. L'utilizzo combinato di prodotti Google Cloud in più località può influire sulla latenza e sui costi del tuo servizio.

Cloud Run è disponibile nelle regioni seguenti:

Soggetto ai prezzi di Livello 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• europe-north1 (Finlandia) A basse emissioni di CO₂
• europe-southwest1 (Madrid)
• europe-west1 (Belgio) A basse emissioni di CO₂
• europe-west4 (Paesi Bassi)
• europe-west8 (Milano)
• europe-west9 (Parigi) A basse emissioni di CO₂
• me-west1 (Tel Aviv)
• us-central1 (Iowa) A basse emissioni di CO₂
• us-east1 (Carolina del Sud)
• us-east4 (Virginia del Nord)
• us-east5 (Colombo)
• us-south1 (Dallas)
• us-west1 (Oregon) A basse emissioni 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-south1 (Mumbai, India)
• asia-south2 (Delhi, India)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Varsavia, Polonia)
• europe-west10 (Berlino)
• europe-west12 (Torino)
• europe-west2 (Londra, Regno Unito) A basse emissioni di CO₂
• europe-west3 (Francoforte, Germania) A basse emissioni di CO₂
• europe-west6 (Zurigo, Svizzera) A basse emissioni di CO₂
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) A basse emissioni di CO₂
• northamerica-northeast2 (Toronto) A basse emissioni di CO₂
• southamerica-east1 (San Paolo, Brasile) A basse emissioni di CO₂
• southamerica-west1 (Santiago, Cile) A basse emissioni 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 all'interno della console Google Cloud.

Ok

Quando crei un nuovo job, l'agente di servizio Cloud Run deve poter accedere al container (operazione predefinita).

Aggiorna un job esistente

La modifica delle impostazioni di configurazione richiede l'aggiornamento del job, anche se l'immagine container non viene modificata. Tieni presente che, per le impostazioni non modificate, verranno 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. Vai a Cloud Run

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

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

4. Fai clic su Modifica.

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

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

7. Facoltativamente, fai clic su Container, volumi, networking, sicurezza per aggiornare eventuali proprietà aggiuntive del job come preferisci:

   • Nella sezione Capacità attività:
   1. Nel menu a discesa Memoria, specifica la quantità di memoria richiesta. Il valore predefinito è il minimo richiesto, 512 MiB.
   2. Nel menu a discesa della CPU, specifica la quantità di CPU richiesta. Il valore predefinito è il minimo richiesto, 1 CPU.
   3. In Timeout attività, specifica il tempo massimo in secondi per cui l'attività può essere eseguita, fino a 24 ore. 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 tentativi in caso di errori delle attività. Il valore predefinito è 3 nuovi tentativi.

   • Con parallelismo:

     1. Nella maggior parte dei casi puoi selezionare Esegui il maggior numero possibile di attività contemporaneamente.
     2. Se devi impostare un limite inferiore a causa dei 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 nella casella di testo Limite di parallelismo personalizzato.

8. Facoltativamente, configura altre impostazioni nelle schede appropriate:

   • Configurazione container
   • Limiti della CPU
   • Limiti di memoria
   • Secret
   • Variabili di ambiente
   • Etichette
   • Account di servizio
   • 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, vedi Eseguire job o eseguire i job in base a una pianificazione.

gcloud

1. Nella console Google Cloud, attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

2. Esegui il comando:

   gcloud run jobs update JOB_NAME

   Sostituisci

   • JOB_NAME con il nome del job che vuoi aggiornare.

   • Se vuoi, sostituisci OPTIONS con le seguenti opzioni:

     Opzione	Descrizione
     --tasks	Accetta numeri interi uguali o maggiori di 1. Il valore predefinito è 1,il 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, insieme a CLOUD_RUN_TASK_COUNT, che è il numero di attività
     --max-retries	Il numero di volte in cui viene ripetuto un'attività non riuscita. Quando un'attività supera questo limite, l'intero job viene contrassegnato come non riuscito. Ad esempio, se il valore è impostato su 1, un'attività non riuscita verrà ripetuta una volta per un totale di due tentativi. Il valore predefinito è 3. Accetta numeri interi compresi tra 0 e 10.
     --task-timeout	Accetta una durata come "2 s". Il valore predefinito è 10 minuti; il massimo è 24 ore.
     --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. Fai riferimento a Parallelismo per conoscere l'intervallo di valori.

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

   • Configurazione container
   • Limiti della CPU
   • Limiti di memoria
   • Secret
   • Variabili di ambiente
   • Etichette
   • Account di servizio
   • Connessioni Cloud SQL
   • Connessione VPC

   Per un elenco completo delle opzioni disponibili per la creazione di un job, consulta la documentazione della riga di comando gcloud runjob 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, vedi Eseguire job o eseguire i job in base a una pianificazione.

YAML

Attenzione: le seguenti istruzioni sostituiscono la configurazione del job esistente con quella specificata nel file YAML. Pertanto, se utilizzi YAML per apportare modifiche, dovresti evitare anche di utilizzare 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 di job, modifica qualsiasi attributo figlio di spec.template in base alle tue esigenze per aggiornare le impostazioni di configurazione, quindi riesegui il deployment:

1. Aggiorna la configurazione del job esistente:

   gcloud run jobs replace job.yaml

2. Per eseguire il job, vedi Eseguire job o eseguire i 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 di Terraform per:

• Parallelismo
• Numero massimo di nuovi tentativi
• Timeout

Per saperne di più, fai riferimento alle 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, se utilizzi 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 dispone delle 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. Dall'interno di un'istanza di container Cloud Run, puoi recuperare un token di accesso utilizzando il server di metadati dell'istanza di container.
• JOB_NAME con il nome del job che vuoi aggiornare.
• IMAGE_URL con l'URL dell'immagine container 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 i vari linguaggi.

Passaggi successivi

Dopo aver creato o aggiornato un job, puoi effettuare le seguenti operazioni:

• Esecuzione di un job
• Eseguire un job in base a una pianificazione
• Gestione delle offerte di lavoro
• Gestire le esecuzioni dei job
• Visualizza i log dei job
• Monitorare le prestazioni lavorative
• Impostare i limiti di memoria
• Impostare le variabili di ambiente