Como armazenar e recuperar metadados de instâncias

Os metadados de cada instância são armazenados em um servidor de metadados. É possível consultar esse servidor de maneira programática na própria instância e usando a API do Compute Engine. Também é possível consultar informações sobre a instância, como nome do host, ID, scripts de inicialização e desligamento, metadados personalizados e informações da conta de serviço. O acesso da instância à API do servidor de metadados é concedido automaticamente, sem qualquer autorização extra.

O servidor de metadados é útil principalmente quando usado com os scripts de inicialização e de encerramento, já que é possível usar esse servidor para receber, de maneira programática, informações exclusivas sobre uma instância sem a necessidade de outra autorização. Por exemplo, é possível escrever um script de inicialização que busca o par de chave-valor de metadados do IP externo de uma instância e usar esse IP no seu script para configurar um banco de dados. Como as chaves de metadados padrão são iguais em todas as instâncias, esse script pode ser reutilizado sem a necessidade de atualizá-lo para cada instância. Com isso, você consegue criar um código mais robusto para seus aplicativos.

Os metadados são armazenados no formato key:value. Há um conjunto padrão de entradas de metadados a que todas as instâncias têm acesso. Também é possível definir metadados personalizados.

Para acessar o servidor de metadados, consulte o URL de metadados.

Versão atual: v1

Recomendamos sempre usar a versão mais recente do servidor de metadados, mesmo que haja mais de uma versão dos metadados no Compute Engine. A qualquer momento, podem ser adicionadas novas entradas ao servidor de metadados e novos campos às respostas no Google Compute Engine. Verifique periodicamente se há atualizações.

Para informações, consulte Como verificar a versão do endpoint do servidor.

Os endpoints do servidor de metadados v1beta1 e v0.1 estão obsoletos e serão encerrados em breve. Verifique se você atualizou todas as solicitações para usar a v1. Para mais informações, consulte Como fazer a transição para o endpoint de servidor de metadados v1.

Antes de começar

Permissões exigidas para a tarefa

Para executar esta tarefa, é preciso ter as permissões a seguir:

  • compute.instances.setMetadata na instância, se você quiser definir metadados de instância
  • compute.projects.setCommonInstanceMetadata no projeto, se você quiser definir metadados de todo o projeto
  • compute.projects.get no projeto, se você quiser apenas receber metadados
  • compute.instances.get na instância, se você quiser apenas receber metadados

Metadados de projeto e instância

Metadados podem ser atribuídos a projetos e instâncias. Os metadados do projeto são propagados para todas as instâncias de máquina virtual (VM, na sigla em inglês) no projeto. Já os metadados de uma instância afetam somente essa instância.

Chaves de metadados padrão

Um conjunto de entradas de metadados padrão é definido pelo Compute Engine para fornecer informações sobre a instância ou o projeto. Os metadados padrão são sempre definidos e configurados no servidor. Não é possível editar manualmente nenhum desses pares de metadados.

Os metadados a seguir estão disponíveis, por padrão, para qualquer projeto. Algumas entradas de metadados são diretórios em que há outras chaves de metadados. Essa diferença é marcada por uma barra no final do nome do metadado. Por exemplo, attributes/ é um diretório que contém outras chaves e numeric-project-id é uma chave de metadados associada a um valor.

Relativo a http://metadata.google.internal/computeMetadata/v1/project/
Entrada de metadados Descrição
attributes/ Um diretório de valores de metadados personalizados que foram definidos para o projeto.
attributes/disable-legacy-endpoints Desativa os endpoints legados do servidor de metadados de todas as instâncias no projeto. Sempre defina disable-legacy-endpoints=TRUE, a não ser que o projeto use endpoints legados. Atualize seus aplicativos para usar os endpoints v1.
attributes/enable-oslogin Ativa o recurso Login do SO para gerenciamento de chaves SSH no projeto quando você define enable-oslogin=TRUE.
attributes/vmdnssetting Configura como os nomes DNS internos são formatados para as instâncias no projeto. Leia Como configurar nomes DNS para saber mais sobre nomes DNS internos.
attributes/ssh-keys Se o projeto e as instâncias não estiverem configurados para usar o Login do SO no gerenciamento de chaves SSH, esse atributo permitirá que você configure chaves SSH públicas que possam se conectar a instâncias no projeto. Se houver várias chaves SSH, elas serão separadas por um caractere de nova linha (\n). Esse valor é uma string. As chaves SSH gerenciadas pelo Login do SO não são visíveis nesse valor de metadados.

Exemplo: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

numeric-project-id O ID numérico do projeto (número do projeto) da instância, que é diferente do nome do projeto no Console do Google Cloud. Esse valor é diferente do valor de entrada de metadados project-id.
project-id O ID do projeto.

Por padrão, os seguintes metadados estão disponíveis para uma instância:

Relativo a http://metadata.google.internal/computeMetadata/v1/instance/
Entrada de metadados Descrição
attributes/ Um diretório de valores de metadados personalizados passados para a instância durante a inicialização ou o encerramento. Consulte Como especificar metadados personalizados abaixo.
attributes/enable-oslogin Ativa o recurso Login do SO para gerenciamento de chaves SSH na instância quando você define enable-oslogin=TRUE.
attributes/vmdnssetting Configura como os nomes DNS internos são formatados na instância. Leia Como configurar nomes DNS para saber mais sobre nomes DNS internos.
attributes/ssh-keys Se a instância não estiver configurada para usar o Login do SO no gerenciamento de chaves SSH, esse atributo permitirá que você configure chaves SSH públicas que possam se conectar à instância. Se houver várias chaves SSH, elas serão separadas por um caractere de nova linha (\n). Esse valor é uma string. As chaves SSH gerenciadas pelo Login do SO não são visíveis nesse valor de metadados.

Exemplo: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

cpu-platform Plataforma de CPU da instância.
description A descrição em texto livre de uma instância que é atribuída usando a sinalização --description ou definida na API.
disks/ Um diretório de discos anexados à instância.
guest-attributes/ Valores de metadados personalizados de uma instância que podem ser usados para publicar notificações de status pouco frequentes, dados de baixo volume ou dados de baixa frequência. Esses valores são úteis para indicar quando os scripts de inicialização foram concluídos ou para fornecer outras notificações de status pouco frequentes a outros aplicativos. Qualquer usuário ou processo na sua instância de VM pode fazer leituras e gravações nos namespaces e nas chaves dos metadados “guest-attributes”.
hostname O nome do host da instância.
id O ID da instância. Este é um ID numérico exclusivo, gerado pelo Compute Engine. Isso é útil para identificar instâncias, se você não quiser usar nomes.
machine-type O valor de metadados para o tipo de máquina da instância, com este formato: projects/projectnum/machineTypes/machine-type.
name O nome da instância.
network-interfaces/ Um diretório das interfaces de rede da instância.
network-interfaces/<index>/forwarded-ips/ Um diretório de IPs externos que no momento apontam para a instância de máquina virtual na interface de rede em <index>. Nele, é fornecida especificamente uma lista dos IPs externos atendidos pelas regras de encaminhamento que direcionam pacotes para a instância.
scheduling/ Um diretório com as opções de programação da instância.
scheduling/on-host-maintenance A configuração do comportamento de evento de manutenção transparente da instância. Esse valor é definido com a sinalização --on_host_maintenance ou usando a API.
scheduling/automatic-restart A configuração de reinicialização automática da instância. Esse valor é definido com a sinalização ‑‑automatic_restart ou usando a API.
scheduling/preemptible A configuração preemptiva da instância. Se o valor for TRUE, a instância será preemptiva. Esse valor é definido na criação de uma instância e não pode ser alterado.
maintenance-event O caminho que indica que a instância está sendo afetada por um evento de manutenção transparente. Consulte a notificação de manutenção transparente para mais detalhes.
service-accounts/ Um diretório das contas de serviço associadas à instância.
service-accounts/service-account-name/token Um token de acesso OAuth2 que pode ser usado para autenticar aplicativos.
service-accounts/service-account-name/identity Um JSON Web Token, exclusivo da instância. É necessário incluir o parâmetro audience na solicitação do valor de metadados da instância. Por exemplo, ?audience=http://www.example.com. Leia Como verificar a identidade das instâncias para mais informações sobre como solicitar e verificar os tokens de identidade da instância.
tags Todas as tags associadas à instância.
zone O valor de metadados da zona em que a instância é executada. Esse valor tem este formato: projects/projectnum/zones/zone.

Como buscar metadados

Para consultar o conteúdo do servidor de metadados, faça uma solicitação para os URLs raiz a seguir a partir de uma instância de máquina virtual. Use o URL http://metadata.google.internal/computeMetadata/v1/ para fazer solicitações ao servidor de metadados.

Todos os valores de metadados são definidos como subcaminhos abaixo desses URLs raiz.

Só é possível consultar valores de metadados padrão a partir da instância associada. Não é possível consultar os metadados padrão de uma instância diretamente a partir do seu computador local nem de outra instância. É possível usar ferramentas padrão, como curl ou wget, a partir da instância para fazer consultas ao respectivo servidor de metadados.

Ao consultar metadados, é necessário incluir o cabeçalho a seguir em todas as solicitações:

Metadata-Flavor: Google

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, permitindo que o servidor de metadados retorne os dados solicitados. Se você não fornecer esse cabeçalho, o servidor de metadados negará a solicitação.

Cabeçalho X-Forwarded-For

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 não tenha sido feita por um usuário autorizado. Por motivos de segurança, todas as solicitações desse tipo são rejeitadas.

Limitações

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

