Créer et gérer des 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

Que sont les libellés ?

Un libellé est une paire clé/valeur qui vous permet d'organiser plus efficacement vos instances Google Cloud. Vous pouvez associer un libellé à chaque ressource, puis filtrer les ressources par libellé. Les informations sur les étiquettes sont transmises au système de facturation afin que vous puissiez consulter le détail des frais apparaissant sur votre facture en fonction des étiquettes.

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. Pour en savoir plus, consultez la présentation des tags.

Cas d'utilisation courants des libellés

Nous vous recommandons de ne pas créer de grands nombres de libellés uniques, tels que pour des horodatages ou des valeurs individuelles pour chaque appel d'API. Voici quelques cas d'utilisation courants des libellés :

  • 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 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.

Exigences applicables aux libellés

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

  • Chaque ressource peut posséder plusieurs libellés, jusqu'à un maximum de 64.
  • 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.
  • La partie clé d'un libellé doit être unique. Cependant, vous pouvez utiliser la même clé avec plusieurs ressources.
  • Les clés doivent commencer par une lettre minuscule ou un caractère international.

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.

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": [{
   "key": "webserver",
   "value": "backend"
   },
   {
   "key": "media",
   "value": "images"
  }]
}

Ajouter ou mettre à jour des libellés sur des ressources existantes

Vous pouvez ajouter des libellés ou mettre à jour des libellés existants sur des ressources à l'aide de Cloud Console, de l'outil gcloud ou de l'API Compute Engine. Pour ajouter ou mettre à jour des libellés sur des règles de transfert, utilisez l'outil gcloud 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 indiquez une clé de libellé qui existe déjà, l'outil de ligne de commande gcloud met à jour la clé existante avec la nouvelle valeur du 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 des étiquettes

Vous pouvez afficher les libellés des ressources à l'aide de Cloud Console, de l'outil gcloud ou de l'API Compute Engine. Pour afficher les libellés des règles de transfert, utilisez l'outil gcloud 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. Cloud Console et l'outil de ligne de commande gcloud 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 Cloud Console, de l'outil gcloud ou de l'API Compute Engine. Pour supprimer des libellés des règles de transfert, utilisez l'outil gcloud 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 Cloud Console, de l'outil gcloud ou de l'API Compute Engine. Pour filtrer les règles de transfert par libellé, utilisez l'outil gcloud 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 l'outil gcloud, consultez la documentation gcloud topic filters.

API

Pour filtrer des ressources, envoyez une requête GET à la méthode list des ressources suivantes avec un paramètre de requête filter encodé au format URL :

Par exemple, pour effectuer un filtrage en fonction d'un libellé env:dev, envoyez la requête GET suivante en incluant filter=labels.env+eq+dev dans la chaîne de requête.

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/list?filter=labels.env+eq+dev

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