Crie e faça a gestão de etiquetas de clusters e node pools

Esta página oferece uma vista geral das etiquetas de cluster e das etiquetas de node pool no Google Kubernetes Engine (GKE).

Etiquetas do cluster e do node pool do GKE, e etiquetas do Kubernetes

As etiquetas do cluster e do node pool do GKE são diferentes das etiquetas no Kubernetes. Os dois sistemas de etiquetagem funcionam de forma independente e não herdam nem partilham etiquetas.

As etiquetas de clusters e conjuntos de nós do GKE são metadados arbitrários que são anexados aos seus recursos. Pode usar estas etiquetas para acompanhar informações sobre a faturação e a utilização.

Em separado, no Kubernetes, o sistema usa etiquetas internamente para associar componentes e recursos do cluster (por exemplo, pods e nós) entre si e gerir os ciclos de vida dos recursos. Pode editar etiquetas do Kubernetes com a API Kubernetes. Também pode usar a API GKE para editar etiquetas do Kubernetes nos seus nós com a criação do cluster ou com uma atualização do cluster. Para mais informações, consulte o artigo Atualize as etiquetas e os defeitos dos nós do Kubernetes para node pools.

O que são etiquetas de clusters?

Uma etiqueta de cluster é um par de chave-valor que pode atribuir a Google Cloud clusters. Ajudam a organizar estes recursos e a gerir os custos em grande escala, com a granularidade de que precisa. Pode anexar uma etiqueta a cada recurso e, em seguida, filtrar os recursos com base nas respetivas etiquetas. As informações sobre as etiquetas são encaminhadas para o sistema de faturação que lhe permite discriminar os encargos faturados por etiqueta. Com os relatórios de faturação integrados, pode filtrar e agrupar os custos por etiquetas de recursos. Também pode usar etiquetas para consultar exportações de dados de faturação.

Requisitos para etiquetas de clusters

As etiquetas de cluster aplicadas a um recurso têm de cumprir os seguintes requisitos:

  • Cada recurso pode ter até 64 etiquetas de cluster.
  • Cada etiqueta de cluster tem de ser um par chave-valor.
  • As chaves têm um comprimento mínimo de 1 caráter e um comprimento máximo de 63 carateres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 carateres.
  • As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. Todos os carateres têm de usar a codificação UTF-8, e são permitidos carateres internacionais. As chaves têm de começar com uma letra minúscula ou um caráter internacional.
  • A parte da chave de uma etiqueta de cluster tem de ser exclusiva num único recurso. No entanto, pode usar a mesma chave com vários recursos.

Estes limites aplicam-se à chave e ao valor de cada etiqueta de cluster, bem como aos recursos Google Cloud individuais que têm etiquetas de cluster. Não existe um limite para o número de etiquetas de cluster que pode aplicar a todos os recursos num projeto.

Utilizações comuns de etiquetas de clusters

Seguem-se alguns exemplos de utilização comuns para etiquetas de clusters:

  • Etiquetas de equipa ou centro de custos: adicione etiquetas com base na equipa ou no centro de custos para distinguir clusters pertencentes a diferentes equipas (por exemplo, team:research e team:analytics). Pode usar este tipo de etiqueta para contabilidade de custos ou orçamentação.

  • Etiquetas de clusters de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

  • Etiquetas de ambiente ou cluster de fase: por exemplo, environment:production e environment:test.

  • Etiquetas de clusters de estados: por exemplo, state:active, state:readytodelete e state:archive.

  • Etiquetas de cluster de propriedade: usadas para identificar as equipas responsáveis pelas operações, por exemplo: team:shopping-cart.

Não recomendamos a criação de um grande número de etiquetas únicas, como para carimbos de data/hora ou valores individuais para cada chamada da API. O problema desta abordagem é que, quando os valores mudam frequentemente ou com chaves que desorganizam o catálogo, torna-se difícil filtrar e criar relatórios sobre os recursos de forma eficaz.

Etiquetas e marcadores

As etiquetas podem ser usadas como anotações consultáveis para recursos, mas não podem ser usadas para definir condições nas políticas. As etiquetas oferecem uma forma de permitir ou negar condicionalmente políticas com base no facto de um recurso ter uma etiqueta específica, oferecendo um controlo detalhado sobre as políticas. Para mais informações, consulte a Vista geral das etiquetas.

Etiquetas aplicadas automaticamente

O GKE aplica automaticamente várias etiquetas aos recursos do cluster.

Por exemplo, o GKE aplica etiquetas a instâncias do Compute Engine, discos persistentes e aceleradores (TPU).

A tabela seguinte indica as etiquetas que o GKE aplica automaticamente aos recursos:

Etiqueta Recursos aplicados
goog-gke-node Instância de VM do Compute Engine subjacente a um nó do GKE.
goog-gke-volume Disco persistente do Compute Engine associado a uma instância de VM subjacente a um nó do GKE.
goog-gke-tpu Cloud TPU no GKE.
goog-k8s-cluster-name Instância de VM do Compute Engine e discos persistentes anexados a uma instância de VM subjacente a um nó do GKE.
goog-k8s-cluster-location Instância de VM do Compute Engine e discos persistentes anexados a uma instância de VM subjacente a um nó do GKE.
goog-k8s-node-pool-name Instâncias de VM do Compute Engine e respetivos discos de arranque subjacentes a um nó do GKE.
goog-fleet-project Instância de VM do Compute Engine e discos persistentes anexados a uma instância de VM subjacente a um nó do GKE, se o cluster estiver registado numa frota.
goog-gke-accelerator-type Node pool do GKE.
goog-gke-tpu-node-pool-type Node pool do GKE.
goog-gke-node-pool-provisioning-model Node pool do GKE.

Não edite nem elimine etiquetas reservadas. Quaisquer alterações que fizer às etiquetas reservadas são reconciliadas automaticamente.

Propagação de etiquetas

No GKE, pode aplicar etiquetas a clusters e a node pools do modo padrão. Quando etiqueta um cluster, a etiqueta propaga-se a todos os recursos individuais do cluster, como nós, instâncias e discos persistentes. Quando etiqueta um conjunto de nós, a etiqueta é propagada a todos os recursos individuais do conjunto de nós, como instâncias e discos persistentes. Nos clusters padrão, se as etiquetas do cluster entrarem em conflito com as etiquetas do node pool, por exemplo, quando a chave da etiqueta é a mesma, mas o valor é diferente, as etiquetas do node pool substituem as etiquetas do cluster.

Todas as etiquetas que aplicar aos seus clusters ou conjuntos de nós são propagadas através de um processo em segundo plano executado de hora a hora. Pode demorar até uma hora para que uma etiqueta seja apresentada em todos os recursos associados a um determinado cluster. Além disso, as etiquetas só são propagadas para instâncias do Compute Engine e Persistent Disks associados a instâncias do Compute Engine. Outros recursos, como cargas de trabalho, regras de encaminhamento, endereços IP e discos persistentes não associados, não são etiquetados.

Para clusters padrão, quando as etiquetas de clusters e conjuntos de nós são aplicadas aos recursos do Compute Engine, pode alterar manualmente as etiquetas de recursos sem que essas alterações sejam reconciliadas pelo GKE. Nos clusters do Autopilot, não pode modificar manualmente as etiquetas nos recursos do Compute Engine porque o GKE gere os nós por si. No entanto, recomendamos que faça a gestão destas etiquetas através do GKE. As etiquetas existentes nesses recursos do Compute Engine não são removidas pelo GKE, a menos que entrem em conflito com as etiquetas aplicadas automaticamente.

Antes de começar

Antes de começar, certifique-se de que realizou as seguintes tarefas:

  • Ative a API Google Kubernetes Engine.
    • Ative a API Google Kubernetes Engine
  • Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize-a. Se instalou anteriormente a CLI gcloud, execute gcloud components update para obter a versão mais recente.

Obtenha uma impressão digital de etiqueta para pedidos de API

Pode ignorar este passo se usar a Google Cloud consola ou a CLI gcloud.

Quando atualiza ou adiciona etiquetas de clusters através da API GKE, tem de fornecer a impressão digital da etiqueta de cluster mais recente com o seu pedido para evitar conflitos com outros pedidos.

Para obter a impressão digital da etiqueta do cluster mais recente, execute um pedido GET para o cluster adequado. Por exemplo:

GET https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster

O resultado é semelhante ao seguinte:

200 OK

{

 "name": "mycluster",
 "description": "production-cluster",
 "initialNodeCount": 3,
 ...
 "resourceLabels": {
    "environment": "production",
    ...
  },
  "labelFingerprint": "p1ty_9HoBk0="
}

Neste resultado, a propriedade labelFingerprint é a impressão digital da etiqueta do cluster.

Crie um cluster com etiquetas

Pode criar clusters do Autopilot e Standard com etiquetas através da CLI gcloud, da Google Cloud consola, da API GKE ou do Terraform.

gcloud

Execute o seguinte comando para criar um cluster do Autopilot com etiquetas:

gcloud container clusters create-auto CLUSTER_NAME \
    --labels=KEY=VALUE

Em alternativa, execute o seguinte comando para criar um cluster padrão com etiquetas:

gcloud container clusters create CLUSTER_NAME \
    --labels=KEY=VALUE

Substitua o seguinte:

  • CLUSTER_NAME: o nome do cluster.
  • KEY: a chave do par de chave-valor da etiqueta.
  • VALUE: o valor do par de chave-valor da etiqueta.

Consola

Para adicionar etiquetas ao criar o cluster, faça o seguinte:

  1. Na Google Cloud consola, aceda à página Criar um cluster do Autopilot.

    Aceda a Crie um cluster do Autopilot

    Também pode concluir esta tarefa criando um cluster padrão.

  2. Configure o cluster.

  3. No painel de navegação, em Cluster, clique em Metadados.

  4. Clique em Adicionar etiqueta.

  5. Adicione etiquetas.

  6. Clique em Criar.

API

Para incluir uma etiqueta quando criar o cluster, especifique o objeto resourceLabels no objeto cluster que fornece a projects.zones.clusters.create.

Terraform

Para criar um cluster do Autopilot com etiquetas através do Terraform, consulte o seguinte exemplo:

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-labels"
  location = "us-central1"

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }
}

Para criar um cluster padrão com etiquetas através do Terraform, consulte o seguinte exemplo:

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-central1"
  initial_node_count = 2

  resource_labels = {
    foo = "bar"
  }
}

Para saber mais sobre a utilização do Terraform, consulte o artigo Compatibilidade do Terraform com o GKE.

Adicione ou atualize etiquetas para clusters existentes

Pode adicionar ou atualizar etiquetas para clusters existentes do Autopilot e Standard através da CLI gcloud, da Google Cloud consola ou da API GKE.

gcloud

Execute o seguinte comando:

gcloud container clusters update CLUSTER_NAME \
    --location =CONTROL_PLANE_LOCATION \
    --update-labels=KEY=VALUE

Substitua o seguinte:

  • CLUSTER_NAME: o nome do cluster.
  • CONTROL_PLANE_LOCATION: a localização do Compute Engine do plano de controlo do seu cluster. Indique uma região para clusters regionais ou uma zona para clusters zonais.
  • KEY: a chave do par de chave-valor da etiqueta.
  • VALUE: o valor do par de chave-valor da etiqueta.

A atualização da etiqueta substitui as etiquetas existentes no cluster. Se o cluster tiver etiquetas existentes que quer manter, tem de incluir essas etiquetas juntamente com as novas etiquetas que quer adicionar.

Consola

Para adicionar ou atualizar etiquetas, faça o seguinte:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na página Detalhes do cluster, selecione as caixas de verificação de um ou mais clusters que quer modificar.

  3. Clique em Etiquetas.

  4. Adicione ou atualize etiquetas.

  5. Clique em Guardar.

API

Faça um pedido POSTao método resourceLabels do cluster com a impressão digital mais recente e uma lista completa das etiquetas a aplicar.

Tal como acontece com os metadados e as etiquetas, se o cluster tiver etiquetas existentes que quer manter, tem de incluir essas etiquetas no pedido juntamente com as novas etiquetas que quer adicionar.

Por exemplo, o fragmento seguinte faz um pedido ao método resourceLabels:

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": {
  "environment": "production",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Remova etiquetas de clusters

Pode remover etiquetas de clusters do Autopilot e Standard através da CLI gcloud, da Google Cloud consola ou da API GKE.

gcloud

Execute o comando update com a flag --remove-labels:

gcloud container clusters update CLUSTER_NAME \
    --remove-labels=KEYS

Substitua o seguinte:

  • CLUSTER_NAME: o nome do cluster.
  • KEYS: uma lista separada por vírgulas de chaves para os marcadores que quer remover.

Consola

Para remover etiquetas, faça o seguinte:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na lista de clusters, selecione as caixas de verificação de um ou mais clusters que quer modificar.

  3. Clique em Etiquetas.

  4. Clique em Eliminar item junto ao campo Valor das etiquetas que quer eliminar.

  5. Clique em Guardar.

API

Faça um pedido POST ao método resourceLabels para o cluster adequado. Indique o labelsFingerprint atual e uma lista de etiquetas vazia para remover todas as etiquetas ou indique uma lista de etiquetas que quer manter, omitindo as etiquetas que quer remover. Por exemplo:

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

Crie um node pool padrão com etiquetas

Pode criar um conjunto de nós com etiquetas num cluster padrão através da CLI gcloud, da Google Cloud consola ou da API GKE.

gcloud

Execute o seguinte comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --labels=KEY=VALUE

