Como armazenar e recuperar metadados de instância

Os metadados de cada instância são armazenados em um servidor de metadados. Consulte esse servidor na instância e na API Compute Engine por meio de programação. Faça isso para conseguir informações sobre a instância como nome do host, ID da instância, scripts de inicialização e encerramento, metadados personalizados e dados da conta de serviço. O acesso da instância à API do servidor de metadados é fornecido automaticamente, sem qualquer autorização adicional.

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

Os metadados são armazenados no formato key:value. Há um conjunto padrão de entradas de metadados ao qual você tem acesso em todas as instâncias. Também é possível configurar metadados personalizados.

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

Versão atual: v1

Sempre use 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á alterações.

Antes de começar

Permissões necessárias para a tarefa

Para executar esta tarefa, é preciso ter as permissões abaixo.

  • compute.instances.setMetadata na instância, para configurar metadados na instância
  • compute.projects.setCommonInstanceMetadata no projeto, para configurar metadados do projeto todo
  • compute.projects.get no projeto, apenas para receber metadados
  • compute.instances.get na instância, apenas para receber metadados

Metadados de projeto e instância

É possível atribuir metadados tanto no nível do projeto quanto no nível da instância. Os metadados de projeto são propagados por todas as instâncias de máquina virtual do projeto, enquanto os metadados de instância só afetam uma instância específica.

Chaves de metadados padrão

No Google Compute Engine, é definido um conjunto de entradas de metadados padrão contendo informações sobre a sua instância ou o seu projeto. Os metadados padrão são sempre definidos e configurados no servidor. Não é possível editar nenhum desses pares de metadados manualmente.

A seguir, há uma lista dos metadados padrão disponíveis para um projeto. Algumas entradas de metadados são diretórios que contêm 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, enquanto numeric-project-id é uma chave de metadados associada a um valor.

Referente 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 do servidor de metadados legados para todas as instâncias no projeto. Sempre defina disable-legacy-endpoints=TRUE, a menos que o projeto use endpoints legados. Atualize os aplicativos para usar os endpoints da v1.
attributes/enable-oslogin Ativa o recurso de gerenciamento de chaves SSH do login do SO 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 para gerenciamento de chaves SSH, esse atributo permitirá que você configure chaves SSH públicas que possam se conectar a instâncias nesse projeto. Quando há várias chaves SSH, cada uma é separada por um caractere de nova linha (\n). Esse valor é uma string. Chaves SSH gerenciadas por 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 código do projeto numérico (número do projeto) da instância, que é diferente do nome do projeto visível no Console do Google Cloud Platform. Esse valor é diferente do valor de entrada de metadados project-id.
project-id O ID do projeto.

A seguir, há uma lista dos metadados padrão disponíveis para uma instância:

Referente 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 de gerenciamento de chaves SSH do login do SO nesta instância quando você define enable-oslogin=TRUE.
attributes/vmdnssetting Configura como os nomes DNS internos são formatados para esta 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 para gerenciamento de chaves SSH, esse atributo permitirá que você configure chaves SSH públicas que possam se conectar a essa instância. Quando há várias chaves SSH, cada uma é separada por um caractere de nova linha (\n). Esse valor é uma string. Chaves SSH gerenciadas por 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 de texto livre da instância, atribuída por meio da sinalização --description ou definida na API.
disks/ Um diretório dos discos anexados à instância.
guest-attributes/ Valores de metadados de instância personalizada 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 infrequentes para outros aplicativos. Qualquer usuário ou processo em sua instância de VM pode ler e gravar nos namespaces e nas chaves dos metadados de “guest-attributes”.
hostname O nome do host da instância.
id O ID da instância. Trata-se de um identificador numérico exclusivo gerado pelo Google Compute Engine. Ele é útil para identificar instâncias quando você não quer usar nomes de instância.
machine-type O valor de metadados para o tipo de máquina dessa instância tem o seguinte formato: projects/[NUMERIC_PROJECT_ID]/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 dos IPs externos que apontam para essa instância de máquina virtual para a interface de rede em <index>. Nele, especificamente, é fornecida uma lista dos IPs externos atendidos pelas regras de encaminhamento que direcionam pacotes a esta instância.
scheduling/ Um diretório com opções de programação para a 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 por meio da 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 por meio da API.
scheduling/preemptible A configuração Preemptiva da instância. Se o valor é TRUE, a instância é preemptiva. Esse valor é definido quando você cria 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 Aviso 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>/identity Um Token Web JSON, exclusivo na instância. Inclua o parâmetro "público" na solicitação para o valor de metadados desta instância. Por exemplo, `?audience=http://www.example.com`. Leia Como verificar a identidade das instâncias para saber como solicitar e verificar os tokens de identidade da instância.
tags Qualquer tag associada à instância.
zone O valor de metadados para a zona em que a instância é executada. Esse valor tem o seguinte formato: projects/[NUMERIC_PROJECT_ID]/zones/[ZONE]

