Organize recursos com etiquetas

---

Os marcadores são pares de chave-valor que podem ser usados Google Cloud para agrupar recursos relacionados ou associados. Por exemplo, no Compute Engine, pode usar etiquetas para agrupar VMs em categorias, como produção, preparação ou desenvolvimento, para poder pesquisar recursos que pertencem a cada fase de desenvolvimento.

Depois de adicionar etiquetas aos seus recursos, pode tirar partido da funcionalidade de filtragem aninhada para fazer pesquisas mais precisas dos seus recursos usando etiquetas.

Antes de começar

• Leia a documentação sobre discos persistentes.
• Leia a documentação sobre imagens.
• Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-se no Compute Engine selecionando uma das seguintes opções:

  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. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando:

     gcloud init

     Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

     Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.
  2. Set a default region and zone.

  REST

  Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

  Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando:

  gcloud init

  Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

  Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.

O que são etiquetas?

Uma etiqueta é um par de chave-valor que pode atribuir a Google Cloud instâncias. Ajudam a organizar estes recursos e a gerir os custos em grande escala, com a granularidade de que precisa. Pode anexar uma etiqueta a cada recurso e, em seguida, filtrar os recursos com base nas respetivas etiquetas. As informações sobre as etiquetas são encaminhadas para o sistema de faturação que lhe permite discriminar os encargos faturados por etiqueta. Com os relatórios de faturação integrados, pode filtrar e agrupar os custos por etiquetas de recursos. Também pode usar etiquetas para consultar exportações de dados de faturação.

Requisitos para etiquetas

As etiquetas aplicadas a um recurso têm de cumprir os seguintes requisitos:

• Cada recurso pode ter até 64 etiquetas.
• Cada etiqueta tem de ser um par chave-valor.
• As chaves têm um comprimento mínimo de 1 caráter e um comprimento máximo de 63 carateres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 carateres.
• As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. Todos os carateres têm de usar a codificação UTF-8, e são permitidos carateres internacionais. As chaves têm de começar com uma letra minúscula ou um caráter internacional.
• A parte da chave de uma etiqueta tem de ser exclusiva num único recurso. No entanto, pode usar a mesma chave com vários recursos.

Estes limites aplicam-se à chave e ao valor de cada etiqueta, bem como aos recursos Google Cloud individuais que têm etiquetas. Não existe um limite para o número de etiquetas que pode aplicar a todos os recursos num projeto.

Utilizações comuns das etiquetas

Seguem-se alguns exemplos de utilização comuns das etiquetas:

• Etiquetas de equipa ou centro de custos: adicione etiquetas com base na equipa ou no centro de custos para distinguir instâncias pertencentes a diferentes equipas (por exemplo, team:research e team:analytics). Pode usar este tipo de etiqueta para contabilidade de custos ou orçamentação.

• Etiquetas de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

• Etiquetas de ambiente ou fase: por exemplo, environment:production e environment:test.

• Etiquetas de estado: por exemplo, state:active,state:readytodelete e state:archive.

• Etiquetas de propriedade: usadas para identificar as equipas responsáveis pelas operações, por exemplo: team:shopping-cart.

• Etiquetas de máquinas virtuais: pode anexar uma etiqueta a uma máquina virtual. As etiquetas de máquinas virtuais que definiu no passado aparecem como uma etiqueta sem valor.

Nota: não inclua informações sensíveis em etiquetas, incluindo informações de identificação pessoal, como o nome ou o título de um indivíduo. As etiquetas não foram concebidas para processar informações confidenciais.

Não recomendamos a criação de um grande número de etiquetas únicas, como para carimbos de data/hora ou valores individuais para cada chamada da API. O problema desta abordagem é que, quando os valores mudam frequentemente ou com chaves que desorganizam o catálogo, torna-se difícil filtrar e criar relatórios sobre os recursos de forma eficaz.

Etiquetas e marcadores

As etiquetas podem ser usadas como anotações consultáveis para recursos, mas não podem ser usadas para definir condições nas políticas. As etiquetas oferecem uma forma de permitir ou negar condicionalmente políticas com base no facto de um recurso ter uma etiqueta específica, oferecendo um controlo detalhado sobre as políticas. Para mais informações, consulte a Vista geral das etiquetas.

Use etiquetas no Compute Engine

Pode aplicar etiquetas aos seguintes recursos do Compute Engine:

• Instâncias de máquinas virtuais (VMs)
• Imagens
• Discos persistentes
• Instantâneos do Persistent Disk

Também pode usar etiquetas em componentes Google Cloud relacionados, como os seguintes:

• Contentores do Cloud Storage
• Recursos de rede:
  • Regras de encaminhamento usadas com balanceadores de carga de aplicações internos (outras regras de encaminhamento de balanceadores de carga não são suportadas)
  • Túneis de VPN (pré-visualização)
  • Endereços IP externos estáticos (pré-visualização)

Por exemplo, pode adicionar as seguintes etiquetas como pares de chave-valor aos seus recursos:

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

Crie recursos com etiquetas

Quando cria um novo recurso, pode aplicar-lhe etiquetas.

Nota: não pode adicionar etiquetas a regras de encaminhamento, endereços IP externos estáticos nem túneis VPN quando cria estes recursos. Só pode adicionar etiquetas a estes recursos de rede quando atualiza o recurso. Para ver instruções sobre como adicionar etiquetas durante uma atualização, consulte o artigo Adicione ou atualize etiquetas a recursos existentes neste documento.

Consola

1. Aceda à página de recursos que quer criar.

   • Para instâncias de VM, aceda a Criar uma instância.
   • Para discos, aceda a Crie um disco.
   • Para instantâneos, aceda a Crie um instantâneo.
   • Para imagens, aceda a Crie uma imagem.

2. Em Etiquetas, clique em Adicionar etiqueta.

3. Continue com o processo de criação.

gcloud

Para adicionar uma etiqueta, use o subcomando create com a flag --labels. Pode adicionar etiquetas aos recursos do Compute Engine através dos seguintes comandos gcloud:

• Para instâncias de VM, use o comando gcloud compute instances create.
• Para instantâneos, 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

REST

Na API, durante o pedido POST para adicionar um novo recurso, adicione a propriedade labels no corpo do pedido para aplicar etiquetas ao novo recurso.

• Para instâncias de VM, use o método instances.insert().
• Para instantâneos, 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 fragmento seguinte faz um pedido POST para criar uma instância de VM com as etiquetas 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"
  }
}

Adicione ou atualize etiquetas a recursos existentes

Pode adicionar etiquetas ou atualizar etiquetas existentes em recursos através da Google Cloud consola, da CLI gcloud ou da API Compute Engine. Para adicionar ou atualizar etiquetas para regras de encaminhamento, use a CLI gcloud ou a API Compute Engine.

Consola

1. Aceda à página do recurso ao qual quer adicionar etiquetas.

   • Para instâncias de VM, aceda a Instâncias de VM.
   • Para ver os resumos, aceda a Resumos.
   • Para imagens, aceda a Imagens.
   • Para discos, aceda a Discos.
   • Para endereços IP externos estáticos, aceda a Endereços IP externos.
   • Para túneis de VPN, aceda a VPN.

2. Selecione as caixas de verificação junto aos recursos que quer etiquetar.

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

4. No painel, selecione Etiquetas.

5. Para adicionar etiquetas, clique em Adicionar etiqueta e adicione o par de chave-valor.

6. Para atualizar etiquetas, selecione as etiquetas existentes e modifique os respetivos valores.

7. Guarde as alterações.

gcloud

Para adicionar ou alterar uma etiqueta, use o subcomando update com a flag --update-labels. Pode atualizar as etiquetas dos recursos do Compute Engine com os seguintes comandos gcloud:

• Para instâncias de VM, use o gcloud compute instances updatecomando.
• Para instantâneos, use o gcloud compute snapshots updatecomando.
• Para imagens, use o gcloud compute images updatecomando.
• Para discos, use o gcloud compute disks update comando.
• 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 VPN, use o comando gcloud beta compute vpn-tunnels update.

Exemplo

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

Se fornecer uma chave de etiqueta que já exista, a CLI do Google Cloud atualiza a chave existente com o novo valor da etiqueta. Se fornecer uma nova chave, a ferramenta adiciona a nova chave à lista de etiquetas.

REST

Para adicionar ou atualizar etiquetas, faça um pedido POST ao método setLabels do recurso com a impressão digital mais recente e uma lista completa de etiquetas a aplicar:

• Para instâncias de VM, use o método instances.setLabels().
• Para instantâneos, 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().

Tal como acontece com os metadados e as etiquetas, se o recurso tiver etiquetas existentes que quer manter, tem de incluir essas etiquetas no pedido, juntamente com quaisquer novas etiquetas que quer adicionar.

Por exemplo, o fragmento seguinte faz um pedido POST a uma instância de VM para definir as etiquetas 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 etiquetas

Pode ver as etiquetas dos recursos através da Google Cloud consola, da CLI gcloud ou da API Compute Engine. Para ver as etiquetas das regras de encaminhamento, use a CLI gcloud ou a API Compute Engine.

Consola

1. Aceda à página de recursos.

   • Para instâncias de VM, aceda a Instâncias de VM.
   • Para ver os resumos, aceda a Resumos.
   • Para imagens, aceda a Imagens.
   • Para discos, aceda a Discos.
   • Para endereços IP externos estáticos, aceda a Endereços IP externos.
   • Para túneis de VPN, aceda a VPN.

2. Clique no recurso para ver os respetivos detalhes.

3. Localize Etiquetas.

gcloud

Para ver etiquetas, use o subcomando describe. Pode ver as etiquetas dos recursos do Compute Engine através dos seguintes comandos gcloud:

• Para instâncias de VM, use o gcloud compute instances describecomando.
• Para instantâneos, use o gcloud compute snapshots describecomando.
• Para imagens, use o gcloud compute images describecomando.
• Para discos, use o gcloud compute disks describe comando.
• 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 VPN, use o comando gcloud beta compute vpn-gateways describe.

Exemplo

gcloud compute disks describe example-disk

A saída contém as etiquetas:

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

REST

Para obter etiquetas, faça um pedido GET ao seguinte recurso:

• Para instâncias de VM, use o método instances.get().
• Para instantâneos, 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 seguinte fragmento faz um pedido GET para obter etiquetas para uma instância de VM:

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

Substitua o seguinte:

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

Obtenha uma impressão digital de etiqueta para pedidos de API

Quando atualiza ou adiciona etiquetas na API, tem de fornecer a impressão digital das etiquetas mais recentes com o seu pedido para evitar conflitos com outros pedidos. Só é necessária uma impressão digital para pedidos de API. A ferramenta Google Cloud console e a ferramenta Google Cloud CLI não requerem uma impressão digital.

Nota: só pode obter a impressão digital da etiqueta fazendo uma consulta diretamente à API.

Para obter a versão mais recente do labelsFingerprint, faça um pedido GET aos seguintes recursos:

• Para instâncias de VM, use o método instances.get().
• Para instantâneos, 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 seguinte fragmento 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="
}

Remova uma etiqueta

Pode remover etiquetas de recursos através da Google Cloud consola, da CLI gcloud ou da API Compute Engine. Para remover etiquetas para regras de encaminhamento, use a CLI gcloud ou a API Compute Engine.

Consola

1. Aceda à página de recursos para a qual quer remover etiquetas.

   • Para instâncias de VM, aceda a Instâncias de VM.
   • Para ver os resumos, aceda a Resumos.
   • Para imagens, aceda a Imagens.
   • Para discos, aceda a Discos.
   • Para endereços IP externos estáticos, aceda a Endereços IP externos.
   • Para túneis de VPN, aceda a VPN.

2. Selecione as caixas de verificação junto aos recursos dos quais quer remover etiquetas.

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

