Organiser des ressources à l'aide de libellés

Les libellés sont des paires clé/valeur qui peuvent être utilisées sur Google Cloud pour regrouper des ressources liées ou associées. Par exemple, sur Compute Engine, vous pouvez utiliser des libellés pour regrouper les VM dans des catégories telles que la production, la préproduction ou le développement, afin de pouvoir rechercher des ressources appartenant à chaque étape de développement.

Après avoir ajouté des libellés à vos ressources, vous pouvez tirer parti de la fonctionnalité de filtrage imbriqué pour effectuer des recherches plus précises sur vos ressources avec des libellés.

Avant de commencer

  • Consultez la documentation sur les disques persistants.
  • Lisez la documentation sur les images.
  • Si ce n'est pas déjà fait, configurez l'authentification. L'authentification est le processus permettant de valider votre identité pour accéder aux services et aux API Google Cloud. Pour exécuter du code ou des exemples depuis un environnement de développement local, vous pouvez vous authentifier auprès de Compute Engine comme suit :

    Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :

    Console

    Lorsque vous utilisez la console Google Cloud pour accéder aux services et aux API Google Cloud, vous n'avez pas besoin de configurer l'authentification.

    gcloud

    1. Installez Google Cloud CLI, puis initialisez-la en exécutant la commande suivante : 

      gcloud init
    2. Définissez une région et une zone par défaut.

    REST

    Pour utiliser les exemples d'API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à gcloud CLI.

      Installez Google Cloud CLI, puis initialisez-la en exécutant la commande suivante : 

      gcloud init

Qu'est-ce qu'un libellé ?

Un libellé est une paire clé-valeur que vous pouvez attribuer aux instances Google Cloud. 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 ressource peut comporter jusqu'à 64 étiquettes.
  • Chaque libellé 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 libellé, ainsi qu'aux ressources Google Cloud individuelles associées à des libellés. 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 :

  • Libellés d'équipe ou de centre de coût : ajoutez des libellés en fonction de l'équipe ou du centre de coût pour distinguer les instances appartenant à différentes équipes (par exemple, team:research et team:analytics). Vous pouvez utiliser ce type de libellés pour la comptabilité analytique ou la budgétisation.

  • Libellés 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.

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

  • Libellés de machine virtuelle : un libellé peut être associé à une machine virtuelle. Les tags de machine virtuelle que vous avez définis précédemment apparaissent sous la forme d'un libellé sans valeur.

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.

Utiliser des libellés sur Compute Engine

Vous pouvez appliquer des libellés aux ressources Compute Engine suivantes :

  • Instances de machines virtuelles (VM)
  • Images
  • Disques persistants
  • Instantanés de disque persistant

Vous pouvez également utiliser des libellés sur les composants Google Cloud liés, tels que les suivants :

Par exemple, vous pouvez ajouter les libellés suivants en tant que paires clé/valeur à vos ressources :

{
 "labels": {
    "vmrole": "webserver",
    "environment": "production",
    "location": "west",...
    }
 }

Créer des ressources avec des libellés

Lors de la création d'une ressource, vous pouvez appliquer des libellés à cette ressource.

Console

  1. Accédez à la page de ressources que vous souhaitez créer.

  2. Sous Libellés, cliquez sur Ajouter un libellé.

  3. Poursuivez le processus de création.

gcloud

Pour ajouter un libellé, utilisez la sous-commande create avec l'option --labels. Vous pouvez ajouter des libellés aux ressources Compute Engine à l'aide des commandes gcloud suivantes :

Exemple

gcloud compute instances create ... \
    --labels webserver=backend,media=images

API

Dans l'API, lors de la requête POST pour l'ajout d'une nouvelle ressource, ajoutez la propriété labels dans le corps de la requête afin d'appliquer des libellés à la nouvelle ressource.

Par exemple, l'extrait suivant envoie une requête POST pour créer une instance de VM avec les libellés webserver:backend et media:images :

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances

{
 "name": "myVM",
 "machineType": "zones/us-central1-f/machineTypes/custom-2-15360-ext",
  ...,
 "labels": {
   "webserver": "backend",
   "media": "images"
  }
}

Ajouter ou mettre à jour les libellés de ressources existantes

