Criar e gerenciar identificadores de clusters e de pools de nós

Esta página fornece uma visão geral dos identificadores de cluster e de pools de nós no Google Kubernetes Engine (GKE).

Rótulos de cluster e do pool de nós do GKE e rótulos do Kubernetes

Os rótulos de cluster do GKE e do pool de nós são diferentes dos rótulos do Kubernetes. Os dois sistemas de rotulagem funcionam de forma independente e não herdam nem compartilham rótulos.

Os rótulos de cluster do GKE e do pool de nós são metadados arbitrários anexados aos recursos que podem ser usados para rastrear informações de uso e faturamento.

Separadamente, no Kubernetes, o sistema usa rótulos internamente para associar componentes e recursos do cluster (por exemplo, pods e nós) entre si e gerenciar ciclos de vida de recursos. É possível editar os rótulos do Kubernetes com a API Kubernetes. Também é possível usar a API GKE para editar rótulos do Kubernetes nos nós com a criação de cluster ou com uma atualização de cluster.

O que são rótulos de cluster?

Um rótulo de cluster é um par de chave-valor que pode ser atribuído aos clusters do Google Cloud. Eles ajudam a organizar esses recursos e gerenciar seus custos em escala, com a granularidade necessária. É possível anexar um rótulo a cada recurso e filtrar os recursos com base nesses rótulos. As informações sobre rótulos são encaminhadas ao sistema de faturamento, que permite detalhar as cobranças faturadas por rótulo. Com os relatórios de faturamento integrados, é possível filtrar e agrupar custos por rótulos de recursos. Também é possível usar rótulos para consultar as exportações de dados de faturamento.

Requisitos para rótulos de cluster

Os rótulos de cluster aplicados a um recurso precisam atender aos seguintes requisitos:

Cada recurso pode ter até 64 rótulos de cluster.
Cada marcador de cluster precisa ser um par de chave-valor.
As chaves têm comprimento mínimo de um caractere e comprimento máximo de 63 caracteres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
As chaves e os valores contêm apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Todos os caracteres precisam usar a codificação UTF-8, e os caracteres internacionais são permitidos. As chaves precisam começar com uma letra minúscula ou um caractere internacional.
A parte principal de um rótulo de cluster precisa ser exclusiva a um único recurso. No entanto, é possível usar a mesma chave com vários recursos.

Esses limites se aplicam à chave e ao valor de cada rótulo de cluster e aos recursos individuais do Google Cloud que têm rótulos de cluster. Não há limite para o número de rótulos de cluster que podem ser aplicados a todos os recursos dentro de um projeto.

Usos comuns de rótulos de cluster

Veja a seguir alguns casos de uso comuns de marcadores de cluster:

Rótulos de cluster de centro de custo ou de equipe : adicione rótulos com base na equipe ou no centro de custo para distinguir clusters pertencentes a equipes diferentes, por exemplo, team:research e team:analytics. É possível usar esse tipo de rótulo para contabilidade de custo ou orçamento.
Rótulos de cluster de componente: por exemplo, component:redis, component:frontend, component:ingeste component:dashboard.
Rótulos de cluster de ambiente ou de cenário: por exemplo, environment:production e environment:test.
Identificadores de cluster de estado: por exemplo, state:active, state:readytodelete e state:archive.
Rótulos de cluster de propriedade: usados para identificar as equipes responsáveis pelas operações, por exemplo: team:shopping-cart.

Detalhamento de faturamento: use identificadores de pool de nós para detalhar as cobranças faturadas por pool de nós. Para mais informações, consulte Acessar detalhamento de custos de cluster.

Não recomendamos a criação de um grande número de rótulos exclusivos, como os relacionados a carimbos de data/hora ou valores individuais, para todas as chamadas de API. O problema com essa abordagem é que, quando os valores mudam com frequência ou com chaves que desordenam o catálogo, isso dificulta a filtragem e a geração de relatórios sobre os recursos.

Rótulos e tags

Os rótulos podem ser usados como anotações de consulta para recursos, mas não podem ser usados para definir condições em políticas. Com as tags, é possível permitir ou negar políticas condicionalmente com base em um recurso ter ou não uma tag específica, fornecendo controle refinado sobre as políticas. Para mais informações, consulte a Visão geral das tags.

Rótulos aplicados automaticamente

O GKE aplica automaticamente vários identificadores aos recursos de cluster.

Por exemplo, o GKE aplica rótulos a instâncias do Compute Engine, discos permanentes e aceleradores (TPU).

A tabela a seguir lista os identificadores que o GKE aplica automaticamente aos recursos:

Identificador	Recursos aplicados
`goog-gke-node`	Instância de VM do Compute Engine subjacente a um nó do GKE.
`goog-gke-volume`	Disco permanente do Compute Engine anexado 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 permanentes 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 permanentes 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 os discos de inicialização subjacentes a um nó do GKE.
`goog-fleet-project`	Instância de VM do Compute Engine e discos permanentes anexados a uma instância de VM subjacente a um nó do GKE, se o cluster estiver registrado em uma frota.

