Configurar y consultar atributos de invitados

Los atributos de invitado son un tipo específico de metadatos personalizados que tus aplicaciones pueden escribir mientras se ejecutan en tu instancia de máquina virtual (VM). Cualquier aplicación o usuario de tu instancia de VM puede leer y escribir datos en estos valores de metadatos de atributos de invitado.

Antes de empezar

  • En el caso de las máquinas virtuales de Windows Server, usa PowerShell 3.0 o una versión posterior. Te recomendamos que uses ctrl+v para pegar los bloques de código copiados.
  • Si aún no lo has hecho, configura la autenticación. La autenticación verifica tu identidad para acceder a Google Cloud servicios y APIs. Para ejecutar código o ejemplos desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

    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. Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando: 

      gcloud init

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

    2. Set a default region and zone.

    REST

    Para usar las muestras de la API REST de esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la CLI de gcloud.

      Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando: 

      gcloud init

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

    Para obtener más información, consulta el artículo Autenticarse para usar REST de la documentación sobre autenticación de Google Cloud .

Roles obligatorios

Los permisos o roles necesarios dependen de si completas las tareas desde dentro o desde fuera de la VM.

En la VM

Si vas a definir, consultar o eliminar los atributos de invitado desde la VM, solo necesitas los roles y permisos para conectarte a la VM. Cualquier proceso que se ejecute en la instancia de VM puede escribir en los valores de los atributos de invitado, incluidos los scripts y las aplicaciones que no tengan privilegios de nivel de administrador o sudo.

Para las lecturas y escrituras desde una VM, el servidor de metadatos proporciona autenticación y autorización automáticas a nivel de instancia. Cada VM solo puede leer o escribir en su propio servidor de metadatos. Otras VMs no pueden acceder al servidor de metadatos de otra VM.

Fuera de la VM

Para habilitar los atributos de invitado o verlos desde fuera de la VM mediante la CLI de Google Cloud o REST, se necesitan los siguientes roles y permisos. No puedes definir ni eliminar atributos de invitado desde fuera de una máquina virtual.

Para asegurarte de que tu cuenta de usuario o de servicio tiene los permisos necesarios para habilitar o ver los atributos de invitado, pide a tu administrador que conceda a tu cuenta de usuario o de servicio el rol de gestión de identidades y accesos Administrador de instancias de Compute (v. 1) (roles/compute.instanceAdmin.v1) en la VM o en el proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para habilitar o ver los atributos de invitado. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para habilitar o ver atributos de invitado, se necesitan los siguientes permisos:

  • Para habilitar los atributos de invitado, sigue estos pasos: compute.instances.setMetadata en la VM o el proyecto
  • Para ver los atributos de invitado, sigue estos pasos: compute.instances.getGuestAttributes en la VM o en el proyecto

Es posible que tu administrador también pueda conceder estos permisos a tu usuario o cuenta de servicio con roles personalizados u otros roles predefinidos.

Cuándo usar atributos de invitado

Utilice atributos de invitado solo en los casos prácticos que requieran pequeñas cantidades de datos que no cambien con frecuencia. Los mejores casos prácticos para los atributos de invitado tienen las siguientes características:

  • El número de consultas está limitado a un máximo de 10 consultas por minuto y por instancia de máquina virtual.
  • Las consultas no superan un pico de 3 consultas por segundo. Si se supera este valor máximo, es posible que Compute Engine elimine de forma arbitraria los atributos de invitado que se estén escribiendo. Esta eliminación de datos es necesaria para asegurarse de que se puedan escribir otros datos críticos del sistema en el servidor.

Los atributos de invitado son útiles en situaciones en las que debe publicar datos poco frecuentes y de bajo volumen. Por ejemplo, los atributos de huésped funcionan bien en los siguientes casos prácticos:

  • Secuencias de comandos de inicio que pueden indicar que la inicialización se ha completado correctamente asignando un valor de estado personalizado a los atributos de invitado.
  • Agentes de gestión de configuración que pueden publicar el nombre y la versión de un SO invitado en los atributos de invitado.
  • Agentes de gestión de inventario que pueden publicar una lista de paquetes instalados en la instancia de VM en los atributos de invitado.
  • Software de orquestación de cargas de trabajo que puede indicar que se ha completado una operación en el invitado al plano de control del software asignando un valor de estado personalizado a los atributos del invitado.

Los atributos de invitado no sustituyen al streaming de eventos, a Pub/Sub ni a otras formas de almacenamiento de datos y repositorios de configuración.

Atributos de invitado y otros Google Cloud servicios

Otros servicios de Google Cloud usan los atributos de invitado de la siguiente manera:

  • Seguridad de SSH: si los atributos de invitado están habilitados y el inicio de sesión del SO está inhabilitado, el entorno de invitado y la CLI de gcloud usan atributos de invitado para mejorar la seguridad de SSH. Para ello, usan la API de Google para recuperar las claves de host antes de que puedas conectarte a tu VM mediante SSH.
  • VM Manager: el agente de configuración del SO publica datos del sistema operativo en los atributos de invitado.

