Almacena y recupera metadatos de instancia

Cada instancia almacena sus metadatos en un servidor de metadatos. Puedes consultar este servidor de metadatos de manera programática desde la instancia y la API de Compute Engine para obtener información sobre la instancia, tal como su ID, el nombre de host, las secuencias de comandos de inicio y apagado, los metadatos personalizados y la información de la cuenta de servicio. La instancia obtiene acceso de manera automática a la API del servidor de metadatos sin ninguna autorización adicional.

El servidor de metadatos es muy útil cuando se usa en combinación con las secuencias de comandos de inicio y apagado porque puedes usarlo para obtener información única sobre una instancia, sin autorización adicional y de manera programática. Por ejemplo, puedes escribir una secuencia de comandos de inicio que obtenga el par clave-valor de metadatos para la IP externa de una instancia y usarla en la secuencia de comandos a fin de configurar una base de datos. Debido a que las claves de metadatos predeterminadas son las mismas en cada instancia, puedes volver a usar la secuencia de comandos sin tener que actualizarla para cada instancia. Esto te ayudará a crear un código menos frágil para las aplicaciones.

Los metadatos se almacenan en el formato key:value. Hay un conjunto predeterminado de entradas de metadatos a las que cada instancia tiene acceso. También puedes establecer metadatos personalizados.

Para acceder al servidor de metadatos, puedes consultar la URL de metadatos.

Versión actual: v1

Compute Engine puede ofrecer más de una versión de metadatos a la vez, pero recomendamos que uses siempre la versión más reciente disponible del servidor de metadatos. En cualquier momento, Compute Engine puede agregar entradas nuevas al servidor de metadatos y campos nuevos a las respuestas. Consulta de manera periódica para ver los cambios.

Antes de comenzar

Permisos necesarios para esta tarea

Debes contar con los permisos siguientes para realizar esta tarea:

  • compute.instances.setMetadata en la instancia, si se establecen metadatos de instancia
  • compute.projects.setCommonInstanceMetadata en el proyecto, si estableces metadatos de nivel de proyecto
  • compute.projects.get en el proyecto, si solo se obtienen metadatos
  • compute.instances.get en la instancia, si solo se obtienen metadatos

Metadatos de instancia y de proyecto

Los metadatos se pueden asignar a nivel de proyecto o de instancia. Los metadatos a nivel de proyecto se propagan a todas las instancias de máquinas virtuales dentro del proyecto, y aquellos a nivel de instancia solo afectan a esa instancia.

Claves de metadatos predeterminados

Compute Engine define un conjunto de entradas de metadatos predeterminados que proporcionan información sobre la instancia o el proyecto. El servidor siempre define y establece los metadatos predeterminados. No puedes editar de manera manual ninguno de estos pares de metadatos.

A continuación, se muestra una lista de metadatos predeterminados disponibles para un proyecto. Algunas entradas de metadatos son directorios que contienen otras claves de metadatos. Esta diferencia se indica con una barra diagonal al final del nombre del metadato. Por ejemplo, attributes/ es un directorio que contiene otras claves y numeric-project-id es una clave de metadatos que se asigna a un valor.

Relativo a http://metadata.google.internal/computeMetadata/v1/project/
Entrada de metadatos Descripción
attributes/ Un directorio de valores de metadatos personalizados que se establecieron para este proyecto.
attributes/disable-legacy-endpoints Inhabilita los extremos del servidor de metadatos heredados para todas las instancias del proyecto. Siempre establece disable-legacy-endpoints=TRUE, a menos que el proyecto use extremos heredados. Actualiza las aplicaciones para que usen los extremos v1.
attributes/enable-oslogin Habilita la función de administración de llaves SSH de acceso a SO en el proyecto cuando configuras enable-oslogin=TRUE.
attributes/vmdnssetting Configura cómo se les da formato los nombres DNS internos para las instancias del proyecto. Lee cómo configurar los nombres DNS para obtener más información sobre los nombres DNS internos.
attributes/ssh-keys Si el proyecto y las instancias no están configuradas a fin de usar el acceso a SO para la administración de llaves SSH, este atributo te permite configurar Llaves SSH públicas que pueden conectarse a instancias en este proyecto. Si hay varias Llaves SSH, cada una estará separada por un carácter de línea nueva (\n). Este valor es una string. Las llaves SSH administradas por acceso a SO no son visibles en este valor de metadatos.

Ejemplo: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

numeric-project-id El ID numérico del proyecto (número de proyecto) de la instancia, que no es el mismo que el nombre del proyecto visible en Google Cloud Platform Console. Este valor es diferente al valor de la entrada de metadatos project-id.
project-id El ID del proyecto.

A continuación se muestra una lista de metadatos predeterminados para una instancia:

Relativo a http://metadata.google.internal/computeMetadata/v1/instance/
Entrada de metadatos Descripción
attributes/ Un directorio de valores de metadatos personalizados que se pasan a la instancia durante el inicio o el apagado. Consulta Especifica metadatos personalizados a continuación.
attributes/enable-oslogin Habilita la función de administración de llaves SSH de acceso a SO en esta instancia cuando configuras enable-oslogin=TRUE.
attributes/vmdnssetting Configura cómo se les da formato a los nombres de DNS internos para esta instancia. Lee cómo configurar los nombres DNS para obtener más información sobre los nombres DNS internos.
attributes/ssh-keys Si la instancia no está configurada a fin de usar el acceso a SO para la administración de llaves SSH, este atributo te permite configurar Llaves SSH públicas que pueden conectarse a esta instancia. Si hay varias llaves SSH, cada una estará separada por un carácter de línea nueva (\n). Este valor es una string. Las llaves SSH administradas por acceso a SO no son visibles en este valor de metadatos.

Ejemplo: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

cpu-platform Plataforma de CPU de la instancia.
description La descripción de texto libre de una instancia, asignada con la marca --description, o establecida en la API.
disks/ Un directorio de discos adjuntos a esta instancia.
guest-attributes/ Valores de metadatos de instancia personalizados que puedes usar para publicar notificaciones de estado poco frecuentes, datos de bajo volumen o datos de baja frecuencia. Estos valores son útiles para indicar cuándo finalizaron las secuencias de comandos de inicio o proporcionar otras notificaciones de estado poco frecuentes a otras aplicaciones. Cualquier usuario o proceso en la instancia de VM puede leer y escribir en los espacios de nombres y claves en los metadatos de los atributos de invitado.
hostname El nombre de host de la instancia.
id El ID de la instancia. Este es un ID numérico único que genera Compute Engine. Es útil para identificar instancias si no deseas usar nombres de instancias.
machine-type El valor de metadatos para el tipo de máquina de esta instancia, que tiene este formato: projects/[NUMERIC_PROJECT_ID]/machineTypes/[MACHINE_TYPE]
name El nombre de la instancia.
network-interfaces/ Un directorio de interfaces de red para la instancia.
network-interfaces/<index>/forwarded-ips/ Un directorio de las IP externas que en la actualidad apuntan a esta instancia de máquina virtual para la interfaz de red en <index>. En específico, proporciona una lista de IP externas entregadas mediante reglas de reenvío que dirigen paquetes a esta instancia.
scheduling/ Un directorio con las opciones de programación para la instancia.
scheduling/on-host-maintenance La configuración de comportamiento de evento de mantenimiento transparente de la instancia. Este valor se establece con la marca --on_host_maintenance o la API.
scheduling/automatic-restart La configuración de reinicio automático de la instancia. Este valor se establece con la marca ‑‑automatic_restart o la API.
scheduling/preemptible La configuración interrumpible de la instancia. Si este valor es TRUE, la instancia es interrumpible. Este valor se establece cuando creas una instancia y no se puede cambiar.
maintenance-event La ruta que indica que un evento de mantenimiento transparente afecta a esta instancia. Consulta esta página sobre el aviso de mantenimiento transparente para obtener más detalles.
service-accounts/ Un directorio de cuentas de servicio asociadas a la instancia.
service-accounts/<service-account-name>/identity Un token web JSON que es único de la instancia. Debes incluir el parámetro “audience” en la solicitud para el valor de metadatos de esta instancia. Por ejemplo, `?audiencia=http://www.example.com`. Lee cómo verificar la identidad de las instancias para obtener información sobre cómo solicitar y verificar tokens de identidad de instancia.
tags Cualquier etiqueta asociada con la instancia.
zone El valor de metadatos para la zona en la que se ejecuta esta instancia. Este valor tiene este formato: projects/[NUMERIC_PROJECT_ID]/zones/[ZONE]

Obtén metadatos

Puedes consultar los contenidos del servidor de metadatos si envías una solicitud a las siguientes URL raíz desde una instancia de máquina virtual. Usa la URL http://metadata.google.internal/computeMetadata/v1/ para realizar solicitudes al servidor de metadatos.

Todos los valores de metadatos se definen como subrutas debajo de estas URL raíz.

Puedes consultar los valores de metadatos predeterminados solo desde la instancia asociada. No puedes consultar los metadatos predeterminados de una instancia desde otra o de manera directa desde la computadora local. Puedes usar herramientas estándar como curl o wget desde la instancia a su servidor de metadatos.

Cuando consultas metadatos, debes proporcionar el encabezado siguiente en todas las solicitudes:

Metadata-Flavor: Google

Con este encabezado, se indica que la solicitud se envió con la intención de recuperar valores de metadatos, en lugar de hacerlo de forma involuntaria desde una fuente insegura, y permite que el servidor de metadatos muestre los datos que solicitaste. Si no proporcionas este encabezado, el servidor de metadatos rechaza la solicitud.

Encabezado X-Forwarded-For

El servidor de metadatos rechazará de manera automática cualquier solicitud que contenga el encabezado X-Forwarded-For. Por lo general, este encabezado indica que la solicitud se realizó a través de un proxy y podría provenir de un usuario no autorizado. Por motivos de seguridad, todas esas solicitudes se rechazan.

Limitaciones

Cuando usas el comando "curl" para recuperar metadatos del servidor, ten en cuenta que algunos caracteres codificados no son compatibles con la ruta de la solicitud. Los caracteres codificados solo se admiten en la ruta de la consulta.

