Organiser des ressources à l'aide de libellés

Ce document explique comment utiliser des étiquettes pour organiser vos ressources Batch.

Les étiquettes sont des paires clé/valeur appliquées aux ressources pour les regrouper et les décrire. Batch comporte des étiquettes prédéfinies, qui sont automatiquement appliquées aux ressources, et des étiquettes personnalisées, que vous pouvez définir et appliquer lors de la création d'une tâche.

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 étiquettes pour effectuer les opérations suivantes:

  • Clarifiez et organisez la liste des tâches de votre projet.

  • Distinguez les exécutables d'une tâche à l'aide de libellés pour décrire le type de conteneur ou de script qu'ils spécifient.

  • Analysez les coûts en filtrant les rapports Cloud Billing pour les ressources créées par Batch ou par des tâches spécifiques.

Pour en savoir plus sur les étiquettes, consultez également la documentation de Compute Engine sur les étiquettes.

Avant de commencer

Restrictions

Outre les exigences concernant les étiquettes spécifiées dans la documentation Compute Engine, l'application d'étiquettes à un job par lot et à ses ressources présente les restrictions suivantes:

  • Batch n'est compatible qu'avec les libellés pour les ressources créées à l'aide de Batch et des types suivants:

  • Après avoir pris en compte les étiquettes prédéfinies que Batch applique automatiquement à une tâche, vous pouvez définir les quantités suivantes d'étiquettes personnalisées:

    • Vous pouvez définir un maximum de 63 étiquettes personnalisées à appliquer à la tâche et à ses exécutables.

    • Vous pouvez définir un maximum de 61 étiquettes personnalisées à appliquer à chaque GPU, disque persistant et VM créé pour le job.

  • Batch permet uniquement de définir des étiquettes personnalisées avec des noms uniques. Cela a les conséquences suivantes:

    • Toute tentative de remplacement d'un libellé prédéfini entraîne des erreurs.

    • Si vous définissez une étiquette personnalisée en double, elle remplace l'étiquette personnalisée existante.

  • Batch permet uniquement de définir des étiquettes lors de la création d'un job.

    • Vous ne pouvez pas ajouter, mettre à jour ni supprimer d'étiquettes pour les tâches et les exécutables.

    • Bien qu'il soit possible d'utiliser Compute Engine pour ajouter, mettre à jour ou supprimer des étiquettes pour les disques persistants et les VM créées pour des tâches, cela n'est pas recommandé. La période durant laquelle les ressources d'une tâche existent ne peut pas être estimée de manière fiable, et les modifications peuvent ne pas fonctionner correctement avec Batch.

  • Pour filtrer la liste de tâches à l'aide d'étiquettes, vous devez afficher la liste de tâches à l'aide de gcloud CLI ou de l'API Batch.

Étiquettes prédéfinies

Chaque étiquette prédéfinie comporte une clé commençant 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 de la tâche.

  • Pour chaque GPU, disque persistant et VM créé pour un job:

    • batch-job-id: la valeur de ce libellé est définie sur le nom de la tâche.

    • batch-job-uid: la valeur de ce libellé est définie sur l'identifiant unique (UID) de la tâche.

    • batch-node: la valeur de ce libellé est "null", car il regroupe tous les GPU, disques persistants et VM créés pour les tâches. Par exemple, utilisez cette étiquette lorsque vous affichez un rapport Cloud Billing pour identifier les coûts de tous les GPU, disques persistants et VM créés par Batch.

Définir des étiquettes personnalisées

Vous pouvez éventuellement définir une ou plusieurs étiquettes personnalisées lors de la création d'un job. Vous pouvez définir des étiquettes personnalisées avec de nouvelles clés ou clés déjà utilisées par votre projet. Pour définir des étiquettes personnalisées, sélectionnez une ou plusieurs des méthodes suivantes dans ce document en fonction de leur objectif:

  • Définissez des étiquettes personnalisées pour la tâche et ses ressources.

    Cette section explique comment appliquer une ou plusieurs étiquettes personnalisées à la tâche, ainsi qu'à chaque GPU, disque persistant et VM créé pour cette tâche. Après avoir créé la tâche, vous pouvez utiliser ces étiquettes pour filtrer les rapports Cloud Billing et les listes de tâches, de disques persistants et de VM de votre projet.

  • Définissez des étiquettes personnalisées pour la tâche.

    Cette section explique comment appliquer une ou plusieurs étiquettes personnalisées à la tâche. Après avoir créé la tâche, vous pouvez utiliser ces étiquettes pour filtrer les listes de tâches de votre projet.

  • Définissez des étiquettes personnalisées pour les exécutables.

    Cette section explique comment appliquer une ou plusieurs étiquettes personnalisées à un ou plusieurs exécutables pour la tâche. Après avoir créé la tâche, vous pouvez utiliser ces étiquettes pour filtrer les listes de tâches de votre projet.

Définir des étiquettes personnalisées pour la tâche et ses ressources