Não edite ou exclua rótulos reservados. Todas as mudanças feitas nos rótulos reservados são reconciliadas automaticamente.

Propagação de rótulos

No GKE, é possível aplicar rótulos a clusters e a pools de nós do modo padrão. Ao rotular um cluster, o rótulo é propagado para todos os recursos individuais do cluster, como nós, instâncias e discos permanentes. Ao rotular um pool de nós, ele é propagado para todos os recursos individuais do pool de nós, como instâncias e discos permanentes. Em clusters padrão, se os rótulos do cluster entrarem em conflito com os rótulos do pool de nós, por exemplo, quando a chave do rótulo for a mesma, mas o valor for diferente, os rótulos do pool de nós vão substituir os rótulos do cluster.

Todos os rótulos aplicados a clusters ou pools de nós são propagados por um processo em segundo plano executado a cada hora. Isso significa que pode levar até uma hora para que um identificador apareça em todos os recursos associados ao cluster fornecido. Além disso, os identificadores são propagados somente para instâncias do Compute Engine e discos permanentes anexados a instâncias do Compute Engine. Outros recursos, como cargas de trabalho, regras de encaminhamento, endereços IP e discos permanentes não anexados, não são identificados.

Para clusters padrão, quando os rótulos de cluster e pool de nós são aplicados aos recursos do Compute Engine, é possível alterar manualmente os rótulos de recursos sem que essas alterações sejam reconciliadas pelo GKE. Nos clusters do Autopilot, não é possível modificar manualmente os rótulos nos recursos do Compute Engine porque o GKE gerencia os nós para você. No entanto, recomendamos gerenciar esses rótulos pelo GKE. Os rótulos atuais nesses recursos do Compute Engine não serão removidos pelo GKE, a menos que entrem em conflito com os rótulos aplicados automaticamente.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

Ativar a API Google Kubernetes Engine.

Ativar a API Google Kubernetes Engine

Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como: One of [--zone, --region] must be supplied: Please specify location.

Conseguir uma impressão digital de rótulo para solicitações da API

É possível pular essa etapa se você usa o console do Google Cloud ou a CLI gcloud.

Ao atualizar ou adicionar rótulos de cluster com a API do GKE, é necessário fornecer a impressão digital mais recente do rótulo de cluster na solicitação. Isso evita conflitos com outras solicitações.

Para receber a impressão digital mais recente do rótulo de cluster, execute uma solicitação GET no cluster apropriado. Exemplo:

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

O resultado será assim:

200 OK

{

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

Nessa saída, a propriedade labelFingerprint é a impressão digital do rótulo do cluster.

Criar um cluster com identificadores

É possível criar clusters do Autopilot e Standard com rótulos usando a gcloud CLI, o console do Google Cloud, a API GKE ou o Terraform.

gcloud

Execute o comando a seguir para criar um cluster do Autopilot com identificadores:

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

Ou execute o seguinte comando para criar um cluster padrão com rótulos:

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

Substitua:

CLUSTER_NAME: o nome do cluster.
KEY: a chave do par de chave-valor do rótulo.
VALUE: o valor do par de chave-valor do rótulo.

Console

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

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Clique em Criar.
Em Autopilot ou Standard, clique em Configurar.
Configure seu cluster.
No painel de navegação, em Cluster, clique em Metadados.
Clique em Adicionar rótulo.
Adicionar rótulos.
Clique em Criar.

API

Para incluir um rótulo ao criar o cluster, especifique o objeto resourceLabels no objeto cluster fornecido para projects.zones.clusters.create.

Terraform

Para criar um cluster do Autopilot com rótulos usando o Terraform, consulte o exemplo a seguir:

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

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Para criar um cluster Standard com rótulos usando o Terraform, consulte o exemplo a seguir:

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

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

Para saber mais como usar o Terraform, consulte o Suporte do Terraform para GKE.

Adicionar ou atualizar identificadores de clusters

É possível adicionar ou atualizar rótulos em clusters atuais do Autopilot e Standard usando a CLI gcloud, o console do Google Cloud ou a API GKE.

gcloud

Execute este comando:

gcloud container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --update-labels=KEY=VALUE

Substitua:

CLUSTER_NAME: o nome do cluster.
COMPUTE_REGION: a região do Compute Engine para o novo cluster. Para clusters padrão zonais, use --zone=COMPUTE_ZONE.
KEY: a chave do par de chave-valor do rótulo.
VALUE: o valor do par de chave-valor do rótulo.

A atualização do marcador substitui os identificadores existentes no cluster. Se o cluster tiver identificadores existentes que você quer manter, inclua esses identificadores com os novos que você quer adicionar.

Console

Para adicionar ou atualizar rótulos, faça o seguinte:

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na página Detalhes do cluster, marque as caixas de seleção de um ou mais clusters que você quer modificar.
Clique em Rótulos.
Adicionar ou atualizar rótulos.
Clique em Save.

API

Faça umaPOST solicitação para a classe resourceLabels método com o mais recenteimpressão digital e uma lista completa de etiquetas a serem aplicadas.

Da mesma forma que os metadados e as tags, se o cluster tiver rótulos que você quer manter, inclua esses rótulos na solicitação junto com os novos a serem adicionados.

Por exemplo, o snippet a seguir faz uma solicitação para o 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="
}

