Ce document explique comment utiliser des libellés pour organiser vos ressources Batch.
Les libellés sont des paires clé/valeur appliquées aux ressources pour les regrouper et les décrire. Batch propose des libellés prédéfinis, qui sont automatiquement appliqués aux ressources, et des libellés personnalisés, que vous pouvez définir et appliquer lorsque vous créez un job.
Les libellés vous permettent de filtrer les résultats des listes de ressources et des rapports Cloud Billing. Par exemple, vous pouvez utiliser des libellés pour effectuer les opérations suivantes :
Clarifiez et organisez la liste des tâches de votre projet.
Distinguez les exécutables d'un job en utilisant des libellés pour décrire le type de conteneur ou de script qu'ils spécifient.
Analysez les coûts en filtrant les rapports sur la facturation Cloud pour les ressources créées par Batch ou pour des jobs spécifiques.
Pour en savoir plus sur les libellés, consultez également la documentation Compute Engine sur les libellés.
Avant de commencer
- Si vous n'avez jamais utilisé Batch, consultez Premiers pas avec Batch et activez Batch en remplissant les conditions préalables pour les projets et les utilisateurs.
-
Pour obtenir les autorisations nécessaires pour créer un job, demandez à votre administrateur de vous accorder les rôles IAM suivants :
-
Éditeur de tâches par lot (
roles/batch.jobsEditor
) sur le projet -
Utilisateur du compte de service (
roles/iam.serviceAccountUser
) sur le compte de service du job, qui par défaut est le compte de service Compute Engine par défaut
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.
-
Éditeur de tâches par lot (
Restrictions
En plus des exigences concernant les libellés spécifiées dans la documentation Compute Engine, l'application de libellés à un job Batch et à ses ressources est soumise aux restrictions suivantes :
Batch n'accepte que les libellés pour les ressources créées à l'aide de Batch et des types suivants :
Jobs
Exécutables
Processeurs graphiques (GPU) pour un job (le cas échéant)
Disques persistants (disques de démarrage et volumes de stockage) pour un job
Instances de machine virtuelle (VM) pour un job
Après avoir pris en compte les libellés prédéfinis que Batch applique automatiquement à un job, vous pouvez définir les quantités suivantes de libellés personnalisés :
Vous pouvez définir jusqu'à 63 étiquettes personnalisées à appliquer au job et à ses exécutables.
Vous pouvez définir jusqu'à 61 libellés personnalisés à appliquer à chaque GPU, disque persistant et VM créés pour le job.
Batch n'accepte que la définition de libellés personnalisés avec des noms uniques. En conséquence :
Toute tentative de remplacement d'un libellé prédéfini entraîne des erreurs.
Si vous définissez un libellé personnalisé en double, il remplacera celui qui existe déjà.
Batch n'accepte la définition de libellés que lors de la création d'un job.
Vous ne pouvez pas ajouter, modifier ni supprimer les libellés des jobs et des exécutables.
Bien qu'il soit possible d'utiliser Compute Engine pour ajouter, modifier ou supprimer des libellés pour les disques persistants et les VM créés pour les jobs, cela n'est pas recommandé. Il est impossible d'estimer de manière fiable la période pendant laquelle les ressources d'un job existent. De plus, il est possible que les modifications ne fonctionnent pas correctement avec Batch.
Pour utiliser des libellés afin de filtrer votre liste de jobs, vous devez afficher votre liste de jobs à l'aide de gcloud CLI ou de l'API Batch.
Libellés prédéfinis
Chaque libellé prédéfini possède une clé qui commence par le préfixe batch-
. Par défaut, Batch applique automatiquement les libellés prédéfinis suivants :
Pour chaque job que vous créez :
batch-job-id
: la valeur de ce libellé est définie sur le nom du job.
Pour chaque GPU, disque persistant et VM créés pour un job :
batch-job-id
: la valeur de ce libellé est définie sur le nom du job.batch-job-uid
: la valeur de ce libellé est définie sur l'identifiant unique (UID) du job.batch-node
: la valeur de ce libellé est nulle. Il regroupe simplement tous les GPU, disques persistants et VM créés pour les jobs. Par exemple, utilisez ce libellé lorsque vous affichez un rapport sur la facturation Cloud pour identifier les coûts de tous les GPU, disques persistants et VM créés par Batch.
Définir des libellés personnalisés
Vous pouvez éventuellement définir une ou plusieurs étiquettes personnalisées lorsque vous créez un job. Vous pouvez définir des libellés personnalisés avec de nouvelles clés ou des clés que votre projet utilise déjà. Pour définir des libellés personnalisés, sélectionnez une ou plusieurs des méthodes suivantes dans ce document en fonction de l'objectif du libellé :
Définissez des libellés personnalisés pour le job et ses ressources.
Cette section explique comment appliquer un ou plusieurs libellés personnalisés au job, ainsi qu'à chaque GPU, disque persistant et VM créés pour le job. Une fois le job créé, vous pouvez utiliser ces libellés pour filtrer les rapports Cloud Billing et les listes de jobs, de disques persistants et de VM de votre projet.
Définissez des libellés personnalisés pour le job.
Cette section explique comment appliquer un ou plusieurs libellés personnalisés à la tâche. Une fois le job créé, vous pouvez utiliser ces libellés pour filtrer les listes de jobs de votre projet.
Définissez des libellés personnalisés pour les exécutables.
Cette section explique comment appliquer un ou plusieurs libellés personnalisés à un ou plusieurs exécutables pour le job. Une fois le job créé, vous pouvez utiliser ces libellés pour filtrer les listes de jobs de votre projet.
Définir des libellés personnalisés pour le job et ses ressources
Les libellés définis dans le champ labels
de la stratégie d'allocation d'un job sont appliqués au job, ainsi qu'à chaque GPU (le cas échéant), disque persistant (tous les disques de démarrage et tous les nouveaux volumes de stockage) et VM créés pour le job.
Vous pouvez définir des libellés pour un job et ses ressources lorsque vous créez un job à l'aide de gcloud CLI ou de l'API Batch.
gcloud
Par exemple, pour créer un job de conteneur de base dans us-central1
qui définit deux étiquettes personnalisées s'appliquant au job et aux ressources créées pour le job, procédez comme suit :
Créez un fichier JSON qui spécifie les détails de configuration du job et le champ
allocationPolicy.labels
.{ "allocationPolicy": { "instances": [ { "policy": { "machineType": "e2-standard-4" } } ], "labels": { "VM_LABEL_NAME1": "VM_LABEL_VALUE1", "VM_LABEL_NAME2": "VM_LABEL_VALUE2" } }, "taskGroups": [ { "taskSpec": { "runnables": [ { "container": { "imageUri": "gcr.io/google-containers/busybox", "entrypoint": "/bin/sh", "commands": [ "-c", "echo Hello world!" ] } } ] } } ] }
Remplacez les éléments suivants :
VM_LABEL_NAME1
: nom du premier libellé à appliquer aux VM créées pour le job.VM_LABEL_VALUE1
: valeur du premier libellé à appliquer aux VM créées pour le job.VM_LABEL_NAME2
: nom du deuxième libellé à appliquer aux VM créées pour le job.VM_LABEL_VALUE2
: valeur de la deuxième étiquette à appliquer aux VM créées pour le job.
Créez le job dans
us-central1
à l'aide de la commandegcloud batch jobs submit
.gcloud batch jobs submit example-job \ --config=JSON_CONFIGURATION_FILE \ --location=us-central1
Remplacez
JSON_CONFIGURATION_FILE
par le chemin d'accès au fichier JSON contenant les détails de configuration du job que vous avez créé à l'étape précédente.
API
Par exemple, pour créer un job de conteneur de base dans us-central1
qui définit deux libellés personnalisés s'appliquant au job et aux ressources créées pour le job, envoyez une requête POST
à la méthode jobs.create
et spécifiez le champ allocationPolicy.labels
.
POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job
{
"allocationPolicy": {
"instances": [
{
"policy": {
"machineType": "e2-standard-4"
}
}
],
"labels": {
"VM_LABEL_NAME1": "VM_LABEL_VALUE1",
"VM_LABEL_NAME2": "VM_LABEL_VALUE2"
}
},
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"container": {
"imageUri": "gcr.io/google-containers/busybox",
"entrypoint": "/bin/sh",
"commands": [
"-c",
"echo Hello world!"
]
}
}
]
}
}
]
}
Remplacez les éléments suivants :
VM_LABEL_NAME1
: nom du premier libellé à appliquer aux VM créées pour le job.VM_LABEL_VALUE1
: valeur du premier libellé à appliquer aux VM créées pour le job.VM_LABEL_NAME2
: nom du deuxième libellé à appliquer aux VM créées pour le job.VM_LABEL_VALUE2
: valeur de la deuxième étiquette à appliquer aux VM créées pour le job.
Java
Node.js
Python
Définir des libellés personnalisés pour le job
Les libellés définis dans le champ labels
de la tâche ne sont appliqués qu'à la tâche.
Vous pouvez définir des libellés pour un job lorsque vous le créez à l'aide de gcloud CLI ou de l'API Batch.
gcloud
Par exemple, pour créer un job de conteneur de base dans us-central1
qui définit deux libellés personnalisés s'appliquant au job lui-même, procédez comme suit :
Créez un fichier JSON qui spécifie les détails de configuration du job et le champ
labels
.{ "taskGroups": [ { "taskSpec": { "runnables": [ { "container": { "imageUri": "gcr.io/google-containers/busybox", "entrypoint": "/bin/sh", "commands": [ "-c", "echo Hello World!" ] } } ] } } ], "labels": { "JOB_LABEL_NAME1": "JOB_LABEL_VALUE1", "JOB_LABEL_NAME2": "JOB_LABEL_VALUE2" } }
Remplacez les éléments suivants :
JOB_LABEL_NAME1
: nom du premier libellé à appliquer à votre tâche.JOB_LABEL_VALUE1
: valeur du premier libellé à appliquer à votre job.JOB_LABEL_NAME2
: nom du deuxième libellé à appliquer à votre job.JOB_LABEL_VALUE2
: valeur de la deuxième étiquette à appliquer à votre tâche.
Créez le job dans
us-central1
à l'aide de la commandegcloud batch jobs submit
avec les options suivantes :gcloud batch jobs submit example-job \ --config=JSON_CONFIGURATION_FILE \ --location=us-central1
Remplacez
JSON_CONFIGURATION_FILE
par le chemin d'accès au fichier JSON contenant les détails de configuration du job que vous avez créé à l'étape précédente.
API
Par exemple, pour créer un job de conteneur dans us-central1
qui définit deux libellés personnalisés à appliquer au job lui-même, envoyez une requête POST
à la méthode jobs.create
et spécifiez le champ labels
.
POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"container": {
"imageUri": "gcr.io/google-containers/busybox",
"entrypoint": "/bin/sh",
"commands": [
"-c",
"echo Hello World!"
]
}
}
]
}
}
],
"labels": {
"JOB_LABEL_NAME1": "JOB_LABEL_VALUE1",
"JOB_LABEL_NAME2": "JOB_LABEL_VALUE2"
}
}
Remplacez les éléments suivants :
JOB_LABEL_NAME1
: nom du premier libellé à appliquer à votre tâche.JOB_LABEL_VALUE1
: valeur de la première étiquette à appliquer à votre job.JOB_LABEL_NAME2
: nom du deuxième libellé à appliquer à votre tâche.JOB_LABEL_VALUE2
: valeur de la deuxième étiquette à appliquer à votre job.
Java
Node.js
Python
Définir des libellés personnalisés pour les exécutables
Les libellés définis dans le champ labels
d'un exécutable ne s'appliquent qu'à cet exécutable.
Vous pouvez définir des libellés pour un ou plusieurs exécutables lorsque vous créez un job à l'aide de gcloud CLI ou de l'API Batch.
gcloud
Par exemple, pour créer un job dans us-central1
qui définit deux libellés personnalisés, un pour chacun des deux exécutables du job, procédez comme suit :
Créez un fichier JSON qui spécifie les détails de configuration du job et les champs
runnables.labels
.{ "taskGroups": [ { "taskSpec": { "runnables": [ { "container": { "imageUri": "gcr.io/google-containers/busybox", "entrypoint": "/bin/sh", "commands": [ "-c", "echo Hello from task ${BATCH_TASK_INDEX}!" ] }, "labels": { "RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1" } }, { "script": { "text": "echo Hello from task ${BATCH_TASK_INDEX}!" }, "labels": { "RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1" } } ] } } ] }
Remplacez les éléments suivants :
RUNNABLE1_LABEL_NAME1
: nom du libellé à appliquer au premier exécutable du job.RUNNABLE1_LABEL_VALUE1
: valeur du libellé à appliquer au premier exécutable du job.RUNNABLE2_LABEL_NAME1
: nom du libellé à appliquer au deuxième exécutable du job.RUNNABLE2_LABEL_VALUE1
: valeur du libellé à appliquer au deuxième exécutable du job.
Créez le job dans
us-central1
à l'aide de la commandegcloud batch jobs submit
.gcloud batch jobs submit example-job \ --config=JSON_CONFIGURATION_FILE \ --location=us-central1
Remplacez
JSON_CONFIGURATION_FILE
par le chemin d'accès au fichier JSON contenant les détails de configuration du job que vous avez créé à l'étape précédente.
API
Par exemple, pour créer un job dans us-central1
qui définit deux libellés personnalisés, un pour chacun des deux exécutables du job, envoyez une requête POST
à la méthode jobs.create
et spécifiez les champs runnables.labels
.
POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"container": {
"imageUri": "gcr.io/google-containers/busybox",
"entrypoint": "/bin/sh",
"commands": [
"-c",
"echo Hello from ${BATCH_TASK_INDEX}!"
]
},
"labels": {
"RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1"
}
},
{
"script": {
"text": "echo Hello from ${BATCH_TASK_INDEX}!"
},
"labels": {
"RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1"
}
}
]
}
}
]
}
Remplacez les éléments suivants :
RUNNABLE1_LABEL_NAME1
: nom du libellé à appliquer à l'exécutable du premier job.RUNNABLE1_LABEL_VALUE1
: valeur du libellé à appliquer au fichier exécutable du premier job.RUNNABLE2_LABEL_NAME1
: nom du libellé à appliquer à l'exécutable du deuxième job.RUNNABLE2_LABEL_VALUE1
: valeur du libellé à appliquer à l'exécutable de la deuxième tâche.
Java
Node.js
Python
Étapes suivantes
Utilisez des libellés comme filtres lorsque vous effectuez les opérations suivantes :
Découvrez comment supprimer des jobs.