Créer et gérer des libellés.

Vous pouvez appliquer des étiquettes utilisateur aux clusters et aux jobs Managed Service pour Apache Spark afin de regrouper ces ressources pour les filtrer et les lister ultérieurement. Vous associez des libellés aux ressources lors de la création de la ressource, lorsque vous créez un cluster ou envoyez une tâche. Une fois qu'une ressource est associée à un libellé, celui-ci est propagé aux opérations effectuées sur la ressource (création, mise à jour, correction ou suppression de cluster ; envoi, mise à jour, annulation ou suppression de tâches), ce qui vous permet de filtrer et de répertorier les clusters, les tâches et les opérations par libellé.

Vous pouvez également ajouter des libellés aux ressources Compute Engine associées aux ressources de cluster, telles que les instances de machines virtuelles et les disques.

Qu'est-ce qu'un libellé ?

Une étiquette est une paire clé-valeur que vous pouvez attribuer aux clusters et aux jobs Managed Service pour Apache Spark. Elle vous aide à organiser ces ressources et à gérer vos coûts à grande échelle avec la précision dont vous avez besoin. Vous pouvez associer une étiquette à chaque ressource, puis filtrer les ressources par étiquette. Les informations sur les étiquettes sont transmises au système de facturation. Ainsi, vous pouvez trier vos frais facturés par étiquette. Grâce aux rapports de facturation intégrés, vous pouvez filtrer et regrouper les coûts par étiquette de ressource. Vous pouvez également utiliser des étiquettes pour interroger les exportations de données de facturation.

Exigences relatives aux libellés

Les libellés appliqués à une ressource doivent répondre aux exigences suivantes :

  • Chaque cluster ou job peut comporter jusqu'à 32 étiquettes.
  • Chaque étiquette doit correspondre à une paire clé/valeur.
  • Les clés doivent comporter un (1) caractère au minimum et 63 au maximum, et ne peuvent pas être vides. Les valeurs peuvent être vides et comporter 63 caractères au maximum.
  • Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés. Les clés doivent commencer par une lettre minuscule ou un caractère international.
  • La partie clé d'un libellé doit être unique au sein d'une ressource spécifique. Cependant, vous pouvez utiliser la même clé avec plusieurs ressources.

Ces limites s'appliquent à la clé et à la valeur de chaque étiquette, ainsi qu'au cluster ou au job Managed Service pour Apache Spark individuel associé à des étiquettes. Vous pouvez appliquer autant de libellés que vous le souhaitez à toutes les ressources d'un projet.

Cas d'utilisation courants des libellés

Voici quelques cas d'utilisation courants des étiquettes :

  • Étiquettes d'équipe ou de centre de coûts : ajoutez des étiquettes basées sur l'équipe ou le centre de coûts pour distinguer les clusters et les jobs Managed Service pour Apache Spark appartenant à différentes équipes (par exemple, team:research et team:analytics). Vous pouvez utiliser ce type d'étiquette pour la comptabilité analytique ou la budgétisation.

  • Étiquettes de composant : par exemple, component:redis, component:frontend, component:ingest et component:dashboard.

  • Libellés d'environnement ou d'étape : par exemple, environment:production et environment:test.

  • Libellés d'état : par exemple, state:active, state:readytodelete et state:archive.

  • Étiquettes de propriété : permettent d'identifier les équipes responsables des opérations (par exemple, team:shopping-cart).

Nous vous déconseillons de créer de grands nombres d'étiquettes uniques (par exemple, pour les horodatages ou les valeurs individuelles pour chaque appel d'API). Le problème avec cette approche est que lorsque les valeurs changent fréquemment ou que des clés encombrent le catalogue, il est difficile de filtrer efficacement les ressources et de créer des rapports associés.

Libellés et tags

Pour les ressources, les libellés peuvent être utilisés comme des annotations qu'il est possible d'interroger. Cependant, ils ne peuvent pas être utilisés pour définir des conditions dans le cadre de vos stratégies. Les tags permettent d'autoriser ou de refuser des règles de manière conditionnelle selon qu'une ressource possède un tag spécifique ou non, grâce à un contrôle ultraprécis sur les règles. Pour en savoir plus, consultez la présentation des tags.

Créer et utiliser des étiquettes Managed Service pour Apache Spark

Console

Vous pouvez spécifier un ensemble d'étiquettes à ajouter à un cluster ou à un job au moment de la création du cluster ou de l'envoi du job à l'aide de la console Google Cloud .

  • Ajoutez des libellés à un cluster depuis la page Créer un cluster. Cliquez sur Configuration supplémentaire pour développer cette section, puis modifiez Personnalisation et autres, et ajoutez des libellés dans la section Libellés.
  • Ajoutez des étiquettes à un job depuis la page Envoyer un job, dans la section Exécution et propriétés du job > Étiquettes.

Une fois qu'un cluster ou un job a été créé ou envoyé, vous pouvez mettre à jour les étiquettes qui lui sont associées. Pour mettre à jour les étiquettes, cliquez sur la case de sélection d'un cluster ou d'un job listé, puis cliquez sur SHOW INFO PANEL. Voici un exemple de la page Managed Service pour Apache Spark > Lister les clusters.

