Ajouter un libellé aux instances

Cette page décrit les libellés. Elle décrit comment créer une instance avec des libellés, comment ajouter, mettre à jour et supprimer des libellés, et comment utiliser des libellés dans les recherches.

Les libellés sont un moyen simple de regrouper les instances liées ou associées. Par exemple, vous pouvez attribuer à vos instances des libellés selon que vous les utilisez à des fins de test ou de production, ou vous pouvez leur ajouter un code de facturation. Vous pouvez également les employer pour rechercher des instances ou suivre les frais qu'elles occasionnent.

Ajoutez toujours des libellés sous forme de paires clé/valeur :

{
 "userLabels": {
    "track": "production",
    "location": "western-division"
    "billing-code": "34802",...
 }

La modification des libellés n'a aucune incidence sur les performances de l'instance Cloud SQL.

Pour plus d'informations, consultez les sections Que sont les libellés ? et Conditions requises pour les libellés.

Restrictions

  • Vous pouvez attribuer jusqu'à 64 libellés à chaque instance.

  • Les clés et valeurs des libellés doivent respecter les restrictions suivantes :

    • Les clés et les valeurs ne peuvent pas dépasser 63 caractères chacune.
    • Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des caractères numériques, des traits de soulignement et des tirets. Les caractères internationaux sont acceptés.
    • Les libellés doivent commencer par une lettre minuscule.
    • Les libellés ne peuvent pas être vides.

Créer des instances avec des libellés

Lorsque vous créez une instance en utilisant gcloud CLI ou l'API, vous pouvez appliquer des étiquettes à cette instance.

gcloud

Lors de la création de l'instance, incluez l'indicateur "--labels", suivi d'une liste de paires clé/valeur séparées par une virgule correspondant aux libellés. Vous devez utiliser la version bêta de la commande "create" pour inclure les libellés.

Exemple :

gcloud beta sql instances create ... --labels track=production,billing-code=34802

Terraform

Lors de la création d'une instance avec un libellé, utilisez une ressource Terraform : 

resource "google_sql_database_instance" "postgres_instance_labels" {
  name             = "postgres-instance-labels"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Appliquer les modifications

Pour appliquer votre configuration Terraform dans un projet Google Cloud, suivez les procédures des sections suivantes.

Préparer Cloud Shell

  1. Lancez Cloud Shell.

  2. Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

    Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

  1. Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

    Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

    Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.

  3. Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
  4. Enregistrez les modifications.
  5. Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire. 
    terraform init

    Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade : 

    terraform init -upgrade

Appliquer les modifications

  1. Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes : 
    terraform plan

    Corrigez les modifications de la configuration si nécessaire.

  2. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité : 
    terraform apply

    Attendez que Terraform affiche le message "Apply completed!" (Application terminée).

  3. Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud, accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

Supprimer les modifications

Pour supprimer vos modifications, procédez comme suit :

  1. Pour désactiver la protection contre la suppression, définissez l'argument deletion_protection sur false dans le fichier de configuration Terraform. 
    deletion_protection =  "false"
  2. Appliquez la configuration Terraform mise à jour en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité : 
    terraform apply

  1. Supprimez les ressources précédemment appliquées à votre configuration Terraform en exécutant la commande suivante et en saisissant yes à l'invite :

    terraform destroy

curl

Dans l'API, lors de la requête POST visant à ajouter une nouvelle instance, ajoutez la propriété "userLabels" dans le corps de la requête afin d'appliquer des libellés à la nouvelle instance. Par exemple, le corps d'une requête de création d'instance peut comporter les libellés suivants :

          "settings": {"tier":"db-custom-2-7680",
                       "userLabels": {"track": "production",
                                      "location": "western-division",
                                      "billing-code": "34802"},

Ajouter ou mettre à jour des libellés sur une instance existante

Console

  1. Accédez à la page "Instances Cloud SQL" dans Google Cloud Console.

    Accéder à la page Instances Cloud SQL

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

  3. Cliquez sur Afficher le panneau d'informations dans l'angle supérieur droit pour développer la colonne des libellés.

  4. Mettez à jour les libellés ou ajoutez-en de nouveaux, le cas échéant.

  5. Enregistrez les modifications.

gcloud

Exécutez la sous-commande patch (version bêta) pour mettre à jour ou ajouter des libellés sur une instance existante :

gcloud beta sql instances patch [INSTANCE_NAME] --update-labels [KEY1]=[VALUE1]...

Exemple :

gcloud beta sql instances patch my-instance --update-labels track=production,billing-code=34802

Si vous indiquez une clé d'étiquette qui existe déjà, l'outil met à jour la clé existante avec la nouvelle valeur d'étiquette. S'il s'agit d'une nouvelle clé, l'outil l'ajoute à la liste des libellés. Seuls les libellés que vous spécifiez sont affectés. Les libellés existants non inclus dans la commande restent inchangés.

REST v1

Pour ajouter ou mettre à jour des libellés, exécutez la méthode PATCH :

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • project-id : ID du projet
  • instance-id : ID de l'instance
  • label-name-1 : nom du libellé
  • value-1 : valeur de label-name-1
  • label-name-2 : nom du libellé
  • value-2 : valeur de label-name-2

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Si vous indiquez une clé d'étiquette qui existe déjà, l'outil met à jour la clé existante avec la nouvelle valeur d'étiquette. S'il s'agit d'une nouvelle clé, l'outil l'ajoute à la liste des libellés. Seuls les libellés que vous spécifiez sont affectés. Les libellés existants non inclus dans la requête restent inchangés.

REST v1beta4

Pour ajouter ou mettre à jour des libellés, exécutez la méthode PATCH :

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • project-id : ID du projet
  • instance-id : ID de l'instance
  • label-name-1 : nom du libellé
  • value-1 : valeur de label-name-1
  • label-name-2 : nom du libellé
  • value-2 : valeur de label-name-2

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Si vous indiquez une clé d'étiquette qui existe déjà, l'outil met à jour la clé existante avec la nouvelle valeur d'étiquette. S'il s'agit d'une nouvelle clé, l'outil l'ajoute à la liste des libellés. Seuls les libellés que vous spécifiez sont affectés. Les libellés existants non inclus dans la requête restent inchangés.

Supprimer un libellé

Console

  1. Accédez à la page "Instances Cloud SQL" dans Google Cloud Console.

    Accéder à la page Instances Cloud SQL

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

  3. Cliquez sur Afficher le panneau d'informations pour développer la colonne des libellés.

  4. Cliquez sur X à côté de tous les libellés à supprimer.

  5. Enregistrez les modifications.

gcloud

En utilisant gcloud CLI, exécutez la sous-commande patch (version bêta) avec l'option --remove-labels :

gcloud beta sql instances patch [INSTANCE_NAME] --remove-labels [LABEL1],[LABEL2]

Si vous indiquez un nom de libellé qui n'existe pas, aucune erreur n'est renvoyée.

REST v1

Pour supprimer un libellé à l'aide de l'API, définissez sa valeur sur null :

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • project-id : ID du projet
  • instance-id : ID de l'instance
  • label-name : nom du libellé

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

REST v1beta4

Pour supprimer un libellé à l'aide de l'API, définissez sa valeur sur null :

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • project-id : ID du projet
  • instance-id : ID de l'instance
  • label-name : nom du libellé

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Filtrer les résultats de recherche d'instances en utilisant les libellés

Vous pouvez filtrer la liste d'instances par libellé à l'aide de gcloud CLI ou de l'API.

gcloud

Dans gcloud, exécutez une requête list et utilisez l'option --filter. Pour effectuer un filtrage à l'aide des libellés, utilisez la syntaxe labels.[KEY]:[VALUE]. Par exemple, si vous souhaitez filtrer les résultats à l'aide d'un libellé billing-code dont la valeur est 34802, vous pouvez exécuter la commande suivante :

gcloud beta sql instances list --filter='labels.billing-code:34802'

Si vous souhaitez filtrer les résultats en fonction de la présence ou non d'un libellé, quelle que soit sa valeur, procédez comme suit :

gcloud beta sql instances list --filter='labels:billing-code'

Pour obtenir une documentation complète sur la syntaxe du filtrage dans gcloud CLI, consultez la documentation gcloud topic filters.

curl

Dans l'API, exécutez une requête "list" avec un paramètre de requête filter encodé au format URL :

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

Exemple :

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

Lorsque deux valeurs de libellés sont incluses avec un espace (encodé) entre elles, elles doivent toutes les deux être vraies pour qu'une instance soit renvoyée (il s'agit d'une opération AND). Vous pouvez également indiquer les opérateurs AND, OR et NOT de manière explicite. Exemple :

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

Étapes suivantes