Para consultar las entradas de metadatos almacenadas por estos servicios, consulta Claves de metadatos de atributos de invitado predefinidas.

Habilitar atributos de invitado en una VM

De forma predeterminada, los atributos de invitado están inhabilitados. Para habilitar los atributos de invitado, defina los valores de metadatos necesarios en las VMs individuales o en los metadatos de todo el proyecto:

Consola

Define enable-guest-attributes en los metadatos de la instancia al crear una VM:

  1. En la Google Cloud consola, ve a la página Crear una instancia.

    Ir a Crear una instancia

  2. Especifica los detalles de la VM.

  3. Despliega la sección Opciones avanzadas y haz lo siguiente:

    1. Despliega la sección Gestión.

    2. En la sección Metadatos, haga clic en Añadir elemento y añada las siguientes entradas de metadatos:

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

  4. Para crear la VM, haz clic en Crear.

Define enable-guest-attributes en los metadatos de todo el proyecto para que se aplique a todas las VMs del proyecto:

  1. En la Google Cloud consola, ve a la página Metadatos.

    Ir a la página Metadatos

  2. Haz clic en Editar.

  3. Añade una entrada de metadatos en la que la clave sea enable-guest-attributes y el valor sea TRUE. También puedes asignar el valor FALSE para inhabilitar la función.

  4. Haz clic en Guardar para aplicar los cambios.

Define enable-guest-attributes en los metadatos de una VM:

  1. En la consola de Google Cloud , ve a la página Instancias de VM.

    Ve a la página Instancias de VM.

  2. Haga clic en el nombre de la VM en la que quiera definir el valor de los metadatos.
  3. En la parte superior de la página de detalles de la instancia, haz clic en Editar para editar la configuración de la instancia.
  4. En Metadatos personalizados, añade una entrada de metadatos en la que la clave sea enable-guest-attributes y el valor sea TRUE. También puedes asignar el valor FALSE para excluir la VM de la función.
  5. En la parte inferior de la página de detalles de la instancia, haz clic en Guardar para aplicar los cambios a la VM.

gcloud

Define enable-guest-attributes en los metadatos de la instancia al crear una VM:

Usa el comando gcloud compute instances create en la CLI de Google Cloud y define enable-guest-attributes=TRUE para habilitar los atributos de invitado. Sustituye VM_NAME por el nombre de tu VM.

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

Define enable-guest-attributes en los metadatos de todo el proyecto para que se aplique a todas las VMs del proyecto:

Usa el comando project-info add-metadata en Google Cloud CLI y define enable-guest-attributes=TRUE para habilitar los atributos de invitado:

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

También puedes definir enable-guest-attributes como FALSE para inhabilitar los atributos de invitado.

Define enable-guest-attributes en los metadatos de una VM:

Usa el comando instances add-metadata en la CLI de Google Cloud y define enable-guest-attributes=TRUE para habilitar los atributos de invitado. Sustituye VM_NAME por el nombre de tu VM.

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

También puedes asignar el valor FALSE a enable-guest-attributes para evitar que tu VM use atributos de invitado.

Definir atributos de invitado

Cualquier proceso que se ejecute en la instancia de VM puede escribir en los valores de los atributos de invitado, incluidos los scripts y las aplicaciones que no tengan privilegios de nivel de administrador o sudo. Los usuarios o las cuentas de servicio que no estén en la máquina virtual no pueden escribir en los valores de metadatos de los atributos de invitado.

Máquinas virtuales Linux

Por ejemplo, puedes usar una solicitud curl desde tu VM para escribir un valor en la ruta de metadatos guest-attributes:

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

Haz los cambios siguientes:

  • NAMESPACE: una agrupación lógica de tus KEY. Los atributos de invitado deben tener un espacio de nombres.
  • VALUE: el valor que quieres escribir.
  • KEY: la ruta de los metadatos en guest-attributes donde se almacena el valor.

Usa solo letras, números, guiones bajos (_) y guiones (-) en los campos NAMESPACE y KEY.

Máquinas virtuales de Windows

Por ejemplo, puedes usar una solicitud Invoke-RestMethod desde tu VM para escribir un valor en la ruta de metadatos 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

Haz los cambios siguientes:

  • NAMESPACE: una agrupación lógica de tus KEY. Los atributos de invitado deben tener un espacio de nombres.
  • VALUE: el valor que quieres escribir.
  • KEY: la ruta de los metadatos en guest-attributes donde se almacena el valor.

Usa solo letras, números, guiones bajos (_) y guiones (-) en los campos NAMESPACE y KEY.

Obtener atributos de invitados

Los usuarios o las cuentas de servicio pueden leer atributos de invitado desde fuera de una VM si tienen el rol necesario. Como alternativa, cualquier usuario o aplicación de la VM puede leer los valores de metadatos de esa VM específica.

Cualquier proceso que se ejecute en la máquina virtual puede escribir en el valor de los atributos de invitado, lo que incluye secuencias de comandos y aplicaciones que no tienen privilegios de administrador o sudo.