Vous pouvez ajouter des libellés ou mettre à jour des libellés existants sur des ressources à l'aide de la console Google Cloud, de gcloud CLI ou de l'API Compute Engine. Pour ajouter ou mettre à jour des libellés de règles de transfert, utilisez gcloud CLI ou l'API Compute Engine.

Console

  1. Accédez à la page correspondant à la ressource pour laquelle vous souhaitez ajouter des libellés.

  2. Cochez les cases à côté des ressources auxquelles ajouter un libellé.

  3. Pour développer la colonne des libellés, cliquez sur Afficher le panneau d'informations.

  4. Dans le panneau, sélectionnez Libellés.

  5. Pour ajouter des libellés, cliquez sur Ajouter un libellé et ajoutez la paire clé-valeur.

  6. Pour mettre à jour des libellés, sélectionnez les libellés existants et modifiez leurs valeurs.

  7. Enregistrez les modifications.

gcloud

Pour ajouter ou modifier un libellé, utilisez la sous-commande update avec l'option --update-labels. Vous pouvez mettre à jour les libellés des ressources Compute Engine à l'aide des commandes gcloud suivantes :

Exemple

gcloud compute disks update example-disk \
    --update-labels backend=webserver,media=images

Si vous fournissez une clé de libellé qui existe déjà, Google Cloud CLI met à jour la clé existante avec la nouvelle valeur de libellé. S'il s'agit d'une nouvelle clé, l'outil l'ajoute à la liste des libellés.

API

Pour ajouter ou mettre à jour des libellés, envoyez une requête POST à la méthode setLabels de la ressource appropriée avec la dernière empreinte et la liste complète des libellés à appliquer.

Comme pour les métadonnées et les tags, si la ressource comprend des libellés existants à conserver, vous devez inclure ces libellés dans la requête, ainsi que les nouveaux libellés à ajouter.

Par exemple, l'extrait suivant envoie une requête POST à une instance de VM pour définir les libellés environment:test et an-existing-tag:yes :

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": {
  "environment": "test",
  "an-existing-tag": "yes"
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Afficher les libellés

Vous pouvez afficher les libellés des ressources à l'aide de la console Google Cloud, de gcloud CLI ou de l'API Compute Engine. Pour afficher les libellés des règles de transfert, utilisez gcloud CLI ou l'API Compute Engine.

Console

  1. Accédez à la page des ressources.

  2. Cliquez sur la ressource pour en afficher les détails.

  3. Recherchez les libellés.

gcloud

Pour afficher les libellés, utilisez la sous-commande describe. Vous pouvez afficher les libellés des ressources Compute Engine à l'aide des commandes gcloud suivantes :

Exemple

gcloud compute disks describe example-disk

Le résultat contient les libellés suivants :

...
id: '5047929990219134234'
kind: compute#disk
labelFingerprint: GHZ1Un209U=0
labels:
  environment: dev
  department: finance
...

API

Pour récupérer des libellés, envoyez une requête GET à la ressource suivante :

Par exemple, l'extrait suivant envoie une requête GET pour récupérer les libellés d'une instance de VM :

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

Remplacez l'élément suivant :

  • PROJECT_ID : ID du projet
  • ZONE : zone de la VM
  • VM_NAME : nom de la VM

Obtenir l'empreinte d'un libellé pour les requêtes API

Lors de la mise à jour ou de l'ajout de libellés dans l'API, vous devez fournir les empreintes les plus récentes des libellés avec votre requête, afin d'éviter tout conflit avec d'autres requêtes. Une empreinte n'est requise que pour les requêtes API. La console Google Cloud et Google Cloud CLI ne nécessitent pas d'empreinte.

Pour obtenir la dernière version de labelsFingerprint, envoyez une requête GET aux ressources suivantes :

Par exemple, l'extrait suivant renvoie labelsFingerprint pour une instance de VM :

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance

La réponse contient la propriété labelFingerprint :

200 OK

