Attribuer des libellés à des 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",...
 }

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 à l'aide de l'outil de ligne de commande gcloud ou de l'API, vous pouvez appliquer des libellés à cette instance.

gcloud

Lors de la création de votre instance, incluez l'option --labels, suivie d'une liste de paires clé/valeur séparées par une virgule correspondant aux libellés. Utilisez 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

curl

Dans l'API, lors de la requête POST pour l'ajout d'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é de libellé qui existe déjà, l'outil 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. Seuls les libellés que vous spécifiez sont affectés. Les libellés existants non inclus dans la commande restent inchangés.

curl

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

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{"settings" : {"userLabels" :
                              {"<LABEL1>" : "<VALUE1>", "<LABEL2>" : "<VALUE2>"}}}' \
    -X PATCH \
    https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>

Si vous indiquez une clé de libellé qui existe déjà, l'outil 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. 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

À l'aide de l'outil de ligne de commande gcloud, 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.

curl

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

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{"settings": {"userLabels": {"[LABEL_NAME]": null}}}' \
     -X PATCH \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/[INSTANCE_NAME]

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

Vous pouvez filtrer la liste d'instances par libellé à l'aide de l'outil gcloud 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 l'outil gcloud, 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

Étape suivante