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 liste les ressources auxquelles vous pouvez associer des étiquettes d'annotations, et explique comment vous pouvez les utiliser et où vous pouvez les consulter.

À propos des annotations et des libellés

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

Vous pouvez organiser les ressources à l'aide de libellés. Par exemple, vous pouvez appliquer une logique lors de la sélection des étiquettes.

Comme pour les annotations, les étiquettes sont des paires clé/valeur. Toutefois, ils doivent être conformes aux les limites suivantes:

  • Une ressource Cloud Deploy ne peut pas avoir 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 être au format d'encodage UTF-8. Les caractères internationaux sont autorisé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"

Consultez la documentation de l'API Cloud Deploy. pour en savoir plus.

Ajouter des annotations et des étiquettes aux ressources Cloud Deploy

Vous pouvez ajouter des annotations et des étiquettes aux ressources:

  • Pipelines de livraison

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

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

  • Cibles

    Ajoutez des annotations et des étiquettes aux cibles dans la section fichier YAML de configuration cible.

    Par exemple, vous pouvez inclure un lien vers plus d'informations sur le tiers et la surveillance de votre application. En revanche, si la cible est partagée, qu'il pourrait être utilisé pour plusieurs applications, le lien ne doit donc pas propres à chaque application.

  • Versions

    Vous pouvez ajouter des annotations et/ou des étiquettes à une version à l'aide de l'--labels et --annotations sur la commande gcloud deploy releases create. Étiquettes et les annotations que vous ajoutez à une version ne sont pas reportées comme étiquettes sur les déploiements qui en résultent.

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

  • Déploiements

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

    Vous pouvez ajouter des annotations et des étiquettes au premier déploiement en spécifiant --initial-rollout-labels ou --initial-rollout-annotations sur le gcloud deploy releases create.

    Voici quelques exemples de ce que vous pouvez faire à l'aide d'annotations sur un déploiement:

    • Créez une annotation contenant l'URL pointant vers les résultats du test.
    • Créer une annotation avec un numéro de ticket pertinent d'un workflow Google Cloud.

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

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

Depuis la gcloud CLI

Pour afficher les annotations et les étiquettes d'une ressource à partir de la ligne de commande, utilisez un describe sur cette ressource. L'exemple suivant montre les détails pour 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 de n'importe quelle ressource Cloud Deploy qui dispose 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 incluant une annotation:

Détails du pipeline de livraison dans la console Google Cloud

Voici les détails d'une version:

Détails de la version dans la console Google Cloud

Étiquettes automatiques à partir de Cloud Deploy

Par défaut, Cloud Deploy ajoute les étiquettes suivantes au rendu manifests:

  • app.kubernetes.io/managed-by:

    Libellé standard indiquant les outils de déploiement. Elle est toujours définie 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 information est tirée du 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 information est tirée du instantané de la version.

Exemple d'utilisation

Un exemple d'utilisation de ces étiquettes appliquées automatiquement consisterait à créer un graphique dans Google Cloud Observability qui agrège les métriques de conteneur par les 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 métriques:

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ésactivation des étiquettes automatiques

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

Pour empêcher Cloud Deploy d'ajouter automatiquement des étiquettes au rendu fichiers manifestes, définir une contrainte de service de règles d'administration clouddeploy.disableServiceLabelGeneration à appliquer. Appliquer ne vous empêche pas de spécifier des étiquettes manuellement, supprimer les libellés des versions existantes.

Consultez la section Utiliser des contraintes booléennes dans les règles d'administration. pour en savoir plus sur l'activation des contraintes.