Defina e remova metadados personalizados

Cada entrada de metadados é armazenada no servidor de metadados como pares de chave-valor. As chaves de metadados são sensíveis a maiúsculas e minúsculas. As chaves podem ser chaves de metadados predefinidas ou personalizadas.

Os metadados personalizados permitem-lhe criar e usar os seus próprios pares de chave-valor de metadados numa VM individual ou num projeto. Pode adicionar novas chaves de metadados personalizados, atualizar os valores das chaves existentes e remover quaisquer entradas de metadados personalizados quando não precisar delas. A definição de metadados personalizados é útil para transmitir valores arbitrários às VMs num projeto. Também é útil para criar scripts de arranque e encerramento.

Este documento fornece informações sobre como fazer o seguinte:

Antes de começar

  • Reveja os princípios básicos de como os metadados de VMs do Compute Engine são definidos, categorizados e organizados. Para mais informações, consulte o artigo Acerca dos metadados de VMs.

  • Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-se no Compute Engine selecionando uma das seguintes opções:

    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. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    2. Set a default region and zone.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

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

Funções necessárias

Para obter as autorizações de que precisa para definir ou remover metadados personalizados em VMs, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para definir ou remover metadados personalizados em VMs. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para definir ou remover metadados personalizados em VMs:

  • Se as suas 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:
    • compute.projects.get no projeto
    • compute.projects.setCommonInstanceMetadata no projeto
  • Para adicionar, atualizar ou remover metadados zonais personalizados:
    • compute.instanceSettings.get nas definições da instância na zona necessária no projeto
    • compute.instanceSettings.update nas definições da instância na zona necessária no projeto
  • Para adicionar, atualizar ou remover metadados de instâncias personalizadas:
    • compute.instances.get na VM
    • compute.instances.setMetadata na VM

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Limitações

As entradas de metadados de VMs têm as seguintes limitações.

Limitações de tamanho

O Compute Engine aplica um limite total combinado de 512 KB para todas as entradas de metadados. Os limites de tamanho máximos também são aplicados a cada key e value da seguinte forma:

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

Por exemplo, as chaves SSH são armazenadas como metadados personalizados na chave ssh-keys key. Se o conteúdo dos metadados ou value desta chave exceder o limite de 256 KB, não pode adicionar mais chaves SSH. Se atingir este limite, considere remover chaves não usadas para libertar espaço de metadados para novas chaves.

Além disso, se fornecer diretamente o conteúdo do script de arranque ou encerramento, o conteúdo destes scripts também pode ser armazenado como metadados personalizados e contar para estas limitações de tamanho. Para evitar esta situação, armazene o script de arranque ou encerramento como um ficheiro alojado numa localização externa, como o Cloud Storage, e faculte o URL do script de arranque quando criar uma VM. Desta forma, estes ficheiros são transferidos para a VM, em vez de serem armazenados no servidor de metadados.

Limitações de maiúsculas e minúsculas de strings

  • Cada metadado key é sensível a maiúsculas e minúsculas.

  • Cada metadado value é sensível a maiúsculas e minúsculas, exceto para valores booleanos.

Limitações de metadados zonais

  • Só pode definir e remover metadados zonais através da CLI gcloud ou da API REST.

  • Não pode criar duas chaves de metadados separadas com a mesma string, mesmo que as chaves estejam escritas em letras diferentes. Por exemplo, se já existir uma chave de metadados personalizada denominada zonal-metadata-key para metadados zonais numa zona específica, não pode criar novas chaves de metadados zonais que sejam variações da mesma string, como Zonal-Metadata-Key ou ZONAL-METADATA-KEY.

  • Não pode definir valores de metadados zonais para chaves SSH, que são armazenadas como metadados personalizados na chave ssh-keys.

Valores booleanos

Para campos que aceitam valores booleanos, TRUE ou FALSE, também pode usar os seguintes valores:

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

Os valores booleanos não são sensíveis a maiúsculas e minúsculas. Por exemplo, pode usar False, false ou FALSE para desativar uma funcionalidade.

Defina metadados personalizados em VMs

Esta secção explica como adicionar novos metadados personalizados ou atualizar os valores dos metadados personalizados existentes para as suas VMs do Compute Engine de uma das seguintes formas:

Defina metadados personalizados do projeto

Pode adicionar ou atualizar os metadados personalizados para todas as instâncias num projeto através da consola, da Google Cloud CLI ou da API REST. Google Cloud

Use estas instruções para aplicar definições de metadados a todas as VMs no projeto. Por exemplo, se definir um par de metadados do projeto de baz=bat, esse par de metadados é aplicado automaticamente a todas as VMs no projeto.

Consola

  1. Na Google Cloud consola, aceda à página Metadados.

    Aceda à página Metadados personalizados

  2. Clique em Editar na parte superior da página.

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

    1. Navegue para a parte inferior da página e clique em Adicionar item.
    2. No campo Chave, introduza o nome da chave de metadados personalizada.
    3. No campo Valor, introduza o valor dos metadados do projeto personalizados.
    4. Opcional. Para adicionar mais entradas de metadados de projetos personalizados, repita os passos anteriores para cada entrada de metadados que quer adicionar.
    5. Para terminar de adicionar as entradas de metadados do projeto personalizado, clique em Guardar.

  4. Para editar entradas de metadados de projetos personalizados existentes, faça o seguinte:

    1. Navegue para a entrada de metadados que quer editar.
    2. Para atualizar o nome de uma chave de metadados personalizada específica, no campo Chave dessa entrada, introduza o novo nome.
    3. Para atualizar o valor de uma entrada de metadados de projeto personalizada, no campo Valor dessa entrada, introduza o novo valor.
    4. Opcional. Para remover uma entrada de metadados de projeto personalizada específica, clique no ícone de eliminação junto à entrada de metadados.
    5. Para editar várias entradas de metadados de projetos personalizados, repita os passos anteriores para cada entrada de metadados que quer editar.
    6. Para concluir a edição das entradas de metadados do projeto personalizado, clique em Guardar.

gcloud

Use o comando project-info add-metadata.

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

Substitua o seguinte:

  • 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 num projeto, execute o seguinte comando:

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

Opcionalmente, pode especificar um ou mais ficheiros a partir dos quais ler os metadados através da flag --metadata-from-file.

REST

  1. Opcional. Para realizar o bloqueio otimista, pode fornecer uma impressão digital.

    Uma impressão digital é uma string aleatória de carateres gerada pelo Compute Engine. A impressão digital muda após cada pedido e, se fornecer uma impressão digital que não corresponda, o seu pedido é rejeitado.

    Se não fornecer uma impressão digital, não é feita nenhuma verificação de consistência e o pedido projects().setCommonInstanceMetadata é bem-sucedido. Este comportamento é diferente dos métodos instances().setMetadata e instanceSettings().patch, em que é sempre necessário uma impressão digital.

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

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

    O resultado é semelhante ao seguinte:

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

  2. Faça um pedido ao método projects().setCommonInstanceMetadata e defina os 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 seu projeto.

Defina metadados zonais personalizados

Quando define metadados zonais personalizados, adiciona ou atualiza as entradas de metadados zonais para as suas VMs numa zona específica de um projeto. Pode fazer o seguinte ao definir metadados zonais personalizados:

  • Crie novas chaves de metadados personalizados para uma zona específica num projeto e defina metadados para todas as VMs nessa zona nesse projeto.
  • Atualize os valores das entradas de metadados zonais personalizados existentes para todas as VMs numa zona específica de um projeto.
  • Para chaves de metadados personalizados existentes que tenham valores de metadados do projeto, substitua esses valores de metadados do projeto em zonas específicas e, em alternativa, defina metadados zonais. Depois de definir metadados zonais para essas chaves numa zona específica, todas as VMs nessa zona nesse projeto usam os valores de metadados zonais para essas chaves.

Aspetos a ter em conta antes de definir metadados zonais personalizados

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

  • Se adicionar um valor de metadados zonais para uma chave de metadados que já tenha um valor de metadados do projeto, o Compute Engine substitui o valor de metadados do projeto para as VMs nesta zona especificada e atualiza o diretório /project com o valor zonal.
  • Se adicionar um novo valor de metadados do projeto para uma chave de metadados que já tenha um valor de metadados zonais, nada muda. O Compute Engine retém o valor dos metadados zonais no diretório /project na zona específica.
  • Se não especificar um valor de metadados zonais para uma chave de metadados personalizada numa zona específica, mas a chave tiver um valor de metadados do projeto, as suas VMs continuam a ter os valores de metadados do projeto nessas zonas.

Procedimento

Pode adicionar ou atualizar os metadados zonais personalizados numa zona específica de um projeto através da Google Cloud CLI ou da API REST.

gcloud

  • Para adicionar ou atualizar metadados zonais personalizados, 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 o seguinte:

    • PROJECT_ID: o ID do seu projeto
    • ZONE: a zona onde quer adicionar ou atualizar metadados zonais.
    • KEY1, KEY2...: as chaves de metadados personalizadas para as quais quer adicionar ou atualizar valores de metadados zonais.

    • VALUE1, VALUE2...: os valores de metadados zonais que quer definir para as chaves de metadados personalizadas existentes e novas. Consoante a chave e o valor dos metadados personalizados, ocorre uma das seguintes situações:

    • Se a chave de metadados personalizada correspondente for uma chave existente que tenha metadados do projeto, na zona especificada, o Compute Engine substitui o valor dos metadados do projeto da chave pelo valor dos metadados zonais especificado. Todas as VMs na zona especificada no projeto herdam estes metadados zonais recém-especificados para essa chave, e as VMs noutras zonas continuam a reter os respetivos valores de metadados zonais ou de projeto prevalecentes. Se fizer atualizações futuras ao valor de metadados do projeto para esta chave, as VMs nesta zona no projeto permanecem inalteradas e continuam a usar o valor de metadados zonais para esta chave.

    • Se a chave de metadados personalizada correspondente for uma nova chave de metadados que não seja usada para metadados zonais ou de projeto existentes, o Compute Engine cria a chave de metadados personalizada e define este valor como os metadados zonais na zona especificada.

    • Se a chave de metadados personalizada correspondente for uma chave de metadados existente com um valor de metadados zonal na zona especificada:

      • Se o valor de metadados especificado for diferente do valor existente, o Compute Engine atualiza a entrada de metadados zonais com o novo valor.
      • Se o valor dos metadados especificado for igual ao valor existente, a entrada de metadados zonais permanece inalterada.

Exemplo: adicione uma nova entrada de metadados zonais personalizados

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais 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 zonais personalizados 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: atualize os valores de uma entrada de metadados zonais personalizada existente

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 zonais na zona us-central1-a: "key-1":"value-1", "key-2":"value-2" e "key-4":"value-4"

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

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: substitua o valor de metadados do projeto para uma chave e use um valor de metadados zonal

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 zonais 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. Suponhamos que quer definir um valor de metadados zonais value-3 para esta chave para todas as VMs na zona us-central1-a. Quando realiza 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 zonais. As VMs em todas as outras zonas do projeto mantêm os respetivos valores de metadados zonais ou do projeto prevalecentes para key-3.

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

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

REST

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

    Para realizar o bloqueio otimista, tem de fornecer uma impressão digital. Uma impressão digital é uma string aleatória de carateres gerada pelo Compute Engine. A impressão digital muda sempre que faz um pedido para adicionar, atualizar ou remover metadados zonais. Se fornecer uma impressão digital que não corresponda, o Compute Engine rejeita o seu pedido.

    Se não fornecer uma impressão digital, é feita uma verificação de consistência e o seu pedido de atualização não é bem-sucedido. Isto funciona de modo que só é possível fazer um pedido de cada vez, o que evita colisões. Este comportamento corresponde ao instances().setMetadata, em que é sempre necessária uma impressão digital.

    Para obter a impressão digital atual dos metadados zonais, faça um GET pedido ao método instanceSettings().get.

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

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu projeto
    • ZONE: a zona onde quer definir os metadados zonais.

    Segue-se um exemplo de resultado para este pedido:

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

  2. Para adicionar ou atualizar os metadados zonais, faça um pedido PATCH ao método instanceSettings().patch. Tem de fornecer o seguinte com o seu pedido:

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

      • Os novos metadados zonais personalizados que quer adicionar
      • Os metadados zonais personalizados existentes para os quais quer atualizar os valores

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

    • No corpo do pedido, indique o seguinte:

      • As chaves e os valores de metadados para os novos metadados zonais personalizados que quer adicionar
      • As chaves e os valores de metadados para os metadados zonais personalizados existentes que quer atualizar
      • O valor da impressão digital atual

    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 o seguinte:

    • PROJECT_ID: o ID do projeto.
    • ZONE: a zona onde quer definir os metadados zonais.

    • PREFIXED_METADATA_KEYS: a lista de chaves de metadados para o seguinte, em que cada chave tem o prefixo da string metadata.items.:

      • Os novos metadados zonais personalizados que quer adicionar
      • Os metadados zonais personalizados existentes para os quais quer atualizar os valores

      Por exemplo, suponha que as chaves de metadados zonais atuais numa zona específica são key-1 e key-2. Se quiser adicionar uma nova chave, key-3, para metadados zonais nessa zona e também atualizar os metadados zonais de uma das chaves existentes, key-1, a máscara de atualização tem de ter a seguinte string:

      metadata.items.key1,metadata.items.key3

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

    • KEY1, KEY2...: as chaves de metadados zonais personalizadas para as quais quer adicionar ou atualizar valores. Especifique todas as chaves de metadados zonais personalizadas que especificou na máscara de atualização.

    • VALUE1, VALUE2...: os valores de metadados zonais que quer definir para as chaves de metadados personalizadas existentes e novas. Consoante a chave e o valor dos metadados personalizados, ocorre uma das seguintes situações:

      • Se a chave de metadados personalizada correspondente for uma chave existente que tenha metadados do projeto, na zona especificada, o Compute Engine substitui o valor dos metadados do projeto da chave pelo valor dos metadados zonais especificado. Todas as VMs na zona especificada no projeto herdam estes metadados zonais recém-especificados para essa chave, e as VMs noutras zonas continuam a reter os respetivos valores de metadados zonais ou de projeto prevalecentes. Se fizer atualizações futuras ao valor de metadados do projeto para esta chave, as VMs nesta zona no projeto permanecem inalteradas e continuam a usar o valor de metadados zonais para esta chave.
      • Se a chave de metadados personalizada correspondente for uma nova chave de metadados que não seja usada para metadados zonais ou de projetos existentes, o Compute Engine cria a chave de metadados personalizada e define este valor como os metadados zonais na zona especificada.

      • Se a chave de metadados personalizada correspondente for uma chave de metadados existente com um valor de metadados zonal na zona especificada:

      • Se o valor dos metadados especificado for diferente do valor existente, o Compute Engine atualiza a entrada dos metadados zonais com o novo valor.

      • Se o valor de metadados especificado for igual ao valor existente, a entrada de metadados zonais permanece inalterada.

Exemplo: adicione uma nova entrada de metadados zonais personalizados

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais 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 zonais personalizados na zona us-central1-a, faça o seguinte pedido 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: atualize os valores de uma entrada de metadados zonais personalizada existente

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 zonais na zona us-central1-a: "key-1":"value-1", "key-2":"value-2" e "key-4":"value-4"

Para atualizar os valores dos metadados zonais de key-1 e key-4 na zona us-cerntral1-a com novos valores, faça o seguinte pedido 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: substitua o valor de metadados do projeto para uma chave e defina um valor de metadados zonal

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 zonais 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. Suponhamos que quer definir um valor de metadados zonais value-3 para esta chave para todas as VMs na zona us-central1-a. Quando realiza 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 zonais. As VMs em todas as outras zonas do projeto mantêm os respetivos valores de metadados zonais ou do projeto prevalecentes para key-3.

Para substituir o valor de metadados do projeto para key-3 e usar o valor de metadados zonal value-3, faça o seguinte pedido 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"
    }
  }
}

Defina metadados de instância personalizados

Pode adicionar ou atualizar os metadados personalizados de uma única instância de VM através da Google Cloud consola, da Google Cloud CLI ou da REST.

Pode definir metadados de instância personalizados de uma das seguintes formas:

Adicione metadados de instâncias personalizados durante a criação de VMs

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

Consola

  1. Na Google Cloud consola, aceda à página Criar uma instância.

    Aceda a Criar uma instância

  2. Especifique os detalhes da VM.

  3. Expanda a secção Opções avançadas e faça o seguinte:

    1. Expanda a secção Gestão.
    2. Para adicionar vários pares de chave-valor aos metadados personalizados, na secçã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 flag --metadata.

gcloud compute instances create VM_NAME \
--zone=ZONE \
--image-project=IMAGE_PROJECT \
IMAGE_FLAG \
--metadata=KEY=VALUE

Substitua o seguinte:

  • VM_NAME: o nome da sua VM
  • ZONE: a zona na qual criar a VM
  • IMAGE_PROJECT: o projeto que contém a imagem a usar para a VM

  • IMAGE_FLAG: especifique uma das seguintes opções:

    • Use a flag --image IMAGE_NAME para especificar uma versão específica de uma imagem pública.

      Por exemplo, --image debian-12-bookworm-v20241112.

    • Use a flag --image-family IMAGE_FAMILY_NAME para especificar uma família de imagens.

      Isto cria a VM a partir da imagem do SO não descontinuada mais recente na família de imagens. Por exemplo, se especificar --image-family debian-12, o Compute Engine usa a versão mais recente da imagem do SO na família de imagens do Debian 12.

  • KEY: o nome da chave de metadados

  • VALUE: o valor armazenado para esta chave

Exemplo

Por exemplo, para definir uma nova chave env com um valor test numa VM denominada example-instance, execute o seguinte comando:

 gcloud compute instances create example-instance \
   --zone=us-central1-a --image-project=debian-cloud \
   --image-family=debian-12 \
   --metadata=env=test

REST

Use o método instances.insert e forneça os metadados personalizados como parte da propriedade metadata no seu pedido:

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 o seguinte:

  • PROJECT_ID: o ID do seu projeto
  • ZONE: zona na qual criar a VM
  • MACHINE_TYPE: tipo de máquina, predefinido ou personalizado, para a nova VM
  • VM_NAME: name da nova VM
  • KEY: o nome da chave de metadados
  • VALUE: o valor armazenado para esta chave

Adicione ou atualize metadados de instâncias personalizados numa VM existente

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

Consola

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceda à página de instâncias de VM

  2. Clique na instância para a qual quer atualizar os metadados.
  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 existentes.
  5. Guarde as alterações.

gcloud

A atualização dos metadados da VM com a CLI gcloud é uma ação aditiva. Especifique apenas as chaves de metadados que quer adicionar ou alterar. Se já existir uma chave que forneceu, o valor dessa chave é atualizado com o novo valor.

Use o comando instances add-metadata:

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

Substitua o seguinte:

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

Exemplos

Se quiser adicionar a entrada foo=bar, use:

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

Se quiser alterar a entrada foo=bar para foo=bat, use:

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

REST

  1. Obtenha a impressão digital atual e veja todos os pares de chave-valor existentes para a VM. Para tal, chame o método instances().get.

    Uma impressão digital é uma string aleatória de carateres gerada pelo Compute Engine e é usada para realizar o bloqueio otimista. Para atualizar a VM, tem de fornecer o valor da impressão digital correspondente. A impressão digital muda após cada pedido e, se fornecer uma impressão digital que não corresponda, o seu pedido é rejeitado. Isto funciona de modo que só é possível fazer uma atualização de cada vez, o que evita colisões.

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

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu projeto
    • ZONE: a zona onde a sua VM está localizada
    • VM_NAME: nome da sua VM

    O resultado é semelhante ao seguinte:

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

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

    Se a VM tiver pares de chaves-valores existentes que quer manter, tem de os incluir neste pedido com os novos pares de chaves-valores.

    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 o seguinte:

    • PROJECT_ID: o ID do seu projeto
    • ZONE: a zona onde a sua VM está localizada
    • VM_NAME: nome da sua VM

Remova metadados personalizados de VMs

Esta secção fornece informações sobre como remover entradas de metadados personalizados para as suas VMs do Compute Engine de uma das seguintes formas:

Remova metadados de projetos personalizados

Pode remover metadados de projetos personalizados através da Google Cloud consola ou da CLI Google Cloud.

Consola

  1. Na Google Cloud consola, aceda à página Metadados.

    Aceda à página Metadados

  2. Clique em Editar na parte superior da página.

  3. Navegue para a entrada de metadados que quer remover e clique no botão de eliminação junto a essa entrada.

    Repita este passo para cada entrada de metadados que quer remover.

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

gcloud

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

  • Se quiser remover as entradas de metadados personalizados para chaves específicas, especifique essas chaves com a flag --keys e exclua os valores dessas chaves.
gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...
  • Se quiser remover todos os metadados personalizados da VM, especifique a flag --all.
gcloud compute project-info remove-metadata \
    --all

Substitua o seguinte:

  • KEY1, KEY2...: as chaves de metadados de instâncias personalizadas que quer remover.

Remova metadados zonais personalizados

Pode remover metadados zonais personalizados através da CLI Google Cloud ou do REST.

gcloud

Para remover metadados zonais personalizados, use o comando gcloud compute project-zonal-metadata remove e especifique todas as chaves de metadados que quer remover através da flag --keys.

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

Substitua o seguinte:

  • PROJECT_ID: o ID do seu projeto
  • ZONE: a zona onde quer remover os metadados zonais.
  • KEY1, KEY2...: as chaves de metadados zonais personalizadas que 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 herdam esses valores de metadados do projeto. Se a entrada de metadados tiver sido definida apenas ao nível zonal e não existir um valor de metadados do projeto correspondente para essa chave, as VMs nessa zona perdem essas informações de metadados.

Exemplo:

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

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

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

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

REST

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

    Para realizar o bloqueio otimista, tem de fornecer uma impressão digital. Uma impressão digital é uma string aleatória de carateres gerada pelo Compute Engine. A impressão digital muda sempre que faz um pedido para adicionar, atualizar ou remover metadados zonais. Se fornecer uma impressão digital que não corresponda, o Compute Engine rejeita o seu pedido.

    Se não fornecer uma impressão digital, é feita uma verificação de consistência e o seu pedido de eliminação não é bem-sucedido. Isto funciona de modo que só é possível fazer um pedido de cada vez, o que evita colisões. Este comportamento corresponde ao instances().setMetadata, em que é sempre necessária uma impressão digital.

    Para obter a impressão digital atual de um projeto, faça uma chamada ao método instanceSettings().get.

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

    Substitua o seguinte:

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

    Segue-se um exemplo de resultado para este pedido:

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

  2. Para remover metadados zonais personalizados, faça um pedido ao instanceSettings().patch método excluindo as chaves de metadados para as quais quer remover os metadados zonais do corpo do pedido.PATCH Tem de fornecer o seguinte com o seu pedido:

    • Uma máscara de atualização. Use o parâmetro de consulta update_mask. A máscara de atualização tem de conter todas as chaves de metadados personalizados existentes para as quais quer remover os metadados zonais. Tem de adicionar a string metadata.items. como prefixo para cada chave. Por exemplo, metadata.items.key1,metadata.items.key3.

    • No corpo do pedido, indique apenas o valor da impressão digital atual. Excluir todas as chaves de metadados personalizados que especificou na máscara de atualização. Se incluir alguma das chaves de metadados na máscara de atualização e no corpo do pedido, o Compute Engine não remove os metadados zonais 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 o seguinte:

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

    • PREFIXED_METADATA_KEYS: a lista de todas as chaves de metadados personalizadas existentes para as quais quer remover os metadados zonais, em que cada chave tem o prefixo da string metadata.items.. Para garantir que o pedido de eliminação é bem-sucedido, exclua estas chaves de metadados do corpo do pedido. Se incluir alguma das chaves de metadados na máscara de atualização e no corpo do pedido, o Compute Engine não remove os metadados zonais dessas chaves.

      Por exemplo, suponhamos que as suas chaves de metadados atuais com metadados zonais são key-1, key-2, key-3 e key-4, e quer remover as entradas de metadados zonais para key-1 e key-2. Nesse caso, a máscara de atualização tem de ter a seguinte string:

      metadata.items.key1,metadata.items.key2

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

Depois de fazer o pedido, se alguma das chaves especificadas tiver valores de metadados do projeto disponíveis, as VMs na zona especificada herdam esses valores de metadados do projeto. Se a chave de metadados tiver sido definida apenas ao nível da zona e não existir um valor de metadados do projeto correspondente para essa chave, então as VMs nessa zona perdem essas informações de metadados.

Exemplo:

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

  • Metadados do projeto: "key-1":"value-a", "key-2":"value-b" e "key-3":"value-c"
  • Metadados zonais 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 de key-1 e key-2 na zona us-central1-a, faça o seguinte pedido 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": {
    }
  }
}

Após este pedido ser processado, as VMs na zona us-central1-a têm os seguintes metadados personalizados. As VMs herdam os valores de metadados do projeto para key-1 e key-2, mas retêm os metadados zonais para key-3 e key-4.

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

Remova metadados de instâncias personalizadas

Pode remover metadados de instâncias personalizadas através da Google Cloud consola, da Google Cloud CLI ou da API REST.

Consola

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceda à página de instâncias de VM

  2. Na coluna Nome, clique no nome da MV para a qual quer remover metadados.
  3. Clique em Editar na parte superior da página.
  4. Na secção Metadados, clique em Eliminar item para cada uma das entradas de metadados que quer remover.
  5. Para confirmar as alterações e remover os metadados de instância personalizados, clique em Guardar.

gcloud

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

  • Se quiser remover as entradas de metadados personalizados para chaves específicas, especifique essas chaves com a flag --keys e exclua os valores dessas chaves.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...
  • Se quiser remover todos os metadados personalizados da VM, especifique a flag --all.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

Substitua o seguinte:

  • PROJECT_ID: o ID do seu projeto.
  • ZONE: a zona da sua VM.
  • VM_NAME: nome da sua VM
  • KEY1, KEY2...: as chaves de metadados de instâncias personalizadas que quer remover.

REST

  1. Obtenha a impressão digital atual e veja todos os pares de chave-valor existentes para a VM. Para tal, chame o método instances().get.

    Uma impressão digital é uma string aleatória de carateres gerada pelo Compute Engine e é usada para realizar o bloqueio otimista. Para atualizar a VM, tem de fornecer o valor da impressão digital correspondente. A impressão digital muda após cada pedido e, se fornecer uma impressão digital que não corresponda, o seu pedido é rejeitado. Isto funciona de modo que só é possível fazer uma atualização de cada vez, o que evita colisões.

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

    Substitua o seguinte:

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

    O resultado é semelhante ao seguinte:

    {
  ...
  "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 um pedido ao método instances().setMetadata. Tem de incluir o valor da impressão digital dos metadados atual para que o pedido seja bem-sucedido.

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

      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 de instância personalizados na VM, exclua a propriedade items por completo.

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

{
"fingerprint": FINGER_PRINT
}

    Substitua o seguinte:

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

O que se segue?