Por exemplo, esta solicitação talvez não funcione:

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 compatível com o caminho da solicitação (%40) pelo valor equivalente compatível (@).

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts1234567898-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 são compatíveis com o caminho da solicitação.

Caractere codificado Valor aceito
%21

!
%24

$
%27

'
%28

(
%29

)
%2A

*
%2C

,
%40

@

As informações dos metadados são seguras?

Quando você faz uma solicitação para receber informações do servidor de metadados, tanto a solicitação quanto a resposta subsequente com os metadados nunca deixam o host físico que está executando a instância de máquina virtual.

Como consultar listas de diretórios

O servidor de metadados usa diretórios para organizar determinadas chaves de metadados. Todas as entradas de metadados com uma barra no final do nome são diretórios. Por exemplo, a entrada disks/ é um diretório de discos anexados a essa instância:

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

Da mesma forma, se você quiser mais informações sobre o diretório do disco 0/, consulte o URL específico desse diretório:

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

Como consultar endpoints

Se uma chave de metadados não for um diretório, ela será um endpoint que retornará um ou mais valores. Por exemplo, para consultar o modo de um disco específico, consulte este endpoint:

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

Por padrão, cada endpoint tem um formato de resposta predefinido. Alguns endpoints podem retornar dados no formato JSON por padrão, enquanto outros os retornam como uma string. É possível modificar 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.

Por exemplo, a chave tags retorna automaticamente os dados no formato JSON. No entanto, também é possível retornar dados em formato de texto. Para isso, basta especificar o parâmetro de consulta alt=text:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
    
    ["bread","butter","cheese","cream","lettuce"]
    
    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"
    
    bread
    butter
    cheese
    cream
    lettuce
    

Como consultar metadados de maneira recursiva

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

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"
    
    [{"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ê quiser retornar esse conteúdo 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"
    
    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
    

Como definir valores booleanos

Nos campos que aceitam valores booleanos, TRUE ou FALSE, também é possível usar os valores a seguir:

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

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

Como definir metadados personalizados

É possível definir metadados personalizados de uma instância ou um projeto usando o Console do Google Cloud, a ferramenta de linha de comando gcloud ou a API do Compute Engine. Os metadados personalizados são úteis para passar valores arbitrários ao projeto ou à instância e para definir scripts de inicialização e de encerramento.

Limites de tamanho dos metadados personalizados

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

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

Especificamente, as chaves SSH são armazenadas como metadados personalizados na chave ssh-keys. Se o conteúdo de metadados dessa chave ultrapassar o limite de 256 KB, não será possível incluir mais chaves SSH. Se isso ocorrer, remova as chaves não utilizadas para liberar espaço de metadados para novas chaves.

Se você fornecer diretamente o conteúdo de scripts de inicialização ou de encerramento, tal conteúdo também poderá ser armazenado na forma de metadados personalizados e contar para os limites de tamanho. Para evitar isso, armazene seu script de inicialização ou de encerramento como um arquivo hospedado em um local externo, como o Cloud Storage, e forneça o URL do script de inicialização ao criar uma instância. Esses arquivos serão salvos na instância da VM, em vez de armazenados no servidor de metadados.

Como definir metadados de instância

É possível definir os metadados personalizados de uma instância no Console do Cloud, na ferramenta gcloud ou na API. Os metadados de instância se aplicam somente a uma instância específica.

Como definir metadados na criação da instância

Console

  1. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar a página Instâncias de VM (em inglês)

  2. Clique em Criar instância.
  3. Na página Criar uma nova instância, preencha as propriedades da sua instância.
  4. Na seção Metadados, insira quantos pares de chave-valor forem necessários para seus metadados personalizados.
  5. Clique em Criar para criar a instância.

gcloud

Com a ferramenta de linha de comando gcloud, use a sinalização --metadata para definir metadados personalizados.

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

API

Na API, forneça os metadados personalizados como parte da propriedade de metadados na sua solicitação:

    POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

    {
      "...
            }
          ]
        }
      ],
      "metadata": {
        "items": [
          {
           "key": "foo",
           "value": "bar"
          }
        ]
      },
      ..
    }
    

Como atualizar metadados em uma instância em execução

Console

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

    Acessar a página de instâncias de VM

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

gcloud

A atualização de metadados de instância com a ferramenta gcloud é uma ação de adicionalidade. Especifique apenas as chaves de metadados que você quer adicionar ou mudar. Se você especificar uma chave que já existe, o valor dela será atualizado com o novo valor.

Na ferramenta de linha de comando gcloud, use o comando instances add-metadata:

gcloud compute instances add-metadata instance-name \
          --metadata bread=mayo,cheese=cheddar,lettuce=romaine
    

Se você quiser mudar a entrada lettuce=romaine para lettuce=green, use:

gcloud compute instances add-metadata instance-name \
        --metadata lettuce=green
    

