Establece y consulta atributos de invitado

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

Antes de empezar

  • Para VM de Windows Server, usa PowerShell 3.0 o versiones posteriores. Te recomendamos que uses ctrl+v para pegar los bloques de código copiados.
  • Si aún no lo hiciste, configura la autenticación. La autenticación es el proceso mediante el cual se verifica tu identidad para acceder a los servicios y las API de Google Cloud. Para ejecutar un código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine de la siguiente manera.

    Selecciona la pestaña para saber cómo planeas usar las muestras en esta página:

    Consola

    Cuando usas la consola de Google Cloud para acceder a los servicios y las APIs de Google Cloud, no necesitas configurar la autenticación.

    gcloud

    1. Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando: 

      gcloud init
    2. Configura una región y una zona predeterminadas.

    REST

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

      Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando: 

      gcloud init

Funciones obligatorias

Los permisos o las funciones necesarias dependen de si completas las tareas desde o hacia la VM.

Dentro de la VM

Si configuras, consultas o borras los atributos de invitado desde la VM, solo necesitas las funciones y los permisos para conectarte a la VM. Cualquier proceso que se ejecute en la instancia de VM de máquina virtual puede escribir en los valores de los atributos de invitado, incluidas las secuencias de comandos y aplicaciones que no tengan privilegios a nivel de administrador o sudo.

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

Fuera de la VM

Los siguientes roles y permisos son necesarios para habilitar los atributos de invitado o ver los atributos de invitado desde fuera de la VM mediante Google Cloud CLI o REST. No puedes establecer o borrar atributos de invitado desde fuera de una VM.

A fin de asegurarte de que tu cuenta de usuario o de servicio tenga los permisos necesarios para habilitar o ver los atributos de invitado, pídele a tu administrador que le otorgue esta función.Administrador de instancias de Compute (v1) (roles/compute.instanceAdmin.v1 ) rol de IAM en la VM o el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

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

Permisos necesarios

Los siguientes permisos son necesarios para habilitar o ver los atributos de invitado:

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

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

Cuándo usar atributos de invitado

Usa los atributos de invitado solo para 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 características siguientes:

  • La cantidad de consultas está limitada a un máximo de 10 por minuto por instancia de VM.
  • Las consultas no superan un pico de actividad de 3 consultas por segundo. Si se supera esta tasa máxima, Compute Engine podría quitar de manera arbitraria los atributos de invitado que están en proceso de escritura. Este proceso de borrado de datos es necesario para garantizar que se puedan escribir otros datos críticos del sistema en el servidor.

Los atributos de invitado funcionan bien para situaciones en las que debes publicar datos poco frecuentes y de bajo volumen. Por ejemplo, los atributos de invitado funcionan bien para los siguientes casos prácticos:

  • Las secuencias de comandos de inicio que pueden indicar una inicialización exitosa mediante la configuración de un valor de estado personalizado en los atributos de invitado
  • Los agentes administradores de configuración que pueden publicar el nombre y la versión del SO invitado en los atributos de invitado
  • Los agentes administradores de inventario que pueden publicar una lista de los paquetes instalados en la instancia de VM en los atributos de invitado
  • El software de organización de carga de trabajo que puede indicar al plano de control de software que se finalizó una operación en el invitado mediante la configuración de un valor de estado personalizado en los atributos de invitado

Los atributos de invitado no reemplazan la transmisión de eventos, Pub/Sub o cualquier otro método de almacenamiento de datos y repositorios de configuración.

Atributos de invitado y otros servicios de Google Cloud

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

  • Seguridad SSH: Si los atributos de invitado están habilitados y el Acceso al SO está inhabilitado, el entorno invitado y la gcloud CLI usan atributos de invitado para mejorar la seguridad SSH mediante la API de Google a fin de recuperar las claves de host antes de conectarte a la VM mediante SSH.
  • VM Manager: el agente de configuración del SO publica datos del sistema operativo en los atributos de invitado.

Para revisar las entradas de metadatos almacenadas por estos servicios, consulta Claves de metadatos de atributos de invitado predefinidos.

Habilita los atributos de invitado en tu VM

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

Console

Configura enable-guest-attributes en los metadatos de la instancia cuando crees una VM:

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

    Ir a Crear una instancia

  2. Especifica los detalles de la VM.

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

    1. Expande la sección Administración.

    2. En la sección Metadatos, haz clic en Agregar elemento para agregar las siguientes entradas de metadatos:

      • Key: enable-guest-attributes
      • Value: TRUE

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

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

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

    Ir a la página de metadatos

  2. Haz clic en Editar.

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

  4. Haz clic en Guardar para aplicar los cambios.

Configura enable-guest-attributes en los metadatos de una VM existente:

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

    Ir a la página Instancias de VM

  2. Haz clic en el nombre de la VM en la que deseas configurar el valor de 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, agrega una entrada de metadatos donde la clave sea enable-guest-attributes y el valor sea TRUE. También puedes configurar el valor como 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 en la VM.

gcloud

Configura enable-guest-attributes en los metadatos de la instancia cuando crees una VM:

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

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

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

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

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

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

Configura enable-guest-attributes en los metadatos de una VM existente:

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

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

También puedes configurar enable-guest-attributes como FALSE para evitar que tu VM use atributos de invitado.

Configura los atributos de invitado

