Os atributos de convidado são um tipo específico de metadados personalizados em que os aplicativos podem gravar enquanto estão sendo executados na instância da máquina virtual (VM). Qualquer aplicativo ou usuário na instância da VM pode ler e gravar dados nesses valores de metadados dos atributos de convidado.
Antes de começar
- Para VMs do Windows Server, use o
PowerShell 3.0 ou posterior.
Recomendamos que você use
ctrl+v
para colar os blocos de código copiados. -
Configure a autenticação, caso ainda não tenha feito isso.
A autenticação é
o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud .
Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no
Compute Engine selecionando uma das seguintes opções:
Select the tab for how you plan to use the samples on this page:
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
REST
Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.
-
Funções exigidas
As permissões ou os papéis necessários dependem de você estar concluindo tarefas dentro ou fora da VM.
Na VM
Se você estiver configurando, consultando ou excluindo os atributos de convidado de dentro da VM, precisará apenas dos papéis e permissões para se conectar à VM. Qualquer processo executado na instância da VM pode gravar nos valores de metadados dos atributos de convidado, incluindo scripts e aplicativos que não têm privilégios de sudo ou de administrador.
Para leituras e gravações de dentro de uma VM, o servidor de metadados fornece autenticação e autorização automática no nível da instância. Cada VM pode ler ou gravar apenas no próprio servidor de metadados. As VMs não podem acessar o servidor de metadados de outra VM.
Fora da VM
Os papéis e as permissões a seguir são necessários para ativar os atributos de convidado ou visualizar os atributos de convidado de fora da VM usando a Google Cloud CLI ou a REST. Não é possível definir ou excluir atributos de convidado de fora de uma VM.
Para garantir que sua conta de serviço ou usuário tenha as permissões
necessárias para ativar ou visualizar atributos de convidado,
peça ao administrador para conceder ao usuário ou à conta de serviço o
Administrador de instâncias do Compute (v1) (roles/compute.instanceAdmin.v1
) Papel do IAM na VM ou no projeto.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esse papel predefinido contém as permissões necessárias para ativar ou visualizar os atributos de convidado. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para ativar ou ver os atributos de convidado:
-
Para ativar atributos de convidado:
compute.instances.setMetadata
-
Para visualizar os atributos de convidado:
compute.instances.getGuestAttributes
O administrador também pode conceder essa permissão à sua conta de serviço ou usuário com papéis personalizados ou outros papéis predefinidos.
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.
Atributos de convidado e outros Google Cloud serviços
Os atributos de convidado são usados por outros serviços Google Cloud da seguinte maneira:
- Segurança SSH: se os atributos de convidado estiverem ativados e o Login do SO desativado, o ambiente de convidado e a CLI gcloud usarão os atributos de convidado para melhorar a segurança do SSH usando a API do Google para recuperar. as chaves de host antes de se conectar à sua VM usando SSH.
- VM Manager: o agente de configuração do SO publica dados do sistema operacional nos atributos de convidado.
Para analisar as entradas de metadados armazenadas por esses serviços, consulte Chaves de metadados do atributo de convidado predefinidas.
Ativar atributos de convidado na VM
Por padrão, os atributos de convidado estão desativados. Para ativar os atributos de convidado, defina os valores de metadados necessários nas VMs individuais ou nos metadados do projeto:
Defina enable-guest-attributes
nos metadados da instância ao criar uma VM:
No Console do Google Cloud, acesse a página Criar uma instância.
Especifique os detalhes da VM.
Expanda a seção Opções avançadas e faça o seguinte:
- Expanda a seção Gerenciamento.
Na seção Metadados, clique em Adicionar item.
- Chave:
enable-guest-attributes
- Valor:
TRUE
- Chave:
Para criar a VM, clique em Criar.
Defina enable-guest-attributes
nos metadados do projeto para que se aplique a
todas as VMs nele:
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 mudanças.
Para definir enable-guest-attributes
nos metadados de uma VM atual, siga estas instruções:
- No console do Google Cloud, acesse a página Instâncias de VMs.
- Clique no nome da VM 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 VM do recurso. - Na parte inferior da página de detalhes da instância, clique em Salvar para aplicar as alterações à VM.
Defina enable-guest-attributes
nos metadados da instância ao criar uma VM:
Use o
comando gcloud compute instances create
na Google Cloud CLI e defina
enable-guest-attributes=TRUE
para ativar os atributos de convidado. Substitua
VM_NAME
pelo nome da VM.
gcloud compute instances createVM_NAME \ --metadata=enable-guest-attributes=TRUE
Defina enable-guest-attributes
nos metadados do projeto para que
se aplique a todas as VMs nele:
Use o
comando project-info add-metadata
na Google Cloud CLI e defina
enable-guest-attributes=TRUE
para ativar os atributos de convidado:
gcloud compute project-info add-metadata \ --metadata=enable-guest-attributes=TRUE
Se preferir, defina enable-guest-attributes
como FALSE
para desativar os atributos de convidado.
Para definir enable-guest-attributes
nos metadados de uma VM atual, siga estas instruções:
Use o
comando instances add-metadata
na Google Cloud CLI e defina
enable-guest-attributes=TRUE
para ativar os atributos de convidado. Substitua
VM_NAME
pelo nome da VM.
gcloud compute instances add-metadataVM_NAME \ --metadata=enable-guest-attributes=TRUE
Se preferir, defina enable-guest-attributes
como FALSE
para
que a VM não use atributos de convidado.
Definir atributos de convidado
Qualquer processo executado na instância da VM pode gravar nos valores de metadados dos 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 VM não podem gravar em valores de metadados dos atributos de convidado.
Por exemplo, use uma solicitação curl
de dentro da VM 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:
NAMESPACE
: um agrupamento lógico para suaKEY
. Os atributos de convidado precisam ter um namespace.VALUE
: o valor que você quer gravar.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
.
Por exemplo, use uma solicitação Invoke-RestMethod
de dentro da VM para gravar um valor no caminho de metadados
guest-attributes
:
PS C:\> $value = (Invoke-RestMethod ` -Method PUT -Body "VALUE " ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE /KEY ") $value
Substitua:
NAMESPACE
: um agrupamento lógico para suaKEY
. Os atributos de convidado precisam ter um namespace.VALUE
: o valor que você quer gravar.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
.
Receber atributos de convidado
Usuários ou contas de serviço podem ler os atributos de convidado de fora de uma VM se tiverem o papel necessário. Como alternativa, qualquer usuário ou aplicativo na VM pode ler os valores de metadados dessa VM 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.
Consultar o servidor de metadados
Use as instruções a seguir para consultar os atributos de convidado em uma VM.
Conecte-se à VM.
Consulte os atributos de convidado.
Por exemplo, use uma solicitação
curl
de dentro da VM para ler um valor do caminho de metadadosguest-attributes
:curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/
NAMESPACE /KEY -H "Metadata-Flavor: Google"Substitua:
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, retorne todos os valores de atributos de convidado em uma solicitação. Substitua
NAMESPACE
pelo namespace da chaveguest-attributes
que você quer consultar.curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/
NAMESPACE / -H "Metadata-Flavor: Google"Por exemplo, use uma solicitação
Invoke-RestMethod
de dentro da VM para ler um valor do caminho de metadadosguest-attributes
:PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/
NAMESPACE /KEY ") $valueSubstitua:
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, retorne todos os valores de atributos de convidado em uma solicitação. Substitua
NAMESPACE
pelo namespace da chaveguest-attributes
que você quer consultar.PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/
NAMESPACE /") $value
Usar a Google Cloud CLI ou REST
Use as instruções a seguir para ver os atributos de convidado de fora de uma VM.
Use a Google Cloud CLI para ler valores de metadados de atributos de convidado para uma VM. Por exemplo, é possível recuperar todos os valores da VM da seguinte maneira:
gcloud compute instances get-guest-attributesVM_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-attributesVM_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-attributesVM_NAME \ --query-path=NAMESPACE /KEY \ --zone=ZONE
Substitua:
VM_NAME
: o nome da VM em que está o valor de metadados dos atributos de convidado que você quer ler.NAMESPACE
: o namespace da chaveguest-attributes
que você quer consultar.KEY
: o caminho dentro dos metadadosguest-attributes
em que o valor está armazenado.ZONE
: é a zona em que a VM está localizada
Use o
método compute.instances.getguestattributes
.
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID /zones/ZONE /instances/VM_NAME /getGuestAttributes?queryPath=NAMESPACE /KEY
Substitua:
PROJECT_ID
: ID do projetoZONE
: a zona em que a VM está localizada.VM_NAME
: o nome da VM em que está o valor de metadados dos atributos de convidado que você quer ler.NAMESPACE
: o namespace da chaveguest-attributes
que você quer consultar.KEY
: o caminho dentro dos metadadosguest-attributes
em que o valor está armazenado.
Para recuperar todas as chaves de um NAMESPACE
, omita a KEY
:
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID /zones/ZONE /instances/VM_NAME /getGuestAttributes?queryPath=NAMESPACE
Para recuperar todas as chaves em cada namespace na VM, omita NAMESPACE
e queryPath
totalmente:
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID /zones/ZONE /instances/VM_NAME /getGuestAttributes
Como alternativa, se você tiver um token OAuth, poderá usar curl
:
curl -H "Authorization: BearerOAUTH_TOKEN " https://compute.googleapis.com/compute/v1/projects/PROJECT_ID /zones/ZONE /instances/VM_NAME /getGuestAttributes?queryPath=NAMESPACE /KEY
Substitua:
OAUTH_TOKEN
: seu token OAuthPROJECT_ID
: ID do projetoZONE
: a zona em que a VM está localizada.VM_NAME
: o nome da VM em que está o valor de metadados dos atributos de convidado que você quer ler.NAMESPACE
: o namespace da chaveguest-attributes
que você quer consultar.KEY
: o caminho dentro dos metadadosguest-attributes
em que o valor está armazenado.
Como excluir atributos de convidado
Use as instruções a seguir para remover os atributos de convidado de uma VM.
Conecte-se à VM.
Exclua os 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:
NAMESPACE
: o namespace da chaveguest-attributes
que você quer excluir;KEY
: o caminho dentro deguest-attributes
em que o valor está armazenado.
Também é possível excluir os atributos de convidado. Por exemplo, use
Invoke-RestMethod
para excluir uma chave específica:PS C:\> $value = (Invoke-RestMethod ` -Method DELETE ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/
NAMESPACE /KEY ") $valueSubstitua:
NAMESPACE
: o namespace da chaveguest-attributes
que você quer excluir;KEY
: o caminho dentro deguest-attributes
em que o valor está armazenado.
Como desativar atributos de convidado na organização ou pasta
Se você não quiser que nenhuma das VMs 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
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.
A seguir
- Saiba mais sobre os metadados da VM.