Remover identificadores de clusters

É possível remover rótulos dos clusters do Autopilot e Standard usando a CLI gcloud, o console do Google Cloud ou a API GKE.

gcloud

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

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

Substitua:

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

Console

Para remover identificadores, faça o seguinte:

Acesse a página do Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na lista de clusters, marque as caixas de seleção de um ou mais clusters que você quer modificar.
Clique em Identificadores.
Clique em Excluir item ao lado do campo Valor dos rótulos que você quer excluir.
Clique em Save.

API

Faça uma solicitação POST ao método resourceLabels para o cluster apropriado. Forneça o labelsFingerprint atual e uma lista vazia de identificadores para que todos sejam removidos ou forneça uma lista dos identificadores que você quer manter (omitindo aqueles a serem removidos). Exemplo:

Request

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

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

Criar um pool de nós padrão com identificadores

É possível criar um pool de nós com rótulos em um cluster padrão usando a CLI gcloud, o console do Google Cloud ou a API GKE.

gcloud

Execute este comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Substitua:

NODE_POOL_NAME: o nome do pool de nós.
CLUSTER_NAME: o nome do cluster.
COMPUTE_REGION: a região do Compute Engine do cluster; Para clusters zonais, use --zone=COMPUTE_ZONE.
KEY: a chave do par de chave-valor do rótulo.
VALUE: o valor do par de chave-valor do rótulo.

API

Para incluir um identificador ao criar o pool de nós, especifique o objeto resourceLabels no objeto de pool de nós fornecido a projects.zones.clusters.nodePools.create.

Console

Para adicionar rótulos ao novo pool de nós, faça o seguinte:

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na página Detalhes do cluster, clique no nome do cluster que você quer modificar.
Clique em Adicionar pool de nós.
Configure o novo pool de nós.
No painel de navegação, clique em Metadados.
Clique em Adicionar rótulo.
Adicionar rótulos.
Clique em Criar.

Adicionar ou atualizar rótulos para um pool de nós

É possível adicionar ou atualizar identificadores dos clusters atuais usando a CLI gcloud, o Console do Google Cloud ou a API GKE.

gcloud

Execute este comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Substitua:

NODE_POOL_NAME: o nome do pool de nós.
CLUSTER_NAME: o nome do cluster.
COMPUTE_REGION: a região do Compute Engine do cluster; Para clusters zonais, use --zone=COMPUTE_ZONE.
KEY: a chave do par de chave-valor do rótulo.
VALUE: o valor do par de chave-valor do rótulo.

A atualização do identificador substitui os identificadores atuais no pool de nós. Se você quiser manter os identificadores atuais do pool de nós, inclua esses identificadores com os novos que você quer adicionar.

API

Para incluir um identificador ao modificar o pool de nós, especifique o objeto resourceLabels no objeto do pool de nós fornecido para projects.zones.clusters.nodePools.update.

Console

Para adicionar ou atualizar rótulos, faça o seguinte:

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster que contém o pool de nós que você quer modificar.
Na seção Pool de nós, clique no nome do pool de nós que você quer redimensionar.
Clique em Editar
Na seção Rótulos, adicione ou atualize os rótulos.
Clique em Save.

Remover identificadores do pool de nós

É possível remover rótulos de pools de nós usando a CLI gcloud, o console do Google Cloud ou a API GKE.

gcloud

Execute este comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

Substitua:

NODE_POOL_NAME: o nome do pool de nós.
CLUSTER_NAME: o nome do cluster.
COMPUTE_REGION: a região do Compute Engine do cluster; Para clusters zonais, use --zone=COMPUTE_ZONE.
KEY: a chave do par de chave-valor do rótulo.
VALUE: o valor do par de chave-valor do rótulo.

A atualização do identificador substitui os identificadores atuais no pool de nós. Se o pool de nós tiver identificadores que você quer manter, exclua todos os que quiser remover. Se quiser remover todos os identificadores, use --labels= sem pares de chave-valor.

API

Para incluir um identificador ao modificar o pool de nós, especifique o objeto resourceLabels no objeto do pool de nós fornecido para projects.zones.clusters.nodePools.update. Forneça uma lista vazia de identificadores para remover todos eles ou forneça uma lista de identificadores que você quer manter. Omita os identificadores que você quer remover.

Console

Para remover rótulos de um pool de nós, faça o seguinte

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster que contém o pool de nós que você quer modificar.
Na seção Pool de nós, clique no nome do pool de nós que você quer redimensionar.
Clique em Excluir item ao lado do campo Valor dos rótulos que você quer excluir.
Clique em Save.

A seguir

Leia a visão geral do GKE.