Ver e consultar metadados da VM

Linux Windows

---

Cada máquina virtual (VM) armazena os metadados em diretórios em um servidor de metadados. O acesso da VM à API do servidor de metadados é fornecido automaticamente, sem qualquer autorização extra. Use os métodos explicados nas seguintes seções deste documento para visualizar e consultar os valores de metadados da VM:

• Consulte metadados de maneira programática dentro de uma VM
• Ver metadados personalizados das suas VMs

Antes de começar

• Para VMs do Windows Server, use o PowerShell 3.0 ou posterior. Recomendamos que você use ctrl+v para colar os blocos de código copiados.
• 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

     Observação: se você instalou a CLI gcloud anteriormente, verifique se tem a versão mais recente executando gcloud components update.
  2. Defina uma região e uma zona padrão.

  Python

  Para usar as amostras de Python nesta página de um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure o Application Default Credentials com as credenciais de usuário.

  1. Instale a CLI do Google Cloud.

  2. Para inicializar a CLI gcloud, execute o seguinte comando:

     gcloud init

  3. Crie as credenciais de autenticação para sua Conta do Google:

     gcloud auth application-default login

  Veja mais informações em: Configurar a autenticação para um ambiente de desenvolvimento local.

  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

Os papéis e as permissões a seguir são necessários para ver metadados personalizados de fora da VM usando o console do Google Cloud, a CLI do Google Cloud ou REST. Se você estiver consultando os metadados de maneira programática de dentro da VM, precisará apenas dos papéis e das permissões para se conectar a ela.

Para ter as permissões necessárias para ver metadados personalizados de fora da VM, peça ao seu administrador para conceder a você os seguintes papéis do IAM:

• Administrador da instância do Compute (v1) (roles/compute.instanceAdmin.v1) na VM ou no projeto
• Se as VMs usam contas de serviço: Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço ou no projeto

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

Esses papéis predefinidos contêm as permissões necessárias para ver metadados personalizados de fora da VM. 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 ver metadados personalizados de fora da VM:

• Para ver metadados personalizados em todo o projeto: compute.projects.get no projeto
• Para ver metadados personalizados zonais do projeto: compute.instanceSettings.get nas configurações da instância na zona necessária no projeto
• Para ver metadados personalizados de uma instância de VM: compute.instances.get na VM
• Se as VMs usarem contas de serviço: iam.serviceAccounts.actAs nas contas de serviço ou no projeto

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

Consultar metadados programaticamente

Em uma VM, é possível consultar programaticamente valores de metadados padrão ou personalizados usando ferramentas como curl no Linux ou Invoke-RestMethod no Windows.

Partes de uma solicitação de metadados

A tabela a seguir resume as principais partes de uma solicitação de consulta de metadados.

Componentes	Descrição
URL raiz	Todos os valores de metadados são definidos como subcaminhos abaixo do seguinte URL raiz: http://metadata.google.internal/computeMetadata/v1 http://169.254.169.254/v1 http://metadata.goog/v1
Cabeçalho da solicitação	Esse cabeçalho indica que a solicitação foi enviada com a intenção de recuperar valores de metadados, em vez de recuperar involuntariamente de uma fonte insegura e permite que o servidor de metadados retorne os dados solicitados. Se você não fornecer esse cabeçalho, o servidor de metadados negará sua solicitação. Metadata-Flavor: Google Observação: anteriormente, o cabeçalho X-Google-Metadata-Request: True era obrigatório nas solicitações. Esses cabeçalhos ainda são compatíveis, mas recomendamos que você use o cabeçalho Metadata-Flavor em vez do cabeçalho X-Google-Metadata-Request: True.

Consultar uma única entrada de metadados

Use os comandos a seguir para consultar uma única entrada de metadados.

Linux

1. Conecte-se à VM do Linux.

2. Na VM do Linux, use a ferramenta curl para fazer uma consulta.

   • Para consultar uma entrada de metadados da instância de VM, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
     

   • Para consultar uma entrada de metadados do projeto, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
     

   Substitua METADATA_KEY pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.

   Por exemplo, para consultar a imagem de inicialização da VM, execute a seguinte consulta:

   user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/image" -H "Metadata-Flavor: Google"
   

   O resultado será assim:

   projects/rhel-cloud/global/images/rhel-8-v20210122

Windows

1. Conecte-se à VM do Windows:

2. Na VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta.

   • Para consultar uma entrada de metadados da instância de VM, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY")
     $value
     

   • Para consultar uma entrada de metadados do projeto, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY")
     $value
     

   Substitua METADATA_KEY pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.

   Por exemplo, para consultar a imagem de inicialização da VM, execute a seguinte consulta:

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/image")
   $value
   

   O resultado será assim:

   projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

Consultar as listagens do diretório de metadados

Use os comandos a seguir para consultar as listagens do diretório de metadados. As listagens de diretórios são entradas de metadados que contêm outras chaves de metadados. Todas as entradas de metadados com uma barra no final do nome são listagens de diretórios.

Linux

1. Conecte-se à VM do Linux.

2. Na VM do Linux, execute os seguintes comandos:

   • Para consultar um diretório de metadados da instância de VM, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
     

   • Para consultar um diretório de metadados do projeto, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
     

   Substitua METADATA_DIRECTORY_NAME pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listas.

   Por exemplo, considere a entrada disks/, que é um diretório de discos anexado à VM. Para consultar a entrada de disks/, siga estas etapas:

   1. Execute o comando curl ferramenta no diretório de discos.

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
      

      O resultado será assim:

      0/
      1/
      2/
      

   2. Se você quiser mais informações sobre o diretório 0/ do disco, consulte o URL específico desse diretório:

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"
      

      O resultado será assim:

      device-name
      index
      mode
      type
      

   3. Em seguida, para consultar o tipo de disco (type) para discos 0/, execute:

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type" -H "Metadata-Flavor: Google"
      

      O resultado será assim:

      PERSISTENT
      

Windows

A entrada disks/ é um diretório de discos anexado à VM. Para consultar a entrada de discos, siga estas etapas:

1. Conecte-se à VM do Windows:

2. Na VM do Windows, execute os seguintes comandos:

   • Para consultar um diretório de metadados da instância de VM, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/")
     $value
     

   • Para consultar um diretório de metadados do projeto, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/")
     $value
     

   Substitua METADATA_DIRECTORY_NAME pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listas.

   Por exemplo, considere a entrada disks/, que é um diretório de discos anexado à VM. Para consultar a entrada de disks/, siga estas etapas:

   1. Execute oInvoke-RestMethod comando no diretório de discos.

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/")
      $value
      

      O resultado será assim:

      0/
      1/
      2/
      

   2. Se você quiser mais informações sobre o diretório 0/ do disco, consulte o URL específico desse diretório:

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/")
      $value
      

      O resultado será assim:

      device-name
      index
      mode
      type
      

   3. Em seguida, para consultar o tipo de disco (type) para discos 0/, execute:

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type")
      $value
      

      O resultado será assim:

      PERSISTENT
      

Consultar as listagens de diretórios de maneira recursiva

Se você quiser retornar todo o conteúdo em um diretório, use o parâmetro de consulta recursive=true com a sua solicitação:

Linux

1. Conecte-se à VM do Linux.