Se você quiser remover a entrada lettuce=romaine, especifique a chave atual e exclua o valor.

gcloud compute instances remove-metadata instance-name \
        --keys lettuce
    

API

Na API, faça uma solicitação para o método instances().setMetadata. Forneça uma lista dos novos valores de metadados e o valor atual de fingerprint

Impressão digital é uma string de caracteres aleatória, gerada pelo Compute Engine e usada para executar o bloqueio otimista. Forneça o valor da impressão digital correspondente para realizar sua solicitação. A impressão digital muda após cada solicitação. Se você fornecer uma impressão digital incompatível, sua solicitação será rejeitada. Dessa forma, só é possível fazer uma atualização por vez, o que evita conflitos.

Para receber a impressão digital atual de uma instância e consultar os pares de chave-valor atuais dela, envie uma solicitação instances().get:

    GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

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

Depois, faça uma solicitação para o método instances().setMetadata e defina seus pares de chave-valor de metadados personalizados: Se houver pares de chave-valor que você queira manter na instância, será necessário incluí-los nessa solicitação com os novos pares de chave-valor:

    POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

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

Para remover todos os pares de chave-valor de metadados de uma instância, especifique uma solicitação instances().setMetadata e exclua a propriedade items. Você ainda precisará incluir a propriedade de impressão digital de metadados atual para que a solicitação seja realizada com êxito:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{ "fingerprint": "5rC_DXxBUZw=" }

Como definir metadados personalizados para todo o projeto

Os metadados definidos para um projeto inteiro são aplicados a todas as instâncias nesse projeto. Por exemplo, se você definir um par de metadados de baz=bat para todo o projeto, esse par será aplicado automaticamente a todas as instâncias no projeto.

Console

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

    Acessar a página "Metadados"

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

gcloud

Na ferramenta de linha de comando gcloud, use o comando project-info add-metadata. Por exemplo:

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

Use o comando describe para ver os metadados:

gcloud compute project-info describe

Por exemplo, você talvez receba uma resposta semelhante à esta:

    ...
    commonInstanceMetadata:
      fingerprint: RfOFY_-eS64=
      items:

  • key: baz value: bat
  • key: foo value: bar
  • key: ssh-keys ...
Um par de chave-valor de metadados é especificado com um sinal de igual, por exemplo, key=value. Quando há vários pares chave-valor, eles são separados por um espaço.

Se preferir, especifique um ou mais arquivos que terão os metadados lidos usando a sinalização --metadata-from-file. É possível remover valores de metadados com o comando project-info remove-metadata.

API

Na API, faça uma solicitação para o método projects().setCommonInstanceMetadata, fornecendo todos os novos valores de metadados e um valor de fingerprint.

Impressão digital é uma string de caracteres aleatória, gerada pelo Compute Engine e usada para executar o bloqueio otimista. Forneça o valor da impressão digital correspondente para realizar sua solicitação. A impressão digital muda após cada solicitação. Se você fornecer uma impressão digital incompatível, sua solicitação será rejeitada. Dessa forma, só é possível fazer uma atualização por vez, o que evita conflitos.

Para receber a impressão digital atual de uma instância, faça uma solicitação project().get e copie o valor da impressão digital:

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

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

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

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

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

Como consultar metadados personalizados

É possível consultar metadados personalizados de uma instância ou um projeto usando o Console do Cloud, a ferramenta de linha de comando gcloud ou a API.

Console

Para ver os metadados personalizados de todo o projeto, acesse a página Metadados.

Para ver os metadados personalizados de uma instância:

  1. Acesse a página Instâncias de VM.
  2. Clique na instância em que estão os metadados que você quer visualizar.
  3. Em Metadados personalizados, veja os metadados personalizados da instância.

gcloud

Consultar metadados do projeto:

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

Consultar metadados da instância:

gcloud compute instances describe example-instance \
        --flatten="metadata[]"
    

Use a sinalização --flatten para definir o escopo da resposta como a chave de metadados relevante. Por exemplo, a instância a seguir tem um par de chave-valor de metadados personalizados de foo:bar.

    $ gcloud compute instances describe example-instance
    
    ...
    metadata:
      fingerprint: Cad2L9eKNR0=
      items:
      - key: foo
        value: bar
      kind: compute#metadata
    ...
    
    

Para consultar o valor da chave foo, execute:

    gcloud compute instances describe example-instance \
        --flatten="metadata[foo]"
    
    ---
      bar
    
    

API

Para consultar os metadados de um projeto, faça uma solicitação vazia para o método projects().get:

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

Para consultar os metadados de uma instância, faça uma solicitação vazia para o método instance().get:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

Como definir e consultar atributos de convidado

Os atributos de convidado são um tipo específico de metadados personalizados em que seus aplicativos podem fazer gravações enquanto estão sendo executados na sua instância. Qualquer aplicativo ou usuário na instância pode fazer leituras e gravações de dados nesses valores de metadados de atributos de convidado.

