Créer et gérer des étiquettes de cluster et de pool de nœuds

Cette page présente les étiquettes de cluster et de pool de nœuds dans Google Kubernetes Engine.

Étiquettes de cluster et de pool de nœuds GKE, et étiquettes Kubernetes

Les étiquettes de cluster et de pool de nœuds GKE sont distinctes des étiquettes de Kubernetes. Les deux systèmes d'étiquetage fonctionnent indépendamment les uns des autres et n'héritent ni ne partagent les étiquettes.

Les étiquettes de cluster et de pool de nœuds GKE sont des métadonnées arbitraires associées à vos ressources que vous pouvez utiliser pour suivre les informations d'utilisation et de facturation.

Le système utilise également des étiquettes en interne pour associer des composants et des ressources de cluster (par exemple, des pods et des nœuds) et gérer les cycles de vie des ressources. Vous pouvez modifier les étiquettes Kubernetes à l'aide de l'API Kubernetes. Vous pouvez également utiliser l'API GKE pour modifier des étiquettes Kubernetes sur vos nœuds avec la création de cluster ou une mise à jour de cluster.

À quoi correspondent les étiquettes de cluster ?

Un libellé de cluster est une paire clé-valeur que vous pouvez attribuer aux clusters 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.

Conditions requises pour les libellés de cluster

Les étiquettes du cluster appliquées à une ressource doivent répondre aux exigences suivantes :

Chaque ressource peut comporter jusqu'à 64 libellés de cluster.
Chaque étiquette de cluster 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é de cluster 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é de cluster, ainsi qu'aux ressources Google Cloud individuelles associées à des libellés de cluster. Vous pouvez appliquer autant de libellés de cluster que vous le souhaitez à toutes les ressources d'un projet.

Cas d'utilisation courants des étiquettes de cluster

Voici quelques cas d'utilisation courants des étiquettes de cluster :

É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 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 cluster de composants : par exemple, component:redis, component:frontend, component:ingest et component:dashboard.
Étiquettes de cluster d'environnement ou d'étape : par exemple, environment:production et environment:test.
Étiquettes de cluster d'état : par exemple, state:active, state:readytodelete et state:archive.
Libellés de propriété de cluster : permettent d'identifier les équipes responsables des opérations (par exemple, team:shopping-cart).

Répartition des frais : utilisez des étiquettes de pool de nœuds pour ventiler vos frais facturés par pool de nœuds. Pour en savoir plus, consultez la section Afficher la répartition détaillée des coûts du cluster.

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.

Étiquettes appliquées automatiquement

GKE applique automatiquement plusieurs étiquettes aux ressources du cluster.

Par exemple, GKE applique des étiquettes aux instances Compute Engine, aux disques persistants et aux accélérateurs (TPU).

Le tableau suivant affiche les étiquettes que GKE applique automatiquement aux ressources :

Libellé	Ressources concernées
`goog-gke-node`	Instance de VM Compute Engine sous-jacente à un nœud GKE.
`goog-gke-volume`	Disque persistant Compute Engine associé à une instance de VM sous-jacente à un nœud GKE.
`goog-gke-tpu`	Cloud TPU sur GKE
`goog-k8s-cluster-name`	Instance de VM Compute Engine et disques persistants associés à une instance de VM sous-jacente à un nœud GKE.
`goog-k8s-cluster-location`	Instance de VM Compute Engine et disques persistants associés à une instance de VM sous-jacente à un nœud GKE.
`goog-k8s-node-pool-name`	Instances de VM Compute Engine et leurs disques de démarrage sous-jacents à un nœud GKE.
`goog-fleet-project`	Instance de VM Compute Engine et disques persistants associés à une instance de VM sous-jacente à un nœud GKE, si le cluster est enregistré dans un parc.

Ne modifiez pas et ne supprimez pas les étiquettes réservées. Toute modification apportée aux étiquettes réservées fera l'objet d'un rapprochement automatique.

Propagation des étiquettes

