Como armazenar e recuperar metadados de instâncias

Cuidado: qualquer processo que possa consultar o URL de metadados tem acesso a todos os valores no servidor de metadados. Isso inclui todos os valores de metadados personalizados que você grava no servidor. O Google recomenda que você tenha cuidado ao gravar valores confidenciais no servidor de metadados ou ao executar processos de terceiros.

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

O servidor de metadados é útil principalmente quando usado com os scripts de inicialização e de encerramento. É possível usá-los 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 para o IP externo de uma instância e usar 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, é possível reutilizar 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 a que 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.

O uso dos endpoints do servidor v1beta1 e do servidor de metadados v0.1 foi suspenso em 30 de setembro de 2020 e estão no processo de desativação. Verifique se você atualizou todas as solicitações para usar o v1. Para mais informações, consulte Como fazer a transição para o endpoint do servidor de metadados v1.

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

Antes de começar

• Para usar os exemplos de linha de comando deste guia, faça o seguinte:
  1. Instale a ferramenta de linha de comando gcloud ou a atualize para a versão mais recente.
  2. Defina uma região e uma zona padrão.
• Para usar os exemplos de API deste guia, configure o acesso à API.

Permissões exigidas para a tarefa

Para executar esta tarefa, é preciso ter a permissão a seguir:

• compute.instances.setMetadata na instância, se estiver configurando metadados de instância
• compute.projects.setCommonInstanceMetadata no projeto, se estiver configurando metadados de todo o projeto
• compute.projects.get no projeto, se estiver apenas recebendo metadados
• compute.instances.get na instância. se estiver apenas recebendo 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) no projeto, já os metadados da instância afetam somente essa instância.

Chaves de metadados padrão

Para uma lista de valores de metadados padrão que podem ser consultados, veja Valores de metadados da VM padrão.

Buscar metadados

Consulte o conteúdo do servidor de metadados enviando, de uma instância de máquina virtual, uma solicitação para os URLs raiz a seguir. 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 que estejam na instância associada. Não é possível consultar os metadados padrão de uma instância diretamente do seu computador local e nem de outra instância. É possível usar ferramentas padrão como curl ou wget da instância para o respectivo servidor de metadados.

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, em vez de recuperar involuntariamente de uma fonte insegura e permite que o servidor de metadados retorne os dados solicitados. Se você não fornecer esse cabeçalho, o servidor de metadados negará sua solicitação.

Observação: anteriormente o cabeçalho X-Google-Metadata-Request: True era obrigatório nas solicitações. Esses cabeçalhos ainda são compatíveis, mas recomendamos que você use o cabeçalho Metadata-Flavor em vez do cabeçalho X-Google-Metadata-Request: True.

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 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, observe que alguns caracteres codificados não são aceitos no caminho da solicitação. Caracteres codificados são aceitos apenas no caminho da consulta.

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

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

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

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

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

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

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

Quando você faz uma solicitação para receber informações do servidor de metadados, sua solicitação e a resposta de metadados subsequente nunca deixam o host físico que está executando a instância de 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 de discos anexado 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 o seguinte endpoint:

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 endpoint. Em alguns endpoints, os dados podem ser retornados no formato JSON por padrão. Em outros, são retornados como uma string. É possível substituir a especificação de formato de dados padrão usando os parâmetros de consulta alt=json ou alt=text que retornam dados no formato de string JSON ou como uma representação de texto simples, respectivamente.

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

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

Se você quiser retornar todo o conteúdo em um diretório, use o parâmetro de consulta recursive=true com 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 desejar retornar esses conteúdos no formato de texto, anexe o parâmetro de consulta alt=text:

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

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

Em campos que aceitam valores booleanos, TRUE ou FALSE, também é possível usar os seguintes valores:

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

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

Configurar metadados personalizados

Para definir metadados personalizados para uma instância ou um projeto, use o Console do Google Cloud, a ferramenta de linha de comando gcloud ou a API do Compute Engine. Metadados personalizados são úteis para transferir valores arbitrários para seu projeto ou instância e para definir os scripts de inicialização e encerramento.

