Como criar e gerenciar rótulos de cluster

Nesta página, você encontra uma visão geral dos rótulos de cluster no Google Kubernetes Engine (GKE).

O que são rótulos de cluster?

Um rótulo de cluster é um par de chave-valor que ajuda a organizar os clusters do Google Cloud. É possível anexar um rótulo a cada recurso e filtrar os recursos com base nesses rótulos. As informações sobre marcadores são encaminhadas ao sistema de faturamento para que você possa desmembrar as cobranças faturadas por marcador.

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. As tags fornecem uma maneira de permitir ou negar políticas condicionalmente se um recurso tiver uma tag específica. Para mais informações, consulte a Visão geral das tags.

Usos comuns de rótulos de cluster

Não recomendamos a criação de um grande número de rótulos exclusivos, como para carimbos de data/hora ou valores individuais para todas as chamadas de API. Veja a seguir alguns casos de uso comuns de rótulos 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.

  • Rótulos de cluster de estado: por exemplo, state:active, state:readytodelete e state:archive.

Requisitos para rótulos de cluster

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

  • Cada recurso pode ter vários rótulos de cluster, até um máximo de 64.
  • 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.
  • A parte de chave de um marcador de cluster precisa ser exclusiva. No entanto, é possível usar a mesma chave com vários recursos.
  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

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.

Antes de começar

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

Defina as configurações padrão da gcloud usando um dos métodos a seguir:

  • Use gcloud init se quiser orientações para definir os padrões.
  • Use gcloud config para definir individualmente a região, a zona e o ID do projeto.

Como usar o gcloud init

Se você receber o erro One of [--zone, --region] must be supplied: Please specify location, conclua esta seção.

  1. Execute gcloud init e siga as instruções:

    gcloud init

    Se você estiver usando SSH em um servidor remoto, utilize a sinalização --console-only para impedir que o comando inicie um navegador:

    gcloud init --console-only
  2. Siga as instruções para autorizar a gcloud a usar sua conta do Google Cloud.
  3. Crie uma nova configuração ou selecione uma atual.
  4. Escolha um projeto do Google Cloud.
  5. Escolha uma zona padrão do Compute Engine para clusters zonais ou uma região para clusters regionais ou de Autopilot.

Como usar o gcloud config

  • Defina o ID do projeto padrão:
    gcloud config set project PROJECT_ID
  • Se você estiver trabalhando com clusters zonais, defina a zona do Compute padrão:
    gcloud config set compute/zone COMPUTE_ZONE
  • Se você estiver trabalhando com clusters de Autopilot ou regionais, defina a região do Compute padrão:
    gcloud config set compute/region COMPUTE_REGION
  • Atualize gcloud para a versão mais recente:
    gcloud components update

Rótulos aplicados automaticamente

Depois que os clusters são criados, o GKE aplica automaticamente vários rótulos aos recursos deles. Por exemplo, o GKE aplica rótulos a instâncias do Compute Engine, discos permanentes e aceleradores (TPU). Os rótulos aplicados automaticamente têm um prefixo goog-gke- especial.

Os rótulos goog-gke- a seguir são aplicados automaticamente aos recursos do GKE. Todas as modificações realizadas nos rótulos goog-gke- reservados no nível do Compute Engine ou do cluster do GKE serão reconciliadas automaticamente. Por esse motivo, não é recomendável editar ou excluir esses rótulos reservados.

Rótulo Recursos aplicados
goog-gke-node Nós do GKE
goog-gke-volume Discos permanentes anexados a nós do GKE
goog-gke-tpu Cloud TPU no GKE

Sobre a rotulação de clusters

No GKE, você aplica os rótulos no nível do cluster. Quando um cluster é rotulado, o rótulo escolhido é propagado em todos os recursos individuais dele, como nós e discos permanentes.

É possível adicionar, atualizar e remover rótulos de cluster, usando o Console do Google Cloud, a ferramenta de linha de comando gcloud ou a API do GKE.

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

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. Por exemplo:

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

Na resposta, procure a propriedade labelFingerprint:

200 OK

{

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

Como criar um cluster com rótulos

Crie um cluster com rótulos usando a ferramenta gcloud, o Console do Google Cloud ou a API GKE.

gcloud

Execute este comando:

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.

Exemplo:

gcloud container clusters create example-cluster --labels env=dev

Console

Para adicionar rótulos ao criar seu cluster:

  1. Acesse a página do Google Kubernetes Engine no Console do Cloud:

    Acessar o Google Kubernetes Engine

  2. Clique em Criar.

  3. Configure o cluster como quiser.

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

  5. Clique em Adicionar rótulo.

  6. Adicione os marcadores desejados.

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

Como adicionar ou atualizar rótulos em clusters atuais.

gcloud

Para atualizar os rótulos com a ferramenta gcloud, execute o seguinte comando:

gcloud container clusters update CLUSTER_NAME \
    [--region COMPUTE_REGION | --zone COMPUTE_ZONE] \
    --update-labels KEY=VALUE

Substitua:

  • CLUSTER_NAME: o nome do cluster.
  • COMPUTE_REGION: se o cluster for regional, especifique a região do Compute Engine para o cluster.
  • COMPUTE_ZONE: se o cluster for zonal, especifique a zona do Compute Engine para o cluster.
  • KEY: a chave do par de chave-valor do rótulo.
  • VALUE: o valor do par de chave-valor do rótulo.

Exemplo:

gcloud container clusters update example-cluster --zone us-west1-a \
    --update-labels env=dev,release=stable

A atualização do rótulo substituirá todos os rótulos atuais. Inclua os rótulos que você quiser manter com os novos que quiser adicionar.

Console

Para adicionar ou atualizar rótulos:

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

    Acessar o Google Kubernetes Engine

  2. Na lista de clusters, selecione um ou mais clusters que você quer modificar.

  3. Clique em Mostrar painel de informações, se ele ainda não estiver visível.

  4. Adicione ou atualize os rótulos conforme necessário.

  5. Clique em Save.

API

Para atualizar os rótulos, faça uma solicitação POST para o método resourceLabels do cluster com a impressão digital mais recente e uma lista completa dos rótulos a serem aplicados.

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": {
  "env": "test",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Como remover rótulos de cluster

gcloud

Na ferramenta gcloud, execute o comando update com a sinalização --remove-labels. Forneça um conjunto de chaves de rótulo a serem removidas.

gcloud container clusters update CLUSTER_NAME --remove-labels KEY

Substitua:

  • CLUSTER_NAME: o nome do cluster.
  • KEY: a chave do rótulo a ser removido.

Exemplo:

gcloud container clusters update example-cluster --remove-labels env

Console

Para remover rótulos:

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

    Acessar o Google Kubernetes Engine

  2. Na lista de clusters, selecione um ou mais clusters que você quer modificar.

  3. Clique em Mostrar painel de informações, se ele ainda não estiver visível.

  4. Clique em Excluir item ao lado do campo Valor dos rótulos que você quer excluir.

  5. Clique em Save.

API

Na API, faça uma solicitação POST para o método resourceLabels para o cluster apropriado. Forneça o labelsFingerprint atual e uma lista vazia de rótulos para remover todos os rótulos ou forneça uma lista dos rótulos que você quer manter (omitindo aqueles a serem removidos). Por exemplo:

Request

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

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

A seguir

Leia a visão geral do GKE.