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

• Para usar os exemplos de linha de comando deste guia, faça o seguinte:
  1. Instale a ferramenta de linha de comando gcloud ou atualize-a para a versão mais recente.
  2. Defina uma região e uma zona padrão.
• Para usar os exemplos de API deste guia, configure o acesso à API.
• Leia a documentação sobre discos permanentes.
• Leia a documentação sobre imagens.

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.

Observação: ao filtrar o detalhamento de faturamento por chaves de rótulo, não será possível selecionar rótulos aplicados a um projeto. É possível selecionar outros rótulos criados pelo usuário que você configurou e aplicou aos serviços do Google Cloud.

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.

Observação: não inclua informações confidenciais em rótulos, incluindo informações de identificação pessoal, como nome ou título de uma pessoa. Os rótulos não são criados para gerenciar informações confidenciais.

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:

• Buckets do Cloud Storage
• Recursos de rede:
  • Regras de encaminhamento (visualização)
  • Túneis VPN (visualização)
  • Endereços IP externos estáticos (visualização)

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.

Observação: não é possível adicionar rótulos a regras de encaminhamento, endereços IP externos estáticos e túneis VPN ao criar esses recursos. Você só pode adicionar rótulos a esses recursos de rede quando estiver atualizando o recurso. Para instruções sobre como adicionar rótulos durante uma atualização, consulte Como adicionar ou atualizar rótulos aos recursos existentes.

Console

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

   • Para instâncias de VM, acesse Criar uma instância.
   • Para discos, acesse Criar um disco.
   • Para snapshots, acesse Criar um snapshot.
   • Para imagens, acesse Criar uma imagem.

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:

• Para instâncias de VM, use o comando gcloud compute instances create.
• Para snapshots, use o comando gcloud compute disks snapshot.
• Para imagens, use o comando gcloud compute images create.
• Para discos, use o comando gcloud compute disks create.

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.

• Para instâncias de VM, use o método instances.insert().
• Para snapshots, use o método disks.createSnapshot().
• Para imagens, use o método images.insert().
• Para discos, use o método disks.insert().

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": {
   "webserver": "backend",
   "media": "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.

   • Para instâncias de VM, acesse Instâncias de VM.
   • Para snapshots, acesse Snapshots.
   • Para imagens, acesse Imagens.
   • Para discos, acesse Discos.
   • Para endereços IP externos estáticos, acesse Endereços IP externos.
   • Para túneis de VPN, acesse VPN.

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:

• Para instâncias de VM, use o comando gcloud compute instances update.
• Para snapshots, use o comando gcloud compute snapshots update.
• Para imagens, use o comando gcloud compute images update.
• Para discos, use o comando gcloud compute disks update.
• Para regras de encaminhamento, use o comando gcloud beta compute forwarding-rules update.
• Para endereços IP externos estáticos, use o comando gcloud beta compute addresses update.
• Para túneis de VPN, use o comando gcloud beta compute vpn-tunnels update.

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.

• Para instâncias de VM, use o método instances.setLabels().
• Para snapshots, use o método snapshots.setLabels().
• Para imagens, use o método images.setLabels().
• Para discos, use o método disks.setLabels().
• Para regras de encaminhamento, use o método Beta forwardingRules.setLabels().
• Para endereços IP externos estáticos regionais, use o método Beta addresses.setLabels().
• Para endereços IP externos estáticos globais, use o método Beta globalAddresses.setLabels().
• Para túneis VPN, use o método Beta vpnTunnels.setLabels().

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.

   • Para instâncias de VM, acesse Instâncias de VM.
   • Para snapshots, acesse Snapshots.
   • Para imagens, acesse Imagens.
   • Para discos, acesse Discos.
   • Para endereços IP externos estáticos, acesse Endereços IP externos.
   • Para túneis de VPN, acesse VPN.

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:

• Para instâncias de VM, use o comando gcloud compute instances describe.
• Para snapshots, use o comando gcloud compute snapshots describe.
• Para imagens, use o comando gcloud compute images describe.
• Para discos, use o comando gcloud compute disks describe.
• Para regras de encaminhamento, use o comando gcloud beta compute forwarding-rules describe.
• Para endereços IP externos estáticos, use o comando gcloud beta compute addresses describe.
• Para túneis de VPN. use o comando gcloud beta compute vpn-gateways describe.

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:

• Para instâncias de VM, use o método instances.get().
• Para snapshots, use o método snapshots.get().
• Para imagens, use o método images.get().
• Para discos, use o método disks.get().
• Para regras de encaminhamento, use o método Beta forwardingRules.get().
• Para endereços IP externos estáticos regionais, use o método Beta addresses.get().
• Para endereços IP externos estáticos globais, use o método Beta globalAddresses.get().
• Para túneis VPN, use o método Beta vpnTunnels.get().

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.

Observação: é possível obter a impressão digital do rótulo fazendo uma consulta diretamente à API.

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

• Para instâncias de VM, use o método instances.get().
• Para snapshots, use o método snapshots.get().
• Para imagens, use o método images.get().
• Para discos, use o método disks.get().
• Para regras de encaminhamento, use o método Beta forwardingRules.get().
• Para endereços IP externos estáticos regionais, use o método Beta addresses.get().
• Para endereços IP externos estáticos globais, use o método Beta globalAddresses.get().
• Para túneis VPN, use o método Beta vpnTunnels.get().

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.

   • Para instâncias de VM, acesse Instâncias de VM.
   • Para snapshots, acesse Snapshots.
   • Para imagens, acesse Imagens.
   • Para discos, acesse Discos.
   • Para endereços IP externos estáticos, acesse Endereços IP externos.
   • Para túneis de VPN, acesse VPN.

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:

• Para instâncias de VM, use o comando gcloud compute instances update.
• Para snapshots, use o comando gcloud compute snapshots update.
• Para imagens, use o comando gcloud compute images update.
• Para discos, use o comando gcloud compute disks update.
• Para regras de encaminhamento, use o comando gcloud beta compute forwarding-rules update.
• Para endereços IP externos estáticos, use o comando gcloud beta compute addresses update.
• Para túneis de VPN, use o comando gcloud beta compute vpn-tunnels update.

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:

• Para instâncias de VM, use o método instances.setLabels().
• Para snapshots, use o método snapshots.setLabels().
• Para imagens, use o método images.setLabels().
• Para discos, use o método disks.setLabels().
• Para regras de encaminhamento, use o método Beta forwardingRules.setLabels().
• Para endereços IP externos estáticos regionais, use o método Beta addresses.setLabels().
• Para endereços IP externos estáticos globais, use o método Beta globalAddresses.setLabels().
• Para túneis VPN, use o método Beta vpnTunnels.setLabels().

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.

   • Para instâncias de VM, acesse Instâncias de VM.
   • Para snapshots, acesse Snapshots.
   • Para imagens, acesse Imagens.
   • Para discos, acesse Discos.
   • Para endereços IP externos estáticos, acesse Endereços IP externos.
   • Para túneis de VPN, acesse VPN.

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:

• Para instâncias de VM, use o comando gcloud compute instances list.
• Para snapshots, use o comando gcloud compute snapshots list.
• Para imagens, use o comando gcloud compute images list.
• Para discos, use o comando gcloud compute disks list.
• Para regras de encaminhamento, use o comando gcloud beta compute forwarding-rules list.
• Para endereços IP externos estáticos, use o comando gcloud beta compute addresses list.
• Para túneis de VPN, use o comando gcloud beta compute vpn-tunnels list.

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:

• Para instâncias de VM, use o método instances.list().
• Para snapshots, use o método snapshots.list().
• Para imagens, use o método images.list().
• Para discos, use o método disks.list().
• Para regras de encaminhamento, use o método Beta forwardingRules.list().
• Para endereços IP externos estáticos regionais, use o método Beta addresses.list().
• Para endereços IP externos estáticos globais, use o método Beta globalAddresses.list().
• Para túneis VPN, use o método Beta vpnTunnels.list().

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

• Saiba como adicionar tags de rede.
• Saiba mais sobre filtragem.