Almacena y recupera metadatos de instancias

Precaución: Cualquier proceso que pueda consultar la URL de metadatos tiene acceso a todos los valores del servidor de metadatos. Esto incluye cualquier valor de metadatos personalizados que escribas en el servidor. Google recomienda que tengas cuidado cuando escribas valores sensibles en el servidor de metadatos o cuando ejecutes procesos de terceros.

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. Puedes buscar 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 de la IP externa de una instancia y usarla en tu 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 configurar metadatos personalizados.

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

El servidor v1beta1 y los extremos del servidor de metadatos v0.1 quedaron obsoletos el 30 de septiembre de 2020 y están en proceso de cerrarse. Asegúrate de actualizar todas las solicitudes para usar v1. Para obtener más información, consulta Transición al extremo del servidor de metadatos v1.

Para obtener información sobre cómo verificar la versión del extremo del servidor de metadatos, consulta la sección sobre cómo verificar la versión del extremo de tu servidor.

Antes de comenzar

• Si deseas usar los ejemplos de línea de comandos en esta guía, haz lo siguiente:
  1. Instala la herramienta de línea de comandos de gcloud o actualízala a la última versión.
  2. Configura una región y una zona predeterminadas.
• Si deseas usar los ejemplos de API de esta guía, configura el acceso a la API.

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• compute.instances.setMetadata en la instancia, si se configuran los metadatos de la instancia
• compute.projects.setCommonInstanceMetadata en el proyecto, si se establecen los metadatos para todo el proyecto.
• compute.projects.get en el proyecto, si solo obtienes metadatos.
• compute.instances.get en la instancia, si solo obtienes metadatos

Metadatos de instancia y de proyecto

Los metadatos se pueden asignar a instancias y proyectos. Los metadatos del proyecto se propagan a todas las instancias de máquina virtual (VM) dentro del proyecto, mientras que los metadatos de la instancia solo afectan a esa instancia.

Claves de metadatos predeterminados

Para obtener una lista de valores de metadatos predeterminados que puedes consultar, visita la página Valores de metadatos de VM predeterminados.

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 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 de la instancia a su servidor de metadatos.

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

Metadata-Flavor: Google

Este encabezado 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 tu solicitud.

Nota: Antes, el encabezado X-Google-Metadata-Request: True era obligatorio en las solicitudes. Ambos encabezados aún son compatibles, pero recomendamos que uses el encabezado Metadata-Flavor en lugar del encabezado X-Google-Metadata-Request: True.

Encabezado X-Forwarded-For

El servidor de metadatos rechaza de forma automática todas las solicitudes que contengan 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:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

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

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/[e-mail]/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

En la siguiente tabla, se resumen los caracteres codificados que no se admiten en una ruta de solicitud.

Carácter codificado	Valor aceptado
%21	!
%24	$
%27	'
%28	(
%29	)
%2A	*
%2C	,
%40	@

¿Está protegida 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 con una barra diagonal es un directorio. Por ejemplo, la entrada disks/ es un directorio de discos adjuntos 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 su URL específica:

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 siguiente extremo:

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

READ_WRITE

De forma 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 consulta alt=jsono alt=text, que muestran datos en formato de string JSON o como una representación de texto sin formato, respectivamente.

Por ejemplo, la clave tags muestra de forma automática datos en formato JSON. En su lugar, puedes mostrar datos en formato de texto mediante la especificación del 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 todos los contenidos 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"}]

De forma predeterminada, los contenidos recurrentes se muestran en formato JSON. Si deseas mostrar estos contenidos en formato de texto, agrega el parámetro de búsqueda 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

Configura valores booleanos

En el caso de los campos que aceptan valores booleanos, TRUE o FALSE, también se pueden usar los siguientes valores:

Estado	Valores alternativos
TRUE	S, Sí, 1
FALSE	N, No, 0

Los valores booleanos no distinguen entre mayúsculas ni minúsculas. Por ejemplo, puedes usar False, false o FALSE para inhabilitar una función.

Establece metadatos personalizados

Puedes configurar metadatos personalizados para una instancia o un proyecto desde Google Cloud 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 a tu proyecto o instancia y configurar secuencias de comandos de inicio y cierre.

Limitaciones de tamaño de metadatos personalizados

Compute Engine aplica un límite total combinado de 512 KB para todas las entradas de metadatos. Los límites de tamaño máximo también se aplican a cada key y value de la siguiente manera:

• Cada metadato key tiene un límite máximo de 128 bytes.
• Cada metadato value tiene un límite máximo de 256 KB.

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.

