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:

• Pipelines de entrega

  Nos pipelines de entrega, adicione anotações e rótulos ao arquivo de configuração YAML.

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.

Observação: os rótulos e as anotações adicionados aos recursos do Cloud Deploy são aplicados apenas a esses recursos. Elas não são aplicadas transitivamente a recursos implantados.

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 do Google 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 conferir anotações e rótulos de qualquer recurso do Cloud Deploy que tenha esses metadados, acesse os detalhes desse recurso no console do Google Cloud.

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

Veja os detalhes de uma versão:

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 da 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 na Observabilidade do Google Cloud 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"
| 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

Como desativar rótulos automáticos

Sua organização pode proibir esses rótulos automáticos por motivos regulamentares, de conformidade ou outros. Para isso, o Serviço de políticas da organização oferece uma restrição que controla se esses rótulos são aplicados ou não.

Para impedir que o Cloud Deploy adicione marcadores automaticamente aos manifestos renderizados, defina a restrição clouddeploy.disableServiceLabelGeneration do serviço de políticas da organização para ser aplicada. Aplicar essa restrição não impede que você especifique manualmente os rótulos, nem remove rótulos de versões existentes.

Consulte Como usar restrições booleanas na política da organização para mais informações sobre como ativar restrições.