Por ejemplo, la solicitud siguiente podría no funcionar:

http://metadata.goog/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

Para que esta solicitud funcione, debes reemplazar el carácter codificado no admitido en la ruta de solicitud (%40) con el valor aceptado equivalente (@).

http://metadata.goog/computeMetadata/v1/instance/service-accounts1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

En la tabla siguiente, se resumen los caracteres codificados que no son compatibles con una ruta de la solicitud.

Carácter codificado Valor aceptado
%21

!
%24

$
%27

'
%28

(
%29

)
%2A

*
%2C

,
%40

@

¿Es segura la información de los metadatos?

Cuando realizas una solicitud para obtener información del servidor de metadatos, la solicitud y la respuesta de metadatos posterior nunca abandonan el host físico que ejecuta la instancia de máquina virtual.

Consulta listas de directorios

El servidor de metadatos usa directorios para organizar ciertas claves de metadatos. Cualquier entrada de metadatos que termine en una barra diagonal es un directorio. Por ejemplo, la entrada disks/ es un directorio de discos conectados a esa instancia:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"

0/
1/
2/

Del mismo modo, si deseas obtener más información sobre el directorio 0/ del disco, puedes consultar la URL específica del mismo:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"

device-name
index
mode
type

Consulta extremos

Si una clave de metadatos no es un directorio, es un extremo que muestra uno o más valores. Por ejemplo, para consultar el modo de un disco específico, consulta el extremo siguiente:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/mode" -H "Metadata-Flavor: Google"

READ_WRITE

Por configuración predeterminada, cada extremo tiene un formato predefinido para la respuesta. Algunos extremos pueden mostrar datos en formato JSON de forma predeterminada, mientras que otros pueden mostrarlos como una string. Puedes anular la especificación predeterminada del formato de datos con los parámetros de búsqueda alt=json o alt=text, que muestran datos en formato de string JSON o como una representación de texto sin formato de forma respectiva.

Por ejemplo, la clave tags muestra de manera automática datos en formato JSON. En su lugar, puedes mostrar datos en formato de texto si especificas el parámetro de consulta alt=text:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"

["bread","butter","cheese","cream","lettuce"]
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"

bread
butter
cheese
cream
lettuce

Consulta metadatos de manera recurrente

Si deseas mostrar todo el contenido de un directorio, usa el parámetro de consulta recursive=true en tu solicitud:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"

[{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]

Por configuración predeterminada, los contenidos recurrentes se muestran en formato JSON. Si deseas mostrar estos contenidos en formato de texto, agrega el parámetro de consulta alt=text:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"

0/device-name boot
0/index 0
0/mode READ_WRITE
0/type PERSISTENT
1/device-name persistent-disk-1
1/index 1
1/mode READ_WRITE
1/type PERSISTENT
2/device-name persistent-disk-1
2/index 2
2/mode READ_ONLY
2/type PERSISTENT

Establece metadatos personalizados

Puedes establecer metadatos personalizados para una instancia o proyecto desde Google Cloud Platform Console, la herramienta de línea de comandos de gcloud o la API de Compute Engine. Los metadatos personalizados son útiles para pasar valores arbitrarios al proyecto o la instancia y configurar secuencias de comandos de inicio y apagado.

Limitaciones de tamaño de los metadatos personalizados

Compute Engine aplica los siguientes límites en la longitud de los valores de metadatos personalizados:

  • 256 KB para cada entrada de metadatos individual
  • 512 KB en total para todas las entradas de metadatos por instancia

En particular, las llaves SSH se almacenan como metadatos personalizados en la clave ssh-keys. Si tu contenido de metadatos para esta clave excede el límite de 256 KB, no podrás agregar más llaves SSH. Si alcanzas este límite, considera quitar las claves que no se usan a fin de liberar espacio de metadatos para claves nuevas.

El contenido de las secuencias de comandos de inicio y apagado también puede almacenarse como metadatos personalizados y contar para este límite de tamaño, si proporcionas de manera directa el contenido de la secuencia de comandos de inicio o apagado. Para evitar esto, almacena la secuencia de comandos de inicio o apagado como un archivo alojado en una ubicación externa, como Google Cloud Storage, y proporciona la URL de la secuencia de comandos de inicio cuando creas una instancia. Estos archivos se descargarán en la instancia de VM, en lugar de almacenarse en el servidor de metadatos.

Establece metadatos de instancia

Establece metadatos personalizados para una instancia en GCP Console, la herramienta de gcloud o la API. Los metadatos de la instancia se aplican solo a una instancia específica.

Establece metadatos durante la creación de la instancia

En Console

  1. En GCP Console, ve a la página VM Instances.

    Ir a la página Instancias de VM

  2. Haz clic en Crear instancia.
  3. En la página Crear una instancia nueva, llena las propiedades que quieras para tu instancia.
  4. En la sección Metadatos, completa tantos pares clave-valor para los metadatos personalizados como necesites.
  5. Haz clic en Crear para crear la instancia.

En gcloud

Con la herramienta de línea de comandos de gcloud, usa la marca --metadata para establecer metadatos personalizados.

gcloud compute instances create example-instance --metadata foo=bar

En la API

Proporciona metadatos personalizados en la API como parte de la propiedad de metadatos en la solicitud:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{
  "...
        }
      ]
    }
  ],
  "metadata": {
    "items": [
      {
       "key": "foo",
       "value": "bar"
      }
    ]
  },
  ..
}