Cualquier proceso que se ejecute en la instancia de VM de máquina virtual puede escribir en los valores de los atributos de invitado, incluidas las secuencias de comandos y aplicaciones que no tengan privilegios a nivel de administrador o sudo. Los usuarios o las cuentas de servicio fuera de la VM no pueden escribir en los valores de metadatos de los atributos de invitado.

VM de Linux

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

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

Reemplaza lo siguiente:

  • NAMESPACE: Una agrupación lógica para tu KEY. Los atributos de invitado deben tener un espacio de nombres.
  • VALUE: El valor que deseas escribir.
  • KEY: La ruta de acceso de los metadatos dentro de guest-attributes en la que se almacena el valor.

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

VM de Windows

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

Reemplaza lo siguiente:

  • NAMESPACE: Una agrupación lógica para tu KEY. Los atributos de invitado deben tener un espacio de nombres.
  • VALUE: El valor que deseas escribir.
  • KEY: La ruta de acceso de los metadatos dentro de guest-attributes en la que se almacena el valor.

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

Obtén atributos de invitado

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

Cualquier proceso que se ejecute en la máquina virtual puede escribir en el valor de los atributos de invitado, incluidas las secuencias de comandos y las aplicaciones que no tengan privilegios a nivel de administrador o sudo.

Consulta el servidor de metadatos

Usa las siguientes instrucciones para consultar los atributos de invitado desde una VM.

  1. Conéctate a la VM.

  2. Consulta los atributos de invitado.

    VM de Linux

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

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

    Reemplaza lo siguiente:

    • NAMESPACE: El espacio de nombres de la clave de guest-attributes que deseas consultar.
    • KEY: La ruta de acceso dentro de guest-attributes desde la que deseas leer el valor de los metadatos.

    De manera alternativa, puedes mostrar todos los valores de atributo de invitado en una solicitud. Reemplaza NAMESPACE por el espacio de nombres de la clave guest-attributes que deseas consultar.

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

    VM de Windows

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

    Reemplaza lo siguiente:

    • NAMESPACE: El espacio de nombres de la clave de guest-attributes que deseas consultar.
    • KEY: La ruta de acceso dentro de guest-attributes desde la que deseas leer el valor de los metadatos.

    De manera alternativa, puedes mostrar todos los valores de atributo de invitado en una solicitud. Reemplaza NAMESPACE por el espacio de nombres de la clave guest-attributes que deseas consultar.

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

Usa Google Cloud CLI o REST

Usa las siguientes instrucciones para ver los atributos de invitado desde fuera de una VM.

gcloud

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

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

Para recuperar todos los valores en un espacio de nombres específico, incluye la marca --query-path y el espacio de nombres que definiste:

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

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

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

Reemplaza lo siguiente:

  • VM_NAME: Es el nombre de la VM desde la que deseas leer el valor de metadatos del atributo de invitado.
  • NAMESPACE: El espacio de nombres de la clave de guest-attributes que deseas consultar.
  • KEY: La ruta de acceso dentro de los metadatos de guest-attributes en la que se almacena el valor.
  • ZONE: La zona donde se ubica 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

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • ZONE: La zona en la que se encuentra la VM.
  • VM_NAME: Es el nombre de la VM desde la que deseas leer el valor de metadatos del atributo de invitado.
  • NAMESPACE: El espacio de nombres de la clave de guest-attributes que deseas consultar.
  • KEY: La ruta de acceso dentro de los metadatos de guest-attributes en la que se almacena el valor.

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

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

Para recuperar todas las claves en cada espacio de nombres en la VM, omite NAMESPACEy queryPath por completo:

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

De forma alternativa, si tienes un token de OAuth, 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

Reemplaza lo siguiente:

  • OAUTH_TOKEN: Tu token de OAuth.
  • PROJECT_ID: El ID de tu proyecto
  • ZONE: La zona en la que se encuentra la VM.
  • VM_NAME: Es el nombre de la VM desde la que deseas leer el valor de metadatos del atributo de invitado.
  • NAMESPACE: El espacio de nombres de la clave de guest-attributes que deseas consultar.
  • KEY: La ruta de acceso dentro de los metadatos de guest-attributes en la que se almacena el valor.

Borra los atributos de invitado

Usa las siguientes instrucciones para quitar los atributos de invitado de una VM.

  1. Conéctate a la VM.

  2. Borra los atributos de invitado.

    VM de Linux

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

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

    Reemplaza lo siguiente:

    • NAMESPACE: El espacio de nombres de la clave de guest-attributes que deseas borrar.
    • KEY: La ruta de acceso dentro de guest-attributes en la que se almacena el valor.

    VM de Windows

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

    Reemplaza lo siguiente:

    • NAMESPACE: El espacio de nombres de la clave de guest-attributes que deseas borrar.
    • KEY: La ruta de acceso dentro de guest-attributes en la que se almacena el valor.

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

Si no quieres que ninguna de las VM de tu organización o carpeta habilite los atributos de invitado, puedes anular y también inhabilitar la función por completo.

Configura la restricción de constraints/compute.disableGuestAttributesAccess en tu organización o carpeta, mediante el reemplazo de PROJECT_ID por el nombre de tu proyecto:

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

Lee la página sobre el uso de restricciones para obtener más información sobre cómo establecer y administrar restricciones en tus organizaciones.

Próximos pasos