Como usar anotações e rótulos com o Cloud Deploy

É possível anexar anotações e rótulos aos recursos do Cloud Deploy. Eles não são obrigatórios.

Este documento lista os recursos aos quais você pode anexar rótulos e anotações e descreve como você pode usá-los e onde pode visualizá-los.

Sobre anotações e rótulos

Anotações são pares de chave-valor de texto em formato livre. É possível usá-las para anexar informações arbitrárias associadas ao recurso.

Você pode usar rótulos para organizar recursos. Por exemplo, é possível aplicar a lógica com base na seleção de rótulos.

Assim como as anotações, os rótulos são pares de chave-valor. No entanto, eles precisam estar em conformidade com as seguintes limitações:

  • Um recurso do Cloud Deploy não pode ter mais de 64 rótulos.

  • As chaves e os valores precisam ter 128 bytes ou menos.

  • As chaves e valores contêm apenas letras minúsculas, caracteres numéricos, sublinhados e traços.

  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

  • Todos os caracteres precisam usar a codificação UTF-8. Caracteres internacionais são permitidos.

A sinalização --labels (por exemplo, em gcloud deploy releases create) pode receber uma lista de pares de chave-valor.

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

Consulte a documentação da API Cloud Deploy para mais detalhes.

Como adicionar anotações e rótulos aos recursos do Cloud Deploy

É possível adicionar anotações e rótulos aos seguintes recursos do 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: []

  • Destinos

    Adicione anotações e rótulos aos destinos no YAML de configuração de destino.

    Por exemplo, é possível incluir um link para mais informações sobre o monitoramento de terceiros para o aplicativo. No entanto, se o destino for compartilhado, lembre-se de que ele pode ser usado para mais de um aplicativo. Portanto, o link não pode ser específico do aplicativo.

  • Versões

    É possível adicionar anotações ou rótulos, ou ambos, a uma versão usando as sinalizações --labels e --annotations no comando gcloud deploy releases create. Rótulos e anotações que você adiciona a uma versão não são considerados rótulos ou anotações em lançamentos resultantes.

    Por exemplo, é possível usar anotações para incluir uma referência a um PR de autor, autor ou hash SHA da confirmação do Git que contém as alterações a serem implantadas. Consulte Como usar anotações para rastrear a procedência da versão para saber mais.

  • Lançamentos

    É possível adicionar anotações e rótulos a novos lançamentos especificando --labels ou --annotations no comando gcloud deploy releases promote.

    É possível adicionar anotações e rótulos ao primeiro lançamento especificando --initial-rollout-labels ou --initial-rollout-annotations no comando gcloud deploy releases create.

    Algumas coisas que você pode fazer usando anotações em um lançamento:

    • Crie uma anotação contendo o URL que aponta para os resultados do teste.
    • Crie uma anotação com o número de um tíquete relevante de um sistema de gerenciamento de fluxo de trabalho.

Onde encontro as anotações de um recurso?

É possível visualizar anotações e rótulos para qualquer recurso compatível usando o comando describe do recurso ou visualizando os metadados do recurso no console doGoogle Cloud .

Na CLI gcloud

Para visualizar as anotações e os rótulos de um recurso na linha de comando, use um comando describe nesse recurso. O exemplo a seguir mostra os detalhes de uma meta:

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

O comando acima retorna esta saída:

 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'

Observe que essa saída inclui a anotação target_name.

No console do Google Cloud

Para visualizar anotações e rótulos de qualquer recurso do Cloud Deploy que tenha esses metadados, consulte os detalhes desse recurso no console Google Cloud .

Por exemplo, veja os detalhes do pipeline de entrega de um pipeline que inclui uma anotação:

Detalhes do pipeline de entrega no console Google Cloud

Veja os detalhes de uma versão:

Detalhes da versão no console Google Cloud

Rótulos automáticos do Cloud Deploy

Por padrão, o Cloud Deploy adiciona os seguintes rótulos aos manifestos renderizados:

  • app.kubernetes.io/managed-by:

    Um rótulo padrão para indicar as ferramentas de implantação. Ele é sempre definido como google-cloud-deploy para identificar a origem da carga de trabalho.

  • deploy.cloud.google.com/location:

    O local do pipeline de entrega implantado, por exemplo, us-central1.

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

    O ID do projeto do pipeline de entrega implantado.

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

    O ID do recurso do pipeline de entrega usado. Ele é retirado do snapshot de versão.

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

    O ID do recurso da versão implantada.

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

    O ID do recurso do destino de implantação. Ele é retirado do snapshot de versão.

Exemplo de uso

Um exemplo de uso desses rótulos aplicados automaticamente é criar um gráfico no Google Cloud Observability que agrega uma métrica de contêiner por propriedades do 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

Também é possível usá-lo com métricas personalizadas. Por exemplo, se o PodMonitor estiver configurado com um rótulo para corresponder a app.kubernetes.io/managed-by: google-cloud-deploy. Em seguida, use uma consulta para definir um gráfico para métricas personalizadas:

fetch k8s_container
| metric workload.googleapis.com/example_requests_total
| filter metadata.user_labels.c'app.kubernetes.io/managed-by' = "google-cloud-deploy"
|