Actualiza metadatos en una instancia en ejecución

En Console

  1. Ve a la página Instancias de VM.
  2. Haz clic en la instancia para la que deseas actualizar los metadatos.
  3. Haz clic en el botón Editar en la parte superior de la página.
  4. En Metadatos personalizados, haz clic en Agregar elemento o edita las entradas de metadatos existentes.
  5. Guarda los cambios.

En gcloud

La actualización de los metadatos de la instancia con la herramienta de gcloud es una acción aditiva. Especifica solo las claves de metadatos que deseas agregar o cambiar; si una clave que proporcionaste ya existe, el valor de esa clave se actualiza con el nuevo.

Con la herramienta de línea de comandos de gcloud, usa el comando instances add-metadata:

gcloud compute instances add-metadata INSTANCE \
  --metadata bread=mayo,cheese=cheddar,lettuce=romaine

Si quieres cambiar la entrada lettuce=romaine a lettuce=green, usa esto:

gcloud compute instances add-metadata INSTANCE --metadata lettuce=green

Si deseas quitar la entrada lettuce=romaine, especifica la clave existente y excluye el valor.

gcloud compute instances remove-metadata INSTANCE --keys lettuce

En la API

Realiza en la API una solicitud al método de instances().setMetadata. Proporciona una lista de los valores de metadatos nuevos y el valor actual de fingerprint.

Una huella digital es una string aleatoria de caracteres que genera Compute Engine y se usa para realizar un bloqueo optimista. Proporciona el valor de huella digital correspondiente para realizar tu solicitud. La huella digital cambia después de cada solicitud y, si proporcionas una huella digital no coincidente, se rechaza la solicitud. De esta forma, solo se puede realizar una actualización a la vez y se evitan colisiones.

A fin de obtener la huella digital actual de una instancia y ver los pares clave-valor existentes para la instancia, envía una solicitud instances().get:

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

{
 ...
 "name": "example-instance",
 "metadata": {
  "kind": "compute#metadata",
  "fingerprint": "zhma6O1w2l8="
  "items": [
   {
    "key": "foo",
    "value": "bar"
   }
  ]
 },
 ...
}

A continuación, realiza una solicitud al método instances().setMetadata y establece los pares clave-valor de metadatos personalizados. Si la instancia tiene pares clave-valor existentes que deseas conservar, debes incluirlos en esta solicitud con los nuevos:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{
 "fingerprint": "zhma6O1w2l8=",
 "items": [
  {
   "key": "foo",
   "value": "bar"
  },
  {
   "key": "baz",
   "value": "bat"
  }
 ]
}

Para quitar todos los pares clave-valor de metadatos de una instancia, especifica una solicitud instances().setMetadata y excluye la propiedad items. Ten en cuenta que aún debes incluir la propiedad de huella digital de metadatos actual para que esta solicitud tenga éxito:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{
 "fingerprint": "5rC_DXxBUZw="
}

Establece metadatos personalizados para todo el proyecto

Establece metadatos para todo el proyecto a fin de aplicar los metadatos a todas las instancias del proyecto. Por ejemplo, si defines un par de metadatos para todo el proyecto de baz=bat, ese par de metadatos se aplica de manera automática a todas las instancias del proyecto.

En Console

  1. Ve a la página de metadatos.
  2. Haz clic en Editar.
  3. Agrega o edita una entrada de metadatos.
  4. Guarda los cambios.

En gcloud

Con la herramienta de línea de comandos de gcloud, usa el comando project-info add-metadata. Por ejemplo:

gcloud compute project-info add-metadata --metadata foo=bar,baz=bat

Observa los metadatos con el comando describe:

gcloud compute project-info describe

Por ejemplo, puedes obtener una respuesta similar a esta:

...
commonInstanceMetadata:
  fingerprint: RfOFY_-eS64=
  items:
  - key: baz
    value: bat
  - key: foo
    value: bar
  - key: ssh-keys
...

Un par clave-valor de metadatos se especifica con un signo de igual, por ejemplo, key=value. Cuando hay varios pares clave-valor, se separan con espacios.

De manera opcional, puedes especificar uno o más archivos desde los que leer metadatos con la marca --metadata-from-file. Puedes quitar los valores de metadatos con el comando project-info remove-metadata.

En la API

Realiza en la API una solicitud al método projects().setCommonInstanceMetadata, que proporciona todos los valores nuevos de metadatos y un valor de fingerprint.

Una huella digital es una string aleatoria de caracteres que genera Compute Engine y se usa para realizar un bloqueo optimista. Proporciona el valor de huella digital correspondiente para realizar tu solicitud. La huella digital cambia después de cada solicitud y, si proporcionas una huella digital no coincidente, se rechaza la solicitud. De esta forma, solo se puede realizar una actualización a la vez y se evitan colisiones.

