Esegui job

Questa pagina descrive come eseguire i job Cloud Run. L'esecuzione di un job crea un'esecuzione del job in cui tutte le attività devono essere eseguite correttamente fino al completamento affinché l'esecuzione del job vada a buon fine. Le esecuzioni dei job scrivono i log in Cloud Logging e inviano i dati di monitoraggio a Cloud Monitoring.

Oltre a queste funzionalità di logging, puoi anche visualizzare i dettagli di esecuzione dei job per le 1000 esecuzioni più recenti di un job utilizzando il riquadro dei dettagli di esecuzione, insieme a tutte le esecuzioni avvenute negli ultimi sette giorni. I dettagli di esecuzione meno recenti vengono rimossi e non sono più visibili nel riquadro dei dettagli di esecuzione. Tuttavia, i log e i dati di monitoraggio delle esecuzioni precedenti sono ancora disponibili in Cloud Logging e Cloud Monitoring, in base alle norme di conservazione di questi prodotti.

Che cos'è l'esecuzione del job?

Eseguire un job Cloud Run significa istanziare ed eseguire un carico di lavoro configurato fino al completamento, suddiviso in una o più attività parallele o sequenziali, senza ascoltare o gestire richieste HTTP.

Le entità principali di un lavoro sono le seguenti:

  • Job: una configurazione statica e persistente. Definisce l'immagine container, le allocazioni di risorse (CPU, memoria, GPU), le variabili di ambiente e i parametri di esecuzione (attività totali, parallelismo, timeout e tentativi).

  • Esecuzione: l'evento del ciclo di vita temporale creato quando attivi un job. Un'esecuzione rappresenta l'oggetto di monitoraggio complessivo per una singola esecuzione del job.

  • Attività: una singola istanza in esecuzione del container configurato. Un'esecuzione è composta da una o più attività (taskCount).

Esistono fondamentalmente due modi diversi per eseguire un job:

  • Come un lavoro normale.

    Quando esegui un job come job normale (impostazione predefinita), l'esecuzione inizia il prima possibile.

  • Come job ritardato.

    Quando esegui un job come job ritardato, accetti di posticipare le attività non urgenti per un massimo di 12 ore, in cambio di un prezzo migliore.

Sebbene ogni job sia regolare o ritardato, puoi eseguire l'override di queste impostazioni per una singola esecuzione del job, in modo che un job regolare venga eseguito come job ritardato o un job ritardato venga eseguito come job regolare. Per informazioni dettagliate, consulta Ritardare l'esecuzione di un job.

La tabella seguente fornisce una visione più granulare dei possibili scenari di esecuzione per una determinata istanza di job:

Metodo di esecuzione Comando / Trigger Tempistica dell'allocazione delle risorse Livello di costo Ritardo / timeout massimo Caso d'uso tipico
Standard (on demand) gcloud run jobs execute Inizia immediatamente / il prima possibile Tariffe standard per i lavori Avvio immediato; durata massima di esecuzione di 7 giorni Elaborazione dei dati ad hoc, trigger manuali, pipeline basate su eventi
Crea/Aggiorna ed esegui gcloud run jobs create/update --execute-now Inizia immediatamente dopo la creazione Tariffe standard per i lavori Avvio immediato; durata massima di esecuzione di 7 giorni Deployment CI/CD, migrazioni dello schema, pre-riscaldamento post-deployment
Esecuzione ritardata gcloud beta run jobs execute --delay-execution Avvii entro una finestra ottimizzata dal sistema Tariffa scontata Ritardo massimo di 12 ore prima dell'annullamento automatico, timeout massimo di 12 ore Job batch non urgenti, analisi notturne, inferenza AI collettiva
Esecuzione con override gcloud run jobs execute --args=... --tasks=... Inizia immediatamente / il prima possibile Tariffe standard per i lavori Avvio immediato; timeout ignorato Backfill specifici per la partizione, dimensionamento dinamico dei batch, esecuzioni di debug

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per le operazioni descritte in questa pagina, chiedi all'amministratore di concederti uno dei seguenti ruoli IAM nel tuo job Cloud Run:

  • Per eseguire i job utilizzando Google Cloud CLI: Cloud Run Invoker (roles/run.invoker) sul job Cloud Run
  • Per eseguire job utilizzando la console Google Cloud , per ignorare le configurazioni dei job o per annullare le esecuzioni dei job: Sviluppatore Cloud Run (roles/run.developer) per il job Cloud Run

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il tuo job Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestisci l'accesso.

Esegui job

Puoi eseguire i job utilizzando la console Google Cloud , gcloud CLI, le librerie client o l'API REST.

Console

Per eseguire un job:

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

    Vai ai job Cloud Run

  2. Individua l'offerta di lavoro che ti interessa.

  3. Fai clic sul job per visualizzare la pagina dei dettagli.

  4. Fai clic su Esegui.

gcloud

Per eseguire un job esistente, esegui questo comando:

gcloud run jobs execute JOB

Se vuoi che il comando attenda il completamento dell'esecuzione, esegui il seguente comando:

gcloud run jobs execute JOB --wait --region=REGION

Per visualizzare i log dell'esecuzione subito dopo l'avvio, esegui questo comando:

gcloud beta run jobs execute JOB --tail --region=REGION

Sostituisci quanto segue:

  • JOB: il nome del job Cloud Run.
  • REGION: la regione in cui si trova la risorsa. Ad esempio, europe-west1. In alternativa, imposta la proprietà run/region.

Librerie client

Per eseguire un job esistente dal codice:

API REST

Per eseguire un job esistente, invia una richiesta HTTP POST al metodo API jobs.run.

Ad esempio, utilizzando curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB:run

Sostituisci quanto segue:

  • ACCESS_TOKEN: un token di accesso valido per un account che dispone delle autorizzazioni IAM per eseguire un job. Ad esempio, se hai eseguito l'accesso a gcloud, puoi recuperare un token di accesso utilizzando gcloud auth print-access-token. Da un'istanza container Cloud Run, puoi recuperare un token di accesso utilizzando il server dei metadati dell'istanza container.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • REGION: la Google Cloud regione del job.
  • JOB: il nome del job Cloud Run.

Esegui job immediatamente

Console

Per eseguire immediatamente un job:

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

    Vai a Cloud Run

  2. Seleziona Job dal menu di navigazione di Cloud Run:

    1. Se stai creando un nuovo job, fai clic su Deploy container per compilare la pagina delle impostazioni iniziali del job.

    2. Se stai configurando un job esistente, selezionalo, quindi fai clic su Visualizza e modifica la configurazione del job.

  3. Vai in fondo alla pagina e seleziona la casella Esegui subito job prima di creare o aggiornare il job.

gcloud

Puoi specificare il flag --execute-now quando crei o aggiorni un job.

  • Per creare un job, esegui questo comando:

    gcloud run jobs create JOB \
  --image IMAGE_URL \
  --execute-now \
  --region=REGION

  • Per aggiornare un job, esegui questo comando:

    gcloud run jobs update JOB --execute-now --region=REGION

Sostituisci quanto segue:

  • JOB: il nome del job Cloud Run.
  • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.
  • REGION: la regione in cui si trova la risorsa. Ad esempio, europe-west1.

YAML

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

  1. Se stai creando un nuovo job, salta questo passaggio. Se stai aggiornando un job esistente, scarica la relativa configurazione YAML:

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

  2. Configura l'attributo startExecutionToken come mostrato:

    apiVersion: run.googleapis.com/v2
kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE_URL
  startExecutionToken: START_EXECUTION_SUFFIX

    Sostituisci quanto segue:

    • JOB: il nome del job Cloud Run.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.
    • START_EXECUTION_SUFFIX: una stringa univoca utilizzata come suffisso per creare una nuova esecuzione. Il job sarà pronto quando l'esecuzione viene avviata correttamente. La somma della lunghezza del nome del job e del token deve essere inferiore a 63 caratteri.

    Puoi anche specificare più configurazioni, ad esempio variabili di ambiente o limiti di memoria.

  3. Crea o aggiorna il job utilizzando il seguente comando:

    gcloud run jobs replace job.yaml

    Il comando gcloud run jobs replace utilizza per impostazione predefinita il file job.yaml, se presente.

Terraform

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

Aggiungi quanto segue a una risorsa google_cloud_run_v2_job nella configurazione Terraform:
resource "google_cloud_run_v2_job" "default" {
   name     = "cloudrun-job"
   location = "REGION"
   deletion_protection = false
   start_execution_token = "START_EXECUTION_SUFFIX"
   template {
      template {
         containers {
         image = "us-docker.pkg.dev/cloudrun/container/job"
         }
      }
   }
}

Sostituisci quanto segue:

  • REGION: la Google Cloud regione. Ad esempio, europe-west1.
  • START_EXECUTION_SUFFIX: una stringa univoca utilizzata come suffisso per creare una nuova esecuzione. Il job sarà pronto quando l'esecuzione verrà avviata correttamente. La somma della lunghezza del nome del job e del token deve essere inferiore a 63 caratteri.

Librerie client

Per eseguire immediatamente un job dal codice utilizzando le librerie client di Cloud:

API REST

Per eseguire i job immediatamente al momento della creazione, 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"
              }
        }
     },
     "startExecutionToken": "START_EXECUTION_SUFFIX"
  }' \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs?jobId=JOB"

Sostituisci quanto segue:

  • ACCESS_TOKEN: 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. Da un'istanza container Cloud Run, puoi recuperare un token di accesso utilizzando il server dei metadati dell'istanza container.
  • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.
  • START_EXECUTION_SUFFIX: una stringa univoca utilizzata come suffisso per creare una nuova esecuzione. Il job sarà pronto quando l'esecuzione sarà avviata correttamente. La somma della lunghezza del nome del job e del token deve essere inferiore a 63 caratteri.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • REGION: la Google Cloud regione del job.
  • JOB: il nome del job Cloud Run.

