Como definir e consultar atributos de convidado

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 da seguinte maneira.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. 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 na VM ou no projeto
  • Para visualizar os atributos de convidado: compute.instances.getGuestAttributes na VM ou no projeto

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 serviços do Google Cloud

Os atributos de convidado são usados por outros serviços do 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:

Console

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

  1. No Console do Google Cloud, acesse a página Criar uma instância.

    Acesse "Criar uma instância"

  2. Especifique os detalhes da VM.

  3. Expanda a seção Opções avançadas e faça o seguinte:

    1. Expanda a seção Gerenciamento.

    2. Na seção Metadados, clique em Adicionar item.

      • Chave: enable-guest-attributes
      • Valor: TRUE

  4. Para criar a VM, clique em Criar.

Defina enable-guest-attributes nos metadados do projeto para que se aplique a todas as VMs nele:

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

    Acessar a página "Metadados"

  2. Clique em Editar.

  3. Adicione uma entrada de metadados em que a chave é enable-guest-attributes e o valor é TRUE. Se quiser, defina o valor como FALSE para desativar o recurso.

  4. Clique em Salvar para aplicar as mudanças.

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

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

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

  2. Clique no nome da VM em que você quer definir o valor dos metadados.
  3. Para editar as configurações da instância, clique em Editar na parte superior da página de detalhes da instância.
  4. Na seção Metadados personalizados, adicione uma entrada de metadados com a chave enable-guest-attributes e o valor TRUE. Se preferir, defina o valor como FALSE para excluir a VM do recurso.
  5. Na parte inferior da página de detalhes da instância, clique em Salvar para aplicar as alterações à VM.

gcloud

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 create VM_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-metadata VM_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.

VMs do Linux

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 sua KEY. Os atributos de convidado precisam ter um namespace.
  • VALUE: o valor que você quer gravar.
  • KEY: o caminho dos metadados dentro de guest-attributes em que o valor é armazenado.

Use somente letras, numerais, sublinhados (_) e hifens (-) nos campos NAMESPACE e KEY.

VM do Windows

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 sua KEY. Os atributos de convidado precisam ter um namespace.
  • VALUE: o valor que você quer gravar.
  • KEY: o caminho dos metadados dentro de guest-attributes em que o valor é armazenado.

Use somente letras, numerais, sublinhados (_) e hifens (-) nos campos NAMESPACE e KEY.

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.

  1. Conecte-se à VM.

  2. Consulte os atributos de convidado.

    VMs do Linux

    Por exemplo, use uma solicitação curl de dentro da VM 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:

    • NAMESPACE: o namespace da chave guest-attributes que você quer consultar.
    • KEY: o caminho dentro de guest-attributes em que está o valor de metadados que você quer ler.

    Como alternativa, retorne todos os valores de atributos 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"

    VM do Windows

    Por exemplo, use uma solicitação Invoke-RestMethod de dentro da VM para ler um valor do caminho de metadados guest-attributes:

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

    Substitua:

    • NAMESPACE: o namespace da chave guest-attributes que você quer consultar.
    • KEY: o caminho dentro de guest-attributes em que está o valor de metadados que você quer ler.

    Como alternativa, retorne todos os valores de atributos de convidado em uma solicitação. Substitua NAMESPACE pelo namespace da chave guest-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.

gcloud

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-attributes VM_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 VM_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 VM_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 chave guest-attributes que você quer consultar.
  • KEY: o caminho dentro dos metadados guest-attributes em que o valor está armazenado.
  • ZONE: é a zona em que a VM está localizada

REST

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 projeto
  • ZONE: 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 chave guest-attributes que você quer consultar.
  • KEY: o caminho dentro dos metadados guest-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: Bearer OAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

Substitua:

  • OAUTH_TOKEN: seu token OAuth
  • PROJECT_ID: ID do projeto
  • ZONE: 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 chave guest-attributes que você quer consultar.
  • KEY: o caminho dentro dos metadados guest-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.

  1. Conecte-se à VM.

  2. Exclua os atributos de convidado.

    VMs do Linux

    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 chave guest-attributes que você quer excluir;
    • KEY: o caminho dentro de guest-attributes em que o valor está armazenado.

    VM do Windows

    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")
$value

    Substitua:

    • NAMESPACE: o namespace da chave guest-attributes que você quer excluir;
    • KEY: o caminho dentro de guest-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