Quando usar atributos de convidado

Use atributos de convidado somente nos casos de uso que exijam pequenas quantidades de dados que não mudem com frequência. Os casos de uso ideais para o uso de atributos de convidado têm estas características:

  • O número de consultas está limitado a um máximo de 10 consultas por minuto e por instância de VM.
  • As consultas não excedem um burst de três consultas por segundo. Se essa taxa máxima for excedida, o Compute Engine poderá remover arbitrariamente os atributos de convidado que estão em processo de gravação. Essa remoção de dados é necessária para garantir que outros dados críticos do sistema sejam gravados no servidor.

Os atributos de convidado funcionam bem em situações em que é preciso publicar dados pouco frequentes e de baixo volume. Por exemplo, os atributos de convidado são adequados para estes casos de uso:

  • Scripts de inicialização que podem sinalizar uma inicialização bem-sucedida com a definição de um valor de status personalizado nos atributos de convidado.
  • Agentes de gerenciamento de configuração que podem publicar um nome e uma versão de sistema operacional convidado em atributos de convidado.
  • Agentes de gerenciamento de inventário que podem publicar a lista de pacotes instalados na instância da VM nos atributos de convidado.
  • Software de orquestração de carga de trabalho que pode sinalizar a conclusão de uma operação no convidado para o plano de controle do software, com a definição de um valor de status personalizado nos atributos de convidado.

Os atributos de convidado não substituem o streaming de eventos, o Pub/Sub nem outras formas de armazenamento de dados e repositórios de configuração.

Para fazer leituras e gravações a partir de uma instância, o servidor de metadados fornece autenticação e autorização automáticas no nível da instância. Cada instância pode fazer leituras ou gravações apenas no próprio servidor de metadados. O servidor de metadados de uma instância não pode ser acessado por outras instâncias. Os usuários e as contas de serviço só podem fazer leituras de atributos de convidado de uma instância a partir de fora dessa instância se tiverem um papel do Cloud Identity and Access Management com a permissão compute.instances.getGuestAttributes.

Como ativar atributos de convidado na instância

Por padrão, os atributos de convidado estão desativados. Para ativá-los, defina os valores de metadados necessários em cada instância ou para o projeto todo.

Console

Definir enable-guest-attributes nos metadados da instância ao criar uma instância:

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

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

  2. Clique em Criar instância.
  3. Na página Criar uma nova instância, preencha as propriedades desejadas da instância.
  4. Na seção Metadados, inclua uma entrada de metadados com chave enable-guest-attributes e valor TRUE.
  5. Clique em Criar para criar a instância.

Definir enable-guest-attributes nos metadados do projeto todo para que eles sejam aplicados a todas as instâncias do projeto:

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

    Acessar a página "Metadados"

  2. Clique em Editar.
  3. Inclua uma entrada de metadados com chave enable-guest-attributes e valor TRUE. Se preferir, defina o valor como FALSE para desativar o recurso.
  4. Clique em Salvar para aplicar as mudanças.

Definir enable-guest-attributes nos metadados de uma instância atual:

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

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

  2. Clique no nome da instância em que você quer definir o valor dos metadados.
  3. Para editar as configurações da instância, clique em Editar na parte superior da página de detalhes da instância.
  4. Na seção Metadados personalizados, inclua uma entrada de metadados com chave enable-guest-attributes e valor TRUE. Se preferir, defina o valor como FALSE para excluir a instância do recurso.
  5. Para aplicar as mudanças à instância, clique em Salvar na parte inferior da página de detalhes da instância.

gcloud

Definir enable-guest-attributes nos metadados da instância ao criar uma instância:

Use o comando gcloud compute instances create na ferramenta de linha de comando gcloud e defina enable-guest-attributes=TRUE para ativar os atributos de convidado. Substitua instance-name pelo nome da instância.

    gcloud compute instances create instance-name \
        --metadata enable-guest-attributes=TRUE

Definir enable-guest-attributes nos metadados de todo o projeto para que sejam aplicáveis a todas as instâncias no projeto:

Use o comando project-info add-metadata na ferramenta de linha de comando gcloud e defina enable-guest-attributes=TRUE para ativar os atributos de convidado.

gcloud compute project-info add-metadata \
        --metadata enable-guest-attributes=TRUE
    

Se preferir, defina enable-guest-attributes como FALSE para desativar os atributos de convidado.

Definir enable-guest-attributes nos metadados de uma instância atual:

Use o comando instances add-metadata na ferramenta de linha de comando gcloud e defina enable-guest-attributes=TRUE para ativar os atributos de convidado. Substitua instance-name pelo nome da instância.

    gcloud compute instances add-metadata instance-name \
        --metadata enable-guest-attributes=TRUE

Se preferir, defina enable-guest-attributes como FALSE para impedir que sua instância use atributos de convidado.