2. Na VM do Linux, use a ferramenta curl para fazer uma consulta.

   • Para consultar recursivamente as listagens de um diretório de metadados da instância de VM, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
     

   • Para consultar recursivamente as listagens de um diretório de metadados do projeto, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
     

   Substitua METADATA_DIRECTORY_NAME pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listagens de maneira recursiva.

   Por exemplo, o comando a seguir consulta de maneira recursiva as listagens de metadados da instância para o diretório disks/.

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"
     

   O resultado será assim:

     [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
     {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
     {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
     

   Por padrão, o conteúdo recursivo é retornado no formato JSON. Se desejar retornar esses conteúdos no formato de texto, anexe o parâmetro de consulta alt=text:

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"
     

   O resultado será assim:

     0/device-name boot
     0/index 0
     0/mode READ_WRITE
     0/type PERSISTENT
     1/device-name persistent-disk-1
     1/index 1
     1/mode READ_WRITE
     1/type PERSISTENT
     2/device-name persistent-disk-1
     2/index 2
     2/mode READ_ONLY
     2/type PERSISTENT
     

Windows

1. Conecte-se à VM do Windows:

2. Na VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta.

   • Para consultar recursivamente as listagens de um diretório de metadados da instância de VM, execute o seguinte comando:

     $value = (Invoke-RestMethod `
               -Headers @{'Metadata-Flavor' = 'Google'} `
               -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true")
     $value
     

   • Para consultar recursivamente as listagens de um diretório de metadados do projeto, execute o seguinte comando:

     $value = (Invoke-RestMethod `
               -Headers @{'Metadata-Flavor' = 'Google'} `
               -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/?recursive=true")
     $value
     

   Substitua METADATA_DIRECTORY_NAME pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listagens de maneira recursiva.

   Por exemplo, o comando a seguir consulta de maneira recursiva as listagens de metadados da instância para o diretório disks/.

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true")
   $value
   

   O resultado será assim:

   [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
   {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
   {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
   

   Por padrão, o conteúdo recursivo é retornado no formato JSON. Se desejar retornar esses conteúdos no formato de texto, anexe o parâmetro de consulta alt=text:

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text")
   $value
   

   O resultado será assim:

   0/device-name boot
   0/index 0
   0/mode READ_WRITE
   0/type PERSISTENT
   1/device-name persistent-disk-1
   1/index 1
   1/mode READ_WRITE
   1/type PERSISTENT
   2/device-name persistent-disk-1
   2/index 2
   2/mode READ_ONLY
   2/type PERSISTENT
   

Formatar a saída de consulta

Por padrão, cada endpoint tem um formato de resposta predefinido. Em alguns pontos de extremidade, os dados podem ser retornados no formato JSON por padrão. Em outros, eles são retornados como uma string. É possível substituir a especificação de formato de dados padrão usando os parâmetros de consulta alt=json ou alt=text, que retornam dados no formato de string JSON ou como uma representação de texto simples, respectivamente.

Linux

1. Conecte-se à VM do Linux.

2. Na VM do Linux, use a ferramenta curl para fazer uma consulta.

   • Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados da instância de VM, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
     

   • Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados do projeto, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
     

   Substitua:

   • METADATA_KEY: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.
   • DATA_FORMAT: o formato em que você quer os dados de resposta da consulta. Por exemplo, text ou json.

Exemplo

Por exemplo, a tecla tags retorna automaticamente os dados no formato JSON. No entanto, é possível retornar dados em formato de texto especificando o parâmetro de consulta alt=text.

Consulta padrão

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
  

O resultado será assim:

  ["http-server", "db-client", "app-server", "mysql-server"]
  

Consulta com formatação

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"
  

O resultado será assim:

  http-server
  db-client
  app-server
  mysql-server

Windows

1. Conecte-se à VM do Windows:

2. Na VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta.

   • Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados da instância de VM, execute o seguinte comando:

     $value = (Invoke-RestMethod `
               -Headers @{'Metadata-Flavor' = 'Google'} `
               -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT")
     $value
     

   • Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados do projeto, execute o seguinte comando:

     $value = (Invoke-RestMethod `
               -Headers @{'Metadata-Flavor' = 'Google'} `
               -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT")
     $value
     

   Substitua:

   • METADATA_KEY: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.
   • DATA_FORMAT: o formato em que você quer os dados de resposta da consulta. Por exemplo, text ou json.

Exemplo

Por exemplo, a tecla tags retorna automaticamente os dados no formato JSON. No entanto, é possível retornar dados em formato de texto especificando o parâmetro de consulta alt=text.

Consulta padrão

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags")
  $value
  

O resultado será assim:

  ["http-server", "db-client", "app-server", "mysql-server"]
  

Consulta com formatação

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text")
  $value
  

O resultado será assim:

  http-server
  db-client
  app-server
  mysql-server

Consulte alterações de metadados usando o recurso wait-for-change

Os valores de metadados podem mudar durante a execução da VM. Por isso, o servidor de metadados pode ser notificado sobre alterações de metadados usando o recurso wait-for-change. Com essa opção, a solicitação só retornará uma saída quando os metadados especificados tiverem sido alterados.

Use esse recurso em metadados personalizados ou definidos pelo servidor. Assim, se houver alteração na sua instância ou no seu projeto ou se alguém atualizar um entrada de metadado personalizado, você poderá reagir à alteração programaticamente.

Por exemplo, é possível executar uma solicitação na chave tags para que a solicitação seja retornada apenas se o conteúdo dos metadados das tags tiver sido alterado. Quando a solicitação é respondida, ela retorna o novo valor dessa chave de metadados.

O recurso wait-for-change também permite fazer correspondência com a solicitação e definir tempos limites.

Ao trabalhar com o recurso wait-for-change, considere o seguinte:

• Só é possível executar uma solicitação wait-for-change em um endpoint de metadados ou de maneira recursiva no conteúdo de um diretório. Não é possível executar uma solicitação wait-for-change em uma listagem de diretórios. Se você tentar fazer isso, o servidor de metadados falhará na solicitação e retornará um erro 400 Solicitação inválida.

• Não é possível executar uma solicitação wait-for-change para um token de conta de serviço. Se você tentar enviar uma solicitação wait-for-change ao URL do token da conta de serviço, ela falhará imediatamente e retornará um erro 400 Solicitação inválida.

Para executar uma solicitação wait-for-change, consulte uma chave de metadados e anexe o parâmetro de consulta ?wait_for_change=true:

Linux

1. Conecte-se à VM do Linux.

2. Na VM do Linux, use a ferramenta curl para fazer uma consulta.

   • Para executar uma solicitação wait-for-change em uma entrada de metadados da instância de VM, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true" -H "Metadata-Flavor: Google"
     

   • Para executar uma solicitação wait-for-change para uma entrada de metadados do projeto, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
     

   Substitua METADATA_KEY pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.

   Depois que a chave de metadados especificada é alterada, a consulta retorna o novo valor.

Exemplos

Neste exemplo, se uma solicitação for feita para setInstanceTags method, a solicitação retornará com os novos valores:

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"
  

O resultado será assim:

  http-server
  db-client
  

Também é possível executar uma solicitação wait-for-change de maneira recursiva no conteúdo de um diretório:

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"
  

Quando houver alterações, o servidor de metadados retorna o novo conteúdo:

  {"foo":"bar","baz":"bat"}
  

Windows

1. Conecte-se à VM do Windows:

2. Na VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta.

     PS C:> 
     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/METADATA_KEY?wait_for_change=true")
     $value
     

   • Para executar uma solicitação wait-for-change em uma entrada de metadados da instância de VM, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true")
     $value
     

   • Para executar uma solicitação wait-for-change para uma entrada de metadados do projeto, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true")
     $value
     

   Substitua METADATA_KEY pela chave de metadados da instância ou do projeto para a qual você quer executar uma solicitação wait-for-change.

   Depois que a chave de metadados especificada é alterada, a consulta retorna o novo valor.

Exemplos

Depois que a chave de metadados especificada é alterada, a consulta retorna o novo valor. Neste exemplo, se uma solicitação for feita para setInstanceTags method, a solicitação retornará com os novos valores:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true")
  $value
  

O resultado será assim:

  http-server
  db-client
  

Também é possível executar uma solicitação wait-for-change de maneira recursiva no conteúdo de um diretório:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes?recursive=true&wait_for_change=true")
  $value
  

Quando houver alterações, o servidor de metadados retorna o novo conteúdo:

  {"foo":"bar","baz":"bat"}
  

Usar ETags

Quando você envia uma consulta wait-for-change simples, o servidor de metadados retorna uma resposta se algo tiver sido alterado no conteúdo desses metadados. No entanto, há uma disputa inerente entre uma atualização de metadados e uma solicitação wait-for-change que está sendo emitida. Por isso é útil ter uma maneira confiável de saber que você está recebendo o valor de metadados mais recente.

Para ajudar com isso, é possível usar o parâmetro de consulta last_etag, que compara o valor da ETag fornecido com o valor da ETag salvo no servidor de metadados. Se os valores das ETag corresponderem, a solicitação wait-for-change será aceita. Caso contrário, isso indica que o conteúdo dos metadados foi alterado após a última recuperação do valor de ETag, e o valor mais recente é retornado imediatamente no servidor de metadados.

VMs do Linux

Para receber o valor atual da ETag de uma chave de metadados, siga estas etapas:

1. Conecte-se à VM do Linux.

2. Faça uma solicitação para essa chave e imprima os cabeçalhos. Para fazer isso, use a ferramenta curl com a sinalização -v:

   • Para receber a ETag atual de uma entrada de metadados da instância de VM, execute o seguinte comando:

     curl -v "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
     

   • Para receber a ETag atual de uma entrada de metadados do projeto, execute o seguinte comando:

     curl -v "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
     

   Substitua METADATA_KEY pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.

   Por exemplo, o comando a seguir recebe o valor atual da ETag para a chave de metadados da instância tags.

     user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
     

   O resultado será assim:

   * About to connect() to metadata port 80 (#0)
   * Trying 169.254.169.254... connected
   * Connected to metadata (169.254.169.254) port 80 (#0)
   > GET /computeMetadata/v1/instance/tags HTTP/1.1
   > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
   > Host: metadata
   > Accept: */*
   >
   < HTTP/1.1 200 OK
   < Content-Type: application/text
   < ETag: 411261ca6c9e654e
   < Date: Wed, 13 Feb 2013 22:43:45 GMT
   < Server: Metadata Server for VM
   < Content-Length: 26
   < X-XSS-Protection: 1; mode=block
   < X-Frame-Options: SAMEORIGIN
   <
   http-server
   db-client

3. Em seguida, use esse valor de ETag com o comando ferramenta curl na sua solicitação wait-for-change:

   • Para usar o valor da ETag para a solicitação wait-for-change dos metadados da instância, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
     

   • Para usar o valor da ETag para a solicitação wait-for-change dos metadados do projeto, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
     

   Substitua:

   • METADATA_KEY: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.
   • ETAG: o valor da ETag da chave de metadados.

   Neste exemplo, o comando a seguir usa o valor da ETag para a chave tags e consulta a entrada de metadados da instância.

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"
     

   O servidor de metadados corresponde ao valor da ETag especificado e, se esse valor for alterado, a solicitação retornará com o novo conteúdo da chave de metadados.

VM do Windows

Para receber o valor atual da ETag de uma chave de metadados, siga estas etapas:

1. Conecte-se à VM do Windows:

2. Faça uma solicitação para essa chave e imprima os cabeçalhos. No Windows, use o Invoke-WebRequest comando.

   • Para receber a ETag atual de uma entrada de metadados da instância de VM, execute o seguinte comando:

     $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
     -Uri http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY)
     
     $value.Headers.ETag
     

   • Para receber a ETag atual de uma entrada de metadados do projeto, execute o seguinte comando:

     $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
     -Uri http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY)
     
     $value.Headers.ETag
     

   Substitua METADATA_KEY pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.

   Por exemplo, o comando a seguir recebe o valor atual da ETag para a chave de metadados da instância tags.

     PS C:> 
     $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
     -Uri http://metadata.google.internal/computeMetadata/v1/instance/tags)
   
   
   $value.Headers.ETag
     

   O resultado será assim:

     * About to connect() to metadata port 80 (#0)
     * Trying 169.254.169.254... connected
     * Connected to metadata (169.254.169.254) port 80 (#0)
     > GET /computeMetadata/v1/instance/tags HTTP/1.1
     > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
     > Host: metadata
     > Accept: /
     >
     < HTTP/1.1 200 OK
     < Content-Type: application/text
     < ETag: 411261ca6c9e654e
     < Date: Wed, 13 Feb 2013 22:43:45 GMT
     < Server: Metadata Server for VM
     < Content-Length: 26
     < X-XSS-Protection: 1; mode=block
     < X-Frame-Options: SAMEORIGIN
     <
     http-server
     db-client

3. Em seguida, use esse valor de ETag na solicitação wait-for-change:

   • Para usar o valor da ETag para a solicitação wait-for-change dos metadados da instância, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG")
     $value
     

   • Para usar o valor da ETag para a solicitação wait-for-change dos metadados do projeto, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG")
     $value
     

   Substitua:

   • METADATA_KEY: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.
   • ETAG: o valor da ETag da chave de metadados.

   Neste exemplo, o comando a seguir usa o valor da ETag para a chave tags e consulta a entrada de metadados da instância.

     PS C:> 
     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e")
     $value
     

   O servidor de metadados corresponde ao valor da ETag especificado e, se esse valor for alterado, a solicitação retornará com o novo conteúdo da chave de metadados.

Python

Na amostra de Python a seguir, veja como monitorar o servidor de metadados programaticamente para verificar se houve alterações.

Nesta amostra, a ETag inicial foi definida como 0. O servidor de metadados não retornará uma resposta com 0 como o valor da ETag. Quando 0 for especificado como a última ETag em uma solicitação, o servidor de metadados responderá com o valor atual e a ETag. Isso poupa um pouco do código necessário para conseguir o valor e a ETag iniciais.

compute/metadata/main.py

Acessar no GitHub Feedback

last_etag = "0"

while True:
    r = requests.get(
        url,
        params={"last_etag": last_etag, "wait_for_change": True},
        headers=METADATA_HEADERS,
    )

    # During maintenance the service can return a 503, so these should
    # be retried.
    if r.status_code == 503:
        time.sleep(1)
        continue
    r.raise_for_status()

    last_etag = r.headers["etag"]

Definir limites de tempo

Se você quiser que a solicitação wait-for-change expire após um determinado número de segundos, defina o parâmetro timeout_sec. O parâmetro timeout_sec limita o tempo de espera da solicitação ao número de segundos especificado e, quando a solicitação atinge esse limite, retorna o conteúdo atual da chave de metadados.

Quando você define o parâmetro timeout_sec, a solicitação sempre retorna após o número especificado de segundos, independentemente de o valor dos metadados ter sido alterado ou não. O tempo limite só pode ser definido com um valor inteiro.

Linux

1. Conecte-se à VM do Linux.

2. Na VM do Linux, use a ferramenta curl para fazer uma consulta.

   • Para executar uma solicitação wait-for-change com um valor de tempo limite para uma entrada de metadados da instância de VM, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
     

   • Para executar uma solicitação wait-for-change com um valor de tempo limite para uma entrada de metadados do projeto, execute o seguinte comando:

     curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
     

   Substitua:

   • METADATA_KEY: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.
   • TIMEOUT: o valor de tempo limite.

Por exemplo, o comando a seguir executa uma solicitação wait-for-change configurada para expirar após 360 segundos:

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"
  

Windows

1. Conecte-se à VM do Windows:

2. Na VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta.

   • Para executar uma solicitação wait-for-change com um valor de tempo limite para uma entrada de metadados da instância de VM, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT")
     $value
     

   • Para executar uma solicitação wait-for-change com um valor de tempo limite para uma entrada de metadados do projeto, execute o seguinte comando:

     $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT")
     $value
     

   Substitua:

   • METADATA_KEY: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.
   • TIMEOUT: o valor de tempo limite.

Por exemplo, o comando a seguir executa uma solicitação wait-for-change configurada para expirar após 360 segundos:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360")
  $value
  

Códigos de status

Quando você executa uma solicitação wait-for-change, o servidor de metadados retorna códigos de status HTTP padrão para indicar se houve sucesso ou falha. Em caso de erros, as condições da rede podem fazer com que a sua solicitação seja cancelada e um código de erro seja retornado pelo servidor de metadados. Se esse for o caso, desenvolva seu aplicativo para ser tolerante a falhas, reconhecer e tratar esses erros.

Os seguintes status podem ser retornados pelo servidor de metadados:

Status	Descrição
HTTP 200	Pronto. Um valor foi alterado ou você atingiu o valor especificado timeout_sec e a solicitação foi retornada.
Error 400	A solicitação não era válida. Corrija a sua consulta e tente fazer a solicitação novamente.
Error 404	O valor de metadados especificado não existe mais. Esse erro também é retornado no servidor de metadados se os metadados foram excluídos enquanto você aguardava uma alteração.
Error 503	Ocorreu um erro temporário de servidor ou um evento temporário de manutenção. Tente fazer a solicitação novamente.

Limitações

• Todas as solicitações com o cabeçalho X-Forwarded-For são automaticamente rejeitadas pelo servidor de metadados. Isso ocorre porque, em geral, esse cabeçalho é usado para indicar que a solicitação foi enviada por proxy, ou seja, talvez ela não tenha sido feita por um usuário autorizado. Por motivos de segurança, todas as solicitações desse tipo são rejeitadas.

• Quando você usa o comando curl para recuperar metadados do servidor, observe que alguns caracteres codificados não são aceitos no caminho da solicitação. Caracteres codificados são aceitos apenas no caminho da consulta.

  Por exemplo, esta solicitação pode não funcionar:

  curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

  Para que ela funcione, substitua o caractere codificado não aceito no caminho da solicitação (%40) pelo valor equivalente aceito (@).

  curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/[e-mail]/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

  A tabela a seguir resume os caracteres codificados que não são aceitos em um caminho de solicitação.

  Caractere codificado	Valor aceito
  %21	!
  %24	$
  %27	'
  %28	(
  %29	)
  %2A	*
  %2C	,
  %40	@

Conferir os metadados personalizados das suas VMs

É possível visualizar os valores de metadados personalizados para suas VMs do Compute Engine de uma das seguintes maneiras:

• Ver metadados de todo o projeto
• Ver metadados zonais do projeto (Pré-lançamento)
• Ver metadados da instância

Ver metadados de todo o projeto

Para ver metadados personalizados que se aplicam a todas as VMs no projeto, use um dos métodos a seguir.

Console

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

   Acessar a página "Metadados"

   • Na guia Metadados, é possível analisar a maioria dos metadados personalizados do projeto, com exceção dos metadados de chave SSH.
   • Na guia Chaves SSH, é possível revisar todos os metadados de chave SSH no nível do projeto.

gcloud

Use o comando gcloud compute project-info describe para consultar os metadados do projeto:

gcloud compute project-info describe --flatten="commonInstanceMetadata[]"

O resultado será assim:

---
fingerprint: HcSFdS_1_1I=
items:
- key: ssh-keys
  value: USERNAME:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDWZ...
kind: compute#metadata

REST

Para consultar os metadados do projeto, crie uma solicitação GET para o método project.get.

Substitua PROJECT_ID pelo ID do projeto.

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

O resultado será assim:

"kind": "compute#project",
"id": "XXXXXXX",
"creationTimestamp": "2018-12-10T08:34:33.616-08:00",
"name": "YOUR_PROJECT",
"commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "XXXXXCdg=",
  "items": [
    {
      "key": "enable-guest-attributes",
      "value": "TRUE"
    },
    {
      "key": "enable-os-inventory",
      "value": "true"
    },
    {
      "key": "enable-osconfig",
      "value": "TRUE"
    },
    {
      "key": "enable-oslogin",
      "value": "TRUE"
    },
    {
      "key": "sshKeys",
      "value": "XXXXX"
    }
  ]
}, ...

Ver metadados zonais do projeto

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para ver metadados personalizados que se aplicam a todas as instâncias de VM em uma zona específica em um projeto, use um dos métodos a seguir.

gcloud

Para consultar os metadados personalizados zonais do projeto, use o comando gcloud beta compute project-zonal-metadata describe.

gcloud beta compute project-zonal-metadata describe \
    --zone=ZONE \
    --project=PROJECT_ID

Substitua:

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

O resultado será assim:

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

REST

Para consultar os metadados personalizados 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 visualizar os metadados zonais do projeto.

O resultado será assim:

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

Ver metadados da instância

Para ver metadados personalizados que se aplicam a uma única VM no projeto, use um dos métodos a seguir.

Console

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

   Acessar instâncias de VM

2. Clique no nome da VM com os metadados que você quer ver.

   • Chaves SSH para esta VM. Na seção Segurança e acesso, veja o campo Chaves SSH.

     • Um valor None indica que não há chaves SSH armazenadas nos metadados da instância.

     • Qualquer outro valor indica que há chaves SSH armazenadas nos metadados da instância.

   • Chaves SSH de um projeto. Na seção Segurança e acesso, veja o campo Bloquear chaves SSH do projeto inteiro.

     • Um valor de On indica que o valor da chave de metadados block-project-ssh-keys é TRUE nos metadados da instância.

     • Um valor de Off indica que o valor da chave de metadados block-project-ssh-keys é FALSE ou que a chave não está definida.

   • Todos os outros metadados personalizados. Veja a seção Metadados personalizados. Você verá todos os valores e chaves de metadados personalizados, exceto metadados de chave SSH.

gcloud

Use o comando gcloud compute instances describe para consultar os metadados da instância:

gcloud compute instances describe VM_NAME --flatten="metadata[]"

Substitua VM_NAME pelo nome da VM que você quer encontrar os metadados.

O resultado será assim:

---
fingerprint: MTgTJ5m-Cjs=
items:
- key: enable-oslogin
  value: 'true'
kind: compute#metadata

REST

Para consultar metadados de uma VM específica, envie uma solicitação GET para o método instances.get.

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

O resultado será assim:

......
"metadata": {
"kind": "compute#metadata",
"fingerprint": "XXXXXXVo=",
"items": [
  {
    "key": "enable-oslogin",
    "value": "true"
  }
]
},....

Substitua:

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

A seguir

• Saiba mais sobre os metadados da VM.
• Saiba como definir metadados personalizados.
• Saiba como definir e consultar atributos de convidado.