Limites de tamanho para 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.

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, você não poderá adicionar mais chaves SSH. Se isso ocorrer, remova as chaves não utilizadas para liberar espaço de metadados para novas chaves.

O conteúdo dos scripts de inicialização e encerramento também pode ser armazenado na forma de metadados personalizados e contar para essas limitações de tamanho se você fornecer diretamente os scripts de inicialização ou encerramento. Para evitar isso, armazene seu script de inicialização ou 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 são baixados na instância da VM, em vez de serem armazenados no servidor de metadados.

Como definir metadados de instância

Defina metadados personalizados para uma instância no Console do Cloud, na ferramenta gcloud ou na API. Os metadados da instância se aplicam somente a uma instância específica.

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

Console

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

   Acessar instâncias de VM

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

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

Console

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

   Acessar 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 aditiva. Especifique apenas as chaves de metadados que você quer adicionar ou alterar. Se você especificar uma chave atual, o valor dela será atualizado com o novo valor.

Use a ferramenta de linha de comando gcloud e o comando instances add-metadata:

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

Se você quiser alterar 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 é alterada após cada solicitação. Se você fornecer uma impressão digital não correspondente, sua solicitação será rejeitada. Dessa forma, só é possível fazer uma atualização por vez, o que evita conflitos.

Para buscar a impressão digital atual de uma instância e consultar os pares de chave-valor atuais para ela. 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"
   }
  ]
 },
 ...
}

Em seguida, 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, eles precisarão ser incluídos na 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. Observe que ainda é necessário incluir a propriedade da impressão digital atual dos metadados para que a solicitação instances().setMetadata seja feita:

POST https://compute.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, 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

Usar a ferramenta de linha de comando gcloud e o comando project-info add-metadata. 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, é possível 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, é possível especificar um ou mais arquivos que terão os metadados lidos com o uso da 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 ao método projects().setCommonInstanceMetadata, fornecendo todos os novos valores de metadados.

Para realizar o bloqueio otimista, é possível fornecer uma impressão digital. Uma impressão digital é uma string aleatória de caracteres gerados pelo Compute Engine. A impressão digital muda após cada solicitação. Se você fornecer uma impressão digital incompatível, sua solicitação será rejeitada.

Se você não fornecer uma impressão digital, nenhuma verificação de consistência será realizada e a solicitação projects().setCommonInstanceMetadata será realizada. Esse comportamento é diferente de instances().setMetadata, em que uma impressão digital é sempre obrigatória.

Para obter a impressão digital atual de uma instância, execute 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=",
  ...
}

Em seguida, 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

Consulte a instância personalizada ou os metadados do projeto por meio do Console do Cloud, da ferramenta de linha de comando gcloud ou da API.

Console

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

Para consultar 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 direcionar a resposta a uma chave de metadados relevante. Por exemplo, a instância a seguir tem 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, 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 configurar e consultar atributos de convidado

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 atributos de convidado somente para casos de uso que exijam pequenas quantidades de dados que não mudem 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:

• 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 convidado do SO 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.

Observação: qualquer aplicativo ou usuário na instância pode ler e gravar dados nesses valores de metadados de atributo de convidado. Os atributos de convidado não foram criados para casos de uso que exijam um aplicativo do convidado e a autenticação e autorização do usuário. Por exemplo, não armazene chaves nem outros dados confidenciais que não podem estar disponíveis para todos os aplicativos no convidado.

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. As instâncias não podem acessar o servidor de metadados umas das outras. Os usuários e as contas de serviço poderão ler os atributos de convidado de uma instância de fora dela apenas se tiverem um papel de gerenciamento de identidade e acesso (IAM) que forneça 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 ativar os atributos de convidado, defina os valores de metadados necessários nas instâncias individuais ou nos metadados do projeto:

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

   Acessar instâncias de VM

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.

