Usar anotações e etiquetas com o Cloud Deploy

Pode anexar anotações e etiquetas aos seus recursos do Cloud Deploy. Não são obrigatórios.

Este documento lista os recursos aos quais pode anexar etiquetas e anotações, e descreve como pode usá-los e onde os pode ver.

Acerca das anotações e etiquetas

As anotações são pares de chave-valor de texto de forma livre. Pode usá-los para anexar informações arbitrárias associadas ao recurso.

Pode usar etiquetas para organizar recursos. Por exemplo, pode aplicar lógica com base na seleção de etiquetas.

Tal como as anotações, as etiquetas são pares de chave-valor. No entanto, têm de estar em conformidade com as seguintes limitações:

• Um recurso do Cloud Deploy não pode ter mais de 64 etiquetas.

• As chaves e os valores têm de ter, no máximo, 128 bytes.

• As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões.

• As chaves têm de começar com uma letra minúscula ou um caráter internacional.

• Todos os carateres têm de usar a codificação UTF-8. São permitidos carateres internacionais.

A flag --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.

Adicionar anotações e etiquetas a recursos do Cloud Deploy

Pode adicionar anotações e etiquetas aos seguintes recursos do Cloud Deploy:

• Pipelines de entrega

  Para pipelines de entrega, adiciona anotações e etiquetas ao ficheiro 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 etiquetas a alvos no YAML de configuração de alvos.

  Por exemplo, pode incluir um link para mais informações sobre a monitorização de terceiros para a sua aplicação. No entanto, se o destino for partilhado, lembre-se de que pode ser usado para mais do que uma aplicação, pelo que o link não deve ser específico da aplicação.

• Versões

  Pode adicionar anotações ou etiquetas, ou ambas, a um lançamento através das flags --labels e --annotations no comando gcloud deploy releases create. As etiquetas e as anotações que adiciona a um lançamento não são transferidas como etiquetas nem anotações para as implementações resultantes.

  Por exemplo, pode usar anotações para incluir uma referência a um PR do Git, ao autor ou ao hash SHA da consolidação do Git que contém as alterações a implementar. Consulte o artigo Usar anotações para acompanhar a proveniência do lançamento para mais detalhes.

• Implementações

  Pode adicionar anotações e etiquetas a novas implementações especificando --labels ou --annotations no comando gcloud deploy releases promote.

  Pode adicionar anotações e etiquetas à primeira implementação especificando --initial-rollout-labels ou --initial-rollout-annotations no comando gcloud deploy releases create.

  Seguem-se algumas ações que pode realizar com anotações numa implementação:

  • Crie uma anotação que contenha o URL que aponta para os resultados dos testes.
  • Crie uma anotação com um número de pedido relevante a partir de um sistema de gestão de fluxo de trabalho.

Nota: as etiquetas e as anotações adicionadas aos recursos do Cloud Deploy são aplicadas apenas a esses recursos. Não são aplicadas transitivamente aos recursos implementados.

Onde posso encontrar as anotações de um recurso?

Pode ver anotações e etiquetas para qualquer recurso suportado através do comando describe do recurso ou ao ver os metadados do recurso na consolaGoogle Cloud .

A partir da CLI gcloud

Para ver as anotações e as etiquetas de um recurso a partir da linha de comandos, use um comando describe nesse recurso. O exemplo seguinte mostra os detalhes de um alvo:

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

O comando acima devolve o seguinte resultado:

 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'

Repare que esta saída inclui a anotação target_name.

Na Google Cloud consola

Para ver anotações e etiquetas de qualquer recurso do Cloud Deploy que tenha esses metadados, veja os detalhes desse recurso na Google Cloud consola.

Por exemplo, seguem-se os detalhes do pipeline de fornecimento de um pipeline que inclui uma anotação:

Seguem-se os detalhes de um lançamento:

Etiquetas automáticas do Cloud Deploy

Por predefinição, o Cloud Deploy adiciona as seguintes etiquetas aos manifestos renderizados:

• app.kubernetes.io/managed-by:

  Uma etiqueta padrão para indicar ferramentas de implementação. Este valor está sempre definido como google-cloud-deploy para identificar a origem da carga de trabalho.

• deploy.cloud.google.com/location:

  A localização do pipeline de entrega implementado, por exemplo, us-central1.

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

  O ID do projeto do pipeline de fornecimento implementado.

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

  O ID do recurso do pipeline de entrega usado. Esta informação é obtida a partir do instantâneo de lançamento.

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

  O ID do recurso da versão implementada.

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

  O ID do recurso do destino de implementação. Esta informação é obtida a partir do instantâneo de lançamento.

Exemplo de utilização

Um exemplo de utilização destas etiquetas aplicadas automaticamente seria criar um gráfico no Google Cloud Observability que agregue uma métrica de contentor 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 pode usar esta opção com métricas personalizadas. Por exemplo, se o PodMonitor estiver configurado com uma etiqueta para corresponder a app.kubernetes.io/managed-by: google-cloud-deploy. Em seguida, pode usar 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

Desativar etiquetas automáticas

A sua organização pode não permitir estas etiquetas automáticas por motivos regulamentares, de conformidade ou outros. Para suportar esta funcionalidade, o serviço de políticas da organização oferece uma restrição que controla se estas etiquetas são aplicadas ou não.

Para impedir que o Cloud Deploy adicione automaticamente etiquetas aos manifestos renderizados, defina a restrição do serviço de políticas da organização clouddeploy.disableServiceLabelGeneration para ser aplicada. A aplicação desta restrição não impede que especifique manualmente etiquetas, nem remove etiquetas de lançamentos existentes.

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