{
 "kind": "compute#instance",
 "id": "4392196237934605253",
 "creationTimestamp": "2015-09-15T14:05:16.475-07:00",
 "zone": "https://content.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f",
 "status": "RUNNING",
 ...
 "labels": {
  "environment": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Supprimer un libellé

Vous pouvez supprimer des libellés des ressources à l'aide de la console Google Cloud, de gcloud CLI ou de l'API Compute Engine. Pour supprimer des libellés des règles de transfert, utilisez gcloud CLI ou l'API Compute Engine.

Console

  1. Accédez à la page correspondant à la ressource pour laquelle vous souhaitez ajouter des libellés.

  2. Cochez les cases à côté des ressources pour lesquelles vous souhaitez supprimer des libellés.

  3. Pour développer la colonne des libellés, cliquez sur Afficher le panneau d'informations.

  4. Pour supprimer un libellé, cliquez sur Supprimer.

  5. Enregistrez les modifications.

gcloud

Pour ajouter ou modifier un libellé, utilisez la sous-commande update avec l'option --remove-labels. Vous pouvez supprimer les libellés des ressources Compute Engine à l'aide des commandes gcloud suivantes :

Exemple

gcloud compute disks update example-disk \
    --remove-labels backend,media

API

Pour supprimer des libellés, envoyez une requête POST à la méthode setLabels de la ressource suivante en utilisant la dernière empreinte et la liste complète des libellés à appliquer :

Fournissez les valeurs labelsFingerprint actuelles et une liste vide de libellés pour supprimer tous les libellés, ou fournissez une liste de libellés à conserver (en omettant les libellés à supprimer). Par exemple, l'extrait suivant supprime tous les libellés de la VM :

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

Filtrer les résultats de recherche à l'aide de libellés

Vous pouvez effectuer des recherches parmi vos ressources et filtrer les résultats par libellé à l'aide de la console Google Cloud, de gcloud CLI ou de l'API Compute Engine. Pour filtrer les règles de transfert par libellé, utilisez gcloud CLI ou l'API Compute Engine.

Console

  1. Accédez à la page correspondant à la ressource pour laquelle vous souhaitez obtenir une liste filtrée de ressources.

  2. Si vous y êtes invité(e), sélectionnez votre projet et cliquez sur Continuer.

  3. Dans la barre de recherche, saisissez la clé, la valeur ou la paire clé/valeur. Les résultats incluent les correspondances partielles.

    Par exemple, pour n'afficher que les ressources associées au libellé env:dev, vous pouvez saisir l'un des éléments suivants :

    • Saisissez la clé : env
    • Saisissez la valeur : dev
    • Saisissez la paire clé-valeur : env:dev

gcloud

Pour effectuer un filtrage en fonction des libellés, utilisez la sous-commande list des ressources suivantes avec l'indicateur --filter :

La valeur de l'option --filter doit être au format labels.KEY=VALUE. Par exemple, si vous souhaitez effectuer un filtrage à l'aide d'un libellé assorti de la clé env et de la valeur dev, vous pouvez exécuter la commande suivante :

gcloud compute instances list \
    --filter labels.env=dev

Pour en savoir plus sur la syntaxe du filtrage dans gcloud CLI, consultez la documentation de gcloud topic filters.

API

Pour filtrer des ressources, envoyez une requête GET à la méthode list des ressources suivantes et incluez le champ de filtre :

Par exemple, pour répertorier toutes les VM du projet myproject et de la zone us-central1-a avec un libellé dont la paire clé-valeur est env:dev, définissez le champ de filtre sur labels.env:dev dans votre requête list. Si vous incluez le champ de filtre en tant que paramètre de chaîne de requête, utilisez la valeur de paramètre encodée au format URL filter=labels.env%3Adev :

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?filter=labels.env%3Adev

Pour en savoir plus, consultez la documentation concernant le paramètre filter dans la documentation de référence de l'API Compute Engine.

Relation entre les libellés d'instance et les tags réseau

Auparavant, libellés et tags étaient liés. Par exemple, si vous ajoutiez un libellé webserver:test à une VM, Compute Engine ajoutait automatiquement un tag webserver à la VM.

Désormais, libellés et tags sont séparés. Si vous créez un libellé sur une VM, Compute Engine ne crée pas de tag pour cette VM. Si vous souhaitez créer un tag sur une VM, vous devez le créer manuellement.

Pour savoir comment créer des tags, consultez la page Tags réseau.

Étape suivante