Como rotular recursos

O rótulo é uma maneira leve de agrupar recursos relacionados ou associados entre si. Por exemplo, uma prática comum é usá-lo para separar os recursos destinados a produção, testes ou desenvolvimento. Isso facilita a busca por recursos pertencentes a cada estágio de desenvolvimento. Os rótulos podem ser vmrole:webserver, environment:production, location:west e assim por diante. Sempre adicione rótulos como pares de chave-valor:

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

Aplique marcadores a estes recursos:

  • Instâncias de máquina virtual
  • Regras de encaminhamento
  • Imagens
  • discos permanentes
  • Snapshots de disco permanente
  • Buckets do Cloud Storage
  • Endereços IP externos estáticos (beta)
  • Túneis VPN (beta)

Depois de adicionar rótulos aos recursos, aproveite algumas funcionalidades (como a filtragem aninhada) para realizar pesquisas mais precisas dos recursos usando rótulos.

Antes de começar

Restrições

  • Atribua até 64 marcadores a cada recurso.

    Formato do rótulo

  • As chaves e os valores dos rótulos precisam estar em conformidade com a seguinte expressão regex:

    • As chaves e os valores não podem ter mais de 63 caracteres cada.
    • As chaves e os valores podem conter apenas os seguintes elementos:
      • Letras minúsculas
      • Caracteres numéricos
      • Sublinhados
      • Hifens
    • Caracteres internacionais são permitidos.
    • As chaves de rótulos precisam começar com letra minúscula.
    • As chaves do rótulo não podem estar vazias.

Como criar recursos com rótulos

Ao criar um novo recurso, você pode aplicar marcadores a ele.

Console

  1. No Console do Google Cloud, acesse a página Criar uma instância.

    Acesse "Criar uma instância"

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

  3. Continue o processo de criação.

gcloud

Ao criar o recurso, inclua a sinalização --labels, seguida por uma lista separada por vírgulas de pares de chave-valor de rótulos. Por exemplo:

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

A mesma sinalização também se aplica durante a criação imagens e discos.

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 corpo da solicitação para criar uma instância de VM tem os seguintes rótulos:

body = {
  "name": "[INSTANCE_NAME]",
  "machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
   ...,
  "labels": [{
    "key": "webserver",
    "value": "backend"
    },
    {
    "key": "media",
    "value": "images"
   }]
 }

A mesma propriedade também pode ser aplicada durante a criação de imagens e discos.

Como adicionar ou atualizar marcadores a recursos existentes

Você pode adicionar marcadores ou atualizar os existentes em recursos.

Console

  1. Acesse a página do recurso no qual quer adicionar marcadores.
  2. Marque as caixas de seleção referentes aos recursos que terão marcadores adicionados.
  3. Clique em Mostrar painel de informações para expandir a coluna de rótulos.
  4. Atualize ou adicione os novos marcadores desejados.
  5. Salve as alterações.

gcloud

Na ferramenta de linha de comando gcloud, use o subcomando update com a sinalização --add-labels para adicionar ou alterar um rótulo. Por exemplo, para adicionar um rótulo a um disco, use o subcomando gcloud compute disks update [DISK] --add-labels:

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

Se você fornecer uma chave de rótulo que já existe, a ferramenta atualizará a chave atual com o novo valor do rótulo. Se você fornecer uma nova chave, a ferramenta adicionará essa chave à lista de rótulos.

Para instâncias, snapshots e imagens, use os comandos gcloud compute instances, gcloud compute snapshots ou gcloud compute images.

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, no snippet a seguir, uma solicitação foi enviada para o método setLabels de uma instância. Também é possível fazer uma solicitação ao método setLabels de um disco, um snapshot ou uma imagem:

Request

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

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

Da mesma maneira, é possível adicionar rótulos a recursos especificando o objeto labels durante a criação do recurso.

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. Isso é necessário apenas para solicitações de API. O Console do Cloud e a gcloud não exigem uma impressão digital.

Para receber a impressão digital de rótulo mais atualizada e poder fazer uma solicitação, envie uma solicitação GET ao recurso correspondente. Por exemplo, no snippet a seguir, você recebe o labelsFingerprint de uma instância. Crie uma solicitação semelhante para um disco, um snapshot ou uma imagem.

Procure a propriedade labelFingerprint:

Request

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

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="
}

Como remover um rótulo

Console

  1. Acesse a página do recurso no qual quer adicionar marcadores.
  2. Marque as caixas de seleção ao lado dos recursos com os rótulos que serão removidos.
  3. Clique em Mostrar painel de informações para expandir a coluna de rótulos.
  4. Clique no X ao lado dos rótulos que você quer remover.
  5. Salve as alterações.

gcloud

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

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

Para snapshots e imagens, use as coleções gcloud compute snapshots ou gcloud compute images.

API

Na API, faça uma solicitação POST ao método setLabels do recurso de API apropriado: instâncias, discos ou snapshots.

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://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

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

Como filtrar pesquisas usando marcadores

Você pode pesquisar recursos e filtrar os resultados usando marcadores.

Console

  1. Acesse a página do recurso no qual quer adicionar marcadores.
    • Para instâncias, acesse a página Instâncias de VMs.
    • Para discos, acesse a página Discos.
    • Para instantâneos, acesse a página Instantâneos.
    • Para imagens, acesse a página Imagens.
    • Se solicitado, selecione o projeto e clique em Continuar.
    • Na barra de pesquisa, comece a digitar labels. e a barra de pesquisa listará automaticamente os rótulos com que é possível filtrar.

gcloud

Na gcloud, crie uma solicitação list e use a sinalização --filter. Para filtrar rótulos, use a sintaxe 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 conseguir a documentação completa sobre a sintaxe do filtro na ferramenta gcloud, consulte a documentação de gcloud topic filters.

API

Na API, faça uma solicitação de lista com um parâmetro de consulta filter codificado por URL. Por exemplo, para filtrar com base em uma chave de rótulo env que é igual ao valor dev, crie a seguinte solicitação GET:

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 instância e tags de rede

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

Agora, os rótulos e as tags são separados. Se você criar um rótulo em uma instância, o Compute Engine não criará uma tag para ela. Se você precisar criar uma tag em uma instância, deverá fazer isso manualmente.

Consulte a página Tags de rede para aprender a criar tags.

A seguir