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
- Para usar os exemplos de linha de comando deste guia, siga estas etapas:
- Instale ou atualize a ferramenta de linha de comando gcloud para a versão mais recente.
- 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.
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
No Console do Google Cloud, acesse a página Criar uma instância.
Em Rótulos, clique em Adicionar rótulo.
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
- 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.
- Marque as caixas de seleção referentes aos recursos que terão marcadores adicionados.
- Clique em Mostrar painel de informações para expandir a coluna de rótulos.
- Atualize ou adicione os novos marcadores desejados.
- 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
- 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.
- Marque as caixas de seleção ao lado dos recursos com os rótulos que serão removidos.
- Clique em Mostrar painel de informações para expandir a coluna de rótulos.
- Clique no
X
ao lado dos rótulos que você quer remover. - 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
- 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
- Saiba como adicionar tags de rede.
- Saiba mais sobre filtragem.