Gerenciar tags de recursos

Neste guia, descrevemos como criar e gerenciar tags para recursos do Compute Engine. Uma tag é um par de chave-valor que pode ser anexado a um recurso do Google Cloud Platform. As tags são usadas para várias finalidades, incluindo:

  • Permitir ou negar políticas condicionalmente com base em um recurso ter ou não uma tag específica.
  • Definir origens e destinos nas políticas de firewall da rede global e nas políticas de firewall da rede regional.
  • Organizar recursos de maneira lógica.

Depois de criar uma tag e conceder o acesso apropriado a ela e ao recurso, anexe-a como um par de chave-valor. É possível anexar exatamente um valor a um recurso de uma determinada chave. Por exemplo, se você anexar a tag environment: development, não será possível anexar as tags environment: production ou environment: test. Cada recurso pode ter no máximo 50 pares de chave-valor anexados.

Para anexar tags a recursos, crie um recurso TagBinding que vincule o valor da tag ao recurso do Google Cloud. Para mais informações sobre tags e como elas funcionam, consulte a Visão geral sobre tags.

Antes de começar

  • Leia a Visão geral sobre tags na documentação do Resource Manager.
  • Leia Como criar e gerenciar tags na documentação do Resource Manager.
  • 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
    2. Set a default region and zone.

      3. REST

      Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

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

Permissões

Para gerenciar tags de recursos do Compute Engine, os usuários e as contas de serviço precisam receber o papel tagUser. Para mais informações sobre o papel tagUser, consulte Permissões necessárias.

Recursos suportados

Os recursos a seguir aceitam inclusão de tag apenas após a criação do recurso:

  • Instância de máquina virtual (VM)
  • Disco
  • Grupo gerenciado de instâncias
  • Imagem
  • Snapshot
  • A maioria dos recursos de rede, como rede, sub-rede, firewall e verificação de integridade.

Os recursos a seguir também aceitam inclusão de tag durante a criação do recurso:

  • Instância de VM
  • Disco

Como adicionar tags a um recurso

As tags que já existem podem ser anexadas a determinados recursos depois que o recurso é criado, seguindo as instruções abaixo.

Console

Dependendo do tipo de recurso, as etapas específicas podem ser um pouco diferentes. Por exemplo, as etapas a seguir anexam uma tag a uma VM:

  1. No console do Google Cloud, acesse a página Instâncias de VMs.

    Acessar instâncias de VM

  2. Selecione o projeto e clique em Continuar.

  3. Na coluna Nome, clique no nome da VM em que você quer adicionar tags.

  4. Na página Detalhes da VM, siga estas etapas:

    1. Clique em Editar.
    2. Na seção Básico, clique em Gerenciar tags e adicione as tags que você quer na instância.
    3. Clique em Save.

gcloud

Para consultar instruções detalhadas sobre como usar essas flags, leia Anexar uma tag a um recurso na documentação do Resource Manager.

Por exemplo, o comando a seguir anexa uma tag a uma VM:

gcloud resource-manager tags bindings create \
    --location LOCATION_NAME \
    --tag-value=tagValues/TAGVALUE_ID \
    --parent=//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID

Substitua:

  • LOCATION_NAME: a região do recurso de destino, como us-central1
  • TAGVALUE_ID: o ID numérico do valor da tag
  • PROJECT_NUMBER: o ID numérico do seu projeto
  • ZONE: o nome da zona, como us-central1-a
  • VM_ID: o ID numérico da instância da VM

API

Para anexar uma tag a um recurso, primeiro crie uma representação JSON de uma vinculação de tags que inclua o ID permanente ou o nome com namespace do valor da tag e o ID permanente do recurso. Para mais informações sobre o formato de uma vinculação de tags, consulte a referência de TagBinding.

Para anexar a tag a um recurso zonal, como uma instância de VM, use o método tagBindings.create com o endpoint regional em que o recurso está localizado. Exemplo:

POST https://LOCATION-cloudresourcemanager.googleapis.com/v3/tagBindings

O corpo da solicitação pode ser um destes:

{
  "parent": "//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID",
  "tagValue": "tagValue/TAGVALUE_ID"
}

Ou este:

{
  "parent": "//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID",
  "tagValueNamespacedName": TAGVALUE_NAMESPACED_NAME
}

Substitua:

  • LOCATION: o local de onde o recurso de destino é
  • PROJECT_NUMBER: o ID numérico do seu projeto
  • ZONE: o nome da zona, como us-central1-a
  • VM_ID: o ID numérico da VM
  • TAGVALUE_ID: o ID permanente do valor da tag anexado; por exemplo: 4567890123
  • TAGVALUE_NAMESPACED_NAME é o nome com namespace do valor da tag anexado e tem o formato: parentNamespace/tagKeyShortName/tagValueShortName

Adicionar tags a um recurso durante a criação dele

Em determinados cenários, convém incluir tags nos recursos durante a criação deles, e não depois. Por exemplo, é recomendável aplicar tags de firewall a políticas de rede ao criar o recurso do Cloud Next Generation Firewall.

Console

Dependendo do tipo de recurso, as etapas específicas podem ser um pouco diferentes. As etapas a seguir são para uma VM:

  1. No console do Google Cloud, acesse a página Instâncias de VMs.

    Acessar instâncias de VM

  2. Selecione o projeto e clique em Continuar.

  3. Clique em Criar instância.

  4. Clique em Gerenciar tags e rótulos.

  5. Clique em Adicionar tags.

  6. Siga as instruções no painel lateral para selecionar as tags a serem adicionadas à instância.

  7. Clique em Save.

  8. Conclua outras etapas em Criar e iniciar uma instância da VM para concluir a criação da instância.

gcloud

Para anexar uma tag a um recurso durante a criação dele, adicione a flag --resource-manager-tags com o respectivo comando create. Por exemplo, para anexar uma tag a uma VM, use o seguinte comando:

gcloud compute instances create INSTANCE_NAME --resource-manager-tags=tagKeys/TAGKEY_ID=tagValues/TAGVALUE_ID

Substitua:

  • INSTANCE_NAME: o nome da instância
  • TAGKEY_ID: o ID numérico do número da chave da tag
  • TAGVALUE_ID: o ID numérico permanente do valor da tag anexado; por exemplo: 4567890123

Especifique várias tags separando-as por vírgula, por exemplo, TAGKEY1=TAGVALUE1,TAGKEY2=TAGVALUE2.

API

Faça uma solicitação POST para o seguinte URL:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT/zones/ZONE/instances

Inclua o corpo da solicitação JSON a seguir:

{
  "name": INSTANCE_NAME,
  "params": {
    "resourceManagerTags": {
      "tagKeys/TAGKEY_ID: "tagValues/TAGVALUE_ID",
    },
  }
  // other fields omitted
}

Substitua:

  • INSTANCE_NAME: o nome da instância
  • TAGKEY_ID: o ID numérico do número da chave da tag
  • TAGVALUE_ID: o ID numérico permanente do valor da tag anexado; por exemplo: 4567890123

Como remover uma tag de um recurso

É possível desanexar uma tag de um recurso excluindo o recurso de vinculação de tags.

Para ver instruções sobre como remover tags, consulte Como remover uma tag de um recurso na documentação do Resource Manager.

Console

Dependendo do tipo de recurso, as etapas específicas podem ser um pouco diferentes. Por exemplo, as etapas a seguir removem uma tag de uma VM:

  1. No console do Google Cloud, acesse a página Instâncias de VMs.

    Acessar instâncias de VM

  2. Selecione o projeto e clique em Continuar.

  3. Na coluna Nome, clique no nome da VM em que você quer adicionar tags.

  4. Na página Detalhes da VM, siga estas etapas:

    1. Clique em Editar.
    2. Na seção Básico, clique em Gerenciar tags e remova as tags que você quer da instância.
    3. Clique em Save.

gcloud

O exemplo a seguir remove uma tag de uma VM usando a gcloud CLI:

gcloud resource-manager tags bindings delete \
--location LOCATION_NAME \
--tag-value=tagValues/TAGVALUE_ID \
--parent //compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instancesVM_ID

Substitua:

  • LOCATION_NAME: a região do recurso de destino, como us-central1
  • TAGVALUE_ID: o ID numérico da chave da tag
  • PROJECT_NUMBER: o ID numérico do seu projeto
  • ZONE: o nome da zona, como us-central1-a
  • VM_ID: o ID numérico da instância da VM

Para atualizar ou substituir uma vinculação de tags que já existe por outra, remova a vinculação de tags antiga e anexe a nova.

API

Para excluir uma vinculação de tags anexada a um recurso, como uma VM, use o método tagBindings.delete com o endpoint regional em que o recurso está localizado.

DELETE https://LOCATION-cloudresourcemanager.googleapis.com/v3/{name=TAGBINDINGS_NAME}

Em que:

  • TAGBINDINGS_NAME é o ID permanente da TagBinding; por exemplo: tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F1234567890/tagValues/567890123456.

  • LOCATION é o endpoint regional do recurso; por exemplo: us-central1.

Como ver tags anexadas a um recurso

Para ver instruções detalhadas sobre como listar tags, consulte Como listar tags anexadas a um recurso na documentação do Resource Manager.

Console

Dependendo do tipo de recurso, as etapas específicas podem ser um pouco diferentes. Por exemplo, as etapas a seguir mostram como ver as tags de uma VM:

  1. No console do Google Cloud, acesse a página Instâncias de VMs.

    Acessar instâncias de VM

  2. Selecione o projeto e clique em Continuar.

  3. Na coluna Nome, clique no nome da VM com as tags que você quer ver.

  4. Na página de detalhes Instância da VM, procure tags na seção Tags.

gcloud

Para ver uma lista de vinculações de tags anexadas a um recurso, use o comando gcloud resource-manager tags bindings list: Se você adicionar a flag --effective, também retornará uma lista de tags herdadas por esse recurso. Exemplo:

gcloud resource-manager tags bindings list \
    --location=LOCATION_NAME \
    --parent //compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID

Substitua:

  • LOCATION_NAME: a região do recurso de destino, como us-central1
  • PROJECT_NUMBER: o ID numérico do seu projeto
  • ZONE: o nome da zona, como us-central1-a
  • VM_ID: o ID numérico da instância da VM

Se você adicionar a flag --effective ao comando tags bindings list, também retornará uma lista de todas as tags herdadas por esse recurso. Você receberá uma resposta semelhante a esta:

namespacedTagKey: 961309089256/environment
namespacedTagValue: 961309089256/environment/production
tagKey: tagKeys/417628178507
tagValue: tagValues/247197504380
inherited: true

Se todas as tags avaliadas em um recurso forem anexadas diretamente, o campo inherited será falso e ficará omitido.

API

Para listar as vinculações de tags anexadas a um recurso regional, como instâncias do Compute Engine, use o método tagBindings.list com o endpoint regional onde seu recurso está localizado. Exemplo:

GET https://LOCATION_NAME-cloudresourcemanager.googleapis.com/v3/tagBindings

{
    "parent": "//compute.googleapis.com/projects/PROJECT_NUMBER/zones/ZONE/instances/VM_ID"
}

Substitua:

  • LOCATION_NAME: a região do recurso de destino, como us-central1
  • PROJECT_NUMBER: o ID numérico do seu projeto
  • ZONE: o nome da zona, como us-central1-a
  • VM_ID: o ID numérico da instância da VM

A seguir