Para obtener la huella digital actual de una instancia, realiza una solicitud project().get y copia el valor de la huella digital:

GET https://www.googleapis.com/compute/v1/projects/myproject

{
 "name": "myproject",
 "commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "FikclA7UBC0=",
  ...
}

A continuación, realiza una solicitud al método projects().setCommonInstanceMetadata y establece los pares clave-valor de metadatos personalizados:

POST https://www.googleapis.com/compute/v1/projects/myproject/setCommonInstanceMetadata

{
 "fingerprint": "FikclA7UBC0=",
 "items": [
  {
   "key": "foo",
   "value": "bar"
  }
 ]
}

Consulta metadatos personalizados

Consulta instancias personalizadas o metadatos de proyectos a través de GCP Console, la herramienta de línea de comandos de gcloud o la API.

En Console

Para ver los metadatos personalizados de todo el proyecto, dirígete a la página de metadatos.

Para ver los metadatos personalizados de una instancia, haz lo siguiente:

  1. Ve a la página Instancias de VM.
  2. Haz clic en la instancia cuyos metadatos quieres ver.
  3. En Metadatos personalizados, consulta los metadatos personalizados de la instancia.

En gcloud

Haz esto para consultar metadatos de todo el proyecto:

gcloud compute project-info describe --flatten="commonInstanceMetadata[]"

Haz esto para consulta metadatos de la instancia:

gcloud compute instances describe example-instance --flatten="metadata[]"

La marca --flatten puede usarse para definir el alcance del resultado en una clave de metadatos relevante. Toma como ejemplo una instancia que tiene un par clave-valor de metadatos personalizado de foo:bar.

$ gcloud compute instances describe example-instance

...
metadata:
  fingerprint: Cad2L9eKNR0=
  items:
  - key: foo
    value: bar
  kind: compute#metadata
...

Ejecuta esto para consultar el valor de clave, foo:

$ gcloud compute instances describe example-instance --flatten="metadata[foo]"

---
  bar

En la API

Para consultar los metadatos de un proyecto, realiza una solicitud vacía al método projects().get:

GET https://www.googleapis.com/compute/v1/projects/myproject

Para consultar los metadatos de una instancia, realiza una solicitud vacía al método instance().get:

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

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. Cualquier aplicación o usuario en la instancia puede leer y escribir datos en estos valores de metadatos de los atributos de invitado.

Cuándo usar atributos de invitado

Usa los atributos de invitado solo para casos prácticos que requieren pequeñas cantidades de datos que no cambian 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 consultas 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 pueden indicar una inicialización correcta al establecer un valor de estado personalizado en los atributos de invitado.
  • Los agentes administradores de la configuración pueden publicar el nombre y versión del SO invitado en los atributos de invitado.
  • El agente de administración de inventario puede publicar una lista de paquetes instalados en la VM en los atributos de invitado.
  • El software de organización de carga de trabajo puede indicarle al plano de control de software que se finalizó una operación en el invitado al establecer un valor de estado personalizado en los atributos de invitado.

Los atributos de invitado no reemplazan la transmisión de eventos, Cloud Pub/Sub o cualquier otra forma de almacenamiento de datos y repositorios de configuración.

Para lecturas y escrituras desde una instancia, el servidor de metadatos proporciona autenticación y autorización automáticas a nivel de instancia. Cada instancia puede leer o escribir solo en su propio servidor de metadatos. Otras instancias no pueden acceder al servidor de metadatos de otra instancia. Las cuentas de usuario y de servicio pueden leer los atributos de invitado de instancias por fuera de la instancia solo si tienen una función de IAM que proporciona el permiso compute.instances.getGuestAttributes.

Habilita atributos de invitado en la instancia

De forma predeterminada, los atributos de invitado están inhabilitados. Para habilitarlos, debes establecer los valores de metadatos necesarios en las instancias individuales o en los metadatos de todo el proyecto:

En Console

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

  1. En GCP Console, ve a la página de Instancias de VM.

    Ir a la página de VM Instances

  2. Haz clic en Crear instancia.
  3. En la página Crear una instancia nueva, completa las propiedades que quieras para tu instancia.
  4. En la sección Metadatos, agrega una entrada de metadatos en la que la clave sea enable-guest-attributes y el valor sean TRUE.
  5. Haz clic en Crear para crear la instancia.

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

  1. Ve 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. De manera alternativa, puedes establecer el valor en FALSE para inhabilitar la función.
  4. Haz clic en Guardar para aplicar los cambios.

Establece enable-guest-attributes en los metadatos de una instancia existente:

  1. Ve a la página Instancias de VM.
  2. Haz clic en el nombre de la instancia en la que deseas establecer 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, agrega una entrada de metadatos en la que la clave sea enable-guest-attributes y el valor sea TRUE. De manera alternativa, puedes establecer el valor en FALSE para excluir la instancia 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 instancia.

En gcloud

Establece enable-oslogin-2fa en los metadatos de la instancia cuando crees una instancia:

Usa el comando gcloud compute instances create en la herramienta de línea de comandos de gcloud y establece enable-guest-attributes=TRUE para habilitar los atributos de invitado:

gcloud compute instances create [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

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

Usa el comando project-info add-metadata en la herramienta de línea de comandos de gcloud y establece enable-guest-attributes=TRUE para habilitar los atributos de invitado:

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

De manera alternativa, puedes establecer enable-guest-attributes en FALSE para inhabilitar los atributos de invitado.

Establece enable-guest-attributes en los metadatos de una instancia existente:

Usa el comando instances add-metadata en la herramienta de línea de comandos de gcloud y establece enable-guest-attributes=TRUE para habilitar los atributos de invitado:

gcloud compute instances add-metadata [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

De manera alternativa, puedes establecer enable-guest-attributes en FALSE para que la instancia no use los atributos de invitado.

Configura los atributos de invitado

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

Por ejemplo, puedes usar una solicitud curl desde la instancia 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"

donde:

  • [NAMESPACE] es una agrupación lógica para [KEY]. Los atributos de invitado deben tener un espacio de nombres.
  • [VALUE] es el valor que deseas escribir.
  • [KEY] es la ruta dentro de guest-attributes en la que se almacena el valor.

Obtén los atributos de invitado

Los usuarios o las cuentas de servicio pueden leer los atributos de invitado si tienen una función de IAM que proporciona el permiso compute.instances.getGuestAttributes. De manera alternativa, cualquier usuario o aplicación dentro de la instancia puede leer los valores de metadatos para esa instancia específica.

Cualquier proceso que se ejecute en la máquina virtual puede escribir en el valor de los atributos de invitado, que incluyen secuencias de comandos y aplicaciones que no tienen privilegios de nivel de "sudo" o de administrador. Por ejemplo, puedes usar una solicitud curl desde la instancia 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"

donde: [KEY] es la ruta 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:

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

donde:

  • [NAMESPACE] es una agrupación lógica para [KEY]. Los atributos de invitado deben tener un espacio de nombres.
  • [KEY] es la ruta dentro de guest-attributes en la que se almacena el valor.

En gcloud

Usa la herramienta de línea de comandos de gcloud para leer los valores de metadatos de los atributos de invitado de una instancia. Por ejemplo, puedes recuperar todos los valores para la instancia:

gcloud compute instances get-guest-attributes [INSTANCE_NAME] --zone [ZONE]

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

gcloud compute instances get-guest-attributes [INSTANCE_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 [INSTANCE_NAME] --query-path=[NAMESPACE]/[KEY] --zone [ZONE]

donde:

  • [INSTANCE_NAME] es el nombre de la instancia desde la que deseas leer el valor de metadatos del atributo de invitado.
  • [KEY] es la ruta dentro de los metadatos guest-attributes en la que se almacena el valor.
  • [ZONE] es la zona donde se encuentra la instancia.

En la API

Usa el método compute.instances.getguestattributes de la API:

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

donde:

  • [PROJECT_ID] es el ID del proyecto.
  • [ZONE] es la zona donde se encuentra la instancia.
  • [INSTANCE_NAME] es el nombre de la instancia desde la que deseas leer el valor de metadatos del atributo de invitado.
  • [KEY] es la ruta dentro de los metadatos guest-attributes en la que se almacena el valor.

A fin de recuperar todas las claves para un [NAMESPACE], omite la [KEY]:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]

Para recuperar todas las claves en cada espacio de nombres en la instancia, omite el [NAMESPACE] y queryPath por completo:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes

De manera alternativa, si tienes un token de OAuth, puedes usar curl:

curl -H "Authorization: Bearer [OAUTH_TOKEN]" https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]/[KEY]

donde:

  • [OAUTH_TOKEN] es tu token de OAuth.
  • [PROJECT_ID] es el ID del proyecto.
  • [ZONE] es la zona donde se encuentra la instancia.
  • [INSTANCE_NAME] es el nombre de la instancia desde la que deseas leer el valor de metadatos del atributo de invitado.
  • [NAMESPACE] es una agrupación lógica para [KEY]. Los atributos de invitado deben tener un espacio de nombres.
  • [KEY] es la ruta dentro de los metadatos guest-attributes en la que se almacena el valor.

Borra los atributos de invitado

También puedes borrar los 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"

donde:

  • [NAMESPACE] es una agrupación lógica para [KEY]. Los atributos de invitado deben tener un espacio de nombres.
  • [KEY] es la ruta 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 instancias de tu organización o carpeta habilite los atributos de invitado, puedes anular y, luego, inhabilitar la función por completo.

Establece la restricción constraints/compute.disableGuestAttributesAccess en tu organización o carpeta:

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

donde: [PROJECT_ID] es el nombre del proyecto.

Lee Usa restricciones para obtener más información sobre cómo establecer y administrar restricciones en tus organizaciones.

Espera por las actualizaciones

Dado que los valores de metadatos pueden cambiar mientras se ejecuta la instancia, existe la posibilidad de que el servidor de metadatos te notifique los cambios en los metadatos con la función de espera de cambio. Esta función te permite realizar solicitudes HTTP GET pendientes que solo se muestran cuando los metadatos especificados cambiaron. Puedes usar esta función en metadatos personalizados o definidos por el servidor, por lo que si algo cambia en la instancia o el proyecto, o si alguien actualiza un metadato personalizado, puedes reaccionar de manera programática. Por ejemplo, puedes realizar una solicitud en la clave tags para que la solicitud solo se muestre si cambió el contenido de los metadatos de las etiquetas. Cuando se muestra la solicitud, proporciona el valor nuevo de esa clave de metadatos.

Para realizar una solicitud de espera de cambio, consulta una clave de metadatos y agrega el parámetro de consulta ?wait_for_change=true:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"

Después de que se aplique un cambio en la clave de metadatos especificada, la consulta muestra el valor nuevo. En este ejemplo, si se realiza una solicitud al método setInstanceTags, la solicitud muestra los valores nuevos:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"

cheese
lettuce

También puedes realizar una solicitud de espera de cambio sobre el contenido de un directorio de manera recurrente:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"

El servidor de metadatos muestra los contenidos nuevos si hay algún cambio:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"

{"cheese":"lettuce","cookies":"cream"}

La función de espera de cambio también te permite coincidir con la solicitud y establecer tiempos de espera.

Uso de ETags

Cuando envías una consulta simple de espera de cambio, el servidor de metadatos muestra una respuesta si algo cambió en el contenido de esos metadatos. Sin embargo, existe una condición de carrera inherente entre una actualización de metadatos y una solicitud de espera de cambio emitida, por lo que es útil tener una manera confiable de saber que obtienes el valor de metadatos actualizado.

Para ayudar con esto, puedes usar el parámetro de consulta last_etag, que compara el valor ETag proporcionado con el valor ETag guardado en el servidor de metadatos. Si los valores ETag coinciden, se aceptará la solicitud de espera de cambio. Si los valores ETag no coinciden, esto indica que el contenido de los metadatos cambió desde la última vez que recuperaste el valor ETag y el servidor de metadatos muestra de inmediato este último valor.

A fin de obtener el valor ETag actual para una clave de metadatos, solicita esa clave y, luego, imprime los encabezados. En CURL, puedes hacerlo con la marca -v:

user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
* About to connect() to metadata port 80 (#0)
*   Trying 169.254.169.254... connected
* Connected to metadata (169.254.169.254) port 80 (#0)
> GET /computeMetadata/v1/instance/tags HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
> Host: metadata
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/text
< ETag: 411261ca6c9e654e
< Date: Wed, 13 Feb 2013 22:43:45 GMT
< Server: Metadata Server for VM
< Content-Length: 26
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: SAMEORIGIN
<
cheese
lettuce

A continuación, puedes usar ese valor ETag en la solicitud de espera de cambio:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"

El servidor de metadatos coincidirá con el valor ETag especificado y, si ese valor cambia, la solicitud muestra el contenido nuevo de la clave de metadatos.

En el ejemplo siguiente de Python, se muestra cómo observar de manera programática el servidor de metadatos en busca de cambios:

last_etag = '0'

while True:
    r = requests.get(
        url,
        params={'last_etag': last_etag, 'wait_for_change': True},
        headers=METADATA_HEADERS)

    # During maintenance the service can return a 503, so these should
    # be retried.
    if r.status_code == 503:
        time.sleep(1)
        continue
    r.raise_for_status()

    last_etag = r.headers['etag']

Establece tiempos de espera

Si deseas que la solicitud de espera de cambio se agote después de una determinada cantidad de segundos, puedes establecer el parámetro de consulta timeout_sec=<timeout-in-seconds>. El parámetro timeout_sec limita el tiempo de espera de la solicitud a la cantidad de segundos que especificaste y, cuando la solicitud alcanza ese límite, muestra el contenido actual de la clave de metadatos. Aquí hay un ejemplo de una solicitud de espera de cambio que está configurada para que el tiempo de espera se agote después de 360 segundos:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"

Cuando estableces el parámetro timeout_sec, la solicitud siempre se muestra después de la cantidad de segundos especificada, sin importar si cambió el valor de metadatos. Solo es posible establecer un valor de número entero para el tiempo de espera.

Códigos de estado

Cuando realizas una solicitud de espera de cambio, el servidor de metadatos muestra códigos de estado HTTP estándar para indicar el éxito o el fracaso. En caso de que haya errores, las condiciones de la red pueden hacer que el servidor de metadatos haga fallar la solicitud y muestre un código de error. En estos casos, debes diseñar la aplicación para que sea tolerante a errores y pueda reconocerlos y manejarlos.

Estos son los estados posibles que muestra el servidor de metadatos:

Estado Descripción
HTTP 200 Listo. Se modificó un valor o alcanzaste el timeout_sec especificado y la solicitud se mostró correctamente.
Error 400 La solicitud no fue válida. Corrige la consulta y reintenta la solicitud.
Error 404 El valor de metadatos especificado ya no existe. El servidor de metadatos también muestra este error si los metadatos se borran mientras esperas un cambio.
Error 503 Hubo un error temporal del servidor o un evento de mantenimiento temporal. Reintenta la solicitud.

Obtén avisos de migración en vivo

El servidor de metadatos proporciona información sobre las opciones y la configuración de programación de una instancia a través del directorio scheduling/ y el atributo maintenance-event. Puedes usar estos atributos para obtener información sobre las opciones de programación de una instancia de máquina virtual y usar estos metadatos a fin de notificarte cuando un evento de mantenimiento está por suceder a través del atributo maintenance-event. De manera predeterminada, todas las instancias de máquinas virtuales están configuradas para migrar en vivo, por lo que el servidor de metadatos recibirá avisos de eventos de mantenimiento antes de que se migre en vivo una instancia de VM. Si optaste por que la instancia de VM finalice durante el mantenimiento, Compute Engine finalizará de manera automática y, de manera opcional, reiniciará la instancia de VM si se establece el atributo automaticRestart. Para obtener más información sobre los eventos de mantenimiento y el comportamiento de la instancia durante estos, consulta la configuración y opciones de la programación.

Puedes saber cuándo ocurrirá un evento de mantenimiento si consultas de manera periódica el atributo maintenance-event. El valor de este atributo cambiará 60 segundos antes de que comience un evento de mantenimiento, lo que le dará al código de la aplicación una forma de activar cualquier tarea que desees realizar antes de un evento de mantenimiento, como hacer una copia de seguridad de los datos o actualizar los registros. Compute Engine también ofrece una secuencia de comandos de Python de muestra para demostrar cómo verificar los avisos de eventos de mantenimiento.

Compute Engine da la advertencia de 60 segundos solo si se cumplen estas acciones:

  • Si estableciste las opciones de disponibilidad de la instancia para la migración en vivo durante un evento de mantenimiento.

  • Si consultaste el atributo maintenance-event al menos una vez desde el último evento de mantenimiento. Si nunca consultaste el atributo maintenance-event o no lo hiciste desde la última migración, Compute Engine supone que la instancia no requiere una advertencia previa a los eventos de mantenimiento. El evento de mantenimiento se inicia de inmediato y omite la advertencia de 60 segundos. Si no deseas omitir la advertencia de 60 segundos, asegúrate de que el código de cliente consulte el atributo maintenance-event al menos una vez entre eventos de migración.

Haz esto para consultar el atributo maintenance-event:

user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"

NONE

El valor inicial y el predeterminado del atributo maintenance-event es NONE. Antes de que comience un evento de mantenimiento transparente, esto es lo que sucede con el valor maintenance-event:

  1. Cambia de NONE a MIGRATE_ON_HOST_MAINTENANCE.
  2. A lo largo del evento y mientras la VM migra en vivo, el valor permanece como MIGRATE_ON_HOST_MAINTENANCE.
  3. Una vez que finaliza el evento de mantenimiento, el valor vuelve a ser NONE.

Puedes usar el atributo maintenance-event con la función de espera de actualizaciones para notificar a tus secuencias de comandos y aplicaciones cuando un evento de mantenimiento está por comenzar y finalizar. Esto te permite automatizar cualquier acción que desees ejecutar antes o después del evento. La muestra siguiente de Python proporciona un ejemplo de cómo puedes implementar estas dos funciones.


import time

import requests

METADATA_URL = 'http://metadata.google.internal/computeMetadata/v1/'
METADATA_HEADERS = {'Metadata-Flavor': 'Google'}

def wait_for_maintenance(callback):
    url = METADATA_URL + 'instance/maintenance-event'
    last_maintenance_event = None
    last_etag = '0'

    while True:
        r = requests.get(
            url,
            params={'last_etag': last_etag, 'wait_for_change': True},
            headers=METADATA_HEADERS)

        # During maintenance the service can return a 503, so these should
        # be retried.
        if r.status_code == 503:
            time.sleep(1)
            continue
        r.raise_for_status()

        last_etag = r.headers['etag']

        if r.text == 'NONE':
            maintenance_event = None
        else:
            maintenance_event = r.text

        if maintenance_event != last_maintenance_event:
            last_maintenance_event = maintenance_event
            callback(maintenance_event)

def maintenance_callback(event):
    if event:
        print('Undergoing host maintenance: {}'.format(event))
    else:
        print('Finished host maintenance')

def main():
    wait_for_maintenance(maintenance_callback)

if __name__ == '__main__':
    main()

Transición a v1

El servidor de metadatos v1 funciona de manera un poco diferente que el servidor v1beta1 anterior. Estos son algunos de los cambios que se deben realizar en el servidor de metadatos nuevo:

  • Actualiza las solicitudes de metadatos para incluir el encabezado Metadata-Flavor: Google.

    El servidor de metadatos nuevo requiere que todas las solicitudes proporcionen el encabezado Metadata-Flavor: Google, que indica que la solicitud se realizó con la intención de recuperar valores de metadatos. Actualiza las solicitudes para incluir este encabezado nuevo. Por ejemplo, una solicitud al atributo disks/ ahora tiene el aspecto siguiente:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
    
  • Actualiza las solicitudes que usan el encabezado X-Forwarded-For.

    El servidor rechaza de manera automática estas solicitudes, ya que por lo general indica que las solicitudes se realizaron a través de un proxy. Actualiza las solicitudes para que no contengan este encabezado.

Pasos siguientes

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Documentación de Compute Engine