Los contenidos de la secuencia de comandos de inicio y cierre también se pueden almacenar como metadatos personalizados y se cuentan en estos límites de tamaño, si proporcionas de manera directa el contenido de la secuencia de comandos de inicio o cierre. Para evitar esto, almacena la secuencia de comandos de inicio o cierre como un archivo alojado en una ubicación externa, como Cloud Storage, y proporciona la URL de la secuencia de comandos de inicio cuando crees una instancia. Estos archivos se descargan en la instancia de VM, en lugar de almacenarse en el servidor de metadatos.

Establece metadatos de instancia

Configura metadatos personalizados para una instancia en Cloud 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 instancias

Console

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

   Ir a Instancias de VM

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, completa tantos pares clave-valor como necesites para los metadatos personalizados.
5. Haz clic en Crear para crear la instancia.

gcloud

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

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

API

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

POST https://compute.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

Console

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

   Ir a 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.

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-name \
      --metadata bread=mayo,cheese=cheddar,lettuce=romaine

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

gcloud compute instances add-metadata instance-name \
    --metadata lettuce=green

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

gcloud compute instances remove-metadata instance-name \
    --keys lettuce

API

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

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 que coincida para realizar tu solicitud. La huella digital cambia después de cada solicitud y, si proporcionas una huella digital que no coincida, tu solicitud será rechazada. De esta forma, solo se puede realizar una actualización a la vez y se evitan las 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://compute.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"
   }
  ]
 },
 ...
}

Luego, realiza una solicitud al método instances().setMetadata y establece tus 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://compute.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 debes incluir la propiedad de huella digital de metadatos actual para que una solicitud instances().setMetadata se complete correctamente:

POST https://compute.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 de baz=bat para todo el proyecto, este se aplica de forma automática a todas las instancias del proyecto.

Console

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

   Ir a metadatos

2. Haz clic en Editar.

3. Agrega o edita una entrada de metadatos.

4. Guarda los cambios.

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 igual, por ejemplo, key=value. Cuando hay varios pares clave-valor, se separan con espacios.

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

API

En la API, realiza una solicitud al método projects().setCommonInstanceMetadata y proporciona todos los valores nuevos de los metadatos.

Para realizar un bloqueo optimista, puedes proporcionar una huella digital opcional. Una huella digital es una string aleatoria de caracteres generada por Compute Engine. La huella digital cambia después de cada solicitud y, si proporcionas una huella digital que no coincida, se rechazará tu solicitud.

Si no proporcionas una huella digital, no se realizará ninguna verificación de coherencia y la solicitud projects().setCommonInstanceMetadata se realizará correctamente. Este comportamiento es diferente al de instances().setMetadata, en las que siempre se requiere una huella digital.

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

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

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

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

POST https://compute.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 Cloud Console, la herramienta de línea de comandos de gcloud o la API.

Console

Para ver los metadatos personalizados de todo el proyecto, ve a la página 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 para la que deseas ver los metadatos.
3. En Metadatos personalizados, consulta los metadatos personalizados de la instancia.

gcloud

Metadatos del proyecto de consulta:

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

Metadatos de la instancia de consulta:

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

Usa la marca --flatten para definir el alcance de la salida a una clave de metadatos relevante. Por ejemplo, la siguiente instancia tiene un par clave-valor de metadatos personalizados de foo:bar.

$ gcloud compute instances describe example-instance

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

Para consultar el valor de la clave foo, ejecuta este comando:

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

---
  bar

API

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

GET https://compute.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://compute.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 atributos de invitado.

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.

Nota: Cualquier aplicación o usuario de la instancia puede leer y escribir datos en estos valores de metadatos de los atributos de invitado. Los atributos de invitado no están diseñados para casos prácticos que requieran autorización y autenticación de aplicaciones o usuarios del invitado. Por ejemplo, no almacenes en el invitado claves o cualquier otro dato sensible que no deba estar disponible para todas las aplicaciones.

Para operaciones de lectura y escritura 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. Las instancias no pueden acceder al servidor de metadatos de otra. Los usuarios y las cuentas de servicio pueden leer los atributos de invitado de una instancia fuera de ella solo si tienen una función de administración de identidades y accesos (IAM) que proporcione el permiso compute.instances.getGuestAttributes.

Habilita atributos de invitado en la instancia

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

Console

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

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

   Ir a Instancias de VM

2. Haga 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 sea 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 a todas las instancias del proyecto:

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

   Ir a 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 instancia existente:

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

   Ir a 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. También puedes configurar el valor como 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.

