Visualizar e consultar metadados de VM,Visualizar e consultar metadados de VM

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Cada máquina virtual (VM) armazena seus metadados em diretórios em um servidor de metadados. Sua VM tem acesso automático a esta API do servidor de metadados sem qualquer autorização adicional. Você pode usar os métodos explicados nas seções a seguir deste documento para visualizar e consultar valores de metadados da VM:

• Consultar metadados programaticamente de dentro de uma VM
• Visualize metadados personalizados para suas VMs

Se você encontrar erros ao acessar o servidor de metadados, revise Solução de problemas de acesso ao servidor de metadados .

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 princípios básicos de como os metadados de VM do Compute Engine são definidos, categorizados e organizados. Para obter mais informações, consulte Sobre metadados de VM .
• Se ainda não o fez, configure a autenticação. Autenticação é o processo pelo qual sua identidade é verificada para acesso a Google Cloud serviços e APIs. Para executar códigos ou amostras em um ambiente de desenvolvimento local, você pode se autenticar 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. After installing the Google Cloud CLI, initialize it by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Set a default region and zone.

  Python

  Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command:

     gcloud init

  4. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

     If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

  Confira mais informações em Set up authentication for a local development environment.

  REST

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

  After installing the Google Cloud CLI, initialize it by running the following command:

  gcloud init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

Funções obrigatórias

As funções e permissões a seguir são necessárias para visualizar metadados personalizados de fora da VM usando o console do Google Cloud, a CLI do Google Cloud ou REST. Se você estiver consultando programaticamente os metadados na VM, precisará apenas das funções e permissões para se conectar à VM.

Para obter as permissões necessárias para visualizar metadados personalizados de fora da VM, peça ao administrador para conceder a você as seguintes funções do IAM:

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

Para obter mais informações sobre a concessão de funções, consulte Gerenciar acesso a projetos, pastas e organizações .

Essas funções predefinidas contêm as permissões necessárias para visualizar metadados personalizados de fora da VM. Para ver as permissões exatas necessárias, expanda a seção Permissões necessárias :

Você também poderá obter essas permissões com funções personalizadas ou outras funções predefinidas .

Consultar metadados programaticamente

Você pode acessar todos os metadados consultando as entradas de valores de metadados programaticamente em uma VM Linux ou Windows. De dentro da sua VM, você pode consultar programaticamente seus valores de metadados de uma das seguintes maneiras usando ferramentas como curl no Linux ou Invoke-RestMethod no Windows:

• Consultar uma única entrada de metadados
• Consultar uma listagem de diretório de metadados
• Consultar alterações de metadados usando o recurso wait-for-change

Terminais do servidor de metadados

Para consultar metadados programaticamente, em uma VM, você tem os seguintes pontos de extremidade do servidor de metadados:

• Para todas as VMs, você pode consultar o servidor de metadados usando o endpoint http ( http://metadata.google.internal/computeMetadata/v1 ) ou seu endereço IP ( 169.254.169.254 ). Use o endereço IPv4 mesmo com instâncias somente IPv6 ( Preview ).

• Para VMs protegidas , você pode consultar o servidor de metadados usando um dos seguintes procedimentos:

  • O ponto de extremidade http: http://metadata.google.internal/computeMetadata/v1
  • O ponto de extremidade https: ( https://metadata.google.internal/computeMetadata/v1 ). Este endpoint https está disponível em Preview . Para ver o formato de consulta do endpoint https, consulte Consultar metadados usando o endpoint do servidor de metadados HTTPS .

A maioria dos exemplos neste documento usa o endpoint http. No entanto, você pode acessar todas as mesmas entradas de metadados usando o endpoint https ou http.

Partes de uma solicitação de metadados

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

Metadata-Flavor: Google

Consultar uma única entrada de metadados

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

Consultar listagens de diretório de metadados

Use os comandos a seguir para consultar listagens de diretórios de metadados. Listagens de diretório são entradas de metadados que contêm outras chaves de metadados. Qualquer entrada de metadados que termine com uma barra final é uma listagem de diretório

Consultar listagens de diretório recursivamente

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

Formatar saída da consulta

Por padrão, cada endpoint possui um formato predefinido para a resposta. Alguns endpoints podem retornar dados no formato JSON por padrão, enquanto outros endpoints podem retornar dados como uma string. Você pode substituir a especificação do 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.

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

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

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

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

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

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

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

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

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

Dado que os valores de metadados podem mudar enquanto sua VM está em execução, o servidor de metadados pode ser notificado sobre alterações de metadados usando o recurso wait-for-change . Com esta opção, a solicitação só retorna uma saída quando os metadados especificados forem alterados.

Você pode usar esse recurso em metadados personalizados ou metadados definidos pelo servidor, portanto, se algo mudar em sua VM ou projeto, ou se alguém atualizar uma entrada de metadados personalizados, você poderá reagir programaticamente à mudança.

Por exemplo, você pode realizar uma solicitação na chave tags para que a solicitação retorne apenas se o conteúdo dos metadados das tags tiver sido alterado. Quando a solicitação retorna, ela fornece o novo valor dessa chave de metadados.

O recurso wait-for-change também permite que você corresponda à sua solicitação e defina tempos limite .

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

• Você só pode executar uma solicitação wait-for-change em um terminal de metadados ou recursivamente no conteúdo de um diretório. Você não pode executar uma solicitação wait-for-change em uma listagem de diretório. Se você tentar fazer isso, o servidor de metadados falhará em sua 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 fazer uma solicitação wait-for-change para o URL do token da conta de serviço, a solicitação 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 :

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

  http-server
  db-client
  

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

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

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

  http-server
  db-client
  

  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
  

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

Use ETags

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

Para ajudar com isso, você pode usar o parâmetro de consulta last_etag , que compara o valor de ETag fornecido com o valor de ETag salvo no servidor de metadados. Se os valores de ETag corresponderem, a solicitação wait-for-change será aceita. Se os valores de ETag não corresponderem, isso indica que o conteúdo dos metadados foi alterado desde a última vez que você recuperou o valor de ETag e o servidor de metadados retorna imediatamente com esse valor mais recente.

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 tempos limite

Se desejar que sua solicitação wait-for-change expire após um determinado número de segundos, você pode definir o parâmetro timeout_sec . O parâmetro timeout_sec limita o tempo de espera da sua solicitação ao número de segundos especificado e, quando a solicitação atinge esse limite, ele 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 realmente alterado ou não. Só é possível definir um valor inteiro para o seu tempo limite.

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

  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
  

Consultar metadados usando o endpoint do servidor de metadados HTTPS

O endpoint do servidor de metadados HTTPS ( https://metadata.google.internal/computeMetadata/v1 ) fornece segurança adicional para transmissão de informações entre o servidor de metadados e a VM.

Para usar o endpoint do servidor de metadados HTTPS, revise os seguintes requisitos:

• Você deve solicitar acesso à visualização do endpoint do servidor de metadados HTTPS .

• Depois que seu projeto for adicionado à lista de permissões, você poderá criar a VM. A VM deve atender aos seguintes requisitos:

  • O ambiente convidado deve estar em execução na VM .
  • A VM deve ser uma VM protegida. Isso ocorre porque o servidor de metadados HTTPS requer o uso de Unified Extensible Firmware Interface (UEFI) e Virtual Trusted Platform Module (vTPM) para verificar certificados.

Para obter uma visão geral de como as consultas ao endpoint do servidor de metadados HTTPS são tratadas, consulte Endpoint do servidor de metadados HTTPS . Você pode realizar todas as mesmas consultas no servidor de metadados, quer use o endpoint https ou http. No entanto, para chamar o endpoint https, você deve especificar o caminho para os certificados de identidade do cliente e, em alguns casos, o certificado raiz.

Os comandos a seguir demonstram como consultar o servidor de metadados usando o endpoint https.

Limitações

• Quaisquer solicitações que contenham o cabeçalho X-Forwarded-For são automaticamente rejeitadas pelo servidor de metadados. Este cabeçalho geralmente indica que a solicitação foi feita por proxy e pode não ser uma solicitação feita por um usuário autorizado. Por razões de segurança, todos esses pedidos são rejeitados.

• Ao usar o comando curl para recuperar metadados do servidor, observe que alguns caracteres codificados não são suportados no caminho da solicitação. Os caracteres codificados são suportados apenas no caminho da consulta.

  Por exemplo, a seguinte 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 esta solicitação funcione, você deve substituir o caractere codificado não suportado no caminho da solicitação ( %40 ) pelo valor aceito equivalente ( @ ).

  curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/1234567898-compute@developer.gserviceaccount.com/?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 têm suporte em um caminho de solicitação.

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

Códigos de status

Quando você faz uma solicitação ao servidor de metadados, o servidor de metadados retorna códigos de status HTTP padrão para indicar sucesso ou falha. Às vezes, condições de rede ou eventos de host podem fazer com que o servidor de metadados falhe em sua solicitação e retorne um código de erro. Nesses casos, você deve projetar seu aplicativo para ser tolerante a falhas e ser capaz de reconhecer e tratar esses erros.

Para obter uma lista detalhada de códigos de status que podem ser retornados, consulte Solucionar problemas de códigos de servidor .

Veja os metadados personalizados das suas VMs

Você pode visualizar os valores de metadados personalizados das VMs do Compute Engine de uma das seguintes maneiras:

• Ver metadados do projeto
• Ver metadados zonais
• Ver metadados da instância

Ver metadados do projeto

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

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

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

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

"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

Para visualizar metadados personalizados que se aplica a todas as instâncias da VM em uma zona específica em um projeto, use um dos seguintes métodos.

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

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

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

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

Ver metadados da instância

Para visualizar os metadados que se aplica a uma única VM em seu projeto, use um dos seguintes métodos.

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

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

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

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

O que vem a seguir

• Saiba mais sobre os metadados da VM .
• Aprenda a definir metadados personalizados .
• Aprenda a definir e consultar atributos de convidados . ,
  LinuxJanelas

  ---

  Toda máquina virtual (VM) armazena seus metadados em diretórios em um servidor de metadados. Sua VM tem acesso automaticamente a esta API do servidor de metadados sem nenhuma autorização adicional. Você pode usar os métodos explicados nas seções a seguir deste documento para visualizar e consultar os valores dos metadados da VM:

  • Consulta programaticamente metadados de dentro de uma VM
  • Veja metadados personalizados para suas VMs

  Se você encontrar erros ao acessar o servidor de metadados, revise os problemas de acesso ao servidor de metadados .

  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 copiado.
  • Revise o básico de como os metadados da VM para o mecanismo de computação são definidos, categorizados e organizados. Para mais informações, consulte sobre os metadados da VM .
  • Se ainda não o fez, configure a autenticação. Autenticação é o processo pelo qual sua identidade é verificada para acesso a Google Cloud serviços e APIs. Para executar códigos ou amostras em um ambiente de desenvolvimento local, você pode se autenticar 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. After installing the Google Cloud CLI, initialize it by running the following command:

       gcloud init

       If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    2. Set a default region and zone.

    Python

    Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

    1. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. To initialize the gcloud CLI, run the following command:

       gcloud init

    4. If you're using a local shell, then create local authentication credentials for your user account:

       gcloud auth application-default login

       You don't need to do this if you're using Cloud Shell.

       If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

    Confira mais informações em Set up authentication for a local development environment.

    REST

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

    After installing the Google Cloud CLI, initialize it by running the following command:

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

  Funções obrigatórias

  As funções e permissões a seguir são necessárias para visualizar metadados personalizados de fora da VM usando o Google Cloud Console, o Google Cloud CLI ou REST. Se você estiver consultando programaticamente os metadados de dentro da VM, você só precisará das funções e permissões para se conectar à VM.

  Para obter as permissões de que você precisa visualizar metadados personalizados de fora da VM, peça ao seu administrador que conceda as seguintes funções do IAM:

  • Compute Instância Admin (V1) ( roles/compute.instanceAdmin.v1 ) na VM ou projeto
  • Se suas VMs usarem contas de serviço: Usuário da Conta de Serviço ( roles/iam.serviceAccountUser ) na conta de serviço ou projeto

  Para obter mais informações sobre a concessão de funções, consulte Gerenciar acesso a projetos, pastas e organizações .

  Essas funções predefinidas contêm as permissões necessárias para visualizar metadados personalizados de fora da VM. Para ver as permissões exatas necessárias, expanda a seção Permissões necessárias :

  Permissões necessárias

  As seguintes permissões são necessárias para visualizar metadados personalizados de fora da VM:

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

  Você também poderá obter essas permissões com funções personalizadas ou outras funções predefinidas .

  Consulta programaticamente metadados

  Você pode acessar todos os metadados, consultando as entradas de valor de metadados programaticamente de uma VM Linux ou Windows. De dentro da sua VM, você pode consultar programaticamente seus valores de metadados de uma das seguintes maneiras, usando ferramentas como curl no Linux ou Invoke-RestMethod no Windows:

  • Consulta uma única entrada de metadados
  • Consulta uma lista de diretórios de metadados
  • Alterações de metadados de consulta usando o recurso wait-for-change

  Terminais de servidores de metadados

  Para consultar programaticamente os metadados, de dentro de uma VM, você tem os seguintes pontos de extremidade do servidor de metadados:

  • Para todas as VMs, você pode consultar o servidor de metadados usando o endpoint http ( http://metadata.google.internal/computeMetadata/v1 ) ou seu endereço IP ( 169.254.169.254 ). Use o endereço IPv4 mesmo com instâncias somente IPv6 ( visualização ).

  • Para VMs blindadas , você pode consultar o servidor de metadados usando um dos seguintes:

    • O endpoint http: http://metadata.google.internal/computeMetadata/v1
    • O ponto final do https: ( https://metadata.google.internal/computeMetadata/v1 ). Este endpoint HTTPS está disponível na visualização . Para ver o formato para consultar o endpoint HTTPS, consulte os metadados da consulta usando o terminal do servidor de metadados HTTPS .

  A maioria dos exemplos deste documento usa o terminal HTTP. No entanto, você pode acessar todas as mesmas entradas de metadados, independentemente de usar o HTTPS ou o HTTP Endpoint.

  Partes de um pedido de metadados

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

  Componentes	Descrição
  URLs da raiz	Todos os valores de metadados são definidos como sub-caminhos abaixo dos seguintes URLs da raiz: endpoint http : http://metadata.google.internal/computeMetadata/v1 http://169.254.169.254/computeMetadata/v1 http://metadata.goog/computeMetadata/v1 endpoint https ( visualização ) : https://metadata.google.internal/computeMetadata/v1 Este é o único URL suportado durante o estágio de visualização.
  Cabeçalho de solicitação	Esse cabeçalho indica que a solicitação foi enviada com a intenção de recuperar valores de metadados, em vez de não intencionalmente 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

  Consulta uma única entrada de metadados

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

  Linux

  1. Conecte -se à sua VM Linux.

  2. Na sua VM Linux, use a ferramenta curl para fazer uma consulta. Para consultar uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

     • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
     • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
     • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.

     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"
     

     A saída é semelhante à seguinte:

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

  Windows

  1. Conecte -se à sua VM do Windows.

  2. Na sua VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta. Para consultar uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

     • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
     • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
     • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.

     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
     

     A saída é semelhante à seguinte:

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

  Listagens de diretórios de metadados de consulta

  Use os seguintes comandos para consultar listagens de diretórios de metadados. As listagens de diretórios são entradas de metadados que contêm outras teclas de metadados. Qualquer entrada de metadados que termina em uma barra de ar truque é uma listagem de diretórios

  Linux

  1. Conecte -se à sua VM Linux.

  2. Para consultar uma instância da VM ou diretório de metadados do projeto, a partir da sua VM Linux, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_DIRECTORY pelo caminho para a instância da VM ou diretório de metadados do projeto para o qual você deseja consultar recursivamente as listagens. Por exemplo:

     • Para visualizar a entrada do diretório de metadados do projeto attributes , o caminho para especificar é project/attributes/ .
     • Para visualizar a entrada do diretório de metadados da instância da VM disks , o caminho para especificar é instance/disks/ .

     Por exemplo, considere os disks/ entrada, que é um diretório de discos anexados à VM. Para consultar os disks/ entrada, complete as seguintes etapas:

     1. Execute o comando curl Tool no diretório DISKS.

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

        A saída é semelhante à seguinte:

        0/
        1/
        2/
        

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

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

        A saída é semelhante à seguinte:

        device-name
        index
        mode
        type
        

     3. Em seguida, para consultar o tipo de disco ( type ) para discos 0/ , você pode executar o seguinte:

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

        A saída é semelhante à seguinte:

        PERSISTENT
        

  Windows

  Os disks/ entrada são um diretório de discos anexados à VM. Para consultar a entrada dos discos, complete as seguintes etapas:

  1. Conecte -se à sua VM do Windows.

  2. Para consultar uma instância da VM ou diretório de metadados do projeto, a partir do seu Windows VM, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_DIRECTORY pelo caminho para a instância da VM ou diretório de metadados do projeto para o qual você deseja consultar recursivamente as listagens. Por exemplo:

     • Para visualizar a entrada do diretório de metadados do projeto attributes , o caminho para especificar é project/attributes/ .
     • Para visualizar a entrada do diretório de metadados da instância da VM disks , o caminho para especificar é instance/disks/ .

     Por exemplo, considere os disks/ entrada, que é um diretório de discos anexados à VM. Para consultar os disks/ entrada, complete as seguintes etapas:

     1. Use o comando Invoke-RestMethod no diretório DISKS.

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

        A saída é semelhante à seguinte:

        0/
        1/
        2/
        

     2. Se você deseja mais informações sobre o disco 0/ diretório, você pode consultar o URL específico para esse diretório:

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

        A saída é semelhante à seguinte:

        device-name
        index
        mode
        type
        

     3. Em seguida, para consultar o tipo de disco ( type ) para discos 0/ , você pode executar o seguinte:

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

        A saída é semelhante à seguinte:

        PERSISTENT
        

  Listagens de diretórios de consulta recursivamente

  Se você deseja devolver todos os conteúdos em um diretório, use o parâmetro recursive=true Query com sua solicitação:

  Linux

  1. Conecte -se à sua VM Linux.

  2. Na sua VM Linux, use a ferramenta curl para fazer uma consulta. Para consultar recursivamente as listagens de uma instância da VM ou diretório de metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_DIRECTORY pelo caminho para a instância da VM ou diretório de metadados do projeto para o qual você deseja consultar recursivamente as listagens. Por exemplo:

     • Para visualizar a entrada do diretório de metadados do projeto attributes , o caminho para especificar é project/attributes/ .
     • Para visualizar a entrada do diretório de metadados da instância da VM disks , o caminho para especificar é instance/disks/ .

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

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

     A saída é semelhante à seguinte:

       [{"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 você deseja 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"
       

     A saída é semelhante à seguinte:

       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 à sua VM do Windows.

  2. Na sua VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta. Para consultar recursivamente as listagens de uma instância da VM ou diretório de metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_DIRECTORY pelo caminho para a instância da VM ou diretório de metadados do projeto para o qual você deseja consultar recursivamente as listagens. Por exemplo:

     • Para visualizar a entrada do diretório de metadados do projeto attributes , o caminho para especificar é project/attributes/ .
     • Para visualizar a entrada do diretório de metadados da instância da VM disks , o caminho para especificar é instance/disks/ .

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

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

     A saída é semelhante à seguinte:

     [{"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 você deseja 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
     

     A saída é semelhante à seguinte:

     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
     

  Saída de consulta de formato

  Por padrão, cada terminal possui um formato predefinido para a resposta. Alguns pontos de extremidade podem retornar dados no formato JSON por padrão, enquanto outros pontos de extremidade podem retornar os dados como uma string. Você pode substituir a especificação padrão do formato de dados usando os parâmetros de consulta alt=json ou alt=text , que retornam dados no formato JSON String ou como uma representação de texto sem formatação, respectivamente.

  Linux

  1. Conecte -se à sua VM Linux.

  2. Na sua VM Linux, use a ferramenta curl para fazer uma consulta. Para alterar o formato de dados de resposta da consulta para uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o seguinte:

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.
     • DATA_FORMAT : o formato no qual você deseja os dados de resposta da consulta - por exemplo, text ou json .

  Exemplo

  Por exemplo, a tecla tags retorna automaticamente dados no formato JSON. Você pode retornar os dados no 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"
    

  A saída é semelhante à seguinte:

    ["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"
    

  A saída é semelhante à seguinte:

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

  Windows

  1. Conecte -se à sua VM do Windows.

  2. Na sua VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta. Para alterar o formato de dados de resposta da consulta para uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o seguinte:

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.
     • DATA_FORMAT : o formato no qual você deseja os dados de resposta da consulta - por exemplo, text ou json .

  Exemplo

  Por exemplo, a tecla tags retorna automaticamente dados no formato JSON. Você pode retornar os dados no 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
    

  A saída é semelhante à seguinte:

    ["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
    

  A saída é semelhante à seguinte:

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

  Alterações de metadados de consulta usando o recurso wait-for-change

  Dado que os valores de metadados podem mudar enquanto sua VM está em execução, o servidor de metadados pode ser notificado sobre alterações de metadados usando o recurso wait-for-change . Com esta opção, a solicitação retorna apenas uma saída quando os metadados especificados foram alterados.

  Você pode usar esse recurso em metadados personalizados ou metadados definidos pelo servidor; portanto, se algo mudar sobre sua VM ou projeto ou se alguém atualizar uma entrada de metadados personalizados, poderá reagir programaticamente à alteração.

  Por exemplo, você pode executar uma solicitação na tecla tags para que a solicitação retorne apenas se o conteúdo dos metadados das tags tiver alterado. Quando a solicitação retorna, ele fornece o novo valor dessa chave de metadados.

  O recurso wait-for-change também permite combinar com sua solicitação e definir os tempos limite .

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

  • Você só pode executar uma solicitação wait-for-change em um terminal de metadados ou recursivamente no conteúdo de um diretório. Você não pode executar uma solicitação wait-for-change em uma listagem de diretórios. Se você tentar fazer isso, o servidor de metadados falha na sua solicitação e retorna um erro de solicitação inválido de 400 .

  • Você não pode executar uma solicitação wait-for-change para um token de conta de serviço. Se você tentar fazer uma solicitação wait-for-change para a URL do token da conta de serviço, a solicitação falha imediatamente e retorna um erro de solicitação inválido de 400 .

  Para executar uma solicitação wait-for-change , consulte uma chave de metadados e anexa o ?wait_for_change=true :

  Linux

  1. Conecte -se à sua VM Linux.

  2. Na sua VM Linux, use a ferramenta curl para fazer uma consulta. Para executar uma solicitação wait-for-change para uma entrada de metadados da VM ou metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

     • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
     • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
     • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.

     Depois que há uma alteração na chave de metadados especificada, a consulta retorna com o novo valor.

  Exemplos

  Neste exemplo, se uma solicitação for feita ao setInstanceTags method , a solicitação retorna com os novos valores:

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

  A saída é semelhante à seguinte:

    http-server
    db-client
    

  Você também pode executar uma solicitação wait-for-change recursivamente 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"
    

  O servidor de metadados retorna o novo conteúdo se houver alguma alteração:

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

  Windows

  1. Conecte -se à sua VM do Windows.

  2. Na sua VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta. Para executar uma solicitação wait-for-change para uma entrada de metadados da VM ou metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

     • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
     • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
     • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.

     Depois que há uma alteração na chave de metadados especificada, a consulta retorna com o novo valor.

  Exemplos

  Depois que há uma alteração na chave de metadados especificada, a consulta retorna com o novo valor. Neste exemplo, se uma solicitação for feita ao setInstanceTags method , a solicitação retorna 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
    

  A saída é semelhante à seguinte:

    http-server
    db-client
    

  Você também pode executar uma solicitação wait-for-change recursivamente 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
    

  O servidor de metadados retorna o novo conteúdo se houver alguma alteração:

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

  Use ETAGS

  Quando você envia uma consulta wait-for-change , o servidor de metadados retorna uma resposta se alguma coisa tiver alterado no conteúdo desses metadados. No entanto, existe uma condição de corrida inerente entre uma atualização de metadados e uma solicitação wait-for-change por parte, por isso é útil ter uma maneira confiável de saber que você está obtendo o valor mais recente de metadados.

  Para ajudar com isso, você pode usar o parâmetro de consulta last_etag , que compara o valor ETAG que você fornece com o valor ETAG salvo no servidor de metadados. Se os valores do ETAG corresponderem, a solicitação wait-for-change será aceita. Se os valores do ETAG não corresponderem, isso indica que o conteúdo dos metadados mudou desde a última vez que você recuperou o valor ETAG, e o servidor de metadados retorna imediatamente com este valor mais recente.

  VMs Linux

  Para obter o valor ETAG atual para uma chave de metadados, complete as seguintes etapas:

  1. Conecte -se à sua VM Linux.

  2. Faça uma solicitação para essa chave e imprima os cabeçalhos. Para fazer isso, use a ferramenta curl com o sinalizador -v . Para obter o ETAG atual para uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

     • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
     • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
     • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.

     Por exemplo, o comando a seguir obtém o valor ETAG atual 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"
       

     A saída é semelhante à seguinte:

     * 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. Você pode usar esse valor ETAG com o comando curl Tool em sua solicitação wait-for-change . Para usar o valor ETAG para a solicitação wait-for-change parte dos metadados da instância ou do projeto, execute o seguinte comando:

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

     Substitua o seguinte:

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.
     • ETAG : O valor ETAG para a chave de metadados.

     Neste exemplo, o comando a seguir usa o valor ETAG para a tecla tags e as consultas para 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 seu valor ETAG especificado e, se esse valor mudar, a solicitação retornará com o novo conteúdo da sua chave de metadados.

  VMs do Windows

  Para obter o valor ETAG atual para uma chave de metadados, complete as seguintes etapas:

  1. Conecte -se à sua VM do Windows.

  2. Faça uma solicitação para essa chave e imprima os cabeçalhos. No Windows, use o comando Invoke-WebRequest . Para obter o ETAG atual para uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

     • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
     • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
     • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.

     Por exemplo, o comando a seguir obtém o valor ETAG atual 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
       

     A saída é semelhante à seguinte:

       * 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. Você pode usar esse valor ETAG em sua solicitação wait-for-change . Para usar o valor ETAG para a solicitação wait-for-change parte dos metadados da instância ou do projeto, execute o seguinte comando:

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

     Substitua o seguinte:

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.
     • ETAG : O valor ETAG para a chave de metadados.

     Neste exemplo, o comando a seguir usa o valor ETAG para a tecla tags e as consultas para 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 seu valor ETAG especificado e, se esse valor mudar, a solicitação retornará com o novo conteúdo da sua chave de metadados.

  Pitão

  A amostra Python a seguir mostra como assistir programaticamente ao servidor de metadados para alterações.

  Esta amostra define o ETAG inicial para 0 . O servidor de metadados não retorna uma resposta com 0 como o valor ETAG. Quando 0 é especificado como o último ETAG em uma solicitação, o servidor de metadados responde com o valor atual e o ETAG. Isso economiza um pouco do código necessário para obter o valor inicial e o ETAG.

  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"]

  Defina o tempo limite

  Se você deseja que sua solicitação wait-for-change para tempo de espera após um certo número de segundos, poderá definir o parâmetro timeout_sec . O parâmetro timeout_sec limita o tempo de espera da sua solicitação ao número de segundos que você especificou e, quando a solicitação atingir esse limite, ele 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, se o valor dos metadados realmente mudou. Só é possível definir um valor inteiro para o seu tempo limite.

  Linux

  1. Conecte -se à sua VM Linux.

  2. Na sua VM Linux, use a ferramenta curl para fazer uma consulta. Para executar uma solicitação wait-for-change por um valor de tempo para uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o seguinte:

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.
     • TIMEOUT : o valor do tempo limite.

  Por exemplo, o comando a seguir executa uma solicitação wait-for-change que está definida após o tempo 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 à sua VM do Windows.

  2. Na sua VM do Windows, use o comando Invoke-RestMethod para fazer uma consulta. Para executar uma solicitação wait-for-change por um valor de tempo para uma instância da VM ou entrada de metadados do projeto, execute o seguinte comando:

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

     Substitua o seguinte:

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.
     • TIMEOUT : o valor do tempo limite.

  Por exemplo, o comando a seguir executa uma solicitação wait-for-change que está definida após o tempo 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
    

  Consulta metadados usando o terminal do servidor de metadados HTTPS

  O ponto final do servidor de metadados https ( https://metadata.google.internal/computeMetadata/v1 ) fornece segurança adicional para transmissão de informações entre o servidor de metadados e a VM.

  Para usar o terminal do servidor de metadados HTTPS, revise os seguintes requisitos:

  • Você deve solicitar acesso à visualização do terminal do servidor de metadados HTTPS .

  • Depois que seu projeto é adicionado à lista de permissões, você pode criar a VM. A VM deve atender aos seguintes requisitos:

    • O ambiente do convidado deve estar em execução na VM .
    • A VM deve ser uma VM blindada. Isso ocorre porque o servidor de metadados HTTPS requer o uso de interface de firmware extensível (UEFI) unificada (VTPM) para verificar certificados.

  Para obter uma visão geral de como as consultas para o ponto final do servidor de metadados HTTPS são tratadas, consulte o ponto final do servidor de metadados HTTPS . Você pode executar todas as mesmas consultas no servidor de metadados, se você usa os HTTPs ou o terminal HTTP. No entanto, para chamar o terminal HTTPS, você deve especificar o caminho para os certificados de identidade do cliente e, em alguns casos, o certificado raiz.

  Os seguintes comandos demonstram como consultar o servidor de metadados usando o terminal HTTPS.

  Linux

  1. Conecte -se à sua VM Linux.

  2. Na sua VM Linux, use a ferramenta curl para fazer uma consulta e especificar o certificado de identidade do cliente. Opcionalmente, você também pode especificar o certificado raiz.

     curl "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" \
       -E CLIENT_CERTIFICATE \
       [--cacert ROOT_CERTIFICATE] \
       -H "Metadata-Flavor: Google"
     

     Substitua o seguinte:

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • Para visualizar a enable-oslogin que pode ser armazenada no subdiretório de atributos dos metadados do projeto ou da VM, especifique o project/attributes/enable-oslogin ou instance/attributes/enable-oslogin dependendo do seu caso de uso.
     • CLIENT_CERTIFICATE : o caminho para o certificado de identidade do cliente: /run/google-mds-mtls/client.key .
     • Opcional: ROOT_CERTIFICATE : o caminho para o certificado raiz: /run/google-mds-mtls/root.crt .

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

     user@myinst:~$ 
     curl "https://metadata.google.internal/computeMetadata/v1/instance/image" \
       -E /run/google-mds-mtls/client.key \
       -H "Metadata-Flavor: Google"
     

     A saída é semelhante à seguinte:

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

     Se você vir uma mensagem de erro, revise a documentação de solução de problemas .

  Windows

  1. Conecte -se à sua VM do Windows.

  2. Obtenha o certificado de identidade do cliente usando um dos seguintes comandos:

     • $cert = Get-PfxCertificate -FilePath "C:\ProgramData\Google\Compute Engine\mds-mtls-client.key.pfx"
       

     • $cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Issuer -like "google.internal" }
       

  3. Na sua VM do Windows, use o comando Invoke-RestMethod e especifique o certificado de identidade do cliente para fazer uma consulta.

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

     Substitua o seguinte:

     • CLIENT_CERTIFICATE : o caminho para o certificado de identidade do cliente na VM. Esta é a variável $cert que está definida na etapa anterior.

     • Substitua o PATH_TO_METADATA_ENTRY pelo caminho para a instância da VM ou a chave de metadados do projeto para a qual você deseja consultar o valor. Se a chave estiver em um subdiretório da instância ou diretório do projeto, também inclua o subdiretório. Por exemplo:

       • Para visualizar a chave de metadados project-id , que é armazenada nos metadados do projeto, especifique project/project-id .
       • Para visualizar a tecla de metadados image , que é armazenada nos metadados da instância da VM, especifique instance/image .
       • To view the enable-oslogin which can be stored in the attributes sub-directory of either project or VM instance metadata, specify either project/attributes/enable-oslogin or instance/attributes/enable-oslogin depending on your use case.

     For example, to query the boot image for a Windows server 2019 VM, run the following query:

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

     A saída é semelhante à seguinte:

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

  Limitações

  • Any requests that contain the header X-Forwarded-For are automatically rejected by the metadata server. This header generally indicates that the request was proxied and might not be a request made by an authorized user. For security reasons, all such requests are rejected.

  • When you use the curl command to retrieve metadata from the server, note that some encoded characters aren't supported in the request path. Encoded characters are only supported in the query path.

    For example, the following request might not work:

    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"

    For this request to work, you must replace the unsupported encoded character in the request path ( %40 ) with the equivalent accepted value ( @ ).

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

    The following table summarises the encoded characters that aren't supported in a request path.

    Encoded character	Accepted value
    %21	!
    %24	$
    %27	'
    %28	(
    %29	)
    %2A	*
    %2C	,
    %40	@

  Status codes

  When you make a request to the metadata server, the metadata server returns standard HTTP status codes to indicate success or failure. Sometimes, network conditions or host events can cause the metadata server to fail your request and return an error code. In these cases, you should design your application to be fault-tolerant and to be able to recognize and handle these errors.

  For a detailed list of status codes that can be returned, see Troubleshoot server codes .

  View the custom metadata for your VMs

  You can view the custom metadata values for your Compute Engine VMs in one of the following ways:

  • View project metadata
  • View zonal metadata
  • View instance metadata

  View project metadata

  To view custom metadata that applies to all VMs in your project, use one of the following methods.

  Console

  1. In the Google Cloud console, go to the Metadata page.

     Go to the Metadata page

     On the Metadata page,you see a list of all custom project metadata entries for your project.

  gcloud

  Use the gcloud compute project-info describe command to query project metadata:

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

  A saída é semelhante à seguinte:

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

  DESCANSAR

  To query project metadata, create a GET request to the project.get method .

  Replace PROJECT_ID with your project ID.

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

  A saída é semelhante à seguinte:

  "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"
      }
    ]
  }, ...
  

  View zonal metadata

  To view custom metadata that applies to all VM instances in a specific zone in a project, use one of the following methods.

  gcloud

  To query the custom zonal metadata, use the gcloud compute project-zonal-metadata describe command .

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

  Substitua o seguinte:

  • PROJECT_ID : o ID do seu projeto
  • ZONE : the zone for which you want to view the zonal metadata.

  A saída é semelhante à seguinte:

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

  DESCANSAR

  To query the custom zonal metadata, make a GET request to the instanceSettings().get method

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

  Substitua o seguinte:

  • PROJECT_ID : o ID do seu projeto
  • ZONE : the zone for which you want to view the zonal metadata.

  A saída é semelhante à seguinte:

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

  View instance metadata

  To view metadata that applies to a single VM in your project, use one of the following methods.

  Console

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

     Acesse as instâncias de VM

  2. Click the name of the VM for which you want to view metadata.

     • SSH keys for this VM . In the Security and access section, view the SSH keys field.

       • A value of None indicates there are no SSH keys stored in instance metadata.

       • Any other value indicates that there are SSH keys stored in instance metadata.

     • SSH keys for a project . In the Security and access section, view the Block project-wide SSH keys field.

       • A value of On indicates that the value of the metadata key block-project-ssh-keys is TRUE in instance metadata.

       • A value of Off indicates that the value of the metadata key block-project-ssh-keys is FALSE , or that the key isn't set.

     • All other custom metadata . View the Custom metadata section. You see all custom metadata keys and values, other than SSH key metadata.

  gcloud

  Use the gcloud compute instances describe command to query instance metadata:

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

  Replace VM_NAME with the name of the VM you want to find metadata for.

  A saída é semelhante à seguinte:

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

  DESCANSAR

  To query metadata for a specific VM, send a GET request to the instances.get method .

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

  A saída é semelhante à seguinte:

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

  Substitua o seguinte:

  • PROJECT_ID : o ID do seu projeto
  • ZONE : the zone where the VM is located
  • VM_NAME : o nome da VM

  O que vem a seguir

  • Learn more about VM metadata .
  • Learn how to set custom metadata .
  • Learn how to set and query guest attributes .