Dans GKE, vous pouvez appliquer des étiquettes à des clusters et à des pools de nœuds en mode standard. Lorsque vous étiquetez un cluster, l'étiquette se propage à toutes les ressources individuelles du cluster, telles que les nœuds, les instances et les disques persistants. Lorsque vous étiquetez un pool de nœuds, l'étiquette se propage à toutes les ressources individuelles du pool de nœuds, telles que les instances et les disques persistants. Dans les clusters standards, si les étiquettes de cluster sont en conflit avec les étiquettes du pool de nœuds (par exemple, lorsque la clé de l'étiquette est identique, mais que la valeur est différente), les étiquettes de pool de nœuds remplacent les étiquettes de cluster.

Toutes les étiquettes que vous appliquez à vos clusters ou pools de nœuds se propagent via un processus d'arrière-plan qui s'exécute toutes les heures. La diffusion de cette étiquette à toutes les ressources associées peut prendre jusqu'à une heure. En outre, les étiquettes ne se propagent qu'aux instances Compute Engine et aux disques persistants associés à des instances Compute Engine. Les autres ressources telles que les charges de travail, les règles de transfert, les adresses IP et les disques persistants non associés ne sont pas étiquetées.

Pour les clusters standards, lorsque des étiquettes de cluster et de pool de nœuds sont appliquées aux ressources Compute Engine, vous pouvez modifier manuellement les étiquettes de ressources sans que ces modifications ne soient rapprochées par GKE. Dans les clusters Autopilot, vous ne pouvez pas modifier manuellement les étiquettes des ressources Compute Engine, car GKE gère les nœuds à votre place. Cependant, nous vous recommandons de gérer ces étiquettes via GKE. Les étiquettes existantes de ces ressources Compute Engine ne seront pas supprimées par GKE, sauf si elles sont en conflit avec les étiquettes appliquées automatiquement.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

Activez l'API Google Kubernetes Engine.

Activer l'API Google Kubernetes Engine

Si vous souhaitez utiliser Google Cloud CLI pour cette tâche, installez puis initialisez gcloud CLI. Si vous avez déjà installé gcloud CLI, assurez-vous de disposer de la dernière version en exécutant la commande gcloud components update.
Remarque : Pour les installations de gcloud CLI existantes, veillez à définir les propriétés compute/region et compute/zone. En définissant des emplacements par défaut, vous pouvez éviter des erreurs telles que celle-ci dans gcloud CLI : One of [--zone, --region] must be supplied: Please specify location.

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

Vous pouvez ignorer cette étape si vous utilisez la console Google Cloud ou gcloud CLI.

Lorsque vous mettez à jour ou ajoutez des étiquettes de cluster à l'aide de l'API GKE, vous devez fournir la dernière empreinte numérique d'étiquette de cluster avec votre requête afin d'éviter tout conflit avec d'autres requêtes.

Pour obtenir la dernière empreinte numérique d'étiquette de cluster, exécutez une requête GET pour le cluster approprié. Exemple :

GET https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster

Le résultat ressemble à ce qui suit :

200 OK

{

 "name": "mycluster",
 "description": "production-cluster",
 "initialNodeCount": 3,
 ...
 "resourceLabels": {
    "environment": "production",
    ...
  },
  "labelFingerprint": "p1ty_9HoBk0="
}

Dans ce résultat, la propriété labelFingerprint correspond à l'empreinte numérique d'étiquette de cluster.

Créer un cluster avec des étiquettes

Vous pouvez créer des clusters Autopilot et Standard avec des étiquettes à l'aide de gcloud CLI, de la console Google Cloud, de l'API GKE ou de Terraform.

gcloud

Exécutez la commande suivante pour créer un cluster Autopilot avec des étiquettes :

gcloud container clusters create-auto CLUSTER_NAME \
    --labels=KEY=VALUE

Vous pouvez également exécuter la commande suivante pour créer un cluster standard avec des étiquettes :

gcloud container clusters create CLUSTER_NAME \
    --labels=KEY=VALUE

Remplacez les éléments suivants :

CLUSTER_NAME : nom du cluster.
KEY : clé de la paire clé-valeur du libellé.
VALUE : valeur de la paire clé-valeur du libellé.

Console

Pour ajouter des étiquettes lors de la création de votre cluster, procédez comme suit :

Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

Accéder à Google Kubernetes Engine
Cliquez sur Créer.
Configurez votre cluster.
Dans le volet de navigation, sous Cluster, cliquez sur Métadonnées.
Cliquez sur Ajouter une étiquette.
Ajoutez des étiquettes.
Cliquez sur Créer.

API

Pour inclure une étiquette lors de la création de votre cluster, spécifiez l'objet resourceLabels dans l'objet cluster que vous fournissez à projects.zones.clusters.create.

Terraform

Pour créer un cluster Autopilot avec des étiquettes à l'aide de Terraform, reportez-vous à l'exemple suivant :

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-labels"
  location = "us-central1"

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Pour créer un cluster standard avec des étiquettes à l'aide de Terraform, reportez-vous à l'exemple suivant :

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-west1"
  initial_node_count = 2

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Pour en savoir plus sur l'utilisation de Terraform, consultez la page Compatibilité de Terraform avec GKE.

Ajouter ou mettre à jour des étiquettes pour des clusters existants

Vous pouvez ajouter ou mettre à jour des étiquettes pour des clusters Autopilot et Standard existants à l'aide de la gcloud CLI, de la console Google Cloud ou de l'API GKE.

gcloud

Exécutez la commande ci-dessous.

gcloud container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --update-labels=KEY=VALUE

Remplacez les éléments suivants :

CLUSTER_NAME : nom du cluster
COMPUTE_REGION : région Compute Engine du nouveau cluster. Pour les clusters zonaux standards, utilisez --zone=COMPUTE_ZONE.
KEY : clé de la paire clé-valeur du libellé.
VALUE : valeur de la paire clé-valeur du libellé.

La mise à jour des étiquettes écrase toutes les étiquettes existantes sur le cluster. Si le cluster contient des étiquettes existantes que vous souhaitez conserver, vous devez les inclure avec toutes les nouvelles étiquettes que vous souhaitez ajouter.

Console

Pour ajouter ou mettre à jour des étiquettes, procédez comme suit :

Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

Accéder à Google Kubernetes Engine
Sur la page Détails du cluster, cochez les cases correspondant aux clusters que vous souhaitez modifier.
Cliquez sur Étiquettes.
Ajoutez ou mettez à jour des étiquettes.
Cliquez sur Enregistrer.

API

Envoyez une requête POST à la méthode resourceLabels du cluster avec la dernière empreinte numérique et la liste complète des étiquettes à appliquer.

Comme pour les métadonnées et les tags, si le cluster comprend des étiquettes existantes à conserver, vous devez inclure ces étiquettes dans la requête, ainsi que les nouvelles étiquettes à ajouter.

Par exemple, l'extrait suivant envoie une requête à la méthode resourceLabels :

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": {
  "environment": "production",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Supprimer des étiquettes de cluster

Vous pouvez supprimer des étiquettes des clusters Autopilot et Standard à l'aide de la gcloud CLI, de la console Google Cloud ou de l'API GKE.

gcloud

Exécutez la commande update avec l'option --remove-labels.

gcloud container clusters update CLUSTER_NAME \
    --remove-labels=KEYS

Remplacez les éléments suivants :

CLUSTER_NAME : nom du cluster.
KEYS : liste de clés séparées par des virgules pour les étiquettes à supprimer.

Console

Pour supprimer des étiquettes, procédez comme suit :

Accédez à la page Google Kubernetes Engine dans la console Google Cloud.

Accéder à Google Kubernetes Engine
Dans la liste des clusters, cochez les cases correspondant aux clusters que vous souhaitez modifier.
Cliquez sur Étiquettes.
Cliquez sur Supprimer l'élément à côté du champ Valeur correspondant aux étiquettes à supprimer.
Cliquez sur Enregistrer.

API

Envoyez une requête POST à la méthode resourceLabels pour le cluster approprié. Fournissez les valeurs labelsFingerprint actuelles et une liste vide d'étiquettes pour supprimer toutes les étiquettes, ou fournissez une liste des étiquettes à conserver (en omettant celles à supprimer). Exemple :

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

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

Créer un pool de nœuds Standard avec des étiquettes

Vous pouvez créer un pool de nœuds avec des étiquettes dans un cluster standard à l'aide de gcloud CLI, de la console Google Cloud ou de l'API GKE.

gcloud

Exécutez la commande ci-dessous.

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Remplacez les éléments suivants :

NODE_POOL_NAME : nom du pool de nœuds.
CLUSTER_NAME : nom du cluster.
COMPUTE_REGION : région Compute Engine du cluster. Pour les clusters zonaux, utilisez --zone=COMPUTE_ZONE.
KEY : clé de la paire clé-valeur du libellé.
VALUE : valeur de la paire clé-valeur du libellé.

API

Pour inclure une étiquette lors de la création de votre pool de nœuds, spécifiez l'objet resourceLabels dans l'objet de pool de nœuds que vous fournissez à projects.zones.clusters.nodePools.create.

Console

Pour ajouter des étiquettes au nouveau pool de nœuds, procédez comme suit :

Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

Accéder à Google Kubernetes Engine
Sur la page Détails du cluster, cliquez sur le nom du cluster que vous souhaitez modifier.
Cliquez sur Ajouter un pool de nœuds.
Configurez votre nouveau pool de nœuds.
Dans le volet de navigation, cliquez sur Métadonnées.
Cliquez sur Ajouter une étiquette.
Ajoutez des étiquettes.
Cliquez sur Créer.

Ajouter ou mettre à jour des étiquettes pour un pool de nœuds existant

Vous pouvez ajouter ou mettre à jour des étiquettes pour des pools de nœuds existants à l'aide de gcloud CLI, de la console Google Cloud ou de l'API GKE.

gcloud

Exécutez la commande ci-dessous.

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Remplacez les éléments suivants :

NODE_POOL_NAME : nom du pool de nœuds.
CLUSTER_NAME : nom du cluster.
COMPUTE_REGION : région Compute Engine du cluster. Pour les clusters zonaux, utilisez --zone=COMPUTE_ZONE.
KEY : clé de la paire clé-valeur du libellé.
VALUE : valeur de la paire clé-valeur du libellé.

La mise à jour des étiquettes remplace les étiquettes existantes dans le pool de nœuds. Si le pool de nœuds contient des étiquettes existantes que vous souhaitez conserver, vous devez les inclure avec toutes les nouvelles étiquettes que vous souhaitez ajouter.

API

Pour inclure une étiquette lors de la modification de votre pool de nœuds, spécifiez l'objet resourceLabels dans l'objet de pool de nœuds que vous fournissez à projects.zones.clusters.nodePools.update.

Console

Pour ajouter ou mettre à jour des étiquettes, procédez comme suit :

Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

Accéder à Google Kubernetes Engine
Dans la liste des clusters, cliquez sur le nom du cluster contenant le pool de nœuds que vous souhaitez modifier.
Dans la section Pools de nœuds, cliquez sur le nom du pool de nœuds que vous souhaitez modifier.
Cliquez sur Modifier
Dans la section Étiquettes, ajoutez ou mettez à jour des étiquettes.
Cliquez sur Enregistrer.

Supprimer des étiquettes de pool de nœuds

Vous pouvez supprimer des étiquettes des pools de nœuds à l'aide de gcloud CLI, de la console Google Cloud ou de l'API GKE.

gcloud

Exécutez la commande ci-dessous.

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Remplacez les éléments suivants :

NODE_POOL_NAME : nom du pool de nœuds.
CLUSTER_NAME : nom du cluster.
COMPUTE_REGION : région Compute Engine du cluster. Pour les clusters zonaux, utilisez --zone=COMPUTE_ZONE.
KEY : clé de la paire clé-valeur du libellé.
VALUE : valeur de la paire clé-valeur du libellé.

La mise à jour des étiquettes remplace les étiquettes existantes dans le pool de nœuds. Si le pool de nœuds contient des étiquettes existantes que vous souhaitez conserver, vous devez exclure toutes les étiquettes que vous souhaitez supprimer. Si vous souhaitez supprimer toutes les étiquettes, utilisez --labels= sans paires clé/valeur.

API

Pour inclure une étiquette lorsque vous modifiez votre pool de nœuds, spécifiez l'objet resourceLabels dans l'objet de pool de nœuds que vous fournissez à projects.zones.clusters.nodePools.update. Fournissez une liste d'étiquettes vide pour supprimer toutes les étiquettes ou fournissez une liste des étiquettes à conserver. Omettez les étiquettes que vous souhaitez supprimer.

Console

Pour supprimer des étiquettes d'un pool de nœuds, procédez comme suit :

Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

Accéder à Google Kubernetes Engine
Dans la liste des clusters, cliquez sur le nom du cluster contenant le pool de nœuds que vous souhaitez modifier.
Dans la section Pools de nœuds, cliquez sur le nom du pool de nœuds que vous souhaitez modifier.
Cliquez sur Supprimer l'élément à côté du champ Valeur correspondant aux étiquettes à supprimer.
Cliquez sur Enregistrer.

Étapes suivantes

Lisez la présentation de GKE.