Definir e remover metadados personalizados

Cada entrada de metadados é armazenada no servidor de metadados como pares de chave-valor. As chaves de metadados diferenciam maiúsculas de minúsculas. Suas chaves podem ser predefinidas ou personalizadas.

Com os metadados personalizados, é possível criar e usar seus próprios pares de chave-valor de metadados em uma VM individual ou um projeto. É possível adicionar novas chaves de metadados personalizadas, atualizar os valores das chaves existentes e remover entradas de metadados personalizados quando não precisar delas. Definir metadados personalizados é útil para transmitir valores arbitrários às VMs em um projeto. Também é útil para criar scripts de inicialização e desligamento.

Este documento contém informações sobre como fazer o seguinte:

Antes de começar

  • Revise os conceitos básicos de como os metadados de VM para o Compute Engine são definidos, categorizados e organizados. Para mais informações, consulte Sobre metadados da VM.

  • 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.

    Selecione a guia para como planeja usar as amostras nesta página:

    Console

    Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud, não é necessário configurar a autenticação.

    gcloud

    1. Instale a Google Cloud CLI e inicialize-a executando o seguinte comando: 

      gcloud init
    2. Defina uma região e uma zona padrão.

    REST

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

      Instale a Google Cloud CLI e inicialize-a executando o seguinte comando: 

      gcloud init

Funções exigidas

Para ter as permissões necessárias para definir ou remover metadados personalizados nas VMs, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esses papéis predefinidos contêm as permissões necessárias para definir ou remover metadados personalizados nas VMs. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para definir ou remover metadados personalizados nas VMs:

  • Se as VMs usarem contas de serviço: iam.serviceAccounts.actAs nas contas de serviço ou no projeto
  • Para adicionar, atualizar ou remover metadados personalizados do projeto, faça o seguinte:
    • compute.projects.get no projeto
    • compute.projects.setCommonInstanceMetadata no projeto
  • Para adicionar, atualizar ou remover metadados personalizados zonais do projeto:
    • compute.instanceSettings.get nas configurações da instância na zona necessária do projeto
    • compute.instanceSettings.update nas configurações da instância na zona necessária do projeto
  • Para adicionar, atualizar ou remover metadados de instâncias personalizadas:
    • compute.instances.get na VM
    • compute.instances.setMetadata na VM

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Limitações

Com o Compute Engine, é possível impor um limite total combinado de 512 KB para todas as entradas de metadados. Os limites máximos de tamanho também são aplicados a key e value da seguinte maneira:

  • Cada metadado key tem um limite máximo de 128 bytes.

  • Cada metadado key diferencia maiúsculas de minúsculas

    No caso de metadados zonais do projeto, o Compute Engine não permite criar duas chaves de metadados separadas com a mesma string, mesmo que elas sejam gravadas em casos diferentes. Por exemplo, se você tiver uma chave de metadados zonal de projeto chamada project-zonal-metadata-key, não será possível criar novas chaves de metadados zonais do projeto, como Project-Zonal-Metadata-Key, PROJECT-ZONAL-METADATA-KEY, ou quaisquer outras variações da mesma string.

  • Cada metadado value tem um limite máximo de 256 KB.

  • Cada metadado value diferencia maiúsculas de minúsculas, exceto valores booleanos.

Por exemplo, as chaves SSH são armazenadas como metadados personalizados na chave ssh-keys. Se o value ou o conteúdo de metadados dessa chave ultrapassar o limite de 256 KB, você não poderá adicionar mais chaves SSH. Se isso ocorrer, remova as chaves não utilizadas para liberar espaço de metadados para novas chaves.

Além disso, se você fornecer diretamente o conteúdo do script de inicialização ou desligamento, esse conteúdo também poderá ser armazenado como metadados personalizados e contribuir com essas limitações de tamanho. Para evitar isso, armazene o script de inicialização ou desligamento como um arquivo hospedado em um local externo, como o Cloud Storage, e forneça o URL do script de inicialização ao criar uma VM. Dessa forma, esses arquivos são transferidos por download para a VM e não são armazenados no servidor de metadados.

Valores booleanos

Em campos que aceitam valores booleanos, TRUE ou FALSE, também é possível usar os seguintes valores:

Status Valores alternativos
TRUE Y, Yes, 1
FALSE N, No, 0

Valores booleanos não diferenciam maiúsculas de minúsculas. Por exemplo, para desativar um recurso, use False, false ou FALSE.

Definir metadados personalizados em VMs

Nesta seção, você encontra informações sobre como adicionar ou atualizar metadados personalizados para as VMs do Compute Engine de uma das seguintes maneiras:

Definir metadados personalizados do projeto

É possível adicionar ou atualizar os metadados personalizados de todas as instâncias de um projeto usando o console do Google Cloud, a CLI do Google Cloud ou REST.

Use estas instruções para aplicar configurações de metadados a todas as VMs do projeto. Por exemplo, se você definir um par de metadados de baz=bat para todo o projeto, esse par será aplicado automaticamente a todas as VMs do projeto.

Console

  1. No Console do Google Cloud, acesse a página Metadados.

    Acessar a página "Metadados"

  2. Clique em Editar.
  3. Adicione ou edite uma entrada de metadados.
  4. Salve as alterações.

gcloud

Use o comando project-info add-metadata.

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

Substitua:

  • KEY: o nome da chave de metadados
  • VALUE: o valor armazenado para esta chave

Exemplo

Por exemplo, para definir duas novas entradas foo=bar e baz=bat em um projeto, execute o seguinte comando:

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

Opcionalmente, é possível especificar um ou mais arquivos que terão os metadados lidos com o uso da sinalização --metadata-from-file.

REST

  1. Opcional. Para realizar um bloqueio otimista, você tem a opção de fornecer uma impressão digital.

    Uma impressão digital é uma string aleatória de caracteres gerados pelo Compute Engine. A impressão digital muda após cada solicitação. Se você fornecer uma impressão digital incompatível, sua solicitação será rejeitada.

    Se você não fornecer uma impressão digital, nenhuma verificação de consistência será realizada e a solicitação projects().setCommonInstanceMetadata será realizada. Esse comportamento é diferente dos métodos instances().setMetadata e instanceSettings().patch, em que uma impressão digital é sempre necessária.

    Para receber a impressão digital atual de um projeto, chame o método project().get.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID

    A saída será assim:

    {
  "name": "myproject",
  "commonInstanceMetadata": {
    "kind": "compute#metadata",
    "fingerprint": "FikclA7UBC0=",
    ...
  }
}

  2. Faça uma solicitação para o método projects().setCommonInstanceMetadata e defina seus pares de chave-valor de metadados personalizados:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata

{
  "fingerprint": "FikclA7UBC0=",
  "items": [
    {
    "key": "foo",
    "value": "bar"
    }
  ]
}

Substitua PROJECT_ID pelo ID do projeto.

Definir metadados personalizados zonais do projeto

É possível adicionar ou atualizar as entradas de metadados zonais do projeto para suas VMs de uma das seguintes maneiras:

  • É possível adicionar novas chaves de metadados personalizadas no nível da zona do projeto e definir os valores de metadados de todas as VMs que estão em uma zona específica do projeto.
  • É possível atualizar os valores das chaves de metadados zonais do projeto personalizado atuais para todas as VMs que estão em uma zona específica de um projeto.
  • Para chaves de metadados do projeto que já têm valores de todo o projeto, é possível modificar esses valores para todas as VMs em uma zona específica e especificar essas VMs para usar os valores zonais do projeto.

O que você precisa observar antes de definir os metadados de zona do projeto personalizados

As entradas de metadados zonais do projeto e o projeto são armazenadas no mesmo diretório project/. Se você definir valores diferentes para as mesmas chaves de metadados personalizadas para VMs no nível do projeto e da zona do projeto, os valores de metadados zonais do projeto para essas chaves terão precedência sobre os metadados de todo o projeto. nas respectivas zonas.

  • Se você adicionar um valor de metadados de zona do projeto a uma chave de metadados que já tenha um valor para todo o projeto, o Compute Engine vai modificar o valor de todo o projeto para as VMs nessa zona especificada e atualizar o diretório /project com o valor de zona do projeto.
  • Se você adicionar um novo valor de metadados para todo o projeto a uma chave de metadados que já tem um valor de zona do projeto, nada será alterado. O Compute Engine mantém o valor de zona do projeto no diretório /project na zona específica.
  • Se você não especificar um valor de zona do projeto para uma chave de metadados personalizada em uma zona específica, mas a chave tiver um valor para todo o projeto, suas VMs continuarão tendo os valores de todo o projeto nessas zonas. de dois minutos.

Procedimento

É possível adicionar ou atualizar os metadados personalizados de todas as instâncias de VM em uma zona específica de um projeto usando a CLI do Google Cloud ou REST.

gcloud

  • Para adicionar ou atualizar metadados personalizados zonais do projeto, use o comando gcloud beta compute project-zonal-metadata add.

    gcloud beta compute project-zonal-metadata add \
  --zone=ZONE \
  --project=PROJECT_ID  \
  --metadata=KEY1=VALUE1,KEY2=VALUE2,...

    Substitua:

    • PROJECT_ID: ID do projeto;
    • ZONE: a zona em que você quer adicionar ou atualizar os metadados zonais do projeto.
    • KEY1, KEY2...: as chaves personalizadas de metadados zonais do projeto em que você quer adicionar ou atualizar valores.

    • VALUE1, VALUE2...: os valores de metadados zonais do projeto que você quer definir para as chaves de metadados zonais novas e atuais. Dependendo do valor e da chave de metadados personalizados, acontece uma das seguintes situações:

    • Se a chave de metadados personalizados correspondente for uma chave existente para todo o projeto, o Compute Engine modificará o valor de metadados de todo o projeto e usará o valor zonal do projeto para todas as VMs na zona especificada. Todas as VMs na zona especificada herdam o novo valor de zona do projeto. Se você fizer alterações futuras no valor da mesma chave para todo o projeto, essas atualizações não afetarão o valor de zona do projeto, e as VMs nessa zona continuarão tendo o valor zonal do projeto como seus metadados do projeto.

    • Se a chave de metadados personalizados correspondente for uma chave de metadados zonais do projeto atual e o valor de metadados especificado for um novo, o Compute Engine atualizará o valor zonal do projeto da chave atual.

    • Se a chave de metadados personalizados correspondente for uma nova que não faça parte dos metadados atuais do projeto ou da zona do projeto, o Compute Engine criará a chave de metadados por zona do projeto e adicionará esse valor de metadados.

    • Se a chave de metadados personalizados correspondente for uma chave de metadados zonal do projeto atual e o valor de metadados especificado for igual ao atual, a entrada de metadados zonais do projeto permanecerá inalterada.

Exemplo: adicionar uma nova entrada personalizada de metadados zonais do projeto

Por exemplo, considere um projeto chamado my-project com os seguintes metadados personalizados:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"value-1" e "key-2":"value-2"

Para adicionar "key-4":"value-4" como um novo par de metadados zonal de projeto personalizado na zona us-central1-a, execute o seguinte comando:

gcloud beta compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

Exemplo: atualizar os valores de uma entrada de metadados zonais de projetos personalizados atuais

Considere o mesmo projeto de exemplo my-project, que agora tem os seguintes metadados personalizados:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"value-1", "key-2":"value-2" e "key-4":"value-4"

Para atualizar os valores de metadados zonais do projeto de key-1 e key-4 na zona us-cerntral1-a com novos valores, execute o comando a seguir.

gcloud beta compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

Exemplo: modificar o valor do projeto para uma chave de metadados e usar um valor de zona do projeto

Considere o mesmo projeto de exemplo my-project, que agora tem os seguintes metadados personalizados:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2" e "key-4":"new-value-4"

Neste projeto de exemplo, considere key-3, que tem um valor de metadados de todo o projeto de value-c. Suponha que você queira definir um valor value-3 de metadados zonais do projeto para essa chave em todas as VMs na zona us-central1-a. Quando você executa a operação, para todas as VMs na zona us-central1-a, o Compute Engine substitui os valores de todo o projeto e usa os valores zonais do projeto. As VMs em todas as outras zonas do projeto mantêm os valores predominantes de metadados zonais em todo o projeto ou para key-3.

Para substituir o valor de key-3 em todo o projeto e definir um valor de zona do projeto, execute o seguinte comando:

gcloud beta compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

  1. Encontre a impressão digital atual e confira os pares de chave-valor existentes para o projeto nessa zona.

    Para realizar o bloqueio otimista, é necessário fornecer uma impressão digital. Uma impressão digital é uma string aleatória de caracteres gerados pelo Compute Engine. A impressão digital é alterada sempre que você faz uma solicitação para adicionar, atualizar ou remover metadados de zona do projeto. Se você fornecer uma impressão digital incompatível, o Compute Engine rejeitará a solicitação.

    Se você não fornecer uma impressão digital, será realizada uma verificação de consistência e a solicitação de atualização não será realizada. Isso funciona para que apenas uma atualização possa ser feita por vez, evitando colisões. Esse comportamento corresponde a instances().setMetadata, em que uma impressão digital é sempre necessária.

    Para conseguir a impressão digital atual dos metadados zonais do projeto, faça uma solicitação GET para o método instanceSettings().get.

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings

    Substitua:

    • PROJECT_ID: ID do projeto;
    • ZONE: a zona em que você quer definir os metadados zonais do projeto.

    Este é um exemplo de saída para essa solicitação:

        {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }

  2. Para adicionar ou atualizar os metadados zonais do projeto, faça uma solicitação PATCH ao método instanceSettings().patch. Forneça os seguintes itens com sua solicitação:

    • Uma máscara de atualização. Use o parâmetro de consulta update_mask. A máscara de atualização precisa conter as chaves de metadados para:

      • Os novos metadados zonais do projeto personalizados que você quer adicionar
      • Os metadados zonais do projeto personalizados atuais com os valores que você quer atualizar

      É preciso adicionar a string metadata.items. como prefixo para cada chave, por exemplo, metadata.items.key1,metadata.items.key3.

    • No corpo da solicitação, informe o seguinte:

      • as chaves e os valores dos novos metadados de zona do projeto personalizados que você quer adicionar;
      • As chaves e os valores dos metadados zonais do projeto personalizado que você quer atualizar
      • O valor atual da impressão digital

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
      "KEY1": "VALUE1",
      "KEY2": "VALUE2",
      ...
    }
  }
}

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • ZONE: a zona em que você quer definir os metadados zonais do projeto.

    • PREFIXED_METADATA_KEYS: a lista de chaves de metadados das seguintes chaves, em que cada chave é prefixada com a string metadata.items. :

      • Os novos metadados zonais do projeto personalizados que você quer adicionar
      • Os metadados zonais do projeto personalizados atuais com os valores que você quer atualizar

      Por exemplo, suponha que as chaves de metadados zonais do projeto atual sejam key-1 e key-2. Se você quiser adicionar uma nova chave de metadados key-3 e também atualizar uma das chaves de metadados atuais, key-1, sua máscara de atualização precisará ter a seguinte string:

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: o valor atual da impressão digital.

    • KEY1, KEY2...: as chaves personalizadas de metadados zonais do projeto em que você quer adicionar ou atualizar valores. Especifique todas as chaves personalizadas de metadados zonais do projeto especificadas na máscara de atualização.

    • VALUE1, VALUE2...: os valores de metadados zonais do projeto que você quer definir para as chaves de metadados zonais novas e atuais. Dependendo do valor e da chave de metadados personalizados, acontece uma das seguintes situações:

      • Se a chave de metadados personalizados correspondente for uma chave existente para todo o projeto, o Compute Engine modificará o valor de metadados de todo o projeto e usará o valor zonal do projeto para todas as VMs na zona especificada. Todas as VMs na zona especificada herdam o novo valor de zona do projeto. Se você fizer alterações futuras no valor da mesma chave para todo o projeto, essas atualizações não afetarão o valor por zona do projeto, e as VMs nessa zona continuarão tendo o valor zonal do projeto como os metadados do projeto.
      • Se a chave de metadados personalizados correspondente for uma chave de metadados zonais do projeto atual e o valor de metadados especificado for um novo, o Compute Engine atualizará o valor zonal do projeto da chave atual.
      • Se a chave de metadados personalizados correspondente for uma nova que não faça parte dos metadados atuais do projeto ou da zona do projeto, o Compute Engine criará a chave de metadados por zona do projeto e adicionará esse valor de metadados.
      • Se a chave de metadados personalizados correspondente for uma chave de metadados zonal do projeto atual e o valor de metadados especificado for igual ao atual, a entrada de metadados zonais do projeto permanecerá inalterada.

Exemplo: adicionar uma nova entrada personalizada de metadados zonais do projeto

Por exemplo, considere um projeto chamado my-project com os seguintes metadados personalizados:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"value-1" e "key-2":"value-2"

Para adicionar "key-4":"value-4" como um novo par de metadados zonal de projeto personalizado na zona us-central1-a, crie a seguinte solicitação PATCH:

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

Exemplo: atualizar os valores de uma entrada de metadados zonais de projetos personalizados atuais

Considere o mesmo projeto de exemplo my-project, que agora tem os seguintes metadados personalizados:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"value-1", "key-2":"value-2" e "key-4":"value-4"

Para atualizar os valores de metadados zonais do projeto de key-1 e key-4 na zona us-cerntral1-a com novos valores, faça a seguinte solicitação PATCH:

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

Exemplo: modificar o valor do projeto para uma chave de metadados e usar um valor de zona do projeto

Considere o mesmo projeto de exemplo my-project, que agora tem os seguintes metadados personalizados:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2" e "key-4":"new-value-4"

Neste projeto de exemplo, considere key-3, que tem um valor de metadados de todo o projeto de value-c. Suponha que você queira definir um valor value-3 de metadados zonais do projeto para essa chave em todas as VMs na zona us-central1-a. Quando você executa a operação, para todas as VMs na zona us-central1-a, o Compute Engine substitui os valores de todo o projeto e usa os valores zonais do projeto. As VMs em todas as outras zonas do projeto mantêm os valores predominantes de metadados zonais em todo o projeto ou para key-3.

Para substituir o valor de metadados em todo o projeto para key-3 e usar o valor de zona personalizado value-3 do projeto, crie a seguinte solicitação PATCH:

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

Definir metadados de instância personalizados

É possível adicionar ou atualizar os metadados personalizados de uma única instância de VM usando o console do Google Cloud, a CLI do Google Cloud ou REST.

É possível definir metadados de instância personalizados de uma das seguintes maneiras:

Adicionar metadados de instância personalizados durante a criação da VM

Use estas instruções para adicionar metadados a uma instância de VM específica no momento da criação.

Console

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

    Acesse "Criar uma instância"

  2. Especifique os detalhes da VM.

  3. Expanda a seção Opções avançadas e faça isto:

    1. Expanda a seção Gerenciamento.
    2. Para adicionar vários pares de chave-valor aos seus metadados personalizados, na seção Metadados, clique em Adicionar item.

  4. Para criar a VM, clique em Criar.

gcloud

Para definir metadados personalizados, use o comando gcloud compute instances create com a sinalização --metadata.

gcloud compute instances create VM_NAME \
    --metadata=KEY=VALUE

Substitua:

  • VM_NAME: o nome da VM
  • KEY: o nome da chave de metadados
  • VALUE: o valor armazenado para esta chave

Exemplo

Por exemplo, para definir uma nova chave foo que tenha o valor bar em uma VM chamada example-instance, execute o seguinte comando:

gcloud compute instances create example-instance \
    --metadata=foo=bar

REST

Use o método instances.insert e forneça os metadados personalizados como parte da propriedade metadata na solicitação:

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

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

Substitua:

  • PROJECT_ID: ID do projeto
  • ZONE: zona em que a VM será criada
  • MACHINE_TYPE: tipo de máquina, predefinida ou personalizada, para a nova VM
  • VM_NAME: nome da nova VM
  • KEY: o nome da chave de metadados
  • VALUE: o valor armazenado para esta chave

Adicionar ou atualizar metadados de instância personalizados em uma VM atual

Use estas instruções para atualizar metadados em uma instância de VM específica que já existe.

Console

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

    Acessar a página "Instâncias de VMs"

  2. Clique na instância em que estão os metadados que você quer atualizar.
  3. Clique no botão Editar, na parte superior da página.
  4. Em Metadados personalizados, clique em Adicionar item ou edite as entradas de metadados atuais.
  5. Salve as alterações.

gcloud

A atualização de metadados da VM com a CLI gcloud é uma ação aditiva. Especifique apenas as chaves de metadados que você quer adicionar ou mudar. Se você especificar uma chave atual, o valor dela será atualizado com o novo valor.

Use o comando instances add-metadata (em inglês).

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

Substitua:

  • VM_NAME: o nome da VM
  • KEY: o nome da chave de metadados
  • VALUE: o valor armazenado para esta chave

Exemplos

Se você quiser adicionar a entrada foo=bar, use:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

Se você quiser mudar a entrada foo=bar para foo=bat, use:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

  1. Encontre a impressão digital atual e veja os pares de chave-valor atuais da VM. Para fazer isso, chame o método instances().get.

    Impressão digital é uma string de caracteres aleatória, gerada pelo Compute Engine e usada para executar o bloqueio otimista. Para atualizar a VM, forneça o valor da impressão digital correspondente. A impressão digital é alterada após cada solicitação. Se você fornecer uma impressão digital não correspondente, sua solicitação será rejeitada. Isso funciona para que apenas uma atualização possa ser feita por vez, evitando colisões.

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

    Substitua:

    • PROJECT_ID: ID do projeto
    • ZONE: a zona em que a VM está localizada.
    • VM_NAME: o nome da VM.

    O resultado será assim:

    {
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
    },
  ...
}

  2. Faça uma solicitação ao método instances().setMetadata. Forneça uma lista dos novos valores de metadados e o valor atual de fingerprint

    Se houver pares de chave-valor que você quer manter na VM, eles precisarão ser incluídos na solicitação com os novos pares de chave-valor.

    Exemplo

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

{
"fingerprint": "zhma6O1w2l8=",
"items": [
  {
    "key": "foo",
    "value": "bar"
  },
  {
    "key": "baz",
    "value": "bat"
  }
]
}

    Substitua:

    • PROJECT_ID: ID do projeto
    • ZONE: a zona em que a VM está localizada.
    • VM_NAME: o nome da VM.

Remover metadados personalizados de VMs

É possível remover metadados personalizados das suas VMs do Compute Engine de uma das seguintes maneiras:

Remover metadados personalizados de todo o projeto

É possível remover metadados personalizados de todo o projeto usando o console do Google Cloud ou a Google Cloud CLI.

Console

  1. No Console do Google Cloud, acesse a página Metadados.

    Acessar a página "Metadados"

  2. Clique em Editar Editar no topo da página.
  3. Na seção Metadados, clique em excluir Excluir item para cada uma das entradas de metadados que você quer remover.
  4. Para confirmar suas alterações e remover os metadados personalizados de todo o projeto, clique em Salvar.

gcloud

Para remover metadados personalizados de todo o projeto, use o comando gcloud compute project-info remove-metadata.

  • Se você quiser remover as entradas de metadados personalizados de chaves específicas, especifique essas chaves usando a sinalização --keys e exclua os valores delas.
gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...
  • Se você quiser remover todos os metadados personalizados da VM, especifique a sinalização --all.
gcloud compute project-info remove-metadata \
    --all

Substitua:

  • KEY1, KEY2...: as chaves de metadados da instância personalizada que você quer remover.

Remover metadados de zona do projeto personalizados

É possível remover metadados zonais do projeto personalizados usando a Google Cloud CLI ou a API Compute Engine.

gcloud

Para remover metadados personalizados zonais do projeto, use o comando gcloud beta compute project-zonal-metadata remove e especifique todas as chaves de metadados que você quer remover usando a sinalização --keys.

gcloud beta compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

Substitua:

  • PROJECT_ID: ID do projeto;
  • ZONE: a zona em que você quer definir os metadados zonais do projeto.
  • KEY1, KEY2...: as chaves personalizadas de metadados zonais do projeto que você quer remover.

Depois de executar o comando, se alguma das chaves especificadas tiver valores de metadados disponíveis para todo o projeto, as VMs na zona especificada herdarão esses valores do projeto. Se a chave de metadados tiver sido definida apenas no nível de zona do projeto e não houver uma chave correspondente em todo o projeto, as VMs perderão essas informações de metadados.

Exemplo:

Considere um exemplo de projeto my-project, que tem os seguintes metadados de projeto personalizado:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" e "key-4":"new-value-4"

Para remover todos os metadados zonais do projeto da zona us-central1-a, execute o comando a seguir.

gcloud beta compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

Depois de executar o comando, as VMs na zona us-central1-a terão os seguintes metadados de projeto personalizados:

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-c"

REST

  1. Encontre a impressão digital atual e confira os pares de chave-valor existentes para o projeto nessa zona.

    Para realizar o bloqueio otimista, é necessário fornecer uma impressão digital. Uma impressão digital é uma string aleatória de caracteres gerados pelo Compute Engine. A impressão digital é alterada sempre que você faz uma solicitação para adicionar, atualizar ou remover metadados de zona do projeto. Se você fornecer uma impressão digital incompatível, o Compute Engine rejeitará a solicitação.

    Se você não fornecer uma impressão digital, será realizada uma verificação de consistência e a solicitação de exclusão não será realizada. Isso funciona para que apenas uma atualização possa ser feita por vez, evitando colisões. Esse comportamento corresponde a instances().setMetadata, em que uma impressão digital é sempre necessária.

    Para encontrar a impressão digital atual de um projeto, chame o método instanceSettings().get.

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings

    Substitua:

    • PROJECT_ID: ID do projeto;
    • ZONE: a zona de onde você quer remover os metadados zonais do projeto.

    Este é um exemplo de saída para essa solicitação:

        {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }

  2. Para remover metadados zonais personalizados do projeto, crie umPATCH um pedidoinstanceSettings().patch método excluindo as chaves de metadados, para as quais você quer remover os metadados zonais do projeto, do corpo da solicitação . Forneça os seguintes itens com sua solicitação:

    • Uma máscara de atualização. Use o parâmetro de consulta update_mask. A máscara de atualização precisa conter todas as chaves de metadados de zona do projeto personalizadas atuais das quais você quer remover os metadados. É preciso adicionar a string metadata.items. como prefixo para cada chave. Por exemplo, metadata.items.key1,metadata.items.key3.
    • No corpo da solicitação, forneça apenas o valor atual da impressão digital. Exclude all the metadata keys that you specified in the update mask. Se você incluir uma das chaves de metadados na máscara de atualização e no corpo da solicitação, o Compute Engine não removerá os metadados zonais do projeto para essas chaves. 
    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
    }
  }
}

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • ZONE: a zona de onde você quer remover os metadados zonais do projeto.

    • PREFIXED_METADATA_KEYS: a lista de todas as chaves de metadados zonais do projeto personalizado que você quer remover, em que cada chave é prefixada com a string metadata.items. . Para garantir que sua solicitação de exclusão seja bem-sucedida, exclua essas chaves de metadados do corpo da solicitação. Se você incluir uma das chaves de metadados na máscara de atualização e no corpo da solicitação, o Compute Engine não removerá os metadados zonais do projeto para essas chaves.

      Por exemplo, suponha que as chaves de metadados zonais do seu projeto atual sejam key-1, key-2, key-3 e key-4, e você quer remover as entradas de metadados zonais do projeto para key-1 e key-2, a máscara de atualização precisará ter a seguinte string:

      metadata.items.key1,metadata.items.key2

    • FINGER_PRINT: o valor atual da impressão digital.

Depois de fazer a solicitação, se alguma das chaves especificadas tiver valores de metadados disponíveis para todo o projeto, as VMs na zona especificada herdarão esses valores do projeto. Se a chave de metadados tiver sido definida apenas no nível de zona do projeto e não houver uma chave correspondente para todo o projeto, as VMs perderão essas informações de metadados.

Exemplo:

Considere um exemplo de projeto my-project, que tem os seguintes metadados de projeto personalizado:

  • Metadados de todo o projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais do projeto na zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" e "key-4":"new-value-4"

Para remover os metadados zonais do projeto para key-1 e key-2 na zona us-central1-a, faça a seguinte solicitação PATCH.

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

Depois que essa solicitação é processada, as VMs na zona us-central1-a têm os metadados de projeto personalizados a seguir. As VMs herdam os valores de metadados de todo o projeto para key-1 e key-2, mas mantêm o valor de zona do projeto para key-3.

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-3"

Remover metadados de instâncias personalizadas

É possível remover metadados de instância personalizados usando o console do Google Cloud, a CLI do Google Cloud ou REST.

Console

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

    Acessar a página "Instâncias de VMs"

  2. Na coluna Nome, clique no nome da VM com os metadados que você quer remover.
  3. Clique em Editar Editar no topo da página.
  4. Na seção Metadados, clique em excluir Excluir item para cada uma das entradas de metadados que você quer remover.
  5. Para confirmar as alterações e remover os metadados da instância personalizada, clique em Salvar.

gcloud

Para remover metadados de instância personalizados, use o comando gcloud compute instances remove-metadata.

  • Se você quiser remover as entradas de metadados personalizados de chaves específicas, especifique essas chaves usando a sinalização --keys e exclua os valores delas.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...
  • Se você quiser remover todos os metadados personalizados da VM, especifique a sinalização --all.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

Substitua:

  • PROJECT_ID: o ID do projeto.
  • ZONE: a zona da VM;
  • VM_NAME: o nome da VM.
  • KEY1, KEY2...: as chaves de metadados da instância personalizada que você quer remover.

REST

  1. Encontre a impressão digital atual e veja os pares de chave-valor atuais da VM. Para fazer isso, chame o método instances().get.

    Impressão digital é uma string de caracteres aleatória, gerada pelo Compute Engine e usada para executar o bloqueio otimista. Para atualizar a VM, forneça o valor da impressão digital correspondente. A impressão digital é alterada após cada solicitação. Se você fornecer uma impressão digital não correspondente, sua solicitação será rejeitada. Isso funciona para que apenas uma atualização possa ser feita por vez, evitando colisões.

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

    Substitua:

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

    O resultado será assim:

    {
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
    {
      "key": "key-1",
      "value": "value-1"
    }
    {
      "key": "key-2",
      "value": "value-2"
    }
    ]
  },
  ...
}

  2. Faça uma solicitação ao método instances().setMetadata. É necessário incluir o valor atual da impressão digital de metadados para que sua solicitação seja bem-sucedida.

    • Para remover todos os pares de chave-valor de metadados personalizados de uma VM, na propriedade items, exclua as chaves de metadados de que você quer remover valores.

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

{
"fingerprint": "FINGER_PRINT"
"items": [
  {
    "key": "KEY1"
    "value": "VALUE1"
  }
  {
    "key": "KEY2"
    "value": "VALUE2"
  }
  ...
]
}

    • Para remover todos os metadados da instância personalizada na VM, exclua completamente a propriedade items.

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

{
"fingerprint": FINGER_PRINT
}

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • ZONE: a zona da VM;
    • VM_NAME: o nome da VM.
    • FINGER_PRINT: o valor atual da impressão digital.
    • KEY1, KEY2...: as chaves de metadados da instância personalizada que você quer remover.
    • VALUE1, VALUE2...: os valores das chaves de metadados da instância personalizada que você quer remover.

A seguir