Configurando e consultando atributos de convidado

Os atributos de convidado são um tipo específico de metadados personalizados nos quais seus aplicativos podem gravar durante a execução em sua instância de máquina virtual (VM). Qualquer aplicativo ou usuário na sua instância de VM pode ler e gravar dados nesses valores de metadados de 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.
  • Se ainda não o fez, configure a autenticação. Autenticação é o processo pelo qual sua identidade é verificada para acesso a Google Cloud serviços e APIs. Para executar códigos ou amostras em um ambiente de desenvolvimento local, você pode se autenticar no Compute Engine selecionando uma das seguintes opções:

    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. After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    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.

        After installing the Google Cloud CLI, initialize it by running the following command: 

        gcloud init

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Funções obrigatórias

As permissões ou funções necessárias dependem de você estar concluindo tarefas dentro ou fora da VM.

Dentro da VM

Se você estiver configurando, consultando ou excluindo os atributos de convidado na VM, precisará apenas das funções e permissões para se conectar à VM. Qualquer processo em execução na instância da VM pode gravar nos valores dos atributos do convidado, incluindo scripts e aplicativos que não têm privilégios de nível sudo ou de administrador.

Para leituras e gravações em uma VM, o servidor de metadados fornece autenticação e autorização automáticas em nível de instância. Cada VM pode ler ou gravar somente em seu próprio servidor de metadados. Outras VMs não podem acessar o servidor de metadados de outra VM.

Fora da VM

As funções e permissões a seguir são necessárias para ativar atributos de convidado ou visualizar atributos de convidado de fora da VM usando a Google Cloud CLI ou REST. Não é possível definir ou excluir atributos de convidados fora de uma VM.

Para garantir que seu usuário ou conta de serviço tenha as permissões necessárias para ativar ou visualizar atributos de convidado, peça ao administrador para conceder ao seu usuário ou conta de serviço a função IAM Compute Instance Admin (v1) ( roles/compute.instanceAdmin.v1 ) na VM ou no projeto. Para obter mais informações sobre a concessão de funções, consulte Gerenciar acesso a projetos, pastas e organizações .

Esta função predefinida contém as permissões necessárias para ativar ou visualizar atributos de convidado. Para ver 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 visualizar atributos de convidado:

  • Para ativar atributos de convidado: compute.instances.setMetadata na VM ou no projeto
  • Para visualizar atributos de convidado: compute.instances.getGuestAttributes na VM ou no projeto

Seu administrador também poderá conceder essas permissões ao seu usuário ou conta de serviço com funções personalizadas ou outras funções predefinidas .

Quando usar atributos de convidado

Use atributos de convidado somente para casos de uso que exigem pequenas quantidades de dados que não mudam com frequência. Os melhores casos de uso para atributos de convidados têm as seguintes características:

  • 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 intervalo de três consultas por segundo. Se essa taxa máxima for excedida, o Compute Engine poderá remover arbitrariamente atributos de 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 para situações em que você deve publicar dados pouco frequentes e de baixo volume. Por exemplo, os atributos de convidado funcionam bem para os seguintes casos de uso:

  • Scripts de inicialização que podem sinalizar uma inicialização bem-sucedida definindo um valor de status personalizado nos atributos do convidado.
  • Agentes de gerenciamento de configuração que podem publicar um nome e versão de sistema operacional convidado em atributos de convidado.
  • Agentes de gerenciamento de inventário que podem publicar listas de pacotes instalados na instância de VM para 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 de software, definindo um valor de status personalizado nos atributos do convidado.

Os atributos de convidado não substituem o streaming de eventos, o Pub/Sub ou outras formas de armazenamento de dados e repositórios de configuração.

Atributos de convidados e outros Google Cloud serviços

Os atributos de convidado são usados ​​por outros Google Cloud serviços da seguinte forma:

  • Segurança SSH: se os atributos de convidado estiverem ativados e o login do sistema operacional estiver desativado, o ambiente de convidado e a CLI gcloud usarão atributos de convidado para melhorar a segurança SSH usando a API do Google para recuperar chaves de host antes que você possa se conectar à sua VM usando SSH.
  • Gerenciador de VM: o agente de configuração do SO publica dados do sistema operacional em atributos de convidado.

