Definir e consultar atributos de convidados

Os atributos de convidado são um tipo específico de metadados personalizados que as suas aplicações podem escrever enquanto são executadas na instância de máquina virtual (VM). Qualquer aplicação ou utilizador na sua instância de VM pode ler e escrever dados nestes valores de metadados de atributos de convidados.

Antes de começar

  • Para VMs do Windows Server, use o PowerShell 3.0 ou posterior. Recomendamos que use ctrl+v para colar os blocos de código copiados.
  • Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-se 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. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    2. Set a default region and zone.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

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

Funções necessárias

As autorizações ou as funções necessárias dependem de estar a concluir tarefas na VM ou fora dela.

Na VM

Se estiver a definir, consultar ou eliminar os atributos de convidado a partir da VM, só precisa das funções e das autorizações para estabelecer ligação à VM. Qualquer processo em execução na instância de VM pode escrever nos valores dos atributos do convidado, incluindo scripts e aplicações que não tenham privilégios de sudo ou de nível de administrador.

Para leituras e escritas a partir de uma VM, o servidor de metadados fornece autenticação e autorização automáticas ao nível da instância. Cada VM pode ler ou escrever apenas no respetivo servidor de metadados. Outras VMs não podem aceder ao servidor de metadados de outra VM.

Fora da VM

As seguintes funções e autorizações são necessárias para ativar os atributos de hóspedes, ou ver atributos de hóspedes a partir do exterior da VM através da Google Cloud CLI ou REST. Não pode definir nem eliminar atributos de convidados a partir de fora de uma VM.

Para garantir que a sua conta de utilizador ou de serviço tem as autorizações necessárias para ativar ou ver os atributos de convidado, peça ao seu administrador para conceder à sua conta de utilizador ou de serviço a função do IAM Administrador de instâncias do Compute (v1) (roles/compute.instanceAdmin.v1) na VM ou no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para ativar ou ver atributos de convidados. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para ativar ou ver atributos de convidados:

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

O seu administrador também pode atribuir estas autorizações à sua conta de utilizador ou de serviço com funções personalizadas ou outras funções predefinidas.

Quando usar atributos de hóspedes

Use atributos de visitantes apenas para exemplos de utilização que exijam pequenas quantidades de dados que não mudam com frequência. Os melhores exemplos de utilização para atributos de hóspedes têm as seguintes caraterí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 pico de 3 consultas por segundo. Se esta taxa máxima for excedida, o Compute Engine pode remover arbitrariamente atributos de convidados que estejam em processo de escrita. Esta remoção de dados é necessária para garantir que outros dados críticos do sistema podem ser escritos no servidor.

Os atributos de convidados funcionam bem em situações em que tem de publicar dados pouco frequentes e de baixo volume. Por exemplo, os atributos de hóspedes funcionam bem para os seguintes exemplos de utilização:

  • Scripts de arranque que podem sinalizar uma inicialização bem-sucedida definindo um valor de estado personalizado nos atributos do convidado.
  • Agentes de gestão de configuração que podem publicar um nome e uma versão do SO convidado nos atributos do convidado.
  • Agentes de gestão de inventário que podem publicar a lista de pacotes instalados na instância da VM nos atributos do convidado.
  • Software de orquestração de cargas de trabalho que pode sinalizar a conclusão de uma operação no convidado para o plano de controlo do software definindo um valor de estado personalizado nos atributos do convidado.

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

Atributos dos hóspedes e outros Google Cloud serviços

Os atributos de hóspedes são usados por outros Google Cloud serviços da seguinte forma:

  • Segurança de SSH: se os atributos de convidado estiverem ativados e o Início de sessão do SO estiver desativado, o ambiente de convidado e a CLI gcloud usam atributos de convidado para melhorar a segurança de SSH usando a API Google para obter chaves de anfitrião antes de poder estabelecer ligação à sua VM através de SSH.
  • VM Manager: o agente de configuração do SO publica dados do sistema operativo nos atributos de convidado.

