Como criar e gerenciar rótulos

Rótulos são pares de chave-valor que podem ser usados no Google Cloud para agrupar recursos relacionados ou associados. Por exemplo, no Compute Engine, use rótulos para agrupar VMs em categorias como produção, preparo ou desenvolvimento, para que seja possível pesquisar recursos que pertencem a cada estágio de desenvolvimento.

Depois de adicionar rótulos aos recursos, aproveite o recurso de filtragem aninhada para realizar pesquisas mais precisas dos recursos usando rótulos.

Antes de começar

O que são rótulos?

Um rótulo é um par de chave-valor que ajuda a organizar suas instâncias 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 dos rótulos

Não recomendamos a criação de um grande número de rótulos exclusivos, como carimbos de data/hora ou valores individuais para todas as chamadas de API. Veja alguns casos de uso comum de rótulos:

  • Rótulos de centro de custo ou de equipe: adiciona rótulos com base na equipe ou no centro de custo para distinguir as instâncias pertencentes a equipes diferentes (por exemplo, team:research e team:analytics). Você pode usar esse tipo de rótulo para contabilidade de custo ou orçamento.

  • Rótulos de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

  • Rótulos de ambientes ou de estágios: por exemplo, environment:production e environment:test.

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

  • Rótulos de máquina virtual: um rótulo pode ser anexado a uma máquina virtual. As tags de máquina virtual definidas no passado serão exibidas como um rótulo sem um valor.

Requisitos para rótulos

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

  • Cada recurso pode ter vários rótulos, até um máximo de 64.
  • Cada rótulo precisa ser um par de chave-valor.
  • As chaves têm comprimento mínimo de 1 e máximo de 63 caracteres. Além disso, elas 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 da chave de um rótulo precisa ser única. No entanto, use 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 e aos recursos individuais do Google Cloud que têm rótulos. Não há limite para a quantidade de rótulos que podem ser aplicados a todos os recursos em um projeto.

Como usar rótulos no Compute Engine

É possível aplicar rótulos aos seguintes recursos do Compute Engine:

  • Instâncias de máquina virtual (VM)
  • Imagens
  • discos permanentes
  • Snapshots de discos permanentes

Também é possível usar rótulos em componentes relacionados do Google Cloud, como os seguintes:

Por exemplo, é possível adicionar os seguintes rótulos como pares de chave-valor aos seus recursos:

{
 "labels": {
    "vmrole": "webserver",
    "environment": "production",
    "location": "west",...
    }
 }

Como criar recursos com rótulos

Ao criar um novo recurso, é possível aplicar rótulos a ele.

Console

  1. Acesse a página de recursos que você quer criar.

  2. Em Rótulos, clique em Adicionar rótulo.

  3. Continue o processo de criação.

gcloud

Para adicionar um rótulo, use o subcomando create com a sinalização --labels. É possível adicionar rótulos aos recursos do Compute Engine usando os seguintes comandos gcloud:

Exemplo

gcloud compute instances create ... \
    --labels webserver=backend,media=images

API

Na API, durante a solicitação POST para acrescentar um novo recurso, adicione a propriedade labels no corpo da solicitação para aplicar rótulos ao novo recurso.

Por exemplo, o snippet a seguir faz uma solicitação POST para criar uma instância de VM com os rótulos webserver:backend e media:images:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances

{
 "name": "myVM",
 "machineType": "zones/us-central1-f/machineTypes/custom-2-15360-ext",
  ...,
 "labels": [{
   "key": "webserver",
   "value": "backend"
   },
   {
   "key": "media",
   "value": "images"
  }]
}

Como adicionar ou atualizar rótulos a recursos atuais

É possível adicionar ou atualizar rótulos atuais em recursos usando o Console do Cloud, a ferramenta gcloud ou a API Compute Engine. Para adicionar ou atualizar rótulos nas regras de encaminhamento, use a ferramenta gcloud ou a API Compute Engine.

Console

  1. Acesse a página de recursos em que você quer adicionar rótulos.

  2. Marque as caixas de seleção referentes aos recursos que receberão rótulos.

  3. Para expandir a coluna de rótulos, clique em Mostrar painel de informações.

  4. No painel, selecione Rótulos.

  5. Para adicionar rótulos, clique em Adicionar rótulo e inclua o par de chave-valor.

  6. Para atualizar os rótulos, selecione-os e modifique os valores.

  7. Salve as alterações.

gcloud

Para adicionar ou alterar um rótulo, use o subcomando update com a sinalização --update-labels. É possível atualizar os rótulos dos recursos do Compute Engine usando os seguintes comandos gcloud:

Exemplo

gcloud compute disks update example-disk \
    --update-labels backend=webserver,media=images

Se você fornecer uma chave de rótulo que já existe, a ferramenta de linha de comando gcloud atualizará a chave existente com o novo valor do rótulo. Quando uma nova chave é fornecida, ela é adicionada à lista de marcadores.

API

Para adicionar ou atualizar rótulos, faça uma solicitação POST para o método setLabels do recurso apropriado com a impressão digital mais recente e uma lista completa de rótulos a aplicar.

Da mesma maneira que os metadados e as tags, se o recurso 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 POST para uma instância de VM para definir os rótulos environment:test e an-existing-tag:yes:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": {
  "environment": "test",
  "an-existing-tag": "yes"
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Como ver rótulos

