Utilizzo di annotazioni ed etichette con Cloud Deploy

Puoi associare annotazioni ed etichette alle risorse Cloud Deploy. Non sono obbligatori.

Questo documento elenca le risorse a cui puoi applicare etichette e annotazioni, nonché descrive come utilizzarle e dove visualizzarle.

Informazioni su annotazioni ed etichette

Le annotazioni sono coppie chiave-valore di testo in formato libero. Puoi utilizzarli per allegare informazioni arbitrarie associate alla risorsa.

Puoi utilizzare le etichette per organizzare le risorse. Ad esempio, puoi applicare la logica in base alla selezione delle etichette.

Come per le annotazioni, le etichette sono coppie chiave-valore. ma devono rispettare le seguenti limitazioni:

  • Una risorsa Cloud Deploy non può avere più di 64 etichette.

  • Sia le chiavi sia i valori devono avere una dimensione massima di 128 byte.

  • Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini.

  • Le chiavi devono iniziare con una lettera minuscola o un carattere internazionale.

  • Tutti i caratteri devono utilizzare la codifica UTF-8. Sono consentiti caratteri internazionali.

Il flag --labels (ad esempio su gcloud deploy releases create) può accettare un elenco di coppie chiave-valore:

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

Per ulteriori dettagli, consulta la documentazione dell'API Cloud Deploy.

Aggiunta di annotazioni ed etichette alle risorse Cloud Deploy

Puoi aggiungere annotazioni ed etichette alle seguenti risorse Cloud Deploy:

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

  • Destinazioni

    Aggiungi annotazioni ed etichette ai target nel file YAML di configurazione dei target.

    Ad esempio, puoi includere un link a ulteriori informazioni sul monitoraggio di terze parti per la tua applicazione. Tuttavia, se la destinazione è condivisa, ricorda che potrebbe essere utilizzata per più di un'applicazione, pertanto il link non deve essere specifico per l'applicazione.

  • Release

    Puoi aggiungere annotazioni o etichette, o entrambe, a una release utilizzando i flag --labels e --annotations nel comando gcloud deploy releases create. Le etichette e le annotazioni aggiunte a una release non vengono riportate come etichette o annotazioni negli implementazioni risultanti.

    Ad esempio, puoi utilizzare le annotazioni per includere un riferimento a una PR di Git, all'autore o all'hash SHA del commit di Git contenente le modifiche da eseguire. Per ulteriori dettagli, consulta la sezione Utilizzare le annotazioni per monitorare la provenienza della release.

  • Implementazioni

    Puoi aggiungere annotazioni ed etichette ai nuovi implementamenti specificando --labels o --annotations nel comando gcloud deploy releases promote.

    Puoi aggiungere annotazioni ed etichette al primo implementazione specificando --initial-rollout-labels o --initial-rollout-annotations nel comando gcloud deploy releases create.

    Ecco alcune cose che puoi fare utilizzando le annotazioni durante l'implementazione:

    • Crea un'annotazione contenente l'URL che rimanda ai risultati del test.
    • Crea un'annotazione con un numero di ticket pertinente da un sistema di gestione del flusso di lavoro.

Dove posso trovare le annotazioni di una risorsa?

Puoi visualizzare le annotazioni e le etichette per qualsiasi risorsa supportata utilizzando il comando describe della risorsa o visualizzando i metadati della risorsa nella console Google Cloud.

Dall'interfaccia alla gcloud CLI

Per visualizzare le annotazioni e le etichette di una risorsa dalla riga di comando, utilizza un comando describe sulla risorsa. L'esempio seguente mostra i dettagli di un target:

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

Il comando riportato sopra restituisce il seguente output:

 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'

Tieni presente che questo output include l'annotazione target_name.

Nella console Google Cloud

Per visualizzare le annotazioni e le etichette di qualsiasi risorsa Cloud Deploy che abbia questi metadati, visualizza i dettagli della risorsa nella console Google Cloud.

Ad esempio, di seguito sono riportati i dettagli della pipeline di importazione per una pipeline che include un'annotazione:

Dettagli della pipeline di distribuzione nella console Google Cloud

Di seguito sono riportati i dettagli di una release:

Dettagli della release nella console Google Cloud

Etichette automatiche di Cloud Deploy

Per impostazione predefinita, Cloud Deploy aggiunge le seguenti etichette ai manifest visualizzati:

  • app.kubernetes.io/managed-by:

    Un'etichetta standard per indicare gli strumenti di deployment. Questo valore è sempre impostato su google-cloud-deploy per identificare l'origine del carico di lavoro.

  • deploy.cloud.google.com/location:

    La posizione della pipeline di distribuzione di cui è stato eseguito il deployment, ad esempio us-central1.

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

    L'ID progetto della pipeline di importazione di cui è stato eseguito il deployment.

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

    L'ID risorsa della pipeline di importazione utilizzata. Questo valore viene preso dall'istantanea della release.

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

    L'ID risorsa della release di cui è stato eseguito il deployment.

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

    L'ID risorsa della destinazione di deployment. Questo valore viene preso dall'istantanea della release.

Esempio di utilizzo

Un esempio di utilizzo di queste etichette applicate automaticamente è creare un grafico in Google Cloud Observability che aggrega una metrica del contenitore in base alle proprietà 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

Puoi utilizzarlo anche con le metriche personalizzate. Ad esempio, se PodMonitor è configurato con un'etichetta che corrisponde a app.kubernetes.io/managed-by: google-cloud-deploy. Puoi quindi utilizzare una query per definire un grafico per le metriche personalizzate:

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

Disattivare le etichette automatiche

La tua organizzazione potrebbe non consentire queste etichette automatiche per motivi normativi, di conformità o altri. A questo scopo, il servizio di criteri dell'organizzazione offre una limitazione che controlla se queste etichette vengono applicate o meno.

Per impedire a Cloud Deploy di aggiungere automaticamente le etichette ai manifest visualizzati, imposta il vincolo del servizio di criteri dell'organizzazioneclouddeploy.disableServiceLabelGeneration da applicare. L'applicazione di questo vincolo non impedisce di specificare manualmente le etichette né rimuove le etichette dalle release esistenti.

Per ulteriori informazioni sull'attivazione dei vincoli, consulta Utilizzo dei vincoli booleani nei criteri dell'organizzazione.