Como definir atributos de convidado

Qualquer processo executado na instância de máquina virtual pode fazer gravações nos valores de atributos de convidado, incluindo scripts e aplicativos que não têm privilégios de superusuário ou administrador. Usuários ou contas de serviço fora da instância não podem fazer gravações em valores de metadados de atributos de convidado.

Por exemplo, é possível usar uma solicitação curl a partir da instância para gravar um valor no caminho de metadados guest-attributes:

curl -X PUT --data "value" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/namespace/key -H "Metadata-Flavor: Google"

Substitua as seguintes informações:

  • namespace: um agrupamento lógico da sua key. Os atributos de convidado precisam ter um namespace.
  • value: o valor que você quer gravar.
  • key: o caminho dos metadados dentro de guest-attributes em que o valor está armazenado.

Use somente letras, numerais, sublinhados (_) e hifens (-) nos campos namespace e key.

Como buscar atributos de convidado

Usuários ou contas de serviço poderão ler os atributos de convidado se tiverem um papel do Cloud IAM com a permissão compute.instances.getGuestAttributes. Como alternativa, qualquer usuário ou aplicativo em uma instância pode ler os valores de metadados dessa instância específica.

Qualquer processo executado na máquina virtual pode gravar no valor de atributos de convidado, incluindo scripts e aplicativos que não têm privilégios de superusuário ou administrador. Por exemplo, é possível usar uma solicitação curl a partir da instância para ler um valor do caminho de metadados guest-attributes:

curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/namespace/key -H "Metadata-Flavor: Google"

Substitua as seguintes informações:

  • namespace: o namespace da chave guest-attributes que você quer consultar.
  • key: o caminho dentro de guest-attributes em que está o valor de metadados que você quer ler.

Como alternativa, retorne todos os valores de atributos de convidado em uma solicitação. Substitua namespace pelo namespace da chave guest-attributes que você quer consultar.

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

gcloud

Use a ferramenta de linha de comando gcloud para ler os valores de metadados de atributos de convidado de uma instância. Por exemplo, é possível recuperar todos os valores da instância:

    gcloud compute instances get-guest-attributes instance-name \
        --zone zone

Para recuperar todos os valores em um namespace específico, inclua a sinalização --query-path e o namespace que você definiu:

    gcloud compute instances get-guest-attributes instance-name \
        --query-path=namespace \
        --zone zone

Para recuperar todos os valores em um namespace específico, inclua a sinalização --query-path, o namespace e a chave do valor que você definiu:

    gcloud compute instances get-guest-attributes instance-name \
        --query-path=namespace/key \
        --zone zone

Substitua as seguintes informações:

  • instance-name: o nome da instância em que está o valor de metadados de atributos de convidado que você quer ler.
  • namespace: o namespace da chave guest-attributes que você quer consultar.
  • key: o caminho dentro dos metadados guest-attributes em que o valor está armazenado.
  • zone: a zona em que a instância está localizada.

API

Use o método de API compute.instances.getguestattributes:

    GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes?queryPath=namespace/key
    

Substitua as seguintes informações:

  • project-id: o ID do projeto.
  • zone: a zona em que a instância está localizada.
  • instance-name: o nome da instância em que está o valor de metadados de atributos de convidado que você quer ler.
  • namespace: o namespace da chave guest-attributes que você quer consultar.
  • key: o caminho dentro dos metadados guest-attributes em que o valor está armazenado.

Para recuperar todas as chaves de um namespace, omita a key:

    GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes?queryPath=namespace

Para recuperar todas as chaves em cada namespace na instância, omita completamente namespace e queryPath:

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes

Como alternativa, se você tiver um token do OAuth, será possível usar curl:

curl -H "Authorization: Bearer oauth-token" https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes?queryPath=namespace/key

Substitua o seguinte:

  • oauth-token: seu token OAuth.
  • project-id: o ID do projeto.
  • zone: a zona em que a instância está localizada.
  • instance-name: o nome da instância em que está o valor de metadados de atributos de convidado que você quer ler.
  • namespace: o namespace da chave guest-attributes que você quer consultar.
  • key: o caminho dentro dos metadados guest-attributes em que o valor está armazenado.

Como excluir atributos de convidado

Também é possível excluir os atributos de convidado. Por exemplo, use curl para excluir uma chave específica:

curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/namespace/key -H "Metadata-Flavor: Google"

Substitua as seguintes informações:

  • namespace: o namespace da chave guest-attributes que você quer excluir.
  • key: o caminho dentro de guest-attributes em que o valor está armazenado.

Como desativar atributos de convidado na organização ou pasta

Se você não quiser que nenhuma das instâncias da sua organização ou pasta ative os atributos de convidado, modifique e desative o recurso por completo.

