Utilizzo di annotazioni ed etichette con Cloud Deploy

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

Questo documento elenca le risorse a cui puoi allegare etichette e annotazioni e descrive come puoi utilizzarle e dove puoi visualizzarle.

Informazioni su annotazioni ed etichette

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

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

Come nel caso delle annotazioni, anche 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 che 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 di Cloud Deploy:

• Pipeline di distribuzione

  Per le pipeline di distribuzione, aggiungi annotazioni ed etichette al file di configurazione YAML.

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 il target è condiviso, ricorda che potrebbe essere utilizzato per più di un'applicazione, quindi il link non deve essere specifico per l'applicazione.

• Release

  Puoi aggiungere annotazioni e/o etichette a una release utilizzando i flag --labels e --annotations nel comando gcloud deploy releases create. Le etichette e le annotazioni che aggiungi a una release non vengono riportate come etichette o annotazioni sulle implementazioni risultanti.

  Ad esempio, puoi utilizzare le annotazioni per includere un riferimento a un PR, un autore o un hash SHA di Git del commit Git contenente le modifiche di cui eseguire il deployment. Per ulteriori dettagli, consulta la sezione Utilizzo delle annotazioni per monitorare la provenienza della release.

• Implementazioni

  Puoi aggiungere annotazioni ed etichette alle nuove implementazioni specificando --labels o --annotations nel comando gcloud deploy releases promote.

  L'unico modo per aggiungere annotazioni ed etichette al primo lancio è creare un'implementazione utilizzando l'API Cloud Deploy e includere le annotazioni o le etichette nella risorsa rollout.

  Ecco alcune operazioni che puoi eseguire utilizzando le annotazioni su un'implementazione:

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

Nota: le etichette e le annotazioni aggiunte alle risorse Cloud Deploy vengono applicate solo a queste risorse. Non vengono applicati in modo transitivo alle risorse di cui è stato eseguito il deployment.

Dove posso trovare le annotazioni di una risorsa?

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

Da 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 precedente 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'

Nota che questo output include l'annotazione target_name.

Nella console Google Cloud

Per visualizzare annotazioni ed etichette per qualsiasi risorsa Cloud Deploy che include questi metadati, visualizza i dettagli della risorsa nella console Google Cloud.

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

Ecco i dettagli di una nuova uscita:

Etichette automatiche di Cloud Deploy

Per impostazione predefinita, Cloud Deploy aggiunge le seguenti etichette ai manifest sottoposti a rendering:

• app.kubernetes.io/managed-by:

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

• deploy.cloud.google.com/location:

  La località 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 distribuzione di cui è stato eseguito il deployment.

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

  L'ID risorsa della pipeline di distribuzione utilizzata. Viene recuperato dallo 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 del deployment. Viene recuperato dallo istantanea della release.

Esempio di utilizzo

Un esempio di utilizzo di queste etichette applicate automaticamente potrebbe essere la creazione di un grafico all'interno dell'Osservabilità di Google Cloud che aggrega una metrica container 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 utilizzare questa opzione anche con le metriche personalizzate. Ad esempio, se PodMonitor è configurato con un'etichetta corrispondente a app.kubernetes.io/managed-by: google-cloud-deploy, Poi potresti utilizzare una query per definire un grafico per 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

Disattivazione delle etichette automatiche

La tua organizzazione potrebbe non consentire queste etichette automatiche per motivi normativi, di conformità o di altro tipo. A questo scopo, il servizio Criteri dell'organizzazione offre un vincolo che controlla se vengono applicate o meno queste etichette.

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

Per saperne di più sull'abilitazione dei vincoli, consulta Utilizzare i vincoli booleani nei criteri dell'organizzazione.