Definir enable-guest-attributes nos metadados do projeto para que se aplique 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. Adicione uma entrada de metadados em que a chave é enable-guest-attributes e o valor é TRUE. Se quiser, defina o valor como FALSE para desativar o recurso.

4. Clique em Salvar para aplicar as alterações.

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

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

   Acessar 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, adicione uma entrada de metadados com a chave enable-guest-attributes e o valor TRUE. Se preferir, 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

Para definir enable-guest-attributes nos metadados da instância ao criá-la, siga estas instruções:

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 do projeto para que se aplique 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 visitante:

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.

Para definir enable-guest-attributes nos metadados de uma instância atual, siga estas instruções:

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 gravar nos valores de atributos de convidado, incluindo scripts e aplicativos que não têm privilégios de 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, é possível usar uma solicitação curl de dentro 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"

Substitua o seguinte:

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

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

Como ver atributos de convidado

Usuários ou contas de serviço poderão ler atributos de convidado se tiverem um papel do IAM que forneça a permissão compute.instances.getGuestAttributes. Como alternativa, qualquer usuário ou aplicativo na 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 que inclui scripts e aplicativos que não têm privilégios de sudo ou de administrador. Por exemplo, é possível usar uma solicitação curl de dentro 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 o seguinte:

• 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, é possível retornar todos os valores do atributo 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 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

Substitua o seguinte:

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

API

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

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

Substitua o seguinte:

• project-id: o ID do projeto.
• zone: a zona em que a instância está localizada.
• instance-name: o nome da instância da qual você quer ler o valor de metadados do atributo de convidado.
• namespace: o namespace da chave guest-attributes que você quer consultar.
• key: o caminho dentro dos metadados guest-attributes em que o valor é 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 namespace e queryPath inteiramente:

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

Como alternativa, se você tiver um token OAuth, poderá 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 da qual você quer ler o valor de metadados do atributo de convidado.
• namespace: o namespace da chave guest-attributes que você quer consultar.
• key: o caminho dentro dos metadados guest-attributes em que o valor é 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 o seguinte:

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

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

Se você não quiser que nenhuma das instâncias da organização ou pasta ative os atributos de convidado, substitua 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 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.

Aguardar atualizações

Os valores de metadados podem mudar durante a execução da instância, por isso, o servidor de metadados pode ser notificado sobre alterações de metadados pelo recurso wait-for-change. Esse recurso permite executar solicitações HTTP GET pendentes que retornam somente quando os metadados especificados são alterados. Use esse recurso em metadados personalizados ou definidos pelo servidor para que, no caso de algo ser alterado na sua instância ou no seu projeto, ou de alguém atualizar um metadado personalizado, você possa reagir à alteração por meio de programação. Por exemplo, é possível executar uma solicitação na chave tags para que a solicitação seja retornada apenas se o conteúdo dos metadados das tags tiver sido alterado. Quando a solicitação é respondida, ela retorna o novo valor dessa chave de metadados.

Observação: só é possível executar uma solicitação wait-for-change em um endpoint de metadados ou de maneira recursiva no conteúdo de um diretório. Não é possível executar uma solicitação wait-for-change em uma listagem de diretórios, e o servidor de metadados não responderá à sua solicitação se você tentar fazer isso.

Não é possível executar uma solicitação wait-for-change para um token da conta de serviço. Se você tentar enviar uma solicitação wait-for-change ao URL de token da conta de serviço, imediatamente ocorrerá falha na solicitação.

Em ambos os casos, o erro 400 Solicitação inválida é retornado no Compute Engine.

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 disputa inerente entre uma atualização de metadados e uma solicitação wait-for-change que está sendo emitida, por isso é útil ter uma maneira confiável de saber que você está recebendo o valor de metadados mais recente.

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

Para receber o valor da ETag atual 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 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"

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

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

compute/metadata/main.py

Ver no GitHub

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

Observação: nesta amostra, a Etag inicial foi definida como 0. O servidor de metadados nunca retorna uma resposta tendo 0 como a ETag. Quando 0 for especificado como a última ETag em uma solicitação, o servidor de metadados responderá com o valor atual e a ETag. Isso guarda um pouco do código necessário para receber o valor inicial e a ETag.

