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.
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:
- Instala la herramienta de línea de comandos de gcloud o actualízala a la última versión.
- 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 instanciacompute.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
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 forma manual ninguno de estos pares de metadatos.
Los siguientes metadatos están disponibles para un proyecto de forma predeterminada. 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, mientras que numeric-project-id
es una clave de metadatos que se mapea 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 configura disable-legacy-endpoints=TRUE , a menos que para el proyecto se usen extremos heredados. Actualiza tus aplicaciones para usar los extremos v1 .
|
attributes/enable-oslogin |
Habilita la función de administración de Llaves SSH de OS Login en el proyecto cuando configures enable-oslogin=TRUE .
|
attributes/vmdnssetting |
Configura cómo se les da formato los nombres DNS internos para las instancias del proyecto. Lee Configura nombres de DNS para obtener más información sobre los nombres de DNS internos. |
attributes/ssh-keys |
Si tu proyecto y tus instancias no están configurados para usar OS Login para la administración de Llaves SSH, este atributo te permite configurar Llaves SSH públicas que se pueden conectar a instancias en este proyecto. Si hay varias Llaves SSH, cada una estará separada por un carácter de salto de línea (\n ). Este valor es una string. Las Llaves SSH administradas por Acceso al SO no se pueden ver en este valor de metadatos.
Ejemplo: |
numeric-project-id |
El ID de proyecto numérico (número de proyecto) de la instancia, que no es igual al nombre del proyecto que aparece en Google Cloud Console. Este valor es diferente del valor de entrada de metadatos project-id .
|
project-id |
El ID del proyecto. |
Los siguientes metadatos están disponibles para una instancia de forma predeterminada:
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 Establece metadatos personalizados a continuación. |
attributes/enable-oslogin |
Habilita la función de administración de Llaves SSH de OS Login en esta instancia cuando configuras enable-oslogin=TRUE .
|
attributes/vmdnssetting |
Configura cómo se dará formato a los nombres de DNS internos de esta instancia. Lee Configura nombres de DNS para obtener más información sobre los nombres de DNS internos. |
attributes/ssh-keys |
Si la instancia no está configurada para usar Acceso al SO para la administración de Llaves SSH, este atributo te permite configurar Llaves SSH públicas que se pueden conectar a esta instancia. Si hay varias Llaves SSH, cada una estará separada por un carácter de salto de línea (\n ). Este valor es una string. Las Llaves SSH administradas por Acceso al SO no se pueden ver en este valor de metadatos.
Ejemplo: |
cpu-platform |
Plataforma de CPU de la instancia. |
description |
La descripción de texto libre de una instancia que se asigna con la marca --description o se configura 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 del tipo de máquina de esta instancia, que tiene el siguiente formato: projects/projectnum/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 cualquier IP externa que actualmente apunte a esta instancia de máquina virtual para la interfaz de red en <index> . En particular, proporciona una lista de IP externas entregadas mediante las 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 mediante 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 mediante 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 de acceso 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 asociada a la instancia. |
service-accounts/service-account-name/token |
Un token de acceso OAuth2 que se puede usar para autenticar aplicaciones. |
service-accounts/service-account-name/identity |
Un token web JSON que es único de la instancia. Debes incluir el parámetro audience en tu solicitud para el valor de metadatos de esta instancia. Por ejemplo, ?audience=http://www.example.com
Lee Verifica la identidad de las instancias para obtener información sobre cómo solicitar y verificar tokens de identidad de las instancias.
|
tags |
Cualquier etiqueta asociada con la instancia. |
zone |
El valor de metadatos de la zona en la que se ejecuta esta instancia. Este valor tiene el siguiente formato: projects/projectnum/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 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.
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/1234567898-compute@developer.gserviceaccount.com/?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=json
o 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
- En Cloud Console, ve a la página Instancias de VM.
- Haz clic en Crear instancia.
- En la página Crear una instancia nueva, completa las propiedades que quieras para tu instancia.
- En la sección Metadatos, completa tantos pares clave-valor como necesites para los metadatos personalizados.
- 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
- En Google Cloud Console, ve a la página Instancias de VM.
- Haz clic en la instancia para la que deseas actualizar los metadatos.
- Haz clic en el botón Editar en la parte superior de la página.
- En Metadatos personalizados, haz clic en Agregar elemento o edita las entradas de metadatos existentes.
- 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
- En Google Cloud Console, ve a la página Metadatos.
- Haz clic en Editar.
- Agrega o edita una entrada de metadatos.
- 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:
- Ve a la página Instancias de VM.
- Haz clic en la instancia para la que deseas ver los metadatos.
- 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.
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:
- En Google Cloud Console, ve a la página Instancias de VM.
- Haz clic en Crear instancia.
- En la página Crear una instancia nueva, completa las propiedades que quieras para tu instancia.
- En la sección Metadatos, agrega una entrada de metadatos en la que la clave sea
enable-guest-attributes
y el valor seaTRUE
. - 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:
- En Google Cloud Console, ve a la página Metadatos.
- Haz clic en Editar.
- Agrega una entrada de metadatos en la que la clave sea
enable-guest-attributes
y el valor seaTRUE
. También puedes configurar el valor enFALSE
para inhabilitar la función. - Haz clic en Guardar para aplicar los cambios.
Configura enable-guest-attributes
en los metadatos de una instancia existente:
- En Google Cloud Console, ve a la página Instancias de VM.
- Haz clic en el nombre de la instancia en la que deseas establecer el valor de los metadatos.
- 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.
- En Metadatos personalizados, agrega una entrada de metadatos en la que la clave sea
enable-guest-attributes
y el valor seaTRUE
. También puedes configurar el valor comoFALSE
para excluir la instancia de la función. - 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 tukey
. 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 deguest-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 deguest-attributes
que deseas consultar.key
: La ruta de acceso dentro deguest-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 deguest-attributes
que deseas consultar.key
: La ruta de acceso dentro de los metadatos deguest-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 deguest-attributes
que deseas consultar.key
: La ruta de acceso dentro de los metadatos deguest-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 namespace
y 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 deguest-attributes
que deseas consultar.key
: La ruta de acceso dentro de los metadatos deguest-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 deguest-attributes
que deseas borrar.key
: La ruta de acceso dentro deguest-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.
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:
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.
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 atributomaintenance-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 atributomaintenance-event
al menos una vez entre los eventos de migración.
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
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
aTERMINATE_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 atributomaintenance-event
cambia de la siguiente manera:- Al comienzo del evento de migración, el valor cambia de
NONE
aMIGRATE_ON_HOST_MAINTENANCE
. Este atributo se actualiza 60 segundos antes de que comience el evento de detención. - Mientras dura el evento y la instancia de VM se migra en vivo, el valor permanece como
MIGRATE_ON_HOST_MAINTENANCE
. - Cuando finaliza el evento de mantenimiento, el valor vuelve a ser
NONE
.
- Al comienzo del evento de migración, el valor cambia de
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.
Ejemplo de secuencia de comandos de Python para consultar eventos de mantenimiento
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
A fin de prepararte para el cierre de los extremos del servidor de metadatos v0.1 y v1beta1, 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.