Utiliser des annotations et des étiquettes avec Cloud Deploy

Vous pouvez associer des annotations et des étiquettes à vos ressources Cloud Deploy. Elles ne sont pas obligatoires.

Ce document répertorie les ressources auxquelles vous pouvez associer des étiquettes et des annotations, et décrit comment les utiliser et où les afficher.

À propos des annotations et des libellés

Les annotations sont des paires clé-valeur d'un texte au format libre. Vous pouvez les utiliser pour joindre des informations arbitraires associées à la ressource.

Vous pouvez utiliser des libellés pour organiser les ressources. Par exemple, vous pouvez appliquer une logique basée sur la sélection des libellés.

Comme pour les annotations, les étiquettes sont des paires clé/valeur. Toutefois, elles doivent respecter les limites suivantes:

• Une ressource Cloud Deploy ne peut pas comporter plus de 64 étiquettes.

• Les clés et les valeurs ne doivent pas dépasser 128 octets.

• Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets.

• Les clés doivent commencer par une lettre minuscule ou un caractère international.

• Tous les caractères doivent utiliser l'encodage UTF-8. Les caractères internationaux sont acceptés.

L'option --labels (par exemple, sur gcloud deploy releases create) peut accepter une liste de paires clé/valeur:

"name=wrench,mass=1.3kg,count=3"

Pour en savoir plus, consultez la documentation de l'API Cloud Deploy.

Ajouter des annotations et des étiquettes aux ressources Cloud Deploy

Vous pouvez ajouter des annotations et des étiquettes aux ressources Cloud Deploy suivantes:

• Pipelines de livraison

  Pour les pipelines de livraison, vous ajoutez des annotations et des étiquettes au fichier de configuration YAML.

apiVersion: deploy.cloud.google.com/v1
  kind: DeliveryPipeline
  metadata:
   name:
   annotations:
     key: "value"
   labels:
     key: "value"
  description:
  serialPipeline:
   stages:
   - targetId:
     profiles: []
   - targetId:
     profiles: []

• Cibles

  Ajouter des annotations et des étiquettes aux cibles dans le fichier YAML de configuration de la cible.

  Par exemple, vous pouvez inclure un lien vers plus d'informations sur la surveillance tierce pour votre application. Toutefois, si la cible est partagée, n'oubliez pas qu'elle peut être utilisée pour plusieurs applications. Le lien ne doit donc pas être spécifique à une application.

• Versions

  Vous pouvez ajouter des annotations ou des étiquettes à une version à l'aide des options --labels et --annotations de la commande gcloud deploy releases create. Les étiquettes et les annotations que vous ajoutez à une version ne sont pas transférées sous forme de libellés ou d'annotations sur les déploiements qui en résultent.

  Par exemple, vous pouvez utiliser des annotations pour inclure une référence à un PR, à un auteur ou à un hachage SHA Git du commit Git contenant les modifications à déployer. Pour en savoir plus, consultez la section Utiliser des annotations pour suivre la provenance de la version.

• Déploiements

  Vous pouvez ajouter des annotations et des libellés aux nouveaux déploiements en spécifiant --labels ou --annotations sur la commande gcloud deploy releases promote.

  Le seul moyen d'ajouter des annotations et des libellés au premier déploiement consiste à créer un déploiement à l'aide de l'API Cloud Deploy et à inclure les annotations ou les libellés dans la ressource rollout.

  Voici quelques exemples d'utilisation des annotations lors d'un déploiement:

  • Créez une annotation contenant l'URL renvoyant vers les résultats du test.
  • Créez une annotation avec un numéro de demande pertinent provenant d'un système de gestion de workflows.

Remarque :Les libellés et les annotations ajoutés aux ressources Cloud Deploy ne s'appliquent qu'à ces ressources. Elles ne sont pas appliquées de manière transitoire aux ressources déployées.

Où puis-je trouver les annotations d'une ressource ?

Vous pouvez afficher les annotations et les étiquettes de toute ressource compatible à l'aide de la commande describe de la ressource ou en affichant les métadonnées de la ressource dans la console Google Cloud.

Depuis la gcloud CLI

Pour afficher les annotations et les étiquettes d'une ressource à partir de la ligne de commande, exécutez une commande describe sur cette ressource. L'exemple suivant montre les détails d'une cible:

 $ gcloud deploy targets describe qsprod --delivery-pipeline=my-demo-app-1 \
                                              --region=us-central1 \
                                              --project=quickstart-basic8