Para rever as entradas de metadados armazenadas por estes serviços, consulte o artigo Chaves de metadados de atributos de hóspedes predefinidas.

Ative os atributos de convidado na sua VM

Por predefinição, os atributos de convidados estão desativados. Para ativar os atributos de convidados, defina os valores de metadados necessários nas VMs individuais ou nos metadados ao nível do projeto:

Consola

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

  1. Na Google Cloud consola, aceda à página Criar uma instância.

    Aceda a Criar uma instância

  2. Especifique os detalhes da VM.

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

    1. Expanda a secção Gestão.

    2. Na secçã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 ao nível do projeto para que se aplique a todas as VMs no seu projeto:

  1. Na Google Cloud consola, aceda à página Metadados.

    Aceda à página Metadados

  2. Clique em Edit.

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

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

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

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceda à página de instâncias de VM

  2. Clique no nome da VM na qual quer definir o valor dos metadados.
  3. Na parte superior da página de detalhes da instância, clique em Editar para editar as definições da instância.
  4. Em Metadados personalizados, adicione uma entrada de metadados em que a chave é enable-guest-attributes e o valor é TRUE. Em alternativa, defina o valor como FALSE para excluir a VM da funcionalidade.
  5. Na parte inferior da página de detalhes da instância, clique em Guardar para aplicar as alterações à VM.

gcloud

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

Use o comando gcloud compute instances create na CLI gcloud e defina enable-guest-attributes=TRUE para ativar os 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 ao nível do projeto para que se aplique a todas as VMs no seu projeto:

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

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

Em alternativa, pode definir enable-guest-attributes como FALSE para desativar os atributos de visitante.

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

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

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

Em alternativa, pode definir enable-guest-attributes como FALSE para excluir a sua VM da utilização de atributos de convidado.

Defina atributos de convidados

Qualquer processo em execução na instância de VM pode escrever nos valores dos atributos do convidado, incluindo scripts e aplicações que não tenham privilégios de sudo ou de nível de administrador. Os utilizadores ou as contas de serviço fora da VM não podem escrever nos valores dos metadados dos atributos de convidados.

VMs Linux

Por exemplo, pode usar um pedido curl a partir da sua VM para escrever um valor no caminho dos 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 o seu KEY. Os atributos de visitantes têm de ter um espaço de nomes.
  • VALUE: o valor que quer escrever.
  • KEY: o caminho dos metadados em guest-attributes onde o valor é armazenado.

Use apenas letras, números, sublinhados (_) e hífenes (-) nos campos NAMESPACE e KEY.

VMs do Windows

Por exemplo, pode usar um pedido Invoke-RestMethod a partir da sua VM para escrever um valor no caminho dos 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 o seu KEY. Os atributos de visitantes têm de ter um espaço de nomes.
  • VALUE: o valor que quer escrever.
  • KEY: o caminho dos metadados em guest-attributes onde o valor é armazenado.

Use apenas letras, números, sublinhados (_) e hífenes (-) nos campos NAMESPACE e KEY.

Obtenha atributos de convidados

Os utilizadores ou as contas de serviço podem ler atributos de convidados a partir do exterior de uma VM se tiverem a função necessária. Em alternativa, qualquer utilizador ou aplicação na VM pode ler os valores de metadados dessa VM específica.

Qualquer processo em execução na máquina virtual pode escrever no valor dos atributos do convidado, que inclui scripts e aplicações que não têm privilégios de sudo ou ao nível de administrador.

Consultar o servidor de metadados