Ritarda esecuzione

Per disattivare l'esecuzione immediata o convertire il job normale in un job ritardato, consulta Ritardare l'esecuzione di un job.

Eseguire l'override della configurazione del job per un'esecuzione specifica

Puoi eseguire l'override degli argomenti, delle variabili di ambiente, del numero di attività e del timeout dell'attività configurati per un job quando esegui un job impostando questi parametri quando avvii una nuova esecuzione del job. I parametri specificati influiscono solo su questa esecuzione e non su quelle successive, perché la definizione del job sottostante rimane invariata.

Alcuni casi d'uso comuni includono:

  • Esegui il job in modo programmatico dal codice e vuoi sostituire argomenti o variabili di ambiente, ad esempio per indicare al job la posizione dei dati di input per questa esecuzione.
  • Hai un job in cui ogni attività è pensata per elaborare un solo input di dati. Vuoi ignorare il numero di attività in base al numero di input da elaborare.
  • Il tempo di esecuzione del job varia tra le esecuzioni. Vuoi eseguire l'override del timeout dell'attività in base al tempo di esecuzione previsto del job.

Puoi eseguire l'override della configurazione del job per un'esecuzione utilizzando la console Google Cloud , gcloud CLI, le librerie client o l'API REST:

Console

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

    Vai ai job Cloud Run

  2. Fai clic sul job per aprire il riquadro dei dettagli.

  3. Fai clic sulla freccia di espansione davanti al pulsante Modifica e poi su Esegui con override per visualizzare il modulo Esegui job con override.

  4. Configura gli argomenti, le variabili di ambiente, il numero di attività e la configurazione del timeout dell'attività per questa esecuzione, poi fai clic su Esegui.

gcloud

Utilizza il comando:

gcloud run jobs execute JOB \
     --args ARGS \
     --update-env-vars KEY=VALUE,KEY_N=VALUE_N \
     --tasks TASKS \
     --task-timeout TIMEOUT

Sostituisci quanto segue:

Librerie client

Per eseguire un job esistente dal codice, ignorando la configurazione del job:

API REST

Per eseguire l'override della configurazione di un job esistente, 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 '{"overrides": {"containerOverrides": [{"args": ["ARGS"], "env": [{"name": "KEY", "value": "VALUE"}]}], "taskCount": TASKS, "timeout": "TIMEOUT" }}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB:run

Sostituisci quanto segue:

Annulla esecuzione job

Per interrompere l'esecuzione di un job Cloud Run attualmente in esecuzione, utilizza la funzionalità di annullamento. L'annullamento di un'esecuzione del job interrompe l'esecuzione del job corrente. Le esecuzioni annullate hanno lo stato annullato. Potrai comunque visualizzare l'esecuzione, inclusi i dati di configurazione, i log e i dati di monitoraggio.

L'annullamento dell'esecuzione di un job non comporta l'inversione degli addebiti per l'utilizzo di eventuali job Cloud Run per il periodo di esecuzione del job.

Per annullare un'esecuzione, utilizza la console Google Cloud , gcloud CLI, le librerie client o l'API REST:

Console

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

    Vai ai job Cloud Run

  2. Fai clic sul job per aprire il riquadro dei dettagli.

  3. Seleziona l'esecuzione del job da annullare.

  4. Nel menu Azioni, fai clic sull'icona con i tre puntini e poi su Annulla.

gcloud

Utilizza il comando:

gcloud run jobs executions cancel EXECUTION_NAME

Sostituisci EXECUTION_NAME con il nome dell'esecuzione.

Questo comando richiede una conferma, quindi rispondi al prompt inserendo y per confermare.

Librerie client

Per annullare l'esecuzione di un job dal codice:

API REST

Per annullare l'esecuzione di 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 '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB/executions/EXECUTION_NAME:cancel

Sostituisci quanto segue:

  • ACCESS_TOKEN: un token di accesso valido per un account che dispone delle autorizzazioni IAM per annullare le esecuzioni dei job. Ad esempio, se hai eseguito l'accesso a gcloud, puoi recuperare un token di accesso utilizzando gcloud auth print-access-token. Da un'istanza container Cloud Run, puoi recuperare un token di accesso utilizzando il server dei metadati dell'istanza container.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • REGION: la Google Cloud regione del job.
  • JOB: il nome del job Cloud Run.
  • EXECUTION_NAME: il nome dell'esecuzione del job.

Eliminare un'esecuzione del job

Puoi eliminare un'esecuzione del job, anche se è in esecuzione. Se elimini un'esecuzione, questa non potrà continuare. Per maggiori dettagli, vedi Eliminare l'esecuzione di un job.

Passaggi successivi

Dopo aver eseguito un job, puoi seguire questi passaggi: