Como rotular recursos

Um rótulo é uma maneira descomplicada de agrupar recursos relacionados ou associados entre si. Por exemplo, uma prática comum é usá-lo para separar os recursos destinados a produção, preparo ou desenvolvimento. Isso facilita a busca por recursos pertencentes a cada estágio de desenvolvimento, quando necessário. 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 (beta)
  • Imagens
  • discos permanentes
  • Snapshots de disco permanente
  • 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 os rótulos.

Antes de começar

Restrições

Formato do marcador

  • As chaves e os valores de rótulo precisam seguir este formato:

    • Chaves e valores não podem ter mais de 63 caracteres.
    • 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 marcadores precisam começar com letra minúscula.
    • As chaves do rótulo não podem estar vazias.

Como criar recursos com marcadores

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

Console

  1. Acesse a página Criar uma instância.

    Acessar a página "Criar uma instância"

  2. Expanda a seção Gerenciamento, segurança, discos, rede, locatário único.
  3. Em Gerenciamento, especifique os Rótulos que você quer adicionar a esse recurso.
  4. 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. 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 incluir um novo recurso, adicione a propriedade labels ao 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 respectiva página de recursos em que você quer adicionar rótulos.
  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 marcadores.
  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 --update-labels para adicionar ou alterar um rótulo. Por exemplo, para incluir um rótulo em um disco, use o subcomando gcloud compute disks update [DISK] --update-labels:

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

Se você informar uma chave de rótulo que já existe, a ferramenta atualizará a chave atual com o novo valor do rótulo. Se você informar 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 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 marcador para solicitações da API

Ao atualizar ou incluir 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 ferramenta 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 respectiva página de recursos em que você quer adicionar rótulos.
  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 marcadores 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. 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.

Informe 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). 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 respectiva página de recursos em que você quer adicionar rótulos.

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 acessar 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

Antes, 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. Caso você precise criar uma tag em uma instância, terá que fazer isso manualmente.

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

A seguir