Consultar el servidor de metadatos

Sigue estas instrucciones para consultar atributos de invitado desde una máquina virtual.

  1. Conéctate a la VM.

  2. Consulta los atributos de invitado.

    Máquinas virtuales Linux

    Por ejemplo, puede usar una solicitud curl desde su VM para leer un valor de la ruta de metadatos guest-attributes:

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

    Haz los cambios siguientes:

    • NAMESPACE: el espacio de nombres de la clave guest-attributes que quieras consultar.
    • KEY: la ruta de guest-attributes desde la que quieres leer el valor de los metadatos.

    También puedes devolver todos los valores de los atributos de invitado en una sola solicitud. Sustituye NAMESPACE por el espacio de nombres de la clave guest-attributes que quieras consultar.

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

    Máquinas virtuales de Windows

    Por ejemplo, puede usar una solicitud Invoke-RestMethod desde su VM para leer un valor de la ruta de metadatos guest-attributes:

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

    Haz los cambios siguientes:

    • NAMESPACE: el espacio de nombres de la clave guest-attributes que quieras consultar.
    • KEY: la ruta de guest-attributes desde la que quieres leer el valor de los metadatos.

    También puedes devolver todos los valores de los atributos de invitado en una sola solicitud. Sustituye NAMESPACE por el espacio de nombres de la clave guest-attributes que quieras 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 o REST

Sigue estas instrucciones para ver los atributos de invitado desde fuera de una VM.

gcloud

Usa la CLI de Google Cloud para leer los valores de los metadatos de los atributos de invitado de una VM. Por ejemplo, puede recuperar todos los valores de la máquina virtual de la siguiente manera:

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

Para recuperar todos los valores de un espacio de nombres específico, incluya la marca --query-path y el espacio de nombres que haya definido:

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

Para recuperar todos los valores de un espacio de nombres específico, incluye la marca --query-path, el espacio de nombres y la clave del valor que hayas definido:

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

Haz los cambios siguientes:

  • VM_NAME: el nombre de la VM de la que quieres leer el valor de los metadatos del atributo de invitado
  • NAMESPACE: el espacio de nombres de la guest-attributes clave que quieras consultar
  • KEY: la ruta dentro de los metadatos de guest-attributes donde se almacena el valor
  • ZONE: la zona en la que se encuentra la VM

REST

Usa el método compute.instances.getguestattributes:

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

Haz los cambios siguientes:

  • PROJECT_ID: tu ID de proyecto
  • ZONE: la zona en la que se encuentra tu VM
  • VM_NAME: el nombre de la VM de la que quieres leer el valor de los metadatos del atributo de invitado
  • NAMESPACE: el espacio de nombres de la guest-attributes clave que quieras consultar
  • KEY: la ruta dentro de los metadatos de guest-attributes donde se almacena el valor

Para recuperar todas las claves de un NAMESPACE, omite el KEY:

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

Para recuperar todas las claves de cada espacio de nombres de la VM, omite el NAMESPACE:

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

Si tienes un token de OAuth, también puedes 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

Haz los cambios siguientes:

  • OAUTH_TOKEN: tu token de OAuth
  • PROJECT_ID: tu ID de proyecto
  • ZONE: la zona en la que se encuentra tu VM
  • VM_NAME: el nombre de la VM de la que quieres leer el valor de los metadatos del atributo de invitado
  • NAMESPACE: el espacio de nombres de la guest-attributes clave que quieras consultar
  • KEY: la ruta dentro de los metadatos de guest-attributes donde se almacena el valor

Eliminar atributos de invitado

Sigue estas instrucciones para quitar atributos de invitado desde una máquina virtual.

  1. Conéctate a la VM.

  2. Elimina los atributos de invitado.

    Máquinas virtuales Linux

    También puedes eliminar atributos de invitado. Por ejemplo, usa curl para eliminar una clave específica:

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

    Haz los cambios siguientes:

    • NAMESPACE: el espacio de nombres de la clave guest-attributes que quieras eliminar
    • KEY: la ruta de guest-attributes donde se almacena el valor.

    Máquinas virtuales de Windows

    También puedes eliminar atributos de invitado. Por ejemplo, usa Invoke-RestMethod para eliminar una clave 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

    Haz los cambios siguientes:

    • NAMESPACE: el espacio de nombres de la clave guest-attributes que quieras eliminar
    • KEY: la ruta de guest-attributes donde se almacena el valor.

Inhabilitar los atributos de invitado en tu organización o carpeta

Si no quieres que ninguna de las máquinas virtuales de tu organización o carpeta habilite los atributos de invitado, puedes anular y inhabilitar la función por completo.

Define la restricción constraints/compute.disableGuestAttributesAccess en tu organización o carpeta. Sustituye PROJECT_ID por el nombre de tu proyecto:

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

Consulta el artículo Usar restricciones para obtener más información sobre cómo definir y gestionar restricciones en tus organizaciones.

Siguientes pasos