Definir tempos limites

Se você quiser que a solicitação wait-for-change atinja o tempo limite após um determinado número 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 e, quando a solicitação atinge esse limite, retorna o conteúdo atual da chave de metadados. 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ê define o parâmetro timeout_sec, a solicitação sempre retorna após o número especificado de segundos, independentemente de o valor dos metadados ter sido alterado ou não. O tempo limite só pode ser definido com um valor inteiro.

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 retornado pelo servidor de metadados. Se esse for o caso, desenvolva seu aplicativo para ser tolerante a falhas, reconhecer e tratar esses erros.

Os seguintes status podem ser retornados pelo servidor de metadados:

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

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 e usar esses metadados para notificar quando um evento de manutenção estiver prestes a ocorrer por meio do atributo maintenance-event. Por padrão, todas as instâncias de máquina virtual são definidas como migração em tempo real, para que o servidor de metadados receba avisos de eventos de manutenção antes que seja feita a migração de uma instância de VM. Se você escolheu encerrar a instância de VM durante a manutenção, o Compute Engine será interrompido automaticamente e poderá reiniciar a instância de VM se o atributo automaticRestart estiver definido. 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.

É possível saber quando ocorrerá um evento de manutenção, basta consultar o atributo maintenance-event periodicamente. O valor deste 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.

Observação: para instâncias com GPUs, o atributo muda 60 minutos antes do encerramento das instâncias para que você tenha tempo de encerrar e reiniciar em outro host. As instâncias com GPUs não são migradas em tempo real, mas são interrompidas e reiniciadas (opcionalmente). Para saber mais, leia Como lidar com a manutenção de hosts na documentação das GPUs.

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

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

• Você tiver consultado 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 de eventos de manutenção. Esse evento de manutenção é iniciado imediatamente ignorando o aviso de 60 segundos. Se você não quiser ignorar o aviso de 60 segundos, verifique se o atributo maintenance-event está sendo consultado pelo código de cliente no mínimo uma vez entre os eventos de migração.

Observação: você precisa consultar o atributo maintenance-event diretamente para o Compute Engine determinar que você está assistindo a esse atributo. Consultar metadados de nível superior não aciona o aviso antecipado.

Para consultar o atributo maintenance-event:

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

NONE

Atenção: o atributo maintenance-event é preenchido para eventos de manutenção apenas se você tiver definido a opção de programação da instância como migrate ou se a instância tiver uma GPU anexada. Instâncias de máquina virtual sem GPUs definidas como terminate são encerradas e não são notificadas sobre eventos de manutenção por meio desse atributo. Para mais informações sobre as políticas de manutenção migrate e terminate, consulte Como configurar políticas de disponibilidade da instância.

O valor inicial e o 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 interrupção.

• Para instâncias que não são de GPU, mas com uma opção de programação de migrate, o 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 interrupção.
  2. Durante o evento e enquanto a instância de VM está sendo migrada, 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 os 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 na amostra em Python a seguir, como implementar esses dois recursos conjuntamente.

Observação: durante o evento de manutenção, o servidor de metadados pode retornar um código 503 Service Unavailable. Se o aplicativo receber o código de erro 503, faça a solicitação novamente.

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

compute/metadata/main.py

Ver no GitHub

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

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.

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 (obsoleta)	http://metadata.google.internal/0.1/meta-data/…
v1beta1 (obsoleta)	http://metadata.google.internal/computeMetadata/v1beta1/…
v1	http://metadata.google.internal/computeMetadata/v1/…

Como desativar endpoints legados

É possível desativar esses endpoints 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 para definir metadados personalizados e definir 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 o seguinte 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 o endpoint v1, consulte Como fazer a migração para o endpoint de servidor de metadados v1.

A seguir

• Saiba mais sobre como executar scripts de inicialização ou scripts de encerramento no servidor de metadados.
• Saiba mais sobre migração em tempo real.