Como armazenar e recuperar metadados de instâncias

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 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, você pode 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, você pode 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.

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 informações sobre como verificar a versão do endpoint do servidor de metadados, consulte Como verificar a versão do endpoint do servidor.

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

Antes de começar

Permissões exigidas para a tarefa

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

  • compute.instances.setMetadata na instância, se 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

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

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

Relativo a http://metadata.google.internal/computeMetadata/v1/project/
Entrada de metadados Descrição
attributes/ Um diretório de valores de metadados personalizados que foram definidos para o projeto.
attributes/disable-legacy-endpoints Desativa os endpoints legados do servidor de metadados de todas as instâncias no projeto. Sempre defina disable-legacy-endpoints=TRUE, a não ser que o projeto use endpoints legados. Atualize seus aplicativos para usar os endpoints v1.
attributes/enable-oslogin Ativa o recurso de gerenciamento de chaves SSH do login do SO no seu projeto ao definir 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. Se houver várias chaves SSH, cada uma é separada por um caractere (\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 ID numérico do projeto (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.

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

Relativo a http://metadata.google.internal/computeMetadata/v1/instance/
Entrada de metadados Descrição
attributes/ Um diretório de valores de metadados personalizados passados para a instância durante a inicialização ou o encerramento. Consulte Como especificar metadados personalizados, a seguir.
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 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 o gerenciamento de chaves SSH, esse atributo permite que você configure chaves SSH que podem se conectar a essa instância. Se houver várias chaves SSH, cada uma é separada por um caractere (\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 de uma instância que é atribuída usando a sinalização --description ou definida na API.
disks/ Um diretório de discos anexados a essa instância.
guest-attributes/ Valores de metadados de uma 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. Este é um ID numérico exclusivo, gerado pelo Compute Engine. Isso é útil para identificar instâncias, se você não quiser usar nomes de instâncias.
machine-type O valor de metadados para o tipo de máquina dessa instância, que 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 de IPs externos que apontam para esta instância de máquina virtual para a interface de rede em <index>. Nele, é fornecida especificamente uma lista dos IPs externos atendidos pelas regras de encaminhamento que direcionam pacotes a essa 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 com o uso da API.
scheduling/automatic-restart A configuração de reinicialização automática da instância. Este valor é definido com a sinalização ‑‑automatic_restart ou com o uso da API.
scheduling/preemptible A configuração preemptiva da instância. Se o valor for TRUE, a instância será preemptiva. Esse valor é definido na criação de uma instância e não pode ser alterado.
maintenance-event O caminho que indica que a instância está sendo afetada por um evento de manutenção transparente. Consulte Aviso de manutenção transparente para ver 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 da instância. Inclua o parâmetro "audience" 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 tokens de identidade da instância.
tags Quaisquer tags associadas à 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, 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. Você não pode consultar os metadados padrão de uma instância diretamente do seu computador local e nem de outra instância. Não é 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 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.

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:

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

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

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

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

Configurar metadados personalizados

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

Limites de tamanho para metadados personalizados

O Compute Engine impõe os seguintes limites ao tamanho dos seus valores de metadados personalizados:

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

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 GCP , 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 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 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 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 Platform, acesse a página Instâncias de VMs.

    Acessar a página de instâncias de VM

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

gcloud

A atualização de metadados de instância com a ferramenta gcloud é uma ação 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 \
  --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 --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 --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 essa solicitação 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 de metadados será aplicado automaticamente a todas as instâncias no projeto.

Console

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

    Acessar a página de 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 de 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 para o método projects().setCommonInstanceMetadata fornecendo todos os novos valores de metadados e um valor de fingerprint.

Impressão digital é uma string de caracteres aleatória, gerada pelo Compute Engine e usada para executar o bloqueio otimista. Forneça o valor da impressão digital correspondente para realizar sua solicitação. A impressão digital é 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 receber 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"
  }
 ]
}

Consultar metadados personalizados

Consulte a instância personalizada ou os metadados do projeto por meio do Console do GCP, 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 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 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 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 atributos de convidado de uma instância de fora da instância se tiverem um papel do Cloud Identity and Access Management 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 Platform, acesse a página Instâncias de VMs.

    Acessar a página de 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 Platform, acesse a página Metadados.

    Acessar a página de 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 Platform, acesse a página Instâncias de VMs.

    Acessar a página de 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 em que a chave é enable-guest-attributes e o valor é TRUE. Outra opção é definir 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

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

Use o comando gcloud compute instances create na ferramenta de linha de comando gcloud e defina enable-guest-attributes=TRUE para ativar os atributos de visitante:

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.

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

Use o comando instances add-metadata na ferramenta de linha de comando gcloud e defina enable-guest-attributes=TRUE para ativar os atributos de visitante:

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"

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 visitante se tiverem um papel do Cloud 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 para essa 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"

Em que:

  • [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:

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

Em que:

  • [INSTANCE_NAME] é o nome da instância da qual você quer ler o valor de metadados do atributo de convidado.
  • [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]

Em que:

  • [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.
  • [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]

Em que:

  • [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] é um agrupamento lógico para sua [KEY]. Os atributos de convidado precisam ter um namespace.
  • [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"

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 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 visitante, substitua e desative o recurso por completo.

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

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

Em que:

  • [PROJECT_ID] é o nome do projeto.

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.

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, um novo valor é retornado pela consulta. 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 novo conteúdo será retornado pelo servidor de metadados:

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:

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

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 consulta e tente fazer a solicitação novamente.
Error 404 O valor de metadados especificado não existe mais. Esse erro também é retornado pelo servidor de metadados se os metadados tiverem sido excluídos enquanto você aguardava uma alteração.
Error 503 Ocorreu um erro temporário do 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ê tiver optado por encerrar sua instância de VM durante a manutenção, o Compute Engine será encerrado automaticamente e poderá reiniciar sua instância de VM se o atributo automaticRestart estiver definido. Para saber mais sobre 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 desse atributo é alterado 60 segundos antes do início de um evento de manutenção, o que permite ao código do aplicativo acionar qualquer tarefa que você queira executar antes de um evento de manutenção, como fazer backup de dados ou atualizar registros. Um script Python de amostra também é fornecido pelo Compute Engine para demonstrar como verificar os avisos de eventos de manutenção.

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

  • As opções de disponibilidade da instância tiverem sido definidas como 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.

Para consultar o atributo maintenance-event:

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

NONE

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

  1. Muda de NONE para MIGRATE_ON_HOST_MAINTENANCE.
  2. Durante a duração do evento e enquanto sua 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.


import time

import requests

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

def wait_for_maintenance(callback):
    url = METADATA_URL + 'instance/maintenance-event'
    last_maintenance_event = None
    last_etag = '0'

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

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

        last_etag = r.headers['etag']

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

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

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

def main():
    wait_for_maintenance(maintenance_callback)

if __name__ == '__main__':
    main()

Como verificar a versão do endpoint do servidor

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

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

Como desativar endpoints legados

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

Para desativar os endpoints de servidor de metadados v0.1 e v1beta1, siga as instruções 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

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

Enviar comentários sobre…

Documentação do Compute Engine