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:

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.

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 container clusters create-auto CLUSTER_NAME \
    --labels=KEY=VALUE

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

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
}

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
}

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 container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --update-labels=KEY=VALUE

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 container clusters update CLUSTER_NAME \
    --remove-labels=KEYS

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 container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

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 container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

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 container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

A seguir

Leia a visão geral do GKE.