Commande gcloud

Vous pouvez spécifier un ou plusieurs libellés à appliquer à un cluster ou à un job Managed Service pour Apache Spark au moment de la création ou de l'envoi à l'aide de la Google Cloud CLI.

gcloud dataproc clusters create args --labels environment=production,customer=acme
gcloud dataproc jobs submit args --labels environment=production,customer=acme

Une fois qu'un cluster ou un job Managed Service pour Apache Spark a été créé, vous pouvez mettre à jour les étiquettes associées à cette ressource à l'aide de la Google Cloud CLI.

gcloud dataproc clusters update args --update-labels environment=production,customer=acme
gcloud dataproc jobs update args --update-labels environment=production,customer=acme

De même, vous pouvez utiliser la Google Cloud CLI pour filtrer les ressources Managed Service pour Apache Spark par étiquette à l'aide d'une expression de filtre au format suivant : labels.<key=value>.

gcloud dataproc clusters list \
    --region=region \
    --filter="status.state=ACTIVE AND labels.environment=production"
gcloud dataproc jobs list \
    --region=region \
    --filter="status.state=ACTIVE AND labels.customer=acme"

Pour plus d'informations sur l'écriture d'expressions de filtre, consultez les sections clusters.list et jobs.list dans la documentation de l'API Dataproc.

API REST

Les étiquettes peuvent être associées à des clusters ou à des jobs via l'API REST Dataproc. Les API clusters.create et jobs.submit peuvent être utilisées pour associer des libellés à un cluster ou à une tâche lors de la création ou de l'envoi. Les API clusters.patch et jobs.patch peuvent être utilisées pour modifier les étiquettes après la création d'un cluster. Voici un exemple de corps JSON de requête "cluster.create" qui inclut le libellé key1:value associé au cluster.

{
  "clusterName":"cluster-1",
  "projectId":"my-project",
  "config":{
    "configBucket":"",
    "gceClusterConfig":{
      "networkUri":".../networks/default",
      "zoneUri":".../zones/us-central1-f"
    },
    "masterConfig":{
      "numInstances":1,
      "machineTypeUri":"..../machineTypes/n1-standard-4",
      "diskConfig":{
        "bootDiskSizeGb":500,
        "numLocalSsds":0
      }
    },
    "workerConfig":{
      "numInstances":2,
      "machineTypeUri":"...machineTypes/n1-standard-4",
      "diskConfig":{
        "bootDiskSizeGb":500,
        "numLocalSsds":0
      }
    }
  },
  "labels":{
    "key1":"value1"
  }
}

Les API clusters.list et jobs.list peuvent être utilisées pour lister les clusters ou les jobs correspondant à un filtre spécifié, au format suivant : labels.<key=value>.

Voici un exemple de requête HTTPS GET clusters.list à l'API Dataproc qui spécifie un filtre de libellé key=value. L'appelant insère project, region, un filtre label-key et label-value, et un élément api-key. Notez que cet exemple de requête est divisé en deux lignes pour plus de lisibilité.

GET https://dataproc.googleapis.com/v1/projects/project/regions/region/clusters?
filter=labels.label-key=label-value&key=api-key

Pour plus d'informations sur l'écriture d'expressions de filtre, consultez les sections clusters.list et jobs.list dans la documentation de l'API Dataproc.

Une fois le panneau d'informations affiché, vous pouvez mettre à jour les étiquettes de votre cluster ou de votre job. Voici un exemple de mise à jour des étiquettes d'un cluster Managed Service pour Apache Spark.

Il est également possible de mettre à jour des libellés pour plusieurs éléments au cours d'une seule et même opération. Dans cet exemple, les étiquettes sont mises à jour pour plusieurs jobs Managed Service pour Apache Spark en même temps.

Les étiquettes vous permettent de filtrer les ressources affichées sur les pages Lister les clusters et Lister les jobs. En haut de la page, vous pouvez utiliser le format de recherche labels.= pour filtrer les ressources par étiquette.

Étiquettes appliquées automatiquement

Lors de la création ou de la mise à jour d'un cluster, Managed Service pour Apache Spark applique automatiquement plusieurs étiquettes au cluster et à ses ressources. Par exemple, Managed Service pour Apache Spark applique des étiquettes aux machines virtuelles, aux disques persistants et aux accélérateurs lors de la création d'un cluster. Les libellés appliqués automatiquement comportent un préfixe goog-dataproc spécial.

Les étiquettes goog-dataproc suivantes sont automatiquement appliquées aux ressources Managed Service pour Apache Spark. Toutes les valeurs que vous fournissez pour les libellés goog-dataproc réservés lors de la création du cluster remplacent les valeurs fournies automatiquement. Pour cette raison, il n'est pas recommandé de fournir vos propres valeurs pour ces libellés.

Libellé Description
goog-dataproc-cluster-name Nom du cluster spécifié par l'utilisateur
goog-dataproc-cluster-uuid ID de cluster unique
goog-dataproc-location Point de terminaison de cluster régional Managed Service pour Apache Spark

Vous pouvez utiliser ces libellés appliqués automatiquement de différentes manières, par exemple :

Étapes suivantes