Para revisar as entradas de metadados armazenadas por esses serviços, consulte Chaves de metadados de atributos de convidado predefinidas .

Habilite atributos de convidado em sua VM

Por padrão, os atributos de convidado estão desabilitados. Para ativar atributos de convidados, defina os valores de metadados necessários nas suas VMs individuais ou nos metadados de todo o 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 .

    Vá para 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 e adicione as seguintes entradas de metadados:

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

  4. Para criar a VM, clique em Criar .

Defina enable-guest-attributes nos metadados de todo o projeto para que eles se apliquem a todas as VMs do seu projeto:

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

    Vá para a página Metadados

  2. Clique em Editar .

  3. Adicione uma entrada de metadados onde a chave seja enable-guest-attributes e o valor seja TRUE . Como alternativa, defina o valor como FALSE para desativar o recurso.

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

Defina enable-guest-attributes nos metadados de uma VM existente:

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

    Acesse a página de instâncias de VM

  2. Clique no nome da VM na qual você deseja definir o valor dos metadados.
  3. Na parte superior da página de detalhes da instância, clique em Editar para editar as configurações da instância.
  4. Em Custom metadata , adicione uma entrada de metadados onde a chave é enable-guest-attributes e o valor é TRUE . Como alternativa, 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 CLI do Google Cloud e defina enable-guest-attributes=TRUE para ativar atributos de convidado. Substitua VM_NAME pelo nome da sua VM.

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

Defina enable-guest-attributes nos metadados de todo o projeto para que eles se apliquem a todas as VMs do seu projeto:

Use o comando project-info add-metadata na CLI do Google Cloud e defina enable-guest-attributes=TRUE para ativar atributos de convidado:

gcloud compute project-info add-metadata \
    --metadata=enable-guest-attributes=TRUE

Como alternativa, você pode definir enable-guest-attributes como FALSE para desabilitar os atributos do convidado.

Defina enable-guest-attributes nos metadados de uma VM existente:

Use o comando instances add-metadata na CLI do Google Cloud e defina enable-guest-attributes=TRUE para ativar atributos de convidado. Substitua VM_NAME pelo nome da sua VM.

gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE

Como alternativa, você pode definir enable-guest-attributes como FALSE para impedir que sua VM use atributos de convidado.

Definir atributos de convidado

Qualquer processo em execução na instância da VM pode gravar nos valores dos atributos do convidado, incluindo scripts e aplicativos que não têm privilégios de sudo ou de administrador. Os usuários ou contas de serviço fora da VM não podem gravar valores de metadados de atributos de convidado.

VMs Linux

Por exemplo, você pode usar uma solicitação curl de dentro de sua 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 o seguinte:

  • NAMESPACE : um agrupamento lógico para sua KEY . Os atributos de convidado devem ter um namespace.
  • VALUE : o valor que você deseja escrever.
  • KEY : o caminho dos metadados nos guest-attributes onde o valor está armazenado.

Use apenas letras, números, sublinhados ( _ ) e hifens ( - ) para os campos NAMESPACE e KEY .

VMs do Windows

Por exemplo, você pode usar uma solicitação Invoke-RestMethod de dentro da sua 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 o seguinte:

  • NAMESPACE : um agrupamento lógico para sua KEY . Os atributos de convidado devem ter um namespace.
  • VALUE : o valor que você deseja escrever.
  • KEY : o caminho dos metadados nos guest-attributes onde o valor está armazenado.

Use apenas letras, números, sublinhados ( _ ) e hifens ( - ) para os campos NAMESPACE e KEY .

Obtenha atributos de convidado

Os usuários ou contas de serviço poderão ler atributos de convidados de fora de uma VM se tiverem a função necessária . Como alternativa, qualquer usuário ou aplicativo na VM pode ler os valores de metadados dessa VM específica.

Qualquer processo em execução na máquina virtual pode gravar no valor dos atributos do convidado, que inclui scripts e aplicativos que não possuem privilégios de nível sudo ou de administrador.

