Creazione di 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 rimane in ascolto e gestisce le richieste, un job Cloud Run esegue le proprie attività e si chiude solo quando è terminato. Un job non rimane in ascolto né gestisce le richieste.

Dopo aver creato o aggiornato un job, puoi:

Esegui il job come una tantum, in base a una pianificazione o come parte di un flusso di lavoro.
Puoi eseguire l'override dei parametri configurati per un job quando esegui un job.
Puoi gestire singole esecuzioni di job e visualizzare i log di esecuzione.

Puoi strutturare un job come singola attività 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, archiviato nella variabile di ambiente CLOUD_RUN_TASK_INDEX. Il numero complessivo delle attività viene archiviato nella variabile di ambiente CLOUD_RUN_TASK_COUNT. Se stai elaborando dati in parallelo, il codice è responsabile di determinare quale attività gestisce il sottoinsieme di dati.

Puoi impostare i timeout per le attività e specificare il numero di nuovi tentativi in caso di errore. 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 scegliere 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 il completamento di tutte le attività, l'esecuzione del job è completa.

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

Autorizzazioni IAM necessarie per creare ed eseguire

Per utilizzare i job Cloud Run, devi disporre di uno dei seguenti ruoli:

Amministratore Cloud Run per autorizzazioni complete per creare/aggiornare/eliminare ed eseguire job
Invoker di Cloud Run per eseguire i job
Visualizzatore Cloud Run per visualizzare ed elencare i job

Se stai configurando un ruolo personalizzato, utilizza le seguenti autorizzazioni:

run.jobs.{create/update/run/delete/get/list/getIamPolicy/setIamPolicy}
run.executions.{get/list/delete}
run.tasks.{get/list}

run.jobs.run consente a un utente di eseguire un job, avviando così una nuova esecuzione. Non esiste un'autorizzazione run.executions.create separata: l'unico modo per creare un'esecuzione è eseguire un job.

Immagini e registri di container supportati

Puoi utilizzare immagini container archiviate in Artifact Registry, Container Registry (Deprecato) o Docker Hub. Google consiglia l'utilizzo di Artifact Registry.

Puoi utilizzare solo i seguenti tipi di immagini container:

Immagini container archiviate nello stesso progetto in cui stai creando il job o il servizio.
Immagini container di altri progetti Google Cloud (a condizione che siano impostate le autorizzazioni IAM corrette).
Immagini container pubbliche da Artifact Registry, Container Registry o Docker Hub.

Dovresti prendere in considerazione Docker Hub solo per il deployment di immagini container popolari, come Immagini ufficiali Docker o Immagini Docker Sponsorizzate. Per una maggiore disponibilità, Google consiglia di eseguire il deployment di queste immagini Docker Hub tramite un repository remoto di Artifact Registry.

Se archivi immagini container in un altro tipo di Container Registry, segui le istruzioni riportate in Eseguire il deployment di immagini da registry non supportati.

Crea un nuovo lavoro

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

Console

Per creare un nuovo lavoro:

Vai a Cloud Run
Fai clic sulla scheda Job.
Fai clic su Crea job per visualizzare il modulo Crea job.
1. Nel modulo, specifica l'immagine container contenente il codice del job o selezionala 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. Il nome di un job non può essere modificato dopo la creazione del job.
3. Seleziona la regione in cui vuoi che si trovi il job. Il selettore della regione evidenzia le regioni con l'impatto delle emissioni di carbonio più basso.
4. Specifica il numero di attività che vuoi eseguire nel job. Affinché il job abbia esito positivo, tutte le attività devono avere esito positivo. Per impostazione predefinita, le attività vengono eseguite in parallelo.
Fai clic su Container, volumi, networking, sicurezza per impostare ulteriori proprietà del job.
- Nella sezione Capacità dell'attività:
1. Nel menu a discesa Memoria, specifica la quantità di memoria richiesta. Il valore predefinito è il minimo obbligatorio, 512 MiB.
2. Nel menu a discesa CPU, specifica la quantità di CPU richiesta. Il valore predefinito è il minimo richiesto, ovvero 1 CPU.
3. In Timeout attività, specifica la quantità massima di tempo in secondi in cui può essere eseguita l'attività, fino a 24 ore. Ogni attività deve essere completata entro questo 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 dell'attività. Il valore predefinito è 3 nuovi tentativi.
- In 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 il job accede, seleziona Limita il numero massimo di attività simultanee e specifica il numero di attività simultanee nella casella di testo Limite di parallelismo personalizzato.
Facoltativamente, configura altre impostazioni nelle schede appropriate:
Al termine della configurazione del job, fai clic su Crea per creare il job in Cloud Run.
Per eseguire il job, vedi Esegui job o Esegui job in base a una pianificazione.

Riga di comando

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

Per creare un nuovo lavoro:

Esegui il comando:

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS

In alternativa, utilizza il comando deploy:

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 alle variabili di ambiente `CLOUD_RUN_TASK_INDEX` un valore compreso tra 0 e il numero di attività meno 1, insieme a `CLOUD_RUN_TASK_COUNT`, che indica il numero di attività
`--max-retries`	Il numero di nuovi tentativi di un'attività non riuscita. Quando un'attività non supera questo limite, l'intero job viene contrassegnato come non riuscito. Ad esempio, se il valore è impostato su 1, un'attività non riuscita verrà tentata di nuovo una volta, per un totale di due tentativi. Il valore predefinito è 3. Accetta numeri interi da 0 a 10.
`--task-timeout`	Accetta una durata di "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 l'intervallo di valori.
`--execute-now`	Se impostata, immediatamente 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, 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 a riga di comando gcloud run job create.

Attendi il completamento della creazione del job. Al termine verrà visualizzato un messaggio che indica che l'operazione è andata a buon fine.
Per eseguire il job, vedi Esegui job o Esegui job in base a una pianificazione.

YAML

Puoi archiviare le specifiche del job in un file YAML e quindi eseguirne il deployment utilizzando gcloud CLI.

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 avere una lunghezza massima di 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, ad esempio variabili di ambiente o limiti di memoria.
Esegui il deployment del nuovo job utilizzando questo 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 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:

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 dispone delle autorizzazioni IAM per la creazione di 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à di 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 di quella regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità sono 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 ti consigliamo di 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 seguenti regioni:

Soggetto ai prezzi di Livello 1

asia-east1 (Taiwan)
asia-northeast1 (Tokyo)
asia-northeast2 (Osaka)
europe-north1 (Finlandia) Bassi livelli di CO₂
europe-southwest1 (Madrid)
europe-west1 (Belgio) Bassi livelli 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) Bassi livelli 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 nella console Google Cloud.

Quando crei un nuovo job, l'agente di servizio Cloud Run deve essere in grado di 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 subirà modifiche. Tieni presente che, per le impostazioni invariate, vengono 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:

Vai a Cloud Run
Fai clic sulla scheda Job per visualizzare l'elenco dei job.
Fai clic sul job desiderato per visualizzare la pagina Dettagli job.
Fai clic su Modifica.
Se hai apportato modifiche al codice del job, specifica il nuovo digest immagine del container.
Se necessario, modifica il numero di attività presenti nel job.
Facoltativamente, fai clic su Container, volumi, networking, sicurezza per aggiornare eventuali altre proprietà del job come preferisci:
- Nella sezione Capacità dell'attività:
1. Nel menu a discesa Memoria, specifica la quantità di memoria richiesta. Il valore predefinito è il minimo obbligatorio, 512 MiB.
2. Nel menu a discesa CPU, specifica la quantità di CPU richiesta. Il valore predefinito è il minimo richiesto, ovvero 1 CPU.
3. In Timeout attività, specifica la quantità massima di tempo in secondi in cui può essere eseguita l'attività, fino a 24 ore. Ogni attività deve essere completata entro questo 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 dell'attività. Il valore predefinito è 3 nuovi tentativi.
- In 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 di vincoli di scalabilità sulle risorse a cui il job accede, seleziona Limita il numero di attività simultanee e specifica il numero massimo di attività simultanee nella casella di testo Limite di parallelismo personalizzato.
Facoltativamente, configura altre impostazioni nelle schede appropriate:
Al termine della configurazione del job, fai clic su Salva per creare il job in Cloud Run e attendi il completamento della creazione del job.
Per eseguire il job, vedi Esegui job o Esegui job in base a una pianificazione.

Riga di comando

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.

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 alle variabili di ambiente `CLOUD_RUN_TASK_INDEX` un valore compreso tra 0 e il numero di attività meno 1, insieme a `CLOUD_RUN_TASK_COUNT`, che indica il numero di attività
`--max-retries`	Il numero di nuovi tentativi di un'attività non riuscita. Quando un'attività non supera questo limite, l'intero job viene contrassegnato come non riuscito. Ad esempio, se il valore è impostato su 1, un'attività non riuscita verrà tentata di nuovo una volta, per un totale di due tentativi. Il valore predefinito è `3`. Accetta numeri interi da 0 a 10.
`--task-timeout`	Accetta una durata di "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 l'intervallo di valori.

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

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

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

Per eseguire il job, vedi Esegui job o Esegui job in base a una pianificazione.

YAML

Se hai bisogno di scaricare o visualizzare la configurazione di un job esistente, usa 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 un job, modifica qualsiasi attributo secondario spec.template come desiderato per aggiornare le impostazioni di configurazione, quindi esegui nuovamente il deployment:

Aggiorna la configurazione del job esistente:
```
gcloud run jobs replace job.yaml
```
Per eseguire il job, vedi Esegui job o Esegui 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 per Terraform per:

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

Librerie client

Per aggiornare un job esistente dal codice:

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 dispone delle autorizzazioni IAM per l'aggiornamento dei 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 lingua.

Passaggi successivi

Dopo aver creato o aggiornato un job, puoi: