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.

    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.

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 a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para definir ou remover metadados personalizados das 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 de zona, faça o seguinte:
    • 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

Também é possível conseguir essas permissões 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 de zona, 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 atual de metadados personalizados para metadados de zona chamada project-zonal-metadata-key, não será possível criar novas chaves de metadados para os metadados de zona nessa zona, 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 no 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 personalizados"

  2. Clique em Editar no topo da página.

  3. Para adicionar novas entradas de metadados personalizados do projeto, faça o seguinte:

    1. Navegue até a parte inferior da página e clique em Adicionar item.
    2. No campo Chave, insira o nome da chave de metadados personalizados.
    3. No campo Valor, insira o valor dos metadados personalizados do projeto.
    4. Opcional. Para adicionar mais entradas de metadados personalizados do projeto, repita as etapas anteriores para cada entrada que você quer adicionar.
    5. Para concluir a adição das entradas de metadados personalizados do projeto, clique em Salvar.

  4. Para editar as entradas atuais de metadados personalizados do projeto, faça o seguinte:

    1. Navegue até a entrada de metadados que você quer editar.
    2. Para atualizar o nome de uma chave específica de metadados personalizados, no campo Chave da entrada, digite o novo nome.
    3. Para atualizar o valor de uma entrada de metadados personalizados do projeto, insira o novo valor no campo Valor da entrada.
    4. Opcional. Para remover uma entrada específica de metadados personalizados do projeto, clique no ícone de exclusão ao lado da entrada.
    5. Para editar várias entradas de metadados personalizados do projeto, repita as etapas anteriores para cada entrada que você quer editar.
    6. Para concluir a edição das entradas de metadados personalizados do projeto, clique em Salvar.

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 de zona

Ao definir metadados personalizados de zona, você adiciona ou atualiza as entradas de metadados de zona das VMs em uma zona específica de um projeto. Você pode fazer o seguinte definindo metadados personalizados de zona:

  • Crie chaves de metadados personalizados para uma zona específica em um projeto e defina metadados para todas as VMs nessa zona no projeto.
  • Atualize os valores das entradas atuais de metadados personalizados de zona para todas as VMs em uma zona específica de um projeto.
  • Para chaves atuais de metadados personalizados que têm valores de metadados do projeto, substitua esses valores em zonas específicas e defina metadados de zona. Depois de definir metadados de zona para essas chaves em uma zona específica, todas as VMs nessa zona do projeto usarão os valores de metadados de zona para as chaves.

O que você precisa levar em consideração ao definir metadados personalizados de zona

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

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

Procedimento

É possível adicionar ou atualizar metadados personalizados de zona em uma zona específica de um projeto usando a CLI do Google Cloud ou REST.

gcloud

  • Para adicionar ou atualizar metadados personalizados de zona, use o comando gcloud compute project-zonal-metadata add.

    gcloud 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 de zona.
    • KEY1, KEY2...: as chaves de metadados personalizados em que você quer adicionar ou atualizar valores de metadados de zona.

    • VALUE1, VALUE2...: os valores de metadados de zona que você quer definir para as chaves atuais e novas de metadados personalizados. 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 atual com metadados do projeto, o Compute Engine substituirá o valor de metadados do projeto da chave na zona especificada pelo valor de metadados de zona especificado. Todas as VMs na zona especificada do projeto herdam esses metadados de zona recém-especificados para a chave, e as VMs em outras zonas continuam a manter os valores de metadados de zona ou de projeto predominantes. Se você fizer atualizações futuras no valor dos metadados do projeto para essa chave, as VMs nessa zona do projeto permanecerão inalteradas e continuarão a usar o valor de metadados de zona da chave.

    • Se a chave de metadados personalizados correspondente for uma nova chave de metadados que não é usada para metadados atuais de projeto ou zona, o Compute Engine criará a chave de metadados personalizados e definirá esse valor como os metadados de zona na zona especificada.

    • Se a chave de metadados personalizados correspondente for uma chave de metadados atual com um valor de metadados de zona na zona especificada:

      • Se o valor de metadados especificado for diferente do valor atual, o Compute Engine atualizará a entrada de metadados de zona com o novo valor.
      • Se o valor de metadados especificado for igual ao valor atual, a entrada de metadados de zona permanecerá inalterada.

Exemplo: adicionar uma nova entrada de metadados personalizados de zona

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados de zona 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 personalizados de zona na zona us-central1-a, execute o seguinte comando:

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

Exemplo: atualizar os valores de uma entrada atual de metadados personalizados de zona

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

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

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

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

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

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados de zona 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 do projeto de value-c. Suponha que você queira definir um valor de metadados de zona value-3 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 metadados do projeto e usa os valores de metadados de zona. As VMs em todas as outras zonas do projeto mantêm seus valores de metadados do projeto ou de zona predominantes para key-3.

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

gcloud 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. 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, uma verificação de consistência será realizada e a solicitação de atualização não será concluída. 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 de zona, faça uma solicitação GET ao método instanceSettings().get.

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

    Substitua:

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

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

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

  2. Para adicionar ou atualizar os metadados de zona, 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 personalizados de zona que você quer adicionar
      • Os metadados personalizados de zona 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 personalizados de zona que você quer adicionar
      • As chaves e os valores dos metadados personalizados de zona atuais que você quer atualizar
      • O valor atual da impressão digital

    PATCH https://compute.googleapis.com/compute/v1/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 de zona.

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

      • Os novos metadados personalizados de zona que você quer adicionar
      • Os metadados personalizados de zona atuais com os valores que você quer atualizar

      Por exemplo, suponha que as chaves atuais de metadados de zona em uma zona específica sejam key-1 e key-2. Se você quiser adicionar uma nova chave, key-3, aos metadados de zona nessa zona e também atualizar os metadados de zona em uma das chaves atuais, key-1, a máscara de atualização deverá ter a seguinte string:

      metadata.items.key1,metadata.items.key3

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

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

    • VALUE1, VALUE2...: os valores de metadados de zona que você quer definir para as chaves atuais e novas de metadados personalizados. 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 atual com metadados do projeto, o Compute Engine substituirá o valor de metadados do projeto da chave na zona especificada pelo valor de metadados de zona especificado. Todas as VMs na zona especificada do projeto herdam esses metadados de zona recém-especificados para a chave, e as VMs em outras zonas continuam a manter os valores de metadados de zona ou de projeto predominantes. Se você fizer atualizações futuras no valor dos metadados do projeto para essa chave, as VMs nessa zona do projeto permanecerão inalteradas e continuarão a usar o valor de metadados de zona da chave.
      • Se a chave de metadados personalizados correspondente for uma nova chave de metadados que não é usada para metadados atuais de projeto ou zona, o Compute Engine criará a chave de metadados personalizados e definirá esse valor como os metadados de zona na zona especificada.

      • Se a chave de metadados personalizados correspondente for uma chave de metadados atual com um valor de metadados de zona na zona especificada:

      • Se o valor de metadados especificado for diferente do valor atual, o Compute Engine atualizará a entrada de metadados de zona com o novo valor.

      • Se o valor de metadados especificado for igual ao valor atual, a entrada de metadados de zona permanecerá inalterada.

Exemplo: adicionar uma nova entrada de metadados personalizados de zona

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados de zona 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 personalizados de zona na zona us-central1-a, crie a seguinte solicitação PATCH:

PATCH https://compute.googleapis.com/compute/v1/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 atual de metadados personalizados de zona

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

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

Para atualizar os valores de metadados de zona 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/v1/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: substituir o valor de metadados do projeto para uma chave e definir um valor de metadados de zona

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados de zona 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 do projeto de value-c. Suponha que você queira definir um valor de metadados de zona value-3 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 metadados do projeto e usa os valores de metadados de zona. As VMs em todas as outras zonas do projeto mantêm seus valores de metadados do projeto ou de zona predominantes para key-3.

Para substituir o valor de metadados do projeto de key-3 e usar o valor de metadados de zona value-3, faça a seguinte solicitação PATCH:

PATCH https://compute.googleapis.com/compute/v1/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

Esta seção fornece informações sobre como remover entradas de metadados personalizados das VMs do Compute Engine de uma das seguintes maneiras:

Remover os metadados personalizados do projeto

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

Console

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

    Acessar a página "Metadados"

  2. Clique em Editar no topo da página.

  3. Navegue até a entrada de metadados que você quer remover e clique no botão "Excluir" ao lado da entrada.

    Repita essa etapa para cada entrada de metadados que você quer remover.

  4. Para concluir a remoção das entradas de metadados personalizados do projeto, clique em Salvar.

gcloud

Para remover metadados personalizados do 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 personalizados de zona

É possível remover metadados personalizados de zona usando a CLI do Google Cloud ou REST.

gcloud

Para remover metadados personalizados de zona, use o comando gcloud compute project-zonal-metadata remove e especifique todas as chaves de metadados que você quer remover usando a flag --keys.

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

Substitua:

  • PROJECT_ID: ID do projeto
  • ZONE: a zona de onde você quer remover os metadados de zona.
  • KEY1, KEY2...: as chaves de metadados personalizados de zona que você quer remover.

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

Exemplo:

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados de zona 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 de zona da zona us-central1-a, execute o comando a seguir.

gcloud 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 as seguintes entradas de metadados personalizados do projeto:

  • "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. 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, uma verificação de consistência será realizada e a solicitação de exclusão não será concluída. 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 de zona.

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

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

  2. Para remover metadados personalizados de zona, faça uma solicitação PATCH ao método instanceSettings().patch excluindo as chaves de metadados, das quais você quer remover os metadados de zona, 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 atuais de metadados personalizados das quais você quer remover os metadados de zona. É 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. Exclua todas as chaves de metadados personalizados que você especificou na máscara de atualizaçã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 vai remover os metadados de zona dessas 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 de zona.

    • PREFIXED_METADATA_KEYS: a lista de todas as chaves atuais de metadados personalizados das quais você quer remover metadados de zona, 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 vai remover os metadados de zona dessas chaves.

      Por exemplo, suponha que as chaves de metadados atuais com metadados de zona sejam key-1, key-2, key-3 e key-4, e você queira remover as entradas de metadados de zona de key-1 e key-2. Nesse caso, a máscara de atualização deverá 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 do projeto disponíveis, as VMs na zona especificada herdarão esses valores. Se a chave de metadados tiver sido definida apenas no nível da zona e não houver um valor de metadados do projeto correspondente para ela, as VMs nessa zona perderão as informações de metadados.

Exemplo:

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados de zona 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 de zona de key-1 e key-2 na zona us-central1-a, faça a solicitação PATCH a seguir.

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 for processada, as VMs na zona us-central1-a terão os metadados personalizados a seguir. As VMs herdam os valores de metadados do projeto para key-1 e key-2, mas retêm os metadados de zona para key-3 e key-4.

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

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 no topo da página.
  4. Na seção Metadados, clique em Excluir item para cada uma das entradas de metadados que você quer remover.
  5. Para confirmar as mudanças e remover os metadados personalizados da instância, clique em Salvar.

gcloud

Para remover os metadados personalizados da instância, 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