Creazione di job

Questa pagina descrive come creare e aggiornare job Cloud Run da un un'immagine container esistente. A differenza di un servizio Cloud Run, che rimane in ascolto e gestisce le richieste, un job Cloud Run esegue le proprie attività e si chiude solo quando completato. Un job non rimane in ascolto né gestisce le richieste.

Dopo aver creato o aggiornato un job, puoi:

Puoi strutturare un lavoro come singola o come più attività indipendenti (fino a 10.000 attività) che possono essere eseguite in parallelo. Ciascuna l'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 CLOUD_RUN_TASK_INDEX variabile di ambiente. Il conteggio complessivo delle attività archiviati nella variabile di ambiente CLOUD_RUN_TASK_COUNT. Se stai elaborando i dati in parallelo, il tuo codice è responsabile di determinare quale attività gestisce quale sottoinsieme di dati.

Puoi impostare timeout per le attività e specificare il numero di nuovi tentativi in caso di attività errore. Se un'attività supera il numero massimo di nuovi tentativi, l'attività viene contrassegnata come failed e l'esecuzione del job viene contrassegnata come non riuscita dopo che tutte le attività sono state vengono eseguiti tutti i test delle unità.

Per impostazione predefinita, ogni attività viene eseguita per un massimo di 10 minuti: puoi modificare questa impostazione in 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: dopo che tutte le attività sono viene completata, l'esecuzione del job è completata.

I job utilizzano ambiente di esecuzione di seconda generazione.

Ruoli obbligatori

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

Per un elenco di ruoli e autorizzazioni IAM associati Cloud Run, consulta Ruoli IAM di Cloud Run e le autorizzazioni IAM di Cloud Run. Se il tuo job Cloud Run si interfaccia con Le API Google Cloud, come le librerie client di Cloud, consultano guida alla configurazione dell'identità dei servizi. 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.

Dovresti 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 con 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 oppure 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. Tu può modificare o cambiare il nome del job in base alle esigenze. Il nome job non può essere modificato dopo la creazione del job.
    3. Seleziona la regione in cui vuoi collocare il job. Il selettore di regioni evidenzia le regioni con l'impatto ambientale minimo.
    4. Specifica il numero di attività che vuoi eseguire nel job. Tutti questi le attività devono avere esito positivo affinché il job abbia esito positivo. Per impostazione predefinita, 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. La per impostazione predefinita è il minimo richiesto, 1 CPU.

    3. In Timeout attività, specifica il tempo massimo in secondi che l'attività può eseguire, fino a un massimo di 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 in caso di errori delle attività. Il valore predefinito sono 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à alle risorse a cui accede il job, seleziona Limita il numero massimo di attività simultanee e specificare il numero di attività simultanee nel Limite di parallelismo personalizzato casella di testo.

  5. Facoltativamente, configura altre impostazioni nelle schede appropriate:

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

  7. Per eseguire il job, vedi Esegui job oppure eseguire i job in base a una pianificazione.

gcloud

Per utilizzare la riga di comando, è già necessario avere configurare l'interfaccia a riga di comando gcloud.

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 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, per 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 limite 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; è di 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, specifichi anche configurazione come le variabili di ambiente o i limiti di memoria.

      Per un elenco completo delle opzioni disponibili quando crei un job, fai riferimento alle gcloud run job create della riga di comando.

  2. Attendi il completamento della creazione del job. Verrà visualizzato un messaggio di operazione riuscita un completamento.

  3. Per eseguire il job, vedi Esegui job oppure eseguire i job in base a una pianificazione.

YAML

Puoi archiviare la specifica del job in un file YAML e poi 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 49 caratteri o inferiore e deve essere univoco per regione e progetto.
    • IMAGE con l'URL dell'immagine del container del job.

    Puoi anche specificare altre configurazioni, ad esempio le variabili di ambiente 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, consulta: 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 in nel seguente snippet.

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:

API REST

Per creare un job, invia una richiesta HTTP POST a l'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 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 dei tuoi servizi Cloud Run si trova in una regione specifica gestiti da Google affinché siano disponibili in modo ridondante tutte le zone all'interno di quella regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità è fondamentale i fattori necessari per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. Generalmente puoi selezionare la regione più vicina ai tuoi utenti, ma devi considerare la località dell'altro account Google Cloud prodotti utilizzati dal tuo servizio Cloud Run. L'utilizzo combinato dei prodotti Google Cloud in più località può influire nonché la latenza del tuo servizio.

Cloud Run è disponibile nelle regioni seguenti:

Soggetto ai prezzi di Livello 1

Soggetto ai prezzi di Livello 2

Se hai già creato un servizio Cloud Run, puoi visualizzare nella dashboard di Cloud Run all'interno Console Google Cloud.

Quando crei un nuovo job, l'agente di servizio Cloud Run deve poter accedere al container, come avviene per impostazione predefinita.

Aggiorna un job esistente

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

Puoi aggiornare un job esistente utilizzando la console Google Cloud, Google Cloud CLI 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 container digest immagine.

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

  7. Facoltativamente, fai clic su Container, volumi, networking, sicurezza per aggiornare eventuali proprietà del lavoro in base alle tue esigenze:

    • 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. La per impostazione predefinita è il minimo richiesto, 1 CPU.
    3. In Timeout attività, specifica il tempo massimo in secondi che l'attività può eseguire, fino a un massimo di 24 ore. Ogni attività devono essere completati 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 in caso di errori delle attività. Il valore predefinito sono 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à a cui accede il job, seleziona Limita il numero di attività simultanee e specifica il numero massimo di per attività simultanee nella casella di testo Limite di parallelismo personalizzato.

  8. Facoltativamente, configura altre impostazioni nelle schede appropriate:

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

  10. Per eseguire il job, vedi Esegui job oppure 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 il le seguenti opzioni:

      Opzione Descrizione
      --tasks Accetta numeri interi uguali o maggiori di 1. Il valore predefinito è 1; il limite 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; è di 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 configurazioni facoltative impostazioni:

    Per un elenco completo delle opzioni disponibili quando crei un job, fai riferimento alle gcloud run job create della riga di comando.

  3. Attendi il completamento dell'aggiornamento del job. Una volta completato, un successo 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 Esegui job oppure eseguire i job in base a una pianificazione.

YAML

Se devi scaricare o visualizzare la configurazione di un job esistente, utilizza utilizza il comando seguente 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 spec.template in base alle tue esigenze 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, vedi Esegui job oppure eseguire i job in base a una pianificazione.

Terraform

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

Per saperne di più, consulta le opzioni della riga di comando terraform apply.

Librerie client

Per aggiornare un job esistente dal codice:

API REST

Per aggiornare un job, invia una richiesta HTTP PATCH a l'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 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 guide rapide specifiche per lingua.

Passaggi successivi

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