La commande ci-dessus affiche le résultat suivant :

 Target:
   annotations:
     approver_ticket_queue_url: https://workflows.example.com/deploy_approvals/4985729
   createTime: '2021-10-28T19:33:56.907887878Z'
   description: development cluster
   etag: 5b3bbee48f693cd7
   gke:
     cluster: projects/quickstart-basic8/locations/us-central1/clusters/quickstart-cluster-qsdev
   name: projects/quickstart-basic8/locations/us-central1/targets/qsdev
   uid: 3f3a5f8e7e0648e3bb17898ee531455d
   updateTime: '2021-11-10T16:55:11.502660604Z'

Notez que ce résultat inclut l'annotation target_name.

Dans la console Google Cloud

Pour afficher les annotations et les étiquettes d'une ressource Cloud Deploy contenant de telles métadonnées, affichez les détails de cette ressource dans la console Google Cloud.

Par exemple, voici les détails d'un pipeline de livraison comprenant une annotation:

Voici les détails de cette version:

Libellés automatiques de Cloud Deploy

Par défaut, Cloud Deploy ajoute les libellés suivants aux fichiers manifestes affichés:

• app.kubernetes.io/managed-by:

  Libellé standard indiquant les outils de déploiement. Ce paramètre est toujours défini sur google-cloud-deploy pour identifier l'origine de la charge de travail.

• deploy.cloud.google.com/location:

  Emplacement du pipeline de livraison déployé, par exemple us-central1.

• deploy.cloud.google.com/project-id:

  ID du projet du pipeline de livraison déployé.

• deploy.cloud.google.com/delivery-pipeline-id:

  ID de ressource du pipeline de livraison utilisé. Cette image est issue de l'instantané de la version.

• deploy.cloud.google.com/release-id:

  ID de ressource de la version déployée.

• deploy.cloud.google.com/target-id:

  ID de ressource de la cible de déploiement. Cette image est issue de l'instantané de la version.

Exemple d'utilisation

Un exemple d'utilisation de ces libellés appliqués automatiquement consisterait à créer un graphique dans l'observabilité Google Cloud qui agrège une métrique de conteneur par propriétés Cloud Deploy:

fetch k8s_container
| metric 'kubernetes.io/container/cpu/core_usage_time'
| filter metadata.user.c'app.kubernetes.io/managed-by' = "google-cloud-deploy"
| group_by [
    pipeline: metadata.user.c'deploy.cloud.google.com/delivery-pipeline-id',
    target: metadata.user.c'deploy.cloud.google.com/target-id',
    release: metadata.user.c'deploy.cloud.google.com/release-id',],
      sum(val())
| rate 1m

Vous pouvez également l'utiliser avec des métriques personnalisées. Par exemple, si PodMonitor est configuré avec un libellé correspondant à app.kubernetes.io/managed-by: google-cloud-deploy. Vous pouvez ensuite utiliser une requête pour définir un graphique pour des métriques personnalisées:

fetch k8s_container
| metric workload.googleapis.com/example_requests_total
| filter metadata.user_labels.c'app.kubernetes.io/managed-by' = "google-cloud-deploy"
| group_by [
    pipeline: metadata.user.c'deploy.cloud.google.com/delivery-pipeline-id',
    target: metadata.user.c'deploy.cloud.google.com/target-id',
    release: metadata.user.c'deploy.cloud.google.com/release-id',],
    sum(val())
| rate 1m

Désactiver les étiquettes automatiques

Votre organisation peut les interdire pour des raisons réglementaires, de conformité ou autres. Pour ce faire, le service de règles d'administration propose une contrainte qui détermine si ces libellés sont appliqués ou non.

Pour empêcher Cloud Deploy d'ajouter automatiquement des libellés aux fichiers manifestes affichés, définissez la contrainte du service de règles d'administration clouddeploy.disableServiceLabelGeneration à appliquer. Appliquer cette contrainte ne vous empêche pas de spécifier manuellement des libellés et ne supprime pas les libellés des versions existantes.

Pour en savoir plus sur l'activation des contraintes, consultez la page Utiliser des contraintes booléennes dans la règle d'administration.