Organizar recursos usando 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

Leia a documentação sobre discos permanentes.
Leia a documentação sobre imagens.
Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine da seguinte maneira.

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

O que são rótulos?

Um rótulo é um par de chave-valor que pode ser atribuído a instâncias 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

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

Cada recurso pode ter até 64 rótulos.
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. 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 em 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 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.

Usos comuns dos rótulos

Veja alguns casos de uso comum para 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 propriedade: usados para identificar as equipes responsáveis pelas operações, por exemplo: team:shopping-cart.

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.

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.

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
- 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",...
    }
 }

Criar recursos com marcadores

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

Console

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.
Em Rótulos, clique em Adicionar rótulo.
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"
  }
}

Adicionar ou atualizar rótulos a recursos atuais.

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

Console

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.
Marque as caixas de seleção referentes aos recursos que receberão rótulos.
Para expandir a coluna de rótulos, clique em Mostrar painel de informações.
No painel, selecione Rótulos.
Para adicionar rótulos, clique em Adicionar rótulo e inclua o par de chave-valor.
Para atualizar os rótulos, selecione-os e modifique os valores.
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 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 CLI do Google Cloud atualizará a chave atual 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 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="
}

Ver marcadores

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

Console

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.
Clique no recurso para ver os detalhes.
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 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 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.

Conseguir 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 Google Cloud e a ferramenta CLI do Google Cloud não exigem uma impressão digital.

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 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 rótulo

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

Console

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.
Marque as caixas de seleção ao lado dos recursos com os rótulos que serão removidos.
Para expandir a coluna de rótulos, clique em Mostrar painel de informações.
Para excluir o marcador, clique em Excluir.
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 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 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="
}

Filtrar pesquisas usando marcadores

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

Console

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.
Se solicitado, selecione o projeto e clique em Continuar.
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 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 CLI 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 e inclua o campo de filtro:

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 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 listar todas as VMs no projeto myproject e a zona us-central1-a com um rótulo que tem um par de chave-valor de env:dev, defina o campo de filtro como labels.env:dev na sua solicitação list. Se você incluir o campo de filtro como um parâmetro de string de consulta, use um valor de parâmetro codificado por URL, filter=labels.env%3Adev:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?filter=labels.env%3Adev

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.

Organizar recursos usando rótulos

Antes de começar

Console

gcloud

REST

O que são rótulos?

Requisitos para rótulos

Usos comuns dos rótulos

Rótulos e tags

Usar rótulos no Compute Engine

Criar recursos com marcadores

Console

gcloud

API

Adicionar ou atualizar rótulos a recursos atuais.

Console

gcloud

API

Ver marcadores

Console

gcloud

API

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

Remover um rótulo

Console

gcloud

API

Filtrar pesquisas usando marcadores

Console

gcloud

API

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

A seguir