gcloud

Configura enable-guest-attributes 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 configura enable-guest-attributes=TRUE para habilitar los atributos de invitado. Reemplaza instance-name por el nombre de tu instancia.

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 a todas las instancias del proyecto:

Usa el comando project-info add-metadata en la herramienta de línea de comandos de gcloud 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 instancia existente:

Usa el comando instances add-metadata en la herramienta de línea de comandos de gcloud y configura enable-guest-attributes=TRUE para habilitar los atributos de invitado. Reemplaza instance-name por el nombre de tu instancia.

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

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

Configura atributos de invitado

Cualquier proceso que se ejecute en la instancia 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 instancia no pueden escribir en los valores de metadatos de los atributos de invitado.

Por ejemplo, puedes usar una solicitud curl desde tu instancia 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 los siguientes elementos:

• 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 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 proporcione el permiso compute.instances.getGuestAttributes. De manera alternativa, cualquier usuario o aplicación de la instancia puede leer los valores de metadatos de esa instancia 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 de administrador o sudo. Por ejemplo, puedes usar una solicitud curl desde tu instancia 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 los siguientes elementos:

• 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"

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 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 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

Reemplaza los siguientes elementos:

• instance-name: El nombre de la instancia 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 en la que se encuentra la instancia.

API

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

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes?queryPath=namespace/key

Reemplaza los siguientes elementos:

• project-id: El ID de tu proyecto.
• zone: La zona en la que se encuentra la instancia.
• instance-name: El nombre de la instancia 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/instance-name/getGuestAttributes?queryPath=namespace

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

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-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/instance-name/getGuestAttributes?queryPath=namespace/key

Reemplaza los siguientes elementos:

• oauth-token: Tu token de OAuth.
• project-id: El ID de tu proyecto.
• zone: La zona en la que se encuentra la instancia.
• instance-name: El nombre de la instancia 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 atributos de invitado

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 los siguientes elementos:

• 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 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 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.

Espera las actualizaciones

Dado que los valores de metadatos pueden cambiar mientras se ejecuta la instancia, se puede notificar al servidor de metadatos sobre los cambios de metadatos mediante la función de espera de cambio. Esta función te permite realizar solicitudes HTTP GET pendientes que solo se muestran cuando cambian los metadatos especificados. 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 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.

Nota: Solo puedes realizar una solicitud de espera de cambio en un extremo de metadatos o de manera recurrente en el contenido de un directorio. No puedes realizar una solicitud de espera de cambio en una lista de directorio, ya que el servidor de metadatos hace que la solicitud falle si lo intentas.

Tampoco puedes realizar una solicitud de espera de cambio para un token de cuenta de servicio. Si intentas realizar una solicitud de espera de cambio a la URL del token de la cuenta de servicio, la solicitud falla de inmediato.

En ambos casos, Compute Engine muestra un error 400 de solicitud no válida.

Para realizar una solicitud de espera de cambio, consulta una clave de metadatos y adjunta 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 que se emite, por lo que es útil tener una manera confiable de saber si obtienes el valor de metadatos más reciente.

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

A fin de obtener el valor de ETag actual para una clave de metadatos, realiza una solicitud a esa clave y, luego, imprime los encabezados. En curl, puede hacer esto mediante 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

Luego, puedes usar ese valor de 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 coincide con tu valor de ETag especificado y, si ese valor cambia, la solicitud se muestra con los contenidos nuevos de tu clave de metadatos.

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

compute/metadata/main.py

Ver en GitHub

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']

Nota: En esta muestra, se establece la ETag inicial como 0. El servidor de metadatos nunca muestra una respuesta con 0 como la ETag. Cuando se especifica 0 como la última ETag en una solicitud, el servidor de metadatos responderá con el valor y la ETag actuales. Esto ahorra un poco de código necesario para obtener el valor y la ETag iniciales.

Establece tiempos de espera

Si deseas que el tiempo de espera de la solicitud de espera de cambio se agote después de una cierta cantidad de segundos, puedes configurar 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 los contenidos actuales de la clave de metadatos. A continuación, se muestra 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 el valor de metadatos cambió. Solo se puede 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 mediante el 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 para notificarte cuando esté por suceder un evento de mantenimiento mediante el atributo maintenance-event. De forma predeterminada, todas las instancias de máquinas virtuales están configuradas en migración en vivo para que el servidor de metadatos reciba notificaciones de eventos de mantenimiento antes de que una instancia de VM se migre en vivo. Si optaste por que la instancia de VM se detenga durante el mantenimiento, Compute Engine se detiene de forma automática y reinicia la instancia de VM de forma opcional 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 eventos, consulta las opciones y la configuración de programación.

