Créer des jobs

Cette page explique comment créer et mettre à jour des jobs Cloud Run à partir d'une image de conteneur existante. Contrairement à un service Cloud Run, qui écoute et diffuse les requêtes, un job Cloud Run n'exécute que ses tâches et se ferme une fois qu'elle a terminé. Un job n'écoute pas et ne diffuse pas les requêtes.

Après avoir créé ou mis à jour un job, vous pouvez :

Exécuter le job de manière unique, planifiée ou dans le cadre d'un workflow.
Vous pouvez remplacer les paramètres configurés pour un job lorsque vous exécutez un job.
Vous pouvez gérer des exécutions de jobs individuels et afficher les journaux d'exécution.

Vous pouvez structurer un job en tant que tâche unique ou en tant que plusieurs tâches indépendantes (jusqu'à 10 000 tâches) pouvant être exécutées en parallèle. Chaque tâche exécute une instance de conteneur et peut être configurée de manière à être relancée en cas d'échec. Chaque opération connaît son index, qui est stocké dans la variable d'environnement CLOUD_RUN_TASK_INDEX. Le nombre total de tâches est stocké dans la variable d'environnement CLOUD_RUN_TASK_COUNT. Si vous traitez des données en parallèle, votre code est chargé de déterminer quelle tâche gère quel sous-ensemble de données.

Vous pouvez définir des délais avant expiration sur des tâches et spécifier le nombre de tentatives en cas d'échec de la tâche. Si une tâche dépasse son nombre maximal de tentatives, elle est marquée comme failed (échec) et l'exécution du job est marquée comme failed (échec) après l'exécution de toutes les tâches.

Par défaut, chaque tâche s'exécute pendant 10 minutes maximum : vous pouvez définir une durée plus courte ou plus longue dans la limite de 24 heures. Pour ce faire, vous devez modifier le paramètre de délai avant expiration des tâches.

Il n'y a pas de délai explicite pour l'exécution d'un job : lorsque toutes les tâches sont terminées, l'exécution du job est terminée.

Les jobs utilisent l'environnement d'exécution de deuxième génération.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer des jobs Cloud Run, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Développeur Cloud Run (roles/run.developer) sur le job Cloud Run
Utilisateur du compte de service (roles/iam.serviceAccountUser) sur l'identité du service

Pour obtenir la liste des rôles et des autorisations IAM associés à Cloud Run, consultez les sections Rôles IAM Cloud Run et Autorisations IAM Cloud Run. Si votre job Cloud Run communique avec des API Google Cloud, telles que des bibliothèques clientes Cloud, consultez le guide de configuration de l'identité du service. Pour en savoir plus sur l'attribution de rôles, consultez les sections Autorisations de déploiement et Gérer les accès.

Registres de conteneurs et images acceptés

Vous pouvez utiliser directement des images de conteneurs stockées dans Artifact Registry ou Docker Hub. Nous vous recommandons d'utiliser Artifact Registry.

Vous pouvez utiliser des images de conteneurs provenant d'autres registres publics ou privés (tels que JFrog Artifactory, Nexus ou GitHub Container Registry) en configurant un dépôt Artifact Registry distant.

Envisagez d'utiliser Docker Hub uniquement pour déployer des images de conteneurs populaires, telles que des images officielles Docker ou des images OSS sponsorisées par Docker. Pour accroître la disponibilité, Google recommande de déployer ces images Docker Hub via un dépôt Artifact Registry distant.

Créer un job

Vous pouvez créer un job à l'aide de la console Google Cloud, de Google Cloud CLI, de YAML ou de Terraform.

Console

Pour créer un job, procédez comme suit :

Dans la console Google Cloud, accédez à la page Cloud Run :

Accédez à Cloud Run
Cliquez sur Déployer un conteneur et sélectionnez Tâche pour afficher le formulaire Créer une tâche.
1. Dans le formulaire, spécifiez l'image de conteneur contenant le code de la tâche ou sélectionnez-la dans la liste des conteneurs précédemment déployés.
2. Le nom de la tâche est généré automatiquement à partir de l'image du conteneur. Vous pouvez modifier le nom de la tâche si nécessaire. Un nom de tâche ne peut plus être modifié une fois que la tâche a été créée.
3. Sélectionnez la région dans laquelle vous souhaitez créer votre tâche. Le sélecteur de région met en avant les régions ayant l'impact carbone le plus faible.
4. Spécifiez le nombre de tâches que vous souhaitez exécuter dans le job. Toutes les tâches doivent réussir pour que le job aboutisse. Par défaut, les tâches s'exécutent en parallèle.
Cliquez sur Conteneur(s), volumes, mise en réseau, sécurité pour définir d'autres propriétés de job.
- Sous "Capacité de l'opération" :
1. Dans le menu Mémoire, spécifiez la quantité de mémoire requise. La valeur par défaut est la valeur minimale requise (512 Mio).
2. Dans le menu déroulant Processeur, spécifiez la quantité de processeurs requise. La valeur par défaut est la configuration minimale requise (un processeur).
3. Sous Délai avant expiration de la tâche, spécifiez la durée maximale en secondes pendant laquelle la tâche peut être exécutée, dans la limite de 24 heures. Chaque tâche doit être terminée dans ce délai. La valeur par défaut est de 10 minutes (600 secondes).
4. Sous Nombre de nouvelles tentatives par tâche en échec, spécifiez le nombre de tentatives en cas d'échec de la tâche. La valeur par défaut est de trois nouvelles tentatives.
- Sous "Parallélisme" :
  1. Dans la plupart des cas, vous pouvez sélectionner Exécuter simultanément autant de tâches que possible.
  2. Si vous devez définir une limite inférieure en raison de contraintes de scaling sur les ressources auxquelles votre job accède, sélectionnez Limiter le nombre maximal de tâches simultanées et spécifiez le nombre de tâches simultanées dans la zone de texte Limite de parallélisme personnalisée.
Vous pouvez également configurer d'autres paramètres dans les onglets appropriés :
Une fois la tâche configurée, cliquez sur Créer pour créer la tâche dans Cloud Run.
Pour exécuter le job, consultez la page Exécuter des jobs ou Exécuter des jobs selon un calendrier.

gcloud

Pour utiliser la ligne de commande, vous devez déjà avoir configuré gcloud CLI.

Pour créer un job, procédez comme suit :

Exécutez la commande suivante :

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS

Vous pouvez également utiliser la commande de déploiement :

gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS

Remplacez JOB_NAME par le nom de la tâche que vous souhaitez créer. Vous pouvez omettre ce paramètre, mais dans ce cas, le nom de la tâche vous sera demandé.
Remplacez IMAGE_URL par une référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/job:latest.

Vous pouvez également remplacer OPTIONS par l'une des options suivantes :

Option	Description
`--tasks`	Accepte les entiers supérieurs ou égaux à 1. La valeur par défaut est 1. La valeur maximale est 10 000. Chaque tâche reçoit les variables d'environnement `CLOUD_RUN_TASK_INDEX` avec une valeur comprise entre 0 et le nombre de tâches moins 1, ainsi que `CLOUD_RUN_TASK_COUNT`, qui correspond au nombre de tâches.
`--max-retries`	Nombre de nouvelles tentatives d'exécution d'une tâche ayant échoué. Lorsqu'une tâche dépasse cette limite, l'intégralité de la tâche est marquée comme étant en échec. Par exemple, si vous définissez la valeur sur 1, une tâche ayant échoué est relancée une seule fois, soit un total de deux tentatives. La valeur par défaut est 3. Accepte les entiers compris entre 0 et 10.
`--task-timeout`	Accepte une durée telle que "2s". La valeur par défaut est de 10 minutes. La durée maximale est de 24 heures.
`--parallelism`	Nombre maximal de tâches pouvant s'exécuter en parallèle. Par défaut, les tâches sont démarrées aussi rapidement que possible en parallèle. Pour connaître la plage de valeurs, consultez la page Parallélisme.
`--execute-now`	Si ce champ est défini immédiatement après la création de la tâche, une exécution de tâche démarre. Équivaut à l'appel de `gcloud run jobs create` suivi de `gcloud run jobs execute`.

Outre les options ci-dessus, vous spécifiez d'autres éléments de configuration, tels que des variables d'environnement ou des limites de mémoire.

Pour obtenir la liste complète des options disponibles lors de la création d'une tâche, reportez-vous à la documentation de ligne de commande portant sur gcloud run jobs create.

Patientez pendant la création de la tâche. Un message de réussite s'affiche une fois l'opération terminée.
Pour exécuter le job, consultez la page Exécuter des jobs ou Exécuter des jobs selon un calendrier.

YAML

Vous pouvez stocker votre spécification de tâche dans un fichier YAML, puis la déployer à l'aide de gcloud CLI.

Créez un fichier job.yaml avec le contenu suivant :
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
```
Remplacer
- JOB par le nom de votre tâche Cloud Run Les noms de tâche doivent comporter un maximum de 49 caractères et être uniques par région et par projet.
- IMAGE par l'URL de l'image du conteneur de la tâche.
Vous pouvez également spécifier d'autres éléments de configuration, tels que des variables d'environnement ou des limites de mémoire.
Déployez la nouvelle tâche à l'aide de la commande suivante :
```
gcloud run jobs replace job.yaml
```

Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base.

Pour créer un job Cloud Run, utilisez la ressource google_cloud_run_v2_job et modifiez votre fichier main.tf comme indiqué dans l'extrait suivant.

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

Bibliothèques clientes

Pour créer un job à partir du code, procédez comme suit :

API REST

Pour créer un job, envoyez une requête HTTP POST au point de terminaison jobs de l'API Cloud Run Admin.

Exemple, à l'aide de 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

Remplacez :

ACCESS_TOKEN par un jeton d'accès valide pour un compte disposant des autorisations IAM pour créer des jobs. Par exemple, si vous êtes connecté à gcloud, vous pouvez récupérer un jeton d'accès à l'aide de gcloud auth print-access-token. À partir d'une instance de conteneur Cloud Run, vous pouvez récupérer un jeton d'accès via le serveur de métadonnées d'instance de conteneur.
JOB_NAME par le nom du job que vous souhaitez créer.
IMAGE_URL par l'URL de l'image de conteneur du job (par exemple, us-docker.pkg.dev/cloudrun/container/job:latest).
REGION par la région Google Cloud du job.
PROJECT_ID par l'ID du projet Google Cloud.

Emplacements Cloud Run

Cloud Run est régional, ce qui signifie que l'infrastructure qui exécute vos services Cloud Run est située dans une région spécifique et gérée par Google pour être disponible de manière redondante dans toutes les zones de cette région.

Lors de la sélection de la région dans laquelle exécuter vos services Cloud Run, vous devez tout d'abord considérer vos exigences en matière de latence, de disponibilité et de durabilité. Vous pouvez généralement sélectionner la région la plus proche de vos utilisateurs, mais vous devez tenir compte de l'emplacement des autres produits Google Cloud utilisés par votre service Cloud Run. L'utilisation conjointe de produits Google Cloud dans plusieurs emplacements peut avoir une incidence sur la latence et le coût de votre service.

Cloud Run est disponible dans les régions suivantes :

Soumis aux tarifs de niveau 1

asia-east1 (Taïwan)
asia-northeast1 (Tokyo)
asia-northeast2 (Osaka)
europe-north1 (Finlande) Faibles émissions de CO₂
europe-southwest1 (Madrid) Faibles émissions de CO₂
europe-west1 (Belgique) Faibles émissions de CO₂
europe-west4 (Pays-Bas) Faibles émissions de CO₂
europe-west8 (Milan)
europe-west9 (Paris) Faibles émissions de CO₂
me-west1 (Tel Aviv)
us-central1 (Iowa) Faibles émissions de CO₂
us-east1 (Caroline du Sud)
us-east4 (Virginie du Nord)
us-east5 (Columbus)
us-south1 (Dallas) Faibles émissions de CO₂
us-west1 (Oregon) Faibles émissions de CO₂

Soumis aux tarifs de niveau 2

africa-south1 (Johannesburg)
asia-east2 (Hong Kong)
asia-northeast3 (Séoul, Corée du Sud)
asia-southeast1 (Singapour)
asia-southeast2 (Jakarta)
asia-south1 (Mumbai, Inde)
asia-south2 (Delhi, Inde)
australia-southeast1 (Sydney)
australia-southeast2 (Melbourne)
europe-central2 (Varsovie, Pologne)
europe-west10 (Berlin) Faibles émissions de CO₂.
europe-west12 (Turin)
europe-west2 (Londres, Royaume-Uni) Faibles émissions de CO₂
europe-west3 (Francfort, Allemagne) Faibles émissions de CO₂
europe-west6 (Zurich, Suisse) Faibles émissions de CO₂
me-central1 (Doha)
me-central2 (Dammam)
northamerica-northeast1 (Montréal) Faibles émissions de CO₂
northamerica-northeast2 (Toronto) Faibles émissions de CO₂
southamerica-east1 (São Paulo, Brésil) Faibles émissions de CO₂
southamerica-west1 (Santiago, Chili) Faibles émissions de CO₂
us-west2 (Los Angeles)
us-west3 (Salt Lake City)
us-west4 (Las Vegas)

Si vous avez déjà créé un service Cloud Run, vous pouvez afficher la région dans le tableau de bord Cloud Run de la console Google Cloud.

Lorsque vous créez un job, l'agent de service Cloud Run doit pouvoir accéder au conteneur, ce qui est le cas par défaut.

Mettre à jour un job existant

La modification des paramètres de configuration nécessite de mettre à jour la tâche, même si l'image du conteneur ne change pas. Notez que pour les paramètres inchangés, les paramètres précédents continuent d'être utilisés.

Vous pouvez mettre à jour un job existant à l'aide de la console Google Cloud, de Google Cloud CLI, de YAML ou de Terraform.

Console

Pour mettre à jour un job existant :

Dans la console Google Cloud, accédez à la page Cloud Run :

Accédez à Cloud Run
Cliquez sur l'onglet Tâches pour afficher la liste des tâches.
Cliquez sur la tâche pour afficher la page Informations sur la tâche.
Cliquez sur Modifier.
Si vous avez modifié le code de votre tâche, spécifiez le nouveau condensé de l'image du conteneur.
Si nécessaire, modifiez le nombre de tâches figurant dans le job.
Vous pouvez également cliquer sur Conteneur(s), volumes, mise en réseau et sécurité pour mettre à jour d'autres propriétés du job :
- Sous "Capacité de l'opération" :
1. Dans le menu Mémoire, spécifiez la quantité de mémoire requise. La valeur par défaut est la valeur minimale requise (512 Mio).
2. Dans le menu déroulant Processeur, spécifiez la quantité de processeurs requise. La valeur par défaut est la configuration minimale requise (un processeur).
3. Sous Délai avant expiration de la tâche, spécifiez la durée maximale en secondes pendant laquelle la tâche peut être exécutée, dans la limite de 24 heures. Chaque tâche doit être terminée dans ce délai. La valeur par défaut est de 10 minutes (600 secondes).
4. Sous Nombre de nouvelles tentatives par tâche en échec, spécifiez le nombre de tentatives en cas d'échec de la tâche. La valeur par défaut est de trois nouvelles tentatives.
- Sous "Parallélisme" :
  1. Dans la plupart des cas, vous pouvez sélectionner Exécuter simultanément autant de tâches que possible.
  2. Si vous devez définir une limite inférieure en raison de contraintes de scaling sur les ressources auxquelles votre job accède, sélectionnez Limiter le nombre maximal de tâches simultanées et spécifiez le nombre maximal de tâches simultanées dans le champ Limite de parallélisme personnalisée.
Vous pouvez également configurer d'autres paramètres dans les onglets appropriés :
Une fois la tâche configurée, cliquez sur Enregistrer pour créer la tâche dans Cloud Run et attendez la fin de la création de la tâche.
Pour exécuter le job, consultez la page Exécuter des jobs ou Exécuter des jobs selon un calendrier.

gcloud

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.

Exécutez la commande suivante :

gcloud run jobs update JOB_NAME

Remplacez :

JOB_NAME par le nom de la tâche que vous souhaitez mettre à jour.

Vous pouvez également remplacer OPTIONS par les options suivantes :

Option	Description
`--tasks`	Accepte les entiers supérieurs ou égaux à 1. La valeur par défaut est 1. La valeur maximale est 10 000. Chaque tâche reçoit les variables d'environnement `CLOUD_RUN_TASK_INDEX` avec une valeur comprise entre 0 et le nombre de tâches moins 1, ainsi que `CLOUD_RUN_TASK_COUNT`, qui correspond au nombre de tâches.
`--max-retries`	Nombre de nouvelles tentatives d'exécution d'une tâche ayant échoué. Lorsqu'une tâche dépasse cette limite, l'intégralité de la tâche est marquée comme étant en échec. Par exemple, si vous définissez la valeur sur 1, une tâche ayant échoué est relancée une seule fois, soit un total de deux tentatives. La valeur par défaut est `3`. Accepte les entiers compris entre 0 et 10.
`--task-timeout`	Accepte une durée telle que "2s". La valeur par défaut est de 10 minutes. La durée maximale est de 24 heures.
`--parallelism`	Nombre maximal de tâches pouvant s'exécuter en parallèle. Par défaut, les tâches sont démarrées aussi rapidement que possible en parallèle. Pour connaître la plage de valeurs, consultez la page Parallélisme.

Outre les options ci-dessus, vous pouvez définir d'autres paramètres de configuration facultatifs :

Pour obtenir la liste complète des options disponibles lors de la création d'une tâche, reportez-vous à la documentation de ligne de commande portant sur gcloud run jobs create.

Patientez jusqu'à la fin de la mise à jour de la tâche. Une fois l'opération achevée, un message de réussite semblable au suivant s'affiche :

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

Pour exécuter le job, consultez la page Exécuter des jobs ou Exécuter des jobs selon un calendrier.

YAML

Si vous devez télécharger ou consulter la configuration d'une tâche existante, exécutez la commande suivante pour enregistrer les résultats dans un fichier YAML :

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

Dans un fichier YAML de configuration de tâche, modifiez les attributs enfants spec.template en fonction de vos besoins pour mettre à jour les paramètres de configuration, puis redéployez votre application :

Mettez à jour la configuration de tâche existante :
```
gcloud run jobs replace job.yaml
```
Pour exécuter le job, consultez la page Exécuter des jobs ou Exécuter des jobs selon un calendrier.

Terraform

Modifiez la configuration de votre job dans votre fichier main.tf à l'aide de la commande terraform apply. Des instructions Terraform détaillées sont disponibles pour :

Pour en savoir plus, consultez les options de ligne de commande terraform apply.

Bibliothèques clientes

Pour mettre à jour un job existant à partir du code, procédez comme suit :

API REST

Pour mettre à jour un job, envoyez une requête HTTP PATCH au point de terminaison jobs de l'API Cloud Run Admin.

Exemple, à l'aide de 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

Remplacez :

ACCESS_TOKEN par un jeton d'accès valide pour un compte disposant des autorisations IAM pour mettre à jour des jobs. Par exemple, si vous êtes connecté à gcloud, vous pouvez récupérer un jeton d'accès à l'aide de gcloud auth print-access-token. À partir d'une instance de conteneur Cloud Run, vous pouvez récupérer un jeton d'accès via le serveur de métadonnées d'instance de conteneur.
JOB_NAME par le nom du job que vous souhaitez mettre à jour.
IMAGE_URL par l'URL de l'image de conteneur du job (par exemple, us-docker.pkg.dev/cloudrun/container/job:latest).
REGION par la région Google Cloud du job.
PROJECT_ID par l'ID du projet Google Cloud.

Exemple de code

Pour obtenir des exemples de code montrant des tâches simples, consultez les guides de démarrage rapide spécifiques au langage.

Étapes suivantes

Après avoir créé ou mis à jour un job, vous pouvez effectuer les opérations suivantes :