Defina a restrição constraints/compute.disableGuestAttributesAccess na sua organização ou pasta, substituindo project-id pelo nome do seu projeto:

    gcloud resource-manager org-policies enable-enforce \
        constraints/compute.disableGuestAttributesAccess \
        --project project-id

Leia Como usar restrições para saber mais sobre como definir e gerenciar restrições nas suas organizações.

Como aguardar atualizações

Os valores de metadados podem mudar durante a execução da instância. Por isso, use o recurso "aguardar mudança" para que o servidor de metadados seja notificado sobre atualizações em metadados. Esse recurso permite executar solicitações HTTP GET pendentes que retornam somente quando ocorrem mudanças nos metadados especificados. É possível usar esse recurso em metadados personalizados ou definidos pelo servidor. Desse modo, se ocorrer qualquer mudança na sua instância ou projeto ou se alguém atualizar um metadado personalizado, será possível reagir às mudanças de maneira programática. Por exemplo, execute uma solicitação na chave tags para que seja retornada apenas se ocorrer mudanças no conteúdo dos metadados das tags. Quando a solicitação retornar, ela informará o novo valor dessa chave de metadados.

Para executar uma solicitação "aguardar mudança", 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"
    

Depois que ocorrer uma mudança na chave de metadados especificada, a consulta retornará um novo valor. Neste exemplo, quando uma solicitação é feita ao método setInstanceTags, ela retorna os valores novos:

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

Também é possível executar uma solicitação "aguardar mudança" 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"
    

Se ocorrer qualquer mudança, o servidor de metadados retornará o conteúdo novo:

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

Com o recurso "aguardar mudança", também é possível fazer correspondência com a solicitação e definir tempos limites.

Como usar ETags

Quando você envia uma consulta "aguardar mudança" simples, o servidor de metadados retornará uma resposta caso ocorra qualquer mudança no conteúdo desses metadados. No entanto, há uma disputa inerente entre uma atualização de metadados e uma solicitação "aguardar mudança" que está sendo emitida. Portanto, é bom ter um meio confiável de saber que você está recebendo o valor de metadados mais recente.

Para ajudar neste caso, use 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 ETags coincidirem, a solicitação "aguardar mudança" será aceita. Caso contrário, isso será uma indicação de que o conteúdo dos metadados mudou após a última recuperação do valor da ETag. O servidor de metadados retorna valor mais recente imediatamente.

Para receber o valor atual da ETag de uma chave de metadados, faça uma solicitação para essa chave e imprima os cabeçalhos. Em curl, isso pode ser feito com o uso da sinalização -v:

    user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
    
    * 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
    <
    cheese
    lettuce

Use esse valor de ETag na solicitação "aguardar mudança":

    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 faz a correspondência com o valor da ETag que você especificou e, se esse valor mudar, a solicitação retornará o novo conteúdo da chave de metadados.

Veja no exemplo em Python a seguir como monitorar, de maneira programática, o servidor de metadados para verificar se ocorreram mudanças:

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

Como definir tempos limites

Se você quiser que a solicitação "aguardar mudança" atinja um tempo limite após uma determinada quantidade de segundos, defina o parâmetro de consulta timeout_sec=<timeout-in-seconds>. O parâmetro timeout_sec limita o tempo de espera da solicitação ao número de segundos especificado. Quando a solicitação atinge esse limite, ela retorna o conteúdo atual da chave de metadados. Veja abaixo um exemplo de uma solicitação "aguardar mudança" que foi 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"
    

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

Códigos de status

Quando você faz uma solicitação "aguardar mudança", o servidor de metadados retorna códigos de status HTTP padrão para indicar se houve sucesso ou falha. As condições da rede podem fazer com que o servidor de metadados falhe ao responder sua solicitação e retorne um código de erro. Se esse for o caso, desenvolva seu aplicativo para ser tolerante a falhas e capaz de reconhecer e processar esses erros.

Os status a seguir podem ser retornados pelo servidor de metadados:

Status Descrição
HTTP 200 Pronto! Ocorreu uma mudança em um valor ou foi atingido o valor de timeout_sec especificado e a solicitação foi retornada com êxito.
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. O servidor de metadados também retorna esse erro se os metadados forem excluídos enquanto você estiver aguardando uma mudança.
Error 503 Ocorreu um erro de servidor ou evento de manutenção temporário. Tente fazer a solicitação novamente.

Como receber notificações de migração em tempo real

O servidor de metadados fornece informações sobre as opções e configurações de programação de uma instância, por meio do diretório scheduling/ e do atributo maintenance-event. É possível usar esses atributos para saber mais sobre as opções de programação de uma instância de máquina virtual. Use também esses metadados para receber uma notificação por meio do atributo maintenance-event quando um evento de manutenção estiver prestes a acontecer. Por padrão, todas as instâncias de máquina virtual são definidas para fazer migração em tempo real. Assim, o servidor de metadados recebe notificações de eventos de manutenção antes que seja feita a migração em tempo real de uma instância de VM. Se escolheu encerrar sua instância de VM durante uma manutenção, o Compute Engine será encerrado automaticamente e poderá reiniciar sua instância de VM se o atributo automaticRestart estiver definido. Para saber mais sobre os eventos de manutenção e o comportamento da instância durante tais eventos, consulte as informações sobre opções e configurações de programação.

Para saber quando um evento de manutenção ocorrerá basta consultar o atributo maintenance-event periodicamente. O valor desse atributo muda 60 segundos antes do início do evento de manutenção. Dessa forma, é possível configurar o código do seu aplicativo para que acione qualquer tarefa que você queira executar antes de um evento de manutenção, como fazer backup de dados ou atualizar registros. Um script Python de amostra também é fornecido pelo Compute Engine para demonstrar como verificar os avisos de eventos de manutenção.

O Compute Engine dá um aviso de 60 segundos somente nestas circunstâncias:

  • Você definiu as opções de disponibilidade da instância como migração em tempo real durante um evento de manutenção.

  • Você consultou o atributo maintenance-event pelo menos uma vez desde o último evento de manutenção. Se você nunca consultou o atributo maintenance-event ou não o fez desde a última migração, o Compute Engine considera que a instância não exige aviso prévio sobre eventos de manutenção. Nesse caso, o evento de manutenção será iniciado imediatamente, ignorando o aviso de 60 segundos. Se você não quiser ignorar tal aviso, certifique-se de que o atributo maintenance-event é consultado pelo código de cliente no mínimo uma vez entre os eventos de migração.

Para consultar o atributo maintenance-event:

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

O valor inicial e padrão do atributo maintenance-event é NONE.

  • Para instâncias de GPU, durante um evento de manutenção, o atributo muda de NONE para TERMINATE_ON_HOST_MAINTENANCE. Esse atributo é atualizado 60 minutos antes do início do evento de encerramento.

  • Para instâncias que não são de GPU, mas com uma opção de programação de migrate, o atributo maintenance-event muda da seguinte maneira:

    1. No início do evento de migração, o valor muda de NONE para MIGRATE_ON_HOST_MAINTENANCE. Esse atributo é atualizado 60 segundos antes do início do evento de encerramento.
    2. Durante o evento e enquanto a instância de VM está sendo migrada em tempo real, o valor permanece como MIGRATE_ON_HOST_MAINTENANCE.
    3. Após o término do evento de manutenção, o valor volta a ser NONE.

É possível usar o atributo maintenance-event com o recurso "aguardando atualizações" para notificar scripts e aplicativos quando um evento de manutenção estiver prestes a começar e terminar. Assim, é possível automatizar qualquer ação que você queira executar antes ou depois do evento. Veja no exemplo em Python a seguir, como implementar esses dois recursos em conjunto.

Exemplo de script em Python para consultar eventos de manutenção


    import time

    import requests

    METADATA_URL = 'http://metadata.google.internal/computeMetadata/v1/'
    METADATA_HEADERS = {'Metadata-Flavor': 'Google'}

    def wait_for_maintenance(callback):
        url = METADATA_URL + 'instance/maintenance-event'
        last_maintenance_event = None
        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']

            if r.text == 'NONE':
                maintenance_event = None
            else:
                maintenance_event = r.text

            if maintenance_event != last_maintenance_event:
                last_maintenance_event = maintenance_event
                callback(maintenance_event)

    def maintenance_callback(event):
        if event:
            print('Undergoing host maintenance: {}'.format(event))
        else:
            print('Finished host maintenance')

    def main():
        wait_for_maintenance(maintenance_callback)

    if __name__ == '__main__':
        main()

Como verificar a versão do endpoint do servidor

Para verificar a versão do endpoint do servidor de metadados, revise o URI que você está usando para fazer solicitações ao servidor.

Versão do endpoint de metadados URI
v0.1 http://metadata.google.internal/0.1/meta-data/…
v1beta1 http://metadata.google.internal/computeMetadata/v1beta1/…
v1 http://metadata.google.internal/computeMetadata/v1/…

Como desativar endpoints legados

Como preparação para o encerramento dos endpoints de servidor de metadados v0.1 e v1beta1, desative-os no nível do projeto ou da instância.

Para desativar os endpoints de servidor de metadados v0.1 e v1beta1, siga as instruções sobre como definir metadados personalizados e defina disable-legacy-endpoints=TRUE.

Por exemplo, para desativar o endpoint do servidor de metadados no nível do projeto usando a ferramenta de linha de comando gcloud, execute este comando:

gcloud compute project-info add-metadata \
        --metadata disable-legacy-endpoints=TRUE 

Como fazer a transição para o endpoint de servidor de metadados v1

Para informações sobre como fazer a transição do endpoint v0.1 ou v1beta1 para v1, consulte Como migrar para o endpoint do servidor de metadados v1.

A seguir