Puedes saber cuándo ocurrirá un evento de mantenimiento si consultas de forma periódica el atributo maintenance-event. El valor de este atributo cambia 60 segundos antes de que se inicie un evento de mantenimiento, lo que le da al código de la aplicación una forma de activar cualquier tarea que desees realizar antes de un evento de mantenimiento, como crear 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 las notificaciones de eventos de mantenimiento.

Nota: En el caso de las instancias con GPU, el atributo cambia 60 minutos antes de que se detengan las instancias a fin de que tengas tiempo de apagar y reiniciar en otro host. Las instancias con GPU no se migran en vivo; en cambio, se detienen y se reinician de forma opcional. Para obtener más información, consulta Maneja el mantenimiento del host en la documentación de las GPU.

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

• 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 del cliente consulte el atributo maintenance-event al menos una vez entre los eventos de migración.

Nota: Debes consultar el atributo maintenance-event directamente en Compute Engine para determinar si lo estás mirando. Consultar metadatos de nivel superior no activa la notificación previa.

Haz lo siguiente para consultar el atributo maintenance-event:

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

NONE

Precaución: El atributo maintenance-event se propaga en los eventos de mantenimiento solo si configuraste la opción de programación de la instancia como migrate o si la instancia tiene una GPU conectada. Para las instancias de máquinas virtuales sin GPU configuradas con la opción terminate, es como si se presionara el botón de encendido, por lo cual no se generarán notificaciones de eventos de mantenimiento mediante este atributo. Para obtener más información sobre las políticas de mantenimiento de migrate y terminate, consulta Configura políticas de disponibilidad de instancia.

El valor inicial y predeterminado del atributo maintenance-event es NONE.

• En las instancias con GPU, durante un evento de mantenimiento, el atributo cambia de NONE a TERMINATE_ON_HOST_MAINTENANCE. Este atributo se actualiza 60 minutos antes de que comience el evento de detención.

• En las instancias sin GPU con una opción de programación de migrate, el atributo maintenance-event cambia de la siguiente manera:

  1. Al comienzo del evento de migración, el valor cambia de NONE a MIGRATE_ON_HOST_MAINTENANCE. Este atributo se actualiza 60 segundos antes de que comience el evento de detención.
  2. Mientras dura el evento y la instancia de VM se migra en vivo, el valor permanece como MIGRATE_ON_HOST_MAINTENANCE.
  3. Cuando 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. En la siguiente muestra de Python, se proporciona un ejemplo de cómo puedes implementar estas dos funciones.

Nota: Durante el evento de mantenimiento, el servidor de metadatos puede mostrar brevemente un código 503 Service Unavailable. Si la aplicación recibe un código de error 503, debes volver a realizar la solicitud.

Ejemplo de secuencia de comandos de Python para consultar eventos de mantenimiento

compute/metadata/main.py

Ver en GitHub

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()

Verifica la versión del extremo del servidor

Versión actual: v1

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

A fin de verificar la versión del extremo del servidor de metadatos, revisa el URI que usas para realizar solicitudes al servidor.

Versión del extremo de metadatos	URI
v0.1 (obsoleta)	http://metadata.google.internal/0.1/meta-data/…
v1beta1 (obsoleta)	http://metadata.google.internal/computeMetadata/v1beta1/…
v1	http://metadata.google.internal/computeMetadata/v1/…

Inhabilita extremos heredados

Puedes inhabilitar estos extremos a nivel de proyecto o instancia.

A fin de inhabilitar los extremos del servidor de metadatos v0.1 y v1beta1, sigue las instrucciones para configurar metadatos personalizados y configura disable-legacy-endpoints=TRUE.

Por ejemplo, para inhabilitar el extremo del servidor de metadatos a nivel del proyecto mediante la herramienta de línea de comandos gcloud, ejecuta el siguiente comando:

gcloud compute project-info add-metadata \
    --metadata disable-legacy-endpoints=TRUE 

Transiciona al extremo del servidor de metadatos v1

Para obtener más información acerca de la transición de v0.1 o v1beta1 al extremo v1, consulta la página sobre cómo migrar al extremo del servidor de metadatos v1.

¿Qué sigue?

• Obtén más información sobre cómo ejecutar secuencias de comandos de inicio o de cierre en el servidor de metadatos.
• Obtén más información sobre la migración en vivo.