4. Para eliminar uma etiqueta, clique em Eliminar.

5. Guarde as alterações.

gcloud

Para adicionar ou alterar uma etiqueta, use o subcomando update com a flag --remove-labels. Pode remover etiquetas dos recursos do Compute Engine usando os seguintes comandos gcloud:

• Para instâncias de VM, use o gcloud compute instances updatecomando.
• Para instantâneos, use o gcloud compute snapshots updatecomando.
• Para imagens, use o gcloud compute images updatecomando.
• Para discos, use o gcloud compute disks update comando.
• 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 VPN, use o comando gcloud beta compute vpn-tunnels update.

Exemplo

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

REST

Para remover etiquetas, faça um pedido POST ao método setLabels do seguinte recurso com a impressão digital mais recente e uma lista completa de etiquetas a aplicar:

• Para instâncias de VM, use o método instances.setLabels().
• Para instantâneos, 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().

Indique o labelsFingerprint atual e uma lista vazia de etiquetas para remover todas as etiquetas ou indique uma lista de etiquetas que quer manter (omitindo as etiquetas que quer remover). Por exemplo, o seguinte fragmento remove todas as etiquetas da VM:

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

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

Filtre pesquisas com etiquetas

Pode pesquisar os seus recursos e filtrar os resultados por etiquetas através da Google Cloud consola, da CLI gcloud ou da API Compute Engine. Para filtrar regras de encaminhamento por etiquetas, use a CLI gcloud ou a API Compute Engine.

Consola

1. Aceda à página de recursos para a qual quer obter uma lista filtrada de recursos.

   • Para instâncias de VM, aceda a Instâncias de VM.
   • Para ver os resumos, aceda a Resumos.
   • Para imagens, aceda a Imagens.
   • Para discos, aceda a Discos.
   • Para endereços IP externos estáticos, aceda a Endereços IP externos.
   • Para túneis de VPN, aceda a VPN.

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

3. Na barra de pesquisa, introduza a chave, o valor ou o par de chave-valor. Os resultados incluem correspondências parciais.

   Por exemplo, para mostrar apenas recursos com a etiqueta env:dev, pode introduzir qualquer um dos seguintes elementos:

   • Introduza a chave: env
   • Introduza o valor: dev
   • Introduza o par de chave-valor: env:dev

gcloud

Para filtrar com base em etiquetas, use o subcomando list dos seguintes recursos com a flag --filter:

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

O valor da flag --filter tem de estar no formato labels.KEY=VALUE. Por exemplo, se quiser filtrar por uma etiqueta com env como chave e dev como valor, pode executar este comando:

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

Para mais informações sobre a sintaxe de filtros na CLI gcloud, consulte a gcloud topic filters documentação.

REST

Para filtrar recursos, faça um pedido GET ao método list dos seguintes recursos e inclua o campo de filtro:

• Para instâncias de VM, use o método instances.list().
• Para instantâneos, 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 na zona us-central1-a com uma etiqueta que tenha um par de chave-valor de env:dev, defina o campo de filtro como labels.env:dev no seu pedido list. Se 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 filter documentação na referência da API Compute Engine.

Relação entre etiquetas e tags de VMs

Anteriormente, as etiquetas e os marcadores estavam relacionados. Por exemplo, se adicionou uma etiqueta webserver:test a uma VM, o Compute Engine adicionou automaticamente uma etiqueta webserver à VM.

Agora, as etiquetas e os marcadores estão separados. Se criar uma etiqueta numa VM, o Compute Engine não cria uma etiqueta para a VM. Se precisar de criar uma etiqueta numa VM, tem de criar a etiqueta manualmente.

Para saber mais sobre as etiquetas e as respetivas utilizações, consulte o artigo Vista geral das etiquetas.

O que se segue?

• Saiba como comparar etiquetas e etiquetas de rede.
• Saiba como gerir etiquetas para recursos do Compute Engine.
• Reveja o parâmetro de consulta filter para saber mais sobre a filtragem.