Substitua o seguinte:

  • NODE_POOL_NAME: o nome do node pool.
  • CLUSTER_NAME: o nome do cluster.
  • CONTROL_PLANE_LOCATION: a localização do Compute Engine do plano de controlo do seu cluster. Indique uma região para clusters regionais ou uma zona para clusters zonais.
  • KEY: a chave do par de chave-valor da etiqueta.
  • VALUE: o valor do par de chave-valor da etiqueta.

API

Para incluir uma etiqueta quando criar o conjunto de nós, especifique o objeto resourceLabels no objeto do conjunto de nós que fornece a projects.zones.clusters.nodePools.create.

Consola

Para adicionar etiquetas ao novo conjunto de nós, faça o seguinte:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na página Detalhes do cluster, clique no nome do cluster que quer modificar.

  3. Clique em Adicionar conjunto de nós.

  4. Configure o novo node pool.

  5. No painel de navegação, clique em Metadados.

  6. Clique em Adicionar etiqueta.

  7. Adicione etiquetas.

  8. Clique em Criar.

Adicione ou atualize etiquetas para um conjunto de nós existente

Pode adicionar ou atualizar etiquetas para pools de nós existentes através da CLI gcloud, da Google Cloud consola ou da API GKE.

Esta alteração requer a recriação dos nós, o que pode causar interrupções nas cargas de trabalho em execução. Para ver detalhes sobre esta alteração específica, procure a linha correspondente na tabela alterações manuais que recriam os nós através de uma estratégia de atualização de nós sem respeitar as políticas de manutenção. Para saber mais sobre as atualizações de nós, consulte o artigo Planeamento de interrupções de atualizações de nós.

gcloud

Execute o seguinte comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --labels=KEY=VALUE

Substitua o seguinte:

  • NODE_POOL_NAME: o nome do node pool
  • CLUSTER_NAME: o nome do cluster.
  • CONTROL_PLANE_LOCATION: a localização do Compute Engine do plano de controlo do seu cluster. Indique uma região para clusters regionais ou uma zona para clusters zonais.
  • KEY: a chave do par de chave-valor da etiqueta.
  • VALUE: o valor do par de chave-valor da etiqueta.

A atualização de etiquetas substitui quaisquer etiquetas existentes no node pool. Se o conjunto de nós tiver etiquetas existentes que quer manter, tem de incluir essas etiquetas juntamente com as novas etiquetas que quer adicionar.

API

Para incluir uma etiqueta quando modificar o conjunto de nós, especifique o objeto resourceLabels no objeto do conjunto de nós que fornece a projects.zones.clusters.nodePools.update.

Consola

Para adicionar ou atualizar etiquetas, faça o seguinte:

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que contém o conjunto de nós que quer modificar.

  3. Na secção Conjuntos de nós, clique no nome do conjunto de nós que quer modificar.

  4. Clique em Editar

  5. Na secção Etiquetas, adicione ou atualize etiquetas.

  6. Clique em Guardar.

Remova etiquetas de node pool

Pode remover etiquetas de conjuntos de nós através da CLI gcloud, da Google Cloud consola ou da API GKE.

gcloud

Execute o seguinte comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --labels=KEY=VALUE

Substitua o seguinte:

  • NODE_POOL_NAME: o nome do node pool.
  • CLUSTER_NAME: o nome do cluster.
  • CONTROL_PLANE_LOCATION: a localização do Compute Engine do plano de controlo do seu cluster. Indique uma região para clusters regionais ou uma zona para clusters zonais.
  • KEY: a chave do par de chave-valor da etiqueta.
  • VALUE: o valor do par de chave-valor da etiqueta.

A atualização de etiquetas substitui quaisquer etiquetas existentes no node pool. Se o conjunto de nós tiver etiquetas existentes que quer manter, tem de excluir todas as etiquetas que quer remover. Se quiser remover todas as etiquetas, use --labels= sem pares de chave-valor.

API

Para incluir uma etiqueta quando modificar o conjunto de nós, especifique o objeto resourceLabels no objeto do conjunto de nós que fornece a projects.zones.clusters.nodePools.update. Forneça uma lista vazia de etiquetas para remover todas as etiquetas ou forneça uma lista de etiquetas que quer manter. Omita as etiquetas que quer remover.

Consola

Para remover etiquetas de um conjunto de nós, faça o seguinte

  1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

    Aceda ao Google Kubernetes Engine

  2. Na lista de clusters, clique no nome do cluster que contém o conjunto de nós que quer modificar.

  3. Na secção Conjuntos de nós, clique no nome do conjunto de nós que quer modificar.

  4. Clique em Eliminar item junto ao campo Valor para as etiquetas que quer eliminar.

  5. Clique em Guardar.

O que se segue?

Leia a vista geral do GKE.