Consultar o servidor de metadados

Use as instruções a seguir para consultar atributos de convidado em uma VM.

  1. Conecte-se à VM.

  2. Consulte os atributos do convidado.

    VMs Linux

    Por exemplo, você pode usar uma solicitação curl de dentro da sua 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 o seguinte:

    • NAMESPACE : o namespace da chave de guest-attributes que você deseja consultar.
    • KEY : o caminho nos guest-attributes do qual você deseja ler o valor dos metadados.

    Alternativamente, você pode retornar todos os valores de atributos de convidado em uma solicitação. Substitua NAMESPACE pelo namespace da chave de guest-attributes que você deseja consultar.

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/ -H "Metadata-Flavor: Google"

    VMs do Windows

    Por exemplo, você pode usar uma solicitação Invoke-RestMethod de dentro da sua 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 o seguinte:

    • NAMESPACE : o namespace da chave de guest-attributes que você deseja consultar.
    • KEY : o caminho nos guest-attributes do qual você deseja ler o valor dos metadados.

    Alternativamente, você pode retornar todos os valores de atributos de convidado em uma solicitação. Substitua NAMESPACE pelo namespace da chave de guest-attributes que você deseja consultar.

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

Usar Google Cloud CLI ou REST

Use as instruções a seguir para visualizar atributos de convidados de fora de uma VM.

gcloud

Use a CLI do Google Cloud para ler valores de metadados de atributos de convidado para uma VM. Por exemplo, você pode 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 o sinalizador --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 o sinalizador --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 o seguinte:

  • VM_NAME : o nome da VM da qual você deseja ler o valor dos metadados do atributo guest
  • NAMESPACE : o namespace da chave guest-attributes que você deseja consultar
  • KEY : o caminho nos metadados guest-attributes onde o valor é armazenado
  • ZONE : a zona onde a VM está localizada

DESCANSAR

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 o seguinte:

  • PROJECT_ID : o ID do seu projeto
  • ZONE : a zona onde sua VM está localizada
  • VM_NAME : o nome da VM da qual você deseja ler o valor dos metadados do atributo guest
  • NAMESPACE : o namespace da chave guest-attributes que você deseja consultar
  • KEY : o caminho nos metadados guest-attributes onde o valor é armazenado

Para recuperar todas as chaves de um NAMESPACE , omita 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 totalmente NAMESPACE e queryPath : 

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 o seguinte:

  • OAUTH_TOKEN : seu token OAuth
  • PROJECT_ID : o ID do seu projeto
  • ZONE : a zona onde sua VM está localizada
  • VM_NAME : o nome da VM da qual você deseja ler o valor dos metadados do atributo guest
  • NAMESPACE : o namespace da chave guest-attributes que você deseja consultar
  • KEY : o caminho nos metadados guest-attributes onde o valor é armazenado

Excluindo atributos de convidado

Use as instruções a seguir para remover atributos de convidado de uma VM.

  1. Conecte-se à VM.

  2. Exclua os atributos do convidado.

    VMs Linux

    Você também pode excluir atributos de convidado. Por exemplo, use curl para excluir uma chave específica: 

    curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    Substitua o seguinte:

    • NAMESPACE : o namespace da chave guest-attributes que você deseja excluir
    • KEY : o caminho dentro guest-attributes onde o valor está armazenado

    VMs do Windows

    Você também pode excluir 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 o seguinte:

    • NAMESPACE : o namespace da chave guest-attributes que você deseja excluir
    • KEY : o caminho dentro guest-attributes onde o valor é armazenado

Desativar atributos de convidado na sua organização ou pasta

Se não quiser que nenhuma das VMs da sua organização ou pasta habilite atributos de convidado, você poderá substituir e desabilitar o recurso completamente.

Defina a restrição constraints/compute.disableGuestAttributesAccess em sua organização ou pasta, substituindo PROJECT_ID pelo nome do seu projeto: 

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

Leia Usando restrições para saber mais sobre como definir e gerenciar restrições em suas organizações.

O que vem a seguir?