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.
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, siga estas etapas:
- Instale ou atualize a ferramenta de linha de comando gcloud para a versão mais recente.
- 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ânciacompute.projects.setCommonInstanceMetadata
no projeto, se estiver configurando metadados de todo o projetocompute.projects.get
no projeto, se estiver apenas recebendo metadadoscompute.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: |
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
. 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 na instância. Leia Como configurar nomes DNS para saber mais sobre nomes DNS internos. |
attributes/ssh-keys |
Se a instância não estiver configurada para usar o Login do SO 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:
|
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” (atributos de convidado). |
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/projectnum/machineTypes/machine-type
|
name |
O nome da instância. |
network-interfaces/ |
Um diretório das interfaces de rede da instância. |
network-interfaces/<index>/forwarded-ips/ |
Um diretório de IPs externos que 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/token |
Um token de acesso OAuth2 que pode ser usado para
autenticar aplicativos.
|
service-accounts/service-account-name/identity |
Um JSON Web Token, exclusivo da instância. É necessário
incluir o parâmetro audience na solicitação do
valor de metadados da instância. Por exemplo, ?audience=http://www.example.com .
Leia Como verificar
a identidade das instâncias para mais informações sobre como solicitar e verificar
os tokens de identidade da instância.
|
tags |
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/projectnum/zones/zone
|
Como 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 estão dentro da instância associada. Não foi possível 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:
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/1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"
A tabela a seguir resume os caracteres codificados que não 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 de uma instância ou um projeto, use o
Console do Google Cloud
, 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
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
Para definir metadados personalizados de uma instância, use o
Console do Cloud
, a
ferramenta de linha de comando gcloud
ou a
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
- No Console do Cloud, acesse a página Instâncias de VM.
- Clique em Criar instância.
- Na página Criar uma nova instância, preencha as propriedades da sua instância.
- Na seção Metadados, insira quantos pares de chave-valor forem necessários para os seus metadados personalizados.
- 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
No Console do Google Cloud, acesse a página Instâncias de VM.
Clique na instância em que estão os metadados que você quer atualizar.
Clique no botão Editar, na parte superior da página.
Em Metadados personalizados, clique em Adicionar item ou edite as entradas de metadados atuais.
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
No Console do Google Cloud, acesse a página Metadados.
Clique em Editar.
Adicione ou edite uma entrada de metadados.
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:
- Acesse a página Instâncias de VM.
- Clique na instância em que estão os metadados que você quer visualizar.
- 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.
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:
No Console do Google Cloud, acesse a página Instâncias de VM.
Clique em Criar instância.
Na página Criar uma nova instância, preencha as propriedades pretendidas da instância.
Na seção Metadados, adicione uma entrada de metadados em que a chave é
enable-guest-attributes
e o valor éTRUE
.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:
No Console do Google Cloud, acesse a página Metadados.
Clique em Editar.
Adicione uma entrada de metadados em que a chave é
enable-guest-attributes
e o valor éTRUE
. Se quiser, defina o valor comoFALSE
para desativar o recurso.Clique em Salvar para aplicar as alterações.
Definir enable-guest-attributes
nos metadados de uma instância atual:
No Console do Google Cloud, acesse a página Instâncias de VM.
Clique no nome da instância em que você quer definir o valor dos metadados.
Para editar as configurações da instância, clique em Editar, na parte superior da página de detalhes da instância.
Na seção Metadados personalizados, adicione uma entrada de metadados com a chave
enable-guest-attributes
e o valorTRUE
. Se preferir, defina o valor comoFALSE
para excluir a instância do recurso.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 suakey
. Os atributos de convidado precisam ter um namespace.value
: o valor que você quer escrever.key
: o caminho dos metadados dentro deguest-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 chaveguest-attributes
que você quer consultar.key
: o caminho dentro deguest-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 chaveguest-attributes
que você quer consultar.key
: o caminho dentro dos metadadosguest-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 chaveguest-attributes
que você quer consultar.key
: o caminho dentro dos metadadosguest-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 chaveguest-attributes
que você quer consultar.key
: o caminho dentro dos metadadosguest-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 chaveguest-attributes
que você quer excluir.key
: o caminho dentro deguest-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.
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:
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.
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 atributomaintenance-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 atributomaintenance-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
.
Para instâncias de GPU, durante um evento de manutenção, o atributo muda de
NONE
paraTERMINATE_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
, omaintenance-event
muda da seguinte maneira:- No início do evento de migração, o valor muda de
NONE
paraMIGRATE_ON_HOST_MAINTENANCE
. Esse atributo é atualizado 60 segundos antes do início do evento de interrupção. - Durante o evento e enquanto a instância de VM está sendo
migrada, o valor permanece como
MIGRATE_ON_HOST_MAINTENANCE
. - Após o término do evento de manutenção, o valor volta a ser
NONE
.
- No início do evento de migração, o valor muda de
É 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.
Exemplo de script em Python para consultar eventos de manutenção
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.