É possível visualizar os rótulos dos recursos usando o Console do Cloud, a ferramenta gcloud ou a API Compute Engine. Para visualizar os rótulos de regras de encaminhamento, use a ferramenta gcloud ou a API Compute Engine.

Console

  1. Acesse a página de recursos.

  2. Clique no recurso para ver os detalhes.

  3. Localize Rótulos.

gcloud

Para visualizar os rótulos, use o subcomando describe. É possível visualizar os rótulos dos recursos do Compute Engine usando os seguintes comandos gcloud:

Exemplo

gcloud compute disks describe example-disk

A saída contém os rótulos:

...
id: '5047929990219134234'
kind: compute#disk
labelFingerprint: GHZ1Un209U=0
labels:
  environment: dev
  department: finance
...

API

Para recuperar rótulos, faça uma solicitação GET para o seguinte recurso:

Por exemplo, o snippet a seguir faz uma solicitação GET para recuperar rótulos de uma instância de VM:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

Substitua:

  • PROJECT_ID: o ID do projeto;
  • ZONE: a zona da VM;
  • VM_NAME: O nome da VM.

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

Ao atualizar ou adicionar rótulos na API, forneça a impressão digital mais recente deles com a solicitação para evitar conflitos com outras solicitações. Uma impressão digital só é necessária para solicitações de API. O Console do Cloud e a ferramenta de linha de comando gcloud não exigem uma impressão digital.

Para ver o labelsFingerprint mais recente, faça uma solicitação GET para os seguintes recursos:

Por exemplo, o snippet a seguir recebe um labelsFingerprint para uma instância de VM:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance

A resposta contém a propriedade labelFingerprint:

200 OK

{
 "kind": "compute#instance",
 "id": "4392196237934605253",
 "creationTimestamp": "2015-09-15T14:05:16.475-07:00",
 "zone": "https://content.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f",
 "status": "RUNNING",
 ...
 "labels": {
  "environment": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Remover um marcador

É possível remover rótulos de recursos usando o Console do Cloud, a ferramenta gcloud ou a API Compute Engine. Para remover os rótulos de regras de encaminhamento, use a ferramenta gcloud ou a API Compute Engine.

Console

  1. Acesse a página de recursos da qual você quer remover rótulos.

  2. Marque as caixas de seleção ao lado dos recursos com os rótulos que serão removidos.

  3. Para expandir a coluna de rótulos, clique em Mostrar painel de informações.

  4. Para excluir o marcador, clique em Excluir.

  5. Salve as alterações.

gcloud

Para adicionar ou alterar um rótulo, use o subcomando update com a sinalização --remove-labels. É possível remover os rótulos dos recursos do Compute Engine usando os seguintes comandos gcloud:

Exemplo

gcloud compute disks update example-disk \
    --remove-labels backend,media

API

Para remover rótulos, faça uma solicitação POST para o método setLabels do recurso a seguir com a impressão digital mais recente e uma lista completa dos rótulos a serem aplicados:

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, o snippet a seguir remove todos os rótulos da VM:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

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

Como filtrar pesquisas usando rótulos

É possível pesquisar recursos e filtrar resultados por rótulos usando o Console do Cloud, a ferramenta gcloud ou a API Compute Engine. Para filtrar regras de encaminhamento por rótulos, use a ferramenta gcloud ou a API Compute Engine.

Console

  1. Acesse a página de recursos em que você quer receber uma lista filtrada de recursos.

  2. Se solicitado, selecione o projeto e clique em Continuar.

  3. Na barra de pesquisa, insira seu par de chave, valor ou chave-valor. Os resultados incluem todas as correspondências parciais.

    Por exemplo, para mostrar apenas os recursos com o rótulo env:dev, insira qualquer um dos seguintes itens:

    • Digite a chave: env
    • Insira o valor: dev
    • Insira o par de chave-valor: env:dev

gcloud

Para filtrar com base nos rótulos, use o subcomando list dos seguintes recursos com a sinalização --filter:

O valor da sinalização --filter precisa estar no formato labels.KEY=VALUE. Por exemplo, se você quiser filtrar um rótulo com env como a chave e dev como o valor, execute este comando:

gcloud compute instances list \
    --filter labels.env=dev

Para mais informações sobre a sintaxe do filtro na ferramenta gcloud, consulte a documentação gcloud topic filters.

API

Para filtrar recursos, faça uma solicitação GET para o método list dos seguintes recursos com um parâmetro de consulta filter codificado por URL:

Por exemplo, para filtrar com base em um rótulo env:dev, faça a seguinte solicitação GET com filter=labels.env+eq+dev na string de consulta:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/list?filter=labels.env+eq+dev

Para mais informações, leia a documentação de filter na referência da API Compute Engine.

Relação entre rótulos de VM e tags de rede

Antes, os rótulos e as tags eram relacionados. Por exemplo, se você tivesse adicionado um rótulo webserver:test a uma VM, o Compute Engine automaticamente adicionaria uma tag webserver à VM.

Agora, os rótulos e as tags são separados. Se você criar um rótulo em uma VM, o Compute Engine não criará uma tag para a VM. Caso você precise criar uma tag em uma VM, será necessário criá-la manualmente.

Para saber como criar tags, consulte Tags de rede.

A seguir