Les étiquettes définies dans le champ labels pour la règle d'allocation d'un job sont appliquées à la tâche, ainsi qu'à chaque GPU (le cas échéant), à chaque disque persistant (tous les disques de démarrage et nouveaux volumes de stockage) et à chaque VM créée pour la tâche.

Vous pouvez définir des étiquettes pour une tâche et ses ressources lors de la création d'une tâche à l'aide de gcloud CLI ou de l'API Batch.

gcloud

Par exemple, pour créer une tâche de conteneur de base dans us-central1 qui définit deux étiquettes personnalisées qui s'appliquent à la tâche et aux ressources créées pour celle-ci, procédez comme suit:

  1. Créez un fichier JSON qui spécifie les détails de configuration de la tâche 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 de la première étiquette à appliquer aux VM créées pour la tâche.

    • VM_LABEL_VALUE1: valeur du premier libellé à appliquer aux VM créées pour la tâche.

    • VM_LABEL_NAME2: nom de la deuxième étiquette à appliquer aux VM créées pour la tâche.

    • VM_LABEL_VALUE2: valeur du deuxième libellé à appliquer aux VM créées pour la tâche.

  2. Créez la tâche dans us-central1 à l'aide de la commande gcloud 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 du fichier JSON avec les détails de configuration du job que vous avez créés à l'étape précédente.

API

Par exemple, pour créer une tâche de conteneur de base dans us-central1 qui définit deux étiquettes personnalisées qui s'appliquent à la tâche et aux ressources créées pour celle-ci, 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 de la première étiquette à appliquer aux VM créées pour la tâche.

  • VM_LABEL_VALUE1: valeur du premier libellé à appliquer aux VM créées pour la tâche.

  • VM_LABEL_NAME2: nom de la deuxième étiquette à appliquer aux VM créées pour la tâche.

  • VM_LABEL_VALUE2: valeur du deuxième libellé à appliquer aux VM créées pour la tâche.

Définir des étiquettes personnalisées pour le job

Les étiquettes définies dans le champ labels de la tâche ne sont appliquées qu'à la tâche.

Vous pouvez définir des étiquettes pour une tâche lorsque vous créez une tâche à l'aide de gcloud CLI ou de l'API Batch.

gcloud

Par exemple, pour créer une tâche de conteneur de base dans us-central1 qui définit deux étiquettes personnalisées qui s'appliquent à la tâche elle-même, procédez comme suit:

  1. Créez un fichier JSON qui spécifie les détails de configuration de la tâche 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 tâche.

    • JOB_LABEL_NAME2: nom de la deuxième étiquette à appliquer à votre tâche.

    • JOB_LABEL_VALUE2: valeur du deuxième libellé à appliquer à votre tâche.

  2. Créez la tâche dans us-central1 à l'aide de la commande gcloud 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 du fichier JSON avec les détails de configuration du job que vous avez créés à l'étape précédente.

API

Par exemple, pour créer une tâche de conteneur dans us-central1 qui définit deux étiquettes personnalisées à appliquer aux tâches elles-mêmes, 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 de la première étiquette à appliquer à votre tâche.

  • JOB_LABEL_VALUE1: valeur du premier libellé à appliquer à votre tâche.

  • JOB_LABEL_NAME2: nom de la deuxième étiquette à appliquer à votre tâche.

  • JOB_LABEL_VALUE2: valeur du deuxième libellé à appliquer à votre tâche.

Définir des étiquettes personnalisées pour les exécutables

Les étiquettes définies dans le champ labels pour un exécutable ne sont appliquées qu'à cet exécutable.

Vous pouvez définir des étiquettes pour un ou plusieurs exécutables lorsque vous créez une tâche à l'aide de gcloud CLI ou de l'API Batch.

gcloud

Par exemple, pour créer dans us-central1 une tâche qui définit deux étiquettes personnalisées (une pour chacun des deux exécutables de ces deux tâches), procédez comme suit:

  1. Créez un fichier JSON qui spécifie les détails de configuration de la tâche 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 de la tâche.

    • RUNNABLE1_LABEL_VALUE1: valeur du libellé à appliquer au premier exécutable de la tâche.

    • RUNNABLE2_LABEL_NAME1: nom du libellé à appliquer au deuxième exécutable de la tâche.

    • RUNNABLE2_LABEL_VALUE1: valeur du libellé à appliquer au deuxième exécutable de la tâche.

  2. Créez la tâche dans us-central1 à l'aide de la commande gcloud 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 du fichier JSON avec les détails de configuration du job que vous avez créés à l'étape précédente.

API

Par exemple, pour créer dans us-central1 une tâche qui définit deux étiquettes personnalisées, une pour chacun des deux éléments exécutables, 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 de la première tâche.

  • RUNNABLE1_LABEL_VALUE1: valeur du libellé à appliquer à l'exécutable de la première tâche.

  • RUNNABLE2_LABEL_NAME1: nom du libellé à appliquer à l'exécutable de la deuxième tâche.

  • RUNNABLE2_LABEL_VALUE1: valeur du libellé à appliquer à l'exécutable de la deuxième tâche.

Étapes suivantes