Siga as instruções abaixo para consultar atributos de convidados a partir de uma VM.

  1. Estabeleça ligação à VM.

  2. Consultar os atributos de hóspedes.

    VMs Linux

    Por exemplo, pode usar um pedido curl a partir da sua VM para ler um valor do caminho dos guest-attributes metadados:

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

    Substitua o seguinte:

    • NAMESPACE: o espaço de nomes da guest-attributes chave que quer consultar.
    • KEY: o caminho em guest-attributes a partir do qual quer ler o valor dos metadados.

    Em alternativa, pode devolver todos os valores dos atributos de hóspedes num único pedido. Substitua NAMESPACE pelo espaço de nomes da chave guest-attributes que quer consultar.

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

    VMs do Windows

    Por exemplo, pode usar um pedido Invoke-RestMethod a partir da sua VM para ler um valor do caminho dos guest-attributes metadados:

    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 espaço de nomes da guest-attributes chave que quer consultar.
    • KEY: o caminho em guest-attributes a partir do qual quer ler o valor dos metadados.

    Em alternativa, pode devolver todos os valores dos atributos de hóspedes num único pedido. Substitua NAMESPACE pelo espaço de nomes da chave guest-attributes que quer consultar.

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

Use a Google Cloud CLI ou a REST

Siga as instruções abaixo para ver os atributos do convidado a partir do exterior de uma VM.

gcloud

Use a Google Cloud CLI para ler os valores dos metadados dos atributos de convidado de uma VM. Por exemplo, pode obter todos os valores da VM da seguinte forma:

gcloud compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

Para obter todos os valores num espaço de nomes específico, inclua a flag --query-path e o espaço de nomes que definiu:

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE \
    --zone=ZONE

Para obter todos os valores num espaço de nomes específico, inclua a flag --query-path, o espaço de nomes e a chave do valor que definiu:

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

Substitua o seguinte:

  • VM_NAME: o nome da MV a partir da qual quer ler o valor dos metadados do atributo convidado
  • NAMESPACE: o espaço de nomes da chave guest-attributes que quer consultar
  • KEY: o caminho nos metadados guest-attributes onde o valor está armazenado
  • ZONE: a zona onde 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 o seguinte:

  • PROJECT_ID: o ID do seu projeto
  • ZONE: a zona onde a sua VM está localizada
  • VM_NAME: o nome da VM a partir da qual quer ler o valor dos metadados do atributo convidado
  • NAMESPACE: o espaço de nomes da chave guest-attributes que quer consultar
  • KEY: o caminho nos metadados guest-attributes onde o valor está armazenado

Para obter todas as chaves de um NAMESPACE, omita o KEY:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

Para obter todas as chaves em cada espaço de nomes na VM, omita o NAMESPACE:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=

Em alternativa, se tiver um token OAuth, pode 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: o seu token OAuth
  • PROJECT_ID: o ID do seu projeto
  • ZONE: a zona onde a sua VM está localizada
  • VM_NAME: o nome da VM a partir da qual quer ler o valor dos metadados do atributo convidado
  • NAMESPACE: o espaço de nomes da chave guest-attributes que quer consultar
  • KEY: o caminho nos metadados guest-attributes onde o valor está armazenado

Eliminar atributos de convidados

Siga as instruções abaixo para remover atributos de convidados a partir de uma VM.

  1. Estabeleça ligação à VM.

  2. Elimine os atributos de convidado.

    VMs Linux

    Também pode eliminar atributos de hóspedes. Por exemplo, use curl para eliminar 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 espaço de nomes da chave que quer eliminarguest-attributes
    • KEY: o caminho em guest-attributes onde o valor está armazenado

    VMs do Windows

    Também pode eliminar atributos de hóspedes. Por exemplo, use Invoke-RestMethod para eliminar 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 espaço de nomes da chave que quer eliminarguest-attributes
    • KEY: o caminho em guest-attributes onde o valor está armazenado

Desativar os atributos de convidados na sua organização ou pasta

Se não quiser que nenhuma das VMs na sua organização ou pasta ative os atributos do convidado, pode substituir e desativar completamente a funcionalidade.

Defina a restrição constraints/compute.disableGuestAttributesAccess na 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 o artigo Usar restrições para saber como definir e gerir restrições nas suas organizações.

O que se segue?