Buscar metadados

Consulte o conteúdo do servidor de metadados enviando 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 enviar 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 que estão dentro da instância associada. Não consulte os metadados padrão de uma instância a partir de outra instância, nem diretamente do seu computador local. Use ferramentas padrão da instância como curl ou wget para o servidor de metadados dela.

Ao consultar metadados, inclua o seguinte cabeçalho em todas as suas solicitações:

Metadata-Flavor: Google

Esse cabeçalho indica que a solicitação foi enviada com a intenção de recuperar valores de metadados, não acidentalmente de uma fonte desprotegida. Ele permite que os dados solicitados sejam retornados do servidor de metadados. A solicitação será negada pelo servidor de metadados se esse cabeçalho não for incluído.

Cabeçalho X-Forwarded-For

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

Limitações

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

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

http://metadata.goog/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

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

http://metadata.goog/computeMetadata/v1/instance/service-accounts1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

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

Caractere codificado Valor aceito
%21 

!
%24 

$
%27 

'
%28 

(
%29 

)
%2A 

*
%2C 

,
%40 

@

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

Quando você solicita informações do servidor de metadados, a solicitação e a resposta subsequente de metadados nunca deixam o host físico que executa a instância da máquina virtual.

Consultar listas de diretórios

No servidor de metadados, diretórios são usados 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 dos discos anexados a esta 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 0/ do disco, consulte o URL específico desse diretório:

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

device-name
index
mode
type

Como consultar endpoints

Se a chave de metadados não é um diretório, ela é um ponto de extremidade que retorna um ou mais valores. Por exemplo, para consultar o modo de um disco específico, consulte o seguinte ponto de extremidade:

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

READ_WRITE

Há um formato de resposta predefinido para cada ponto de extremidade. Em alguns pontos de extremidade, os dados podem ser retornados no formato JSON por padrão. Em outros, eles são retornados como uma string. Modifique a especificação de formato de dados padrão usando o parâmetro de consulta alt=json ou alt=text. Com o primeiro parâmetro, os dados são retornados no formato JSON. Com o segundo, eles são retornados como uma representação de texto simples.

Por exemplo, com a chave tags, os dados são retornados automaticamente no formato JSON. Para retornar os dados no formato de texto, especifique 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

Consultar metadados de maneira recursiva

Para retornar todo o conteúdo sob um diretório, use o parâmetro de consulta recursive=true com a 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. Para 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

Configurar metadados personalizados

Configure metadados personalizados para uma instância ou um projeto no Console do Google Cloud Platform, na ferramenta de linha de comando gcloud ou na API Compute Engine. Os metadados personalizados são úteis para passar valores arbitrários ao projeto ou à instância, bem como para definir os scripts de inicialização e de encerramento.

Limites de tamanho para metadados personalizados

No Google Compute Engine, há os seguintes limites de tamanho para valores de metadados personalizados:

  • 256 KB para cada entrada de metadados individual
  • 512 KB total combinado para todas as entradas de metadados por instância

As chaves SSH são armazenadas como metadados personalizados sob a chave ssh-keys. Quando o conteúdo de metadados para essa chave exceder o limite de 256 KB, não será possível adicionar 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 dos scripts de inicialização ou de encerramento, eles também poderão ser armazenados como metadados personalizados e contabilizados para esses limites de tamanho. Para evitar que isso aconteça, armazene o script de inicialização ou de encerramento como um arquivo hospedado em um local externo, como o Google Cloud Storage, e forneça o URL do script de inicialização ao criar uma instância. O download desses arquivos será feito na instância de VM, em vez de armazenados no servidor de metadados.

Como definir metadados de instância

Defina os metadados personalizados de uma instância no Console do GCP, na ferramenta gcloud ou na API. Os metadados de instância são destinados apenas a uma instância específica.

Como definir metadados na criação de uma instância

Console

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

    Acessar a página "Instâncias da 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, insira quantos pares chave-valor forem necessários para os seus metadados personalizados.
  5. Clique em Criar para criar a instância.

gcloud

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

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

API

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

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

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

Atualizar metadados em uma instância em execução

Console

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

gcloud

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

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

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

Para alterar a entrada de lettuce=romaine para lettuce=green, use:

gcloud compute instances add-metadata INSTANCE --metadata lettuce=green

Para remover a entrada lettuce=romaine, especifique a chave e exclua o valor.

gcloud compute instances remove-metadata INSTANCE --keys lettuce

API

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

Impressão digital é uma string aleatória de caracteres gerada pelo Compute Engine que é usada para executar o bloqueio otimista. Forneça o valor de impressão digital correspondente para executar sua solicitação. A impressão digital muda após cada solicitação. Solicitações com impressões digitais incompatíveis são rejeitadas. Dessa forma, só é possível fazer uma atualização por vez, evitando colisões.

Para buscar a impressão digital atual de uma instância e consultar os pares chave-valor existentes para ela. envie uma solicitação instances().get:

GET https://www.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"
   }
  ]
 },
 ...
}

Em seguida, envie uma solicitação ao método instances().setMetadata e configure os seus pares chave-valor de metadados personalizados. Caso haja pares chave-valor que você queira manter na instância, inclua esses pares na solicitação com os novos pares chave-valor.

POST https://www.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 chave-valor de metadados de uma instância, especifique uma solicitação instances().setMetadata e exclua a propriedade items. Note que ainda é necessário incluir a propriedade da impressão digital atual dos metadados para que essa solicitação seja feita:

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

{
 "fingerprint": "5rC_DXxBUZw="
}

Como definir metadados personalizados de projeto

Configure metadados de projeto para aplicar os metadados a todas as instâncias no projeto. Por exemplo, quando você define um par de metadados de projeto baz=bat, esse par é automaticamente aplicado a todas as instâncias no projeto.

Console

  1. Acesse a página Metadados.
  2. Clique em Editar.
  3. Adicione ou edite uma entrada de metadados.
  4. Salve as alterações.

gcloud

Com a 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

Veja os metadados usando o comando describe:

gcloud compute project-info describe

Por exemplo, você pode receber uma resposta semelhante à seguinte:

...
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.

Opcionalmente, use a sinalização --metadata-from-file para especificar um ou mais arquivos de leitura de metadados. É possível remover valores de metadados com o comando project-info remove-metadata.

API

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

Impressão digital é uma string aleatória de caracteres gerada pelo Compute Engine que é usada para executar o bloqueio otimista. Forneça o valor de impressão digital correspondente para executar sua solicitação. A impressão digital muda após cada solicitação. Solicitações com impressões digitais incompatíveis são rejeitadas. Dessa forma, só é possível fazer uma atualização por vez, evitando colisões.

Para buscar 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://www.googleapis.com/compute/v1/projects/myproject

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

Em seguida, envie uma solicitação ao método projects().setCommonInstanceMetadata e configure os seus pares chave-valor de metadados personalizados.

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

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

Consultar metadados personalizados

Consulte metadados personalizados de instância ou projeto no Console do GCP, na ferramenta de linha de comando gcloud ou na API.

Console

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

Para consultar os metadados personalizados de uma instância:

  1. Acesse a página Instâncias de VM.
  2. Clique na instância dos metadados visualizados.
  3. Em Metadados personalizados, veja os metadados personalizados da instância.

gcloud

Consulta dos metadados do projeto:

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

Consulta dos metadados da instância:

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

A sinalização --flatten pode ser usada para definir o escopo da saída para uma chave de metadados relevante. Veja no exemplo a seguir uma instância com um par de chave-valor de metadados personalizados 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, envie uma solicitação vazia ao método projects().get:

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

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

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

Como configurar e atualizar o tempo limite da solicitação

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

Quando usar atributos de convidado

Use os atributos de convidado somente para casos de uso que exigem pequenas quantidades de dados que não mudam com frequência. Os melhores casos de uso para atributos de convidado têm as características a seguir:

  • O número de consultas está limitado a um máximo de 10 consultas por minuto 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 do 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 possam ser gravados no servidor.

Os atributos de convidado funcionam bem em situações em que é preciso publicar dados não frequentes e de baixo volume. Por exemplo, os atributos de convidado funcionam bem nos casos de uso a seguir:

  • Os scripts de inicialização podem sinalizar a inicialização bem-sucedida definindo um valor de status personalizado nos atributos de convidado.
  • Os agentes de gerenciamento de configuração podem publicar um nome e uma versão do sistema operacional de convidado nos atributos de convidado.
  • O agente de gerenciamento de inventário pode publicar a lista de pacotes instalados na VM para os atributos de convidado.
  • O software de orquestração de carga de trabalho pode sinalizar a conclusão de uma operação interna no convidado para o plano de controle do software, definindo um valor de status personalizado nos atributos de convidado.

Os atributos de convidado não são um substituto para o streaming de eventos, o Cloud Pub/Sub ou outras formas de armazenamento de dados e repositórios de configuração.

Para leituras e gravações de dentro de uma instância, o servidor de metadados fornece autenticação e autorização automática no nível da instância. Cada instância pode ler ou gravar apenas no próprio servidor de metadados. Outras instâncias não podem acessar o servidor de metadados de outra instância. Os usuários e as contas de serviço só podem ler instâncias de atributos de visitante de fora da instância se tiverem um papel de IAM que forneça a permissão compute.instances.getGuestAttributes.

Como ativar atributos de convidado na instância

Por padrão, os atributos de convidados estão desativados. Para ativar os atributos de convidado, defina os valores de metadados necessários nas instâncias individuais ou nos metadados do projeto:

Console

Defina enable-guest-attributes nos metadados da instância ao criá-la:

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

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

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

Defina enable-guest-attributes nos metadados de todo o projeto para que seja aplicado a todas as instâncias do projeto:

  1. Acesse a página Metadados.
  2. Clique em Editar.
  3. Adicione uma entrada de metadados em que a chave seja enable-guest-attributes e o valor seja TRUE. Como alternativa, defina o valor como FALSE para desativar o recurso.
  4. Clique em Salvar para aplicar as alterações.

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

  1. Acesse a página Instâncias de VMs.
  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. Em Metadados personalizados, adicione uma entrada de metadados em que a chave é enable-guest-attributes e o valor é TRUE. Como alternativa, defina o valor como FALSE para excluir a instância do recurso.
  5. Na parte inferior da página de detalhes da instância, clique em Salvar para aplicar as alterações à instância.

gcloud

Defina enable-oslogin-2fa nos metadados da instância ao criá-la:

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:

gcloud compute instances create [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

Defina enable-guest-attributes nos metadados de todo o projeto para que seja aplicado a todas as instâncias do 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

Como alternativa, é possível definir enable-guest-attributes como FALSE para desativar os atributos de convidado.

Defina 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:

gcloud compute instances add-metadata [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

Como alternativa, é possível definir enable-guest-attributes como FALSE para impedir que sua instância use atributos de convidado.

Como definir atributos de convidado

Qualquer processo em execução na máquina virtual pode gravar nos valores de atributos de convidado, incluindo scripts e aplicativos que não têm privilégios de nível sudo ou de administrador. Usuários ou contas de serviço fora da instância não podem gravar em valores de metadados de atributos de convidado.

Por exemplo, use uma solicitação de curl de sua 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"

em que:

  • [NAMESPACE] é um agrupamento lógico para sua [KEY]. Os atributos de convidado precisam ter um namespace;
  • [VALUE] é o valor que você quer gravar;
  • [KEY] é o caminho dentro de guest-attributes em que o valor é armazenado.

Como ver atributos de convidado

Usuários ou contas de serviço podem ler os atributos de convidado se tiverem um papel de IAM que forneça a permissão compute.instances.getGuestAttributes. Como alternativa, qualquer usuário ou aplicativo dentro da instância pode ler os valores de metadados para essa instância específica.

Qualquer processo em execução na máquina virtual pode gravar no valor de atributos de convidado, incluindo scripts e aplicativos que não têm privilégios de nível sudo ou de administrador. Por exemplo, use uma solicitação de curl de sua instância para ler um valor no caminho de metadados guest-attributes:

curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/[NAMESPACE]/[KEY] -H "Metadata-Flavor: Google"

[KEY] é o caminho dentro de guest-attributes em que você quer ler o valor dos metadados.

Como alternativa, é possível retornar todos os valores do atributo de convidado em uma solicitação:

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

em que:

  • [NAMESPACE] é um agrupamento lógico para sua [KEY]. Os atributos de convidado precisam ter um namespace;

  • [KEY] é o caminho dentro de guest-attributes em que o valor é armazenado.

gcloud

Use a ferramenta de linha de comando gcloud para ler valores de metadados do atributo 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]

em que:

  • [INSTANCE_NAME] é o nome da instância de que você quer ler o valor de metadados do atributo de convidado;
  • [KEY] é o caminho nos metadados de guest-attributes em que o valor é armazenado;
  • [ZONE] é a zona em que a instância está localizada.

API

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

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]/[KEY]

em que:

  • [PROJECT_ID] é o ID do projeto;
  • [ZONE] é a zona em que o disco está;
  • [INSTANCE_NAME] é o nome da instância de que você quer ler o valor de metadados do atributo de convidado;
  • [KEY] é o caminho nos metadados de guest-attributes em que o valor é armazenado.

Para recuperar todas as chaves de um [NAMESPACE], omita a [KEY]:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]

Para recuperar todas as chaves em cada namespace da instância, omita totalmente o [NAMESPACE] e o queryPath:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes

Como alternativa, se você tiver um token OAuth, use o curl:

curl -H "Authorization: Bearer [OAUTH_TOKEN]" https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]/[KEY]

em que:

  • [OAUTH_TOKEN] é seu token OAuth;
  • [PROJECT_ID] é o ID do projeto;
  • [ZONE] é a zona em que o disco está;
  • [INSTANCE_NAME] é o nome da instância de que você quer ler o valor de metadados do atributo de convidado;
  • [NAMESPACE] é um agrupamento lógico para sua [KEY]. Os atributos de convidado precisam ter um namespace;
  • [KEY] é o caminho nos metadados de guest-attributes em que o valor é armazenado.

Como excluir atributos de convidado

Também é possível excluir os atributos de convidado. Por exemplo, use o 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"

em que:

  • [NAMESPACE] é um agrupamento lógico para sua [KEY]. Os atributos de convidado precisam ter um namespace;
  • [KEY] é o caminho dentro de guest-attributes em que o valor é armazenado.

Como desativar atributos de convidado em sua organização ou pasta

Se você não quiser que nenhuma das instâncias de sua organização ou pasta ative atributos de convidado, substitua e desative o recurso completamente.

Defina a restrição constraints/compute.disableGuestAttributesAccess na sua organização ou pasta:

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess --project [PROJECT_ID]

[PROJECT_ID] é o nome do projeto.

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

Como aguardar atualizações

Como os valores de metadados podem ser alterados durante a execução da instância, no servidor de metadados, você tem a opção de ser notificado sobre alterações de metadados pelo recurso wait-for-change. Com esse recurso, é possível fazer solicitações HTTP GET que são respondidas apenas quando metadados específicos são alterados. Use esse recurso em metadados personalizados ou definidos pelo servidor para que, caso algo seja alterado na sua instância ou no seu projeto ou alguém atualize um metadado personalizado, você possa reagir à alteração por meio de programação. Por exemplo, na chave tags, faça uma solicitação que só é respondida quando o conteúdo dos metadados das tags é alterado. Quando a solicitação é respondida, ela retorna o novo valor dessa chave de metadados.

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"

Depois que a chave de metadados especificada é alterada, a consulta retorna o novo valor. Neste exemplo, quando a solicitação é enviada ao método setInstanceTags, ela retorna os valores:

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 wait-for-change de maneira recursiva no conteúdo de um diretório:

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

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

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 wait-for-change, faça a correspondência com a solicitação e defina os tempos limites.

Como usar ETags

Quando você executa uma consulta wait-for-change simples, uma resposta do servidor de metadados é retornada quando o conteúdo desses metadados é alterado. No entanto, há uma condição de corrida inerente entre uma atualização de metadados e uma solicitação wait-for-change que está sendo emitida, assim, é bom ter uma forma confiável de saber se você está recebendo o valor mais recente dos metadados.

Para isso, use o parâmetro de consulta last_etag para comparar o valor de ETag fornecido com o valor de ETag salvo no servidor de metadados. Quando há correspondência entre os valores de ETag, a solicitação wait-for-change é aceita. Caso contrário, isso indica que o conteúdo dos metadados foi alterado após a última recuperação do valor de ETag, e o valor mais recente é retornado imediatamente no servidor de metadados.

Para buscar o valor de ETag atual para uma chave de metadados, envie uma solicitação a essa chave e imprima os cabeçalhos. No CURL, faça isso com a 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 wait-for-change:

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

A comparação com o valor de ETag que você especificou é feita no servidor de metadados e, se esse valor for alterado, o novo conteúdo da chave de metadados será retornado pela solicitação.

Na amostra de Python a seguir, veja como monitorar o servidor de metadados de maneira programática para verificar se houve alterações:

compute/metadata/main.py 
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 limites

Para a sua solicitação wait-for-change expirar após um determinado número de segundos, configure o parâmetro de consulta timeout_sec=<timeout-in-seconds>. Com o parâmetro timeout_sec, o tempo de espera da sua solicitação é limitado ao número de segundos que você especificou. Quando esse limite é atingido, o conteúdo atual da chave de metadados da solicitação é retornado. Aqui temos um exemplo de uma solicitação wait-for-change configurada para expirar após 360 segundos:

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

Quando você configura o parâmetro timeout_sec, a solicitação sempre é respondida após o número especificado de segundos, mesmo quando o valor dos metadados não é alterado. Só é possível definir um valor inteiro como tempo limite.

Códigos de status

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

Os seguintes status podem ser retornados pelo servidor de metadados:

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

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

O servidor de metadados disponibiliza 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. Use esses atributos para conhecer as opções de programação de uma instância de máquina virtual e utilize esses metadados para notificá-lo quando um evento de manutenção estiver prestes a acontecer por meio do atributo maintenance-event. Por padrão, todas as instâncias da máquina virtual estão configuradas para migração em tempo real, para que o servidor de metadados receba notificações de eventos de manutenção antes que uma instância da VM seja migrada. Se você optar pelo encerramento da sua instância de VM durante a manutenção, o Compute Engine será encerrado automaticamente e, se preferir, a instância da VM será reiniciada, se o atributo automaticRestart estiver configurado. Para saber mais sobre eventos de manutenção e comportamento da instância durante os eventos, leia opções e configurações de programação.

Para saber quando ocorrerá um evento de manutenção, consulte o atributo maintenance-event periodicamente. O valor desse atributo é alterado 60 segundos antes de um evento de manutenção ser iniciado, oferecendo ao código do aplicativo uma forma de acionar as tarefas a serem executadas antes de um evento de manutenção, como backup de dados ou atualização de registros. Um script Python de amostra também é fornecido pelo Compute Engine para demonstrar como verificar os avisos de eventos de manutenção.

O aviso de 60 segundos é fornecido pelo Compute Engine somente quando:

  • As opções de disponibilidade da instância são definidas para migração em tempo real durante um evento de manutenção.

  • O atributo maintenance-event é consultado pelo menos uma vez desde o último evento de manutenção. Se você nunca consultou o atributo maintenance-event ou isso não foi feito desde a última migração, o Compute Engine considera que os avisos de manutenção dessa instância não são necessários. Esse evento de manutenção é iniciado imediatamente ignorando o aviso de 60 segundos. Se você não quiser ignorar o aviso de 60 segundos, o código do cliente precisará consultar o atributo maintenance-event pelo menos uma vez entre os eventos de migração.

Para consultar o atributo do maintenance-event:

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

NONE

O valor inicial padrão do atributo maintenance-event é NONE. Antes de um evento de manutenção transparente ser iniciado, o valor maintenance-event é:

  1. alterado de NONE para MIGRATE_ON_HOST_MAINTENANCE;
  2. durante o evento e a migração da VM, o valor permanece como MIGRATE_ON_HOST_MAINTENANCE;
  3. alterado novamente para NONE depois que o evento de manutenção é concluído.

Use o atributo maintenance-event com o recurso de aguardar atualizações para notificar scripts e aplicativos quando um evento de manutenção estiver prestes a ser iniciado ou concluído. Assim, é possível automatizar qualquer ação que você queira executar antes ou depois do evento. Veja no exemplo a seguir, em Python, como implementar esses dois recursos conjuntamente.

compute/metadata/main.py 

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 fazer a transição para o v1

O servidor de metadados v1 funciona um pouco diferente do servidor v1beta1 anterior. Estas são algumas das alterações que precisam ser feitas para o novo servidor de metadados:

  • Atualize as solicitações de metadados para incluir o cabeçalho Metadata-Flavor: Google.

    No novo servidor de metadados, o cabeçalho Metadata-Flavor: Google é obrigatório em todas as solicitações. Esse cabeçalho é usado para confirmar que a solicitação foi feita com a intenção de recuperar valores de metadados. Atualize as suas solicitações para incluir esse cabeçalho nelas. Por exemplo, agora uma solicitação para o atributo disks/ fica assim:

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

  • Solicitações de atualização usando o cabeçalho X-Forwarded-For

    Essas solicitações são rejeitadas automaticamente pelo servidor porque, em geral, isso indica que foram enviadas por proxy. Remova esse cabeçalho das suas solicitações.

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
Documentação do Compute Engine
Comentários sobre o produto