Visualiza y consulta metadatos de VM


Cada máquina virtual (VM) almacena sus metadatos en directorios en un servidor de metadatos. La VM obtiene acceso de manera automática a la API del servidor de metadatos sin ninguna autorización adicional. Puedes usar los métodos que se explican en las siguientes secciones de este documento para ver y consultar los valores de metadatos de las VMs:

Antes de comenzar

  • Para VM de Windows Server, usa PowerShell 3.0 o versiones posteriores. Te recomendamos que uses ctrl+v para pegar los bloques de código copiados.
  • Revisa los conceptos básicos sobre cómo se definen, clasifican y organizan los metadatos de VMs para Compute Engine. Para obtener más información, consulta Acerca de los metadatos de VMs.
  • Si aún no lo hiciste, configura la autenticación. La autenticación es el proceso mediante el cual se verifica tu identidad para acceder a los servicios y las API de Google Cloud. Para ejecutar un código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine de la siguiente manera.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init
    2. Set a default region and zone.
    3. Python

      Para usar las muestras de Python de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

      1. Install the Google Cloud CLI.
      2. To initialize the gcloud CLI, run the following command:

        gcloud init
      3. If you're using a local shell, then create local authentication credentials for your user account:

        gcloud auth application-default login

        You don't need to do this if you're using Cloud Shell.

      Para obtener más información, consulta Set up authentication for a local development environment.

      REST

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

        Install the Google Cloud CLI, then initialize it by running the following command:

        gcloud init

      Si deseas obtener más información, consulta Autentica para usar REST en la documentación de autenticación de Google Cloud.

Roles obligatorios

Los siguientes roles y permisos son necesarios para ver los metadatos personalizados desde fuera de la VM mediante la consola de Google Cloud, Google Cloud CLI o REST. Si consultas los metadatos desde la VM de manera programática, solo necesitas las funciones y los permisos para conectarte a la VM.

A fin de obtener los permisos que necesitas para ver los metadatos personalizados desde fuera de la VM, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

Estos roles predefinidos contienen los permisos necesarios para ver los metadatos personalizados desde fuera de la VM. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para ver los metadatos personalizados desde fuera de la VM:

  • Para ver los metadatos personalizados de todo el proyecto: compute.projects.get en el proyecto
  • Para ver los metadatos zonales del proyecto personalizados: compute.instanceSettings.get en la configuración de la instancia en la zona requerida del proyecto
  • Para ver los metadatos personalizados de una instancia de VM, haz lo siguiente: compute.instances.get en la VM.
  • Si tus VMs usan cuentas de servicio: iam.serviceAccounts.actAs en las cuentas de servicio o el proyecto

También puedes obtener estos permisos con funciones personalizadas o con otras funciones predefinidas

Consulta metadatos de manera programática

Desde una VM, puedes consultar de manera programática valores de metadatos predeterminados o personalizados con herramientas como curl en Linux o Invoke-RestMethod en Windows.

Partes de una solicitud de metadatos

En la siguiente tabla, se resumen las partes principales de una solicitud de consulta de metadatos.

Componentes Descripción
URL raíz

Todos los valores de metadatos se definen como subrutas de la siguiente URLs raíz:

  • 
    http://metadata.google.internal/computeMetadata/v1
  • 
    http://169.254.169.254/v1
  • 
    http://metadata.goog/v1
Encabezado de la solicitud

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.


Metadata-Flavor: Google

Consulta una sola entrada de metadatos

Usa los siguientes comandos para consultar una sola entrada de metadatos.

Linux

  1. Conéctate a tu VM de Linux.
  2. Desde tu VM de Linux, usa la herramienta de curl para realizar una consulta.

    • Para consultar una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
      
    • Para consultar una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
      

    Reemplaza METADATA_KEY por la instancia o la clave de metadatos del proyecto para la que deseas consultar el valor.

    Por ejemplo, si quieres consultar la imagen de arranque de la VM, ejecuta la siguiente consulta:

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

    El resultado es similar al siguiente:

    projects/rhel-cloud/global/images/rhel-8-v20210122

Windows

  1. Conéctate a tu VM de Windows.
  2. Desde tu VM de Windows, usa el comando Invoke-RestMethod para realizar una consulta.

    • Para consultar una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY")
      $value
      
    • Para consultar una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY")
      $value
      

    Reemplaza METADATA_KEY por la instancia o la clave de metadatos del proyecto para la que deseas consultar el valor.

    Por ejemplo, si quieres consultar la imagen de arranque de la VM, ejecuta la siguiente consulta:

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

    El resultado es similar al siguiente:

    projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

Consulta listas de directorios de metadatos

Usa los siguientes comandos para consultar las listas de directorios de metadatos. Las listas de directorios son entradas de metadatos que contienen otras claves de metadatos. Cualquier entrada de metadatos que termine en una barra diagonal es una lista de directorios.

Linux

  1. Conéctate a tu VM de Linux.

  2. Desde tu VM de Linux, ejecuta los siguientes comandos:

    • Para consultar un directorio de metadatos de la instancia de VM, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
      
    • Para consultar un directorio de metadatos del proyecto, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
      

    Reemplaza METADATA_DIRECTORY_NAME por el nombre de la instancia o el directorio de metadatos del proyecto para el que deseas consultar las listas.

    Por ejemplo, considera la entrada disks/, que es un directorio de discos adjuntos a la VM. Para consultar la entrada disks/, completa los siguientes pasos:

    1. Ejecuta el comando de la herramienta de curl en el directorio de discos.

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

      El resultado es similar al siguiente:

      0/
      1/
      2/
      
    2. 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"
      

      El resultado es similar al siguiente:

      device-name
      index
      mode
      type
      
    3. Luego, para consultar el tipo de disco (type) para los discos 0/, puedes ejecutar lo siguiente:

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

      El resultado es similar al siguiente:

      PERSISTENT
      

Windows

La entrada disks/ es un directorio de discos adjuntos a la VM. Para consultar la entrada del disco, completa los siguientes pasos:

  1. Conéctate a tu VM de Windows.

  2. Desde la VM de Windows, ejecuta los siguientes comandos:

    • Para consultar un directorio de metadatos de la instancia de VM, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/")
      $value
      
    • Para consultar un directorio de metadatos del proyecto, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/")
      $value
      

    Reemplaza METADATA_DIRECTORY_NAME por el nombre de la instancia o el directorio de metadatos del proyecto para el que deseas consultar las listas.

    Por ejemplo, considera la entrada disks/, que es un directorio de discos adjuntos a la VM. Para consultar la entrada disks/, completa los siguientes pasos:

    1. Usa el comando Invoke-RestMethod en el directorio de discos.

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

      El resultado es similar al siguiente:

      0/
      1/
      2/
      
    2. Si deseas obtener más información sobre el directorio 0/ del disco, puedes consultar su URL específica:

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

      El resultado es similar al siguiente:

      device-name
      index
      mode
      type
      
    3. Luego, para consultar el tipo de disco (type) para los discos 0/, puedes ejecutar lo siguiente:

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

      El resultado es similar al siguiente:

      PERSISTENT
      

Consulta de manera recurrente las listas de directorios

Si deseas mostrar todos los contenidos de un directorio, usa el parámetro de búsqueda recursive=true en tu solicitud:

Linux

  1. Conéctate a tu VM de Linux.

  2. Desde tu VM de Linux, usa la herramienta de curl para realizar una consulta.

    • Para consultar las listas de un directorio de metadatos de una instancia de VM de forma recursiva, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
      
    • Para consultar las listas de un directorio de metadatos del proyecto de forma recursiva, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
      

    Reemplaza METADATA_DIRECTORY_NAME por el nombre del directorio de metadatos del proyecto o la instancia para el que deseas consultar las listas de forma recurrente.

    Por ejemplo, con el siguiente comando, se consultan de forma recurrente las listas de metadatos de la instancia para el directorio disks/.

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

    El resultado es similar al siguiente:

      [{"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 consulta alt=text:

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

    El resultado es similar al siguiente:

      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
      

Windows

  1. Conéctate a tu VM de Windows.

  2. Desde tu VM de Windows, usa el comando Invoke-RestMethod para realizar una consulta.

    • Para consultar las listas de un directorio de metadatos de una instancia de VM de forma recursiva, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true")
      $value
      
    • Para consultar las listas de un directorio de metadatos del proyecto de forma recursiva, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/?recursive=true")
      $value
      

    Reemplaza METADATA_DIRECTORY_NAME por el nombre del directorio de metadatos del proyecto o la instancia para el que deseas consultar las listas de forma recurrente.

    Por ejemplo, con el siguiente comando, se consultan de forma recurrente las listas de metadatos de la instancia para el directorio disks/.

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

    El resultado es similar al siguiente:

    [{"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 consulta alt=text:

    PS C:\> 
    $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text")
    $value
    

    El resultado es similar al siguiente:

    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
    

Da formato al resultado de la consulta

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.

Linux

  1. Conéctate a tu VM de Linux.
  2. Desde tu VM de Linux, usa la herramienta de curl para realizar una consulta.

    • Para cambiar el formato de datos de la respuesta de consulta de una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
      
    • Para cambiar el formato de datos de la respuesta de consulta de una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
      

    Reemplaza lo siguiente:

    • METADATA_KEY: la clave de metadatos de la instancia o del proyecto para el que deseas consultar el valor.
    • DATA_FORMAT: el formato en el que deseas obtener los datos de respuesta de la consulta, por ejemplo, text o json.

Ejemplo

Por ejemplo, la clave tags muestra de forma automática datos en formato JSON. Puedes mostrar datos en formato de texto mediante la especificación del parámetro de consulta alt=text.

Consulta predeterminada

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

El resultado es similar al siguiente:

  ["http-server", "db-client", "app-server", "mysql-server"]
  

Consulta con formato

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

El resultado es similar al siguiente:

  http-server
  db-client
  app-server
  mysql-server

Windows

  1. Conéctate a tu VM de Windows.
  2. Desde tu VM de Windows, usa el comando Invoke-RestMethod para realizar una consulta.

    • Para cambiar el formato de datos de la respuesta de consulta de una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT")
      $value
      
    • Para cambiar el formato de datos de la respuesta de consulta de una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT")
      $value
      

    Reemplaza lo siguiente:

    • METADATA_KEY: la clave de metadatos de la instancia o del proyecto para el que deseas consultar el valor.
    • DATA_FORMAT: el formato en el que deseas obtener los datos de respuesta de la consulta, por ejemplo, text o json.

Ejemplo

Por ejemplo, la clave tags muestra de forma automática datos en formato JSON. Puedes mostrar datos en formato de texto mediante la especificación del parámetro de consulta alt=text.

Consulta predeterminada

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

El resultado es similar al siguiente:

  ["http-server", "db-client", "app-server", "mysql-server"]
  

Consulta con formato

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text")
  $value
  

El resultado es similar al siguiente:

  http-server
  db-client
  app-server
  mysql-server

Consulta los cambios en los metadatos con la función wait-for-change

Dado que los valores de metadatos pueden cambiar mientras se ejecuta la VM, se puede notificar al servidor de metadatos sobre los cambios de metadatos mediante la función wait-for-change. Con esta opción, la solicitud solo muestra un resultado cuando los metadatos especificados cambiaron.

Puedes usar esta función en metadatos personalizados o definidos por el servidor, por lo que si algo cambia en la VM o el proyecto, o si alguien actualiza una entrada de metadatos personalizados, 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.

La función wait-for-change también te permite coincidir con la solicitud y establecer tiempos de espera.

Cuando trabajes con la función wait-for-change, ten en cuenta lo siguiente:

  • Solo puedes realizar una solicitud wait-for-change en un extremo de metadatos o de manera recurrente en el contenido de un directorio. No puedes realizar una solicitud wait-for-change en una lista de directorio. Si intentas hacer esto, el servidor de metadatos falla en tu solicitud y muestra un error Solicitud no válida 400.

  • No puedes realizar una solicitud wait-for-change para un token de cuenta de servicio. Si intentas realizar una solicitud wait-for-change a la URL del token de la cuenta de servicio, la solicitud falla de inmediato y muestra un error Solicitud no válida 400.

Para realizar una solicitud wait-for-change, consulta una clave de metadatos y agrega el parámetro de consulta ?wait_for_change=true:

Linux

  1. Conéctate a tu VM de Linux.
  2. Desde tu VM de Linux, usa la herramienta de curl para realizar una consulta.

    • A fin de realizar una solicitud wait-for-change para la entrada de metadatos de una instancia de VM, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true" -H "Metadata-Flavor: Google"
      
    • A fin de realizar una solicitud wait-for-change para una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
      

    Reemplaza METADATA_KEY por la instancia o la clave de metadatos del proyecto para la que deseas consultar el valor.

    Después de que se aplique un cambio en la clave de metadatos especificada, la consulta muestra el valor nuevo.

Ejemplos

En este ejemplo, si se hace una solicitud a setInstanceTags method, 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"
  

El resultado es similar al siguiente:

  http-server
  db-client
  

También puedes realizar una solicitud wait-for-change de manera recurrente en el contenido de un directorio:

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

Si hay algún cambio, el servidor de metadatos muestra el nuevo contenido:

  {"foo":"bar","baz":"bat"}
  

Windows

  1. Conéctate a tu VM de Windows.
  2. Desde tu VM de Windows, usa el comando Invoke-RestMethod para realizar una consulta.

      PS C:> 
      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
                -Uri "http://metadata.google.internal/computeMetadata/v1/METADATA_KEY?wait_for_change=true")
      $value
      

    • A fin de realizar una solicitud wait-for-change para la entrada de metadatos de una instancia de VM, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true")
      $value
      
    • A fin de realizar una solicitud wait-for-change para una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true")
      $value
      

    Reemplaza METADATA_KEY por la instancia o la clave de metadatos del proyecto para la que deseas realizar una solicitud wait-for-change.

    Después de que se aplique un cambio en la clave de metadatos especificada, la consulta muestra el valor nuevo.

Ejemplos

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 hace una solicitud a setInstanceTags method, la solicitud muestra los valores nuevos:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true")
  $value
  

El resultado es similar al siguiente:

  http-server
  db-client
  

También puedes realizar una solicitud wait-for-change de manera recurrente en el contenido de un directorio:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes?recursive=true&wait_for_change=true")
  $value
  

Si hay algún cambio, el servidor de metadatos muestra el nuevo contenido:

  {"foo":"bar","baz":"bat"}
  

Usa ETags

Cuando envías una consulta wait-for-change simple, 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 wait-for-change 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 wait-for-change. Si los valores ETag no coinciden, esto indica que el contenido de los metadatos cambió desde la última vez que recuperaste el valor ETag y el servidor de metadatos muestra de inmediato este último valor.

VM de Linux

Para obtener el valor de ETag actual de una clave de metadatos, completa los siguientes pasos:

  1. Conéctate a tu VM de Linux.
  2. Haz una solicitud a esa clave y, luego, imprime los encabezados. Para ello, usa la herramienta de curl con la marca -v:

    • A fin de obtener la ETag actual para una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      curl -v "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
      
    • A fin de obtener la ETag actual para una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      curl -v "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
      

    Reemplaza METADATA_KEY por la clave de metadatos del proyecto o la instancia cuyo valor deseas consultar.

    Por ejemplo, mediante el siguiente comando, se obtiene el valor de ETag actual para la clave de metadatos de instancia tags.

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

    El resultado es similar al siguiente:

    * 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
    <
    http-server
    db-client
  3. Luego, puedes usar ese valor de ETag con el comando de la herramienta curl en tu solicitud wait-for-change:

    • Si deseas usar el valor de ETag para la solicitud wait-for-change de metadatos de la instancia, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
      
    • Para usar el valor de ETag de la solicitud wait-for-change de metadatos del proyecto, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
      

    Reemplaza lo siguiente:

    • METADATA_KEY: la clave de metadatos de la instancia o del proyecto para el que deseas consultar el valor.
    • ETAG: Es el valor de ETag para la clave de metadatos.

    En este ejemplo, el siguiente comando usa el valor de ETag para la clave tags y las consultas de la entrada de metadatos de la instancia.

      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.

VM de Windows

Para obtener el valor de ETag actual de una clave de metadatos, completa los siguientes pasos:

  1. Conéctate a tu VM de Windows.
  2. Haz una solicitud a esa clave y, luego, imprime los encabezados. En Windows, usa el comando Invoke-WebRequest.

    • A fin de obtener la ETag actual para una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
      -Uri http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY)
      
      $value.Headers.ETag
      
    • A fin de obtener la ETag actual para una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
      -Uri http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY)
      
      $value.Headers.ETag
      

    Reemplaza METADATA_KEY por la clave de metadatos del proyecto o la instancia cuyo valor deseas consultar.

    Por ejemplo, mediante el siguiente comando, se obtiene el valor de ETag actual para la clave de metadatos de instancia tags.

      PS C:> 
      $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
      -Uri http://metadata.google.internal/computeMetadata/v1/instance/tags)

    $value.Headers.ETag

    El resultado es similar al siguiente:

      * 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
      <
      http-server
      db-client

  3. Luego, puedes usar ese valor de ETag en la solicitud wait-for-change:

    • Si deseas usar el valor de ETag para la solicitud wait-for-change de metadatos de la instancia, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG")
      $value
      
    • Para usar el valor de ETag de la solicitud wait-for-change de metadatos del proyecto, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG")
      $value
      

    Reemplaza lo siguiente:

    • METADATA_KEY: la clave de metadatos de la instancia o del proyecto para el que deseas consultar el valor.
    • ETAG: Es el valor de ETag para la clave de metadatos.

    En este ejemplo, el siguiente comando usa el valor de ETag para la clave tags y las consultas de la entrada de metadatos de la instancia.

      PS C:> 
      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e")
      $value
      

    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.

Python

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

En esta muestra, se establece la ETag inicial como 0. El servidor de metadatos no mostrará una respuesta con 0 como valor de 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.

last_etag = "0"

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

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

    last_etag = r.headers["etag"]

Establece tiempos de espera

Si deseas que el tiempo de espera de la solicitud wait-for-change se agote después de una cierta cantidad de segundos, puedes configurar el parámetro timeout_sec. 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.

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.

Linux

  1. Conéctate a tu VM de Linux.
  2. Desde tu VM de Linux, usa la herramienta de curl para realizar una consulta.

    • A fin de reanlizar una solicitud wait-for-change con un valor de tiempo de espera para una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
      
    • Para realizar una solicitud wait-for-change con un valor de tiempo de espera para una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
      

    Reemplaza lo siguiente:

    • METADATA_KEY: la clave de metadatos de la instancia o del proyecto para el que deseas consultar el valor.
    • TIMEOUT: el valor de tiempo de espera.

Por ejemplo, con el siguiente comando, se hace una solicitud wait-for-change 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"
  

Windows

  1. Conéctate a tu VM de Windows.
  2. Desde tu VM de Windows, usa el comando Invoke-RestMethod para realizar una consulta.

    • A fin de reanlizar una solicitud wait-for-change con un valor de tiempo de espera para una entrada de metadatos de la instancia de VM, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT")
      $value
      
    • Para realizar una solicitud wait-for-change con un valor de tiempo de espera para una entrada de metadatos del proyecto, ejecuta el siguiente comando:

      $value = (Invoke-RestMethod `
              -Headers @{'Metadata-Flavor' = 'Google'} `
              -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT")
      $value
      

    Reemplaza lo siguiente:

    • METADATA_KEY: la clave de metadatos de la instancia o del proyecto para el que deseas consultar el valor.
    • TIMEOUT: el valor de tiempo de espera.

Por ejemplo, con el siguiente comando, se hace una solicitud wait-for-change que está configurada para que el tiempo de espera se agote después de 360 segundos:

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360")
  $value
  

Códigos de estado

Cuando realizas una solicitud wait-for-change, 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.

Limitaciones

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

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

Visualiza los metadatos personalizados de tus VMs

Puedes ver los valores de metadatos personalizados para las VMs de Compute Engine de una de las siguientes maneras:

Visualiza metadatos de todo el proyecto

Para ver los metadatos personalizados que se aplican a todas las VMs de tu proyecto, usa uno de los siguientes métodos.

Consola

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

    Ir a metadatos

    • En la pestaña Metadatos, puedes revisar la mayoría de los metadatos de tu proyecto personalizado, excepto los metadatos de claves SSH.
    • En la pestaña Claves SSH, puedes revisar todos los metadatos de las claves SSH a nivel de proyecto.

gcloud

Usa el comando gcloud compute project-info describe para consultar los metadatos de todo el proyecto:

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

El resultado es similar al siguiente:

---
fingerprint: HcSFdS_1_1I=
items:
- key: ssh-keys
  value: USERNAME:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDWZ...
kind: compute#metadata

REST

Para consultar los metadatos del proyecto, crea una solicitud GET al método project.get.

Reemplaza PROJECT_ID con el ID del proyecto.

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

El resultado es similar al siguiente:

"kind": "compute#project",
"id": "XXXXXXX",
"creationTimestamp": "2018-12-10T08:34:33.616-08:00",
"name": "YOUR_PROJECT",
"commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "XXXXXCdg=",
  "items": [
    {
      "key": "enable-guest-attributes",
      "value": "TRUE"
    },
    {
      "key": "enable-os-inventory",
      "value": "true"
    },
    {
      "key": "enable-osconfig",
      "value": "TRUE"
    },
    {
      "key": "enable-oslogin",
      "value": "TRUE"
    },
    {
      "key": "sshKeys",
      "value": "XXXXX"
    }
  ]
}, ...

Visualiza los metadatos zonales del proyecto

Para ver metadatos personalizados que se aplican a todas las instancias de VM en una zona específica de un proyecto, usa uno de los siguientes métodos.

gcloud

Para consultar los metadatos zonales del proyecto personalizado, usa el comando gcloud beta compute project-zonal-metadata describe.

gcloud beta compute project-zonal-metadata describe \
    --zone=ZONE \
    --project=PROJECT_ID

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • ZONE: Es la zona para la que deseas ver los metadatos zonales del proyecto.

El resultado es similar al siguiente:

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

REST

Para consultar los metadatos zonales del proyecto personalizado, hace una solicitud GET al método instanceSettings().get.

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • ZONE: Es la zona para la que deseas ver los metadatos zonales del proyecto.

El resultado es similar al siguiente:

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

Visualiza los metadatos de la instancia

Para ver los metadatos personalizados que se aplican a una sola VM en tu proyecto, usa uno de los siguientes métodos.

Consola

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

    Ir a Instancias de VM

  2. Haz clic en el nombre de la VM para la que deseas ver los metadatos.

    • Llaves SSH para esta VM. En la sección Seguridad y acceso, consulta el campo Claves SSH.

      • Un valor de None indica que no hay Llaves SSH almacenadas en metadatos de instancia.

      • Cualquier otro valor indica que hay claves SSH almacenadas en metadatos de instancia.

    • Llaves SSH para un proyecto. En la sección Seguridad y acceso, consulta el campo Bloquear claves SSH de todo el proyecto.

      • Un valor de On indica que el valor de la clave de metadatos block-project-ssh-keys es TRUE en los metadatos de la instancia.

      • Un valor de Off indica que el valor de la clave de metadatos block-project-ssh-keys es FALSE o que no se configuró la clave.

    • Todos los demás metadatos personalizados. Consulta la sección Metadatos personalizados. Verás todos los valores y las claves de metadatos personalizados, excepto los metadatos de las claves SSH.

gcloud

Usa el comando gcloud compute instances describe para consultar los metadatos de la instancia:

gcloud compute instances describe VM_NAME --flatten="metadata[]"

Reemplaza VM_NAME por el nombre de la VM de la que deseas buscar metadatos.

El resultado es similar al siguiente:

---
fingerprint: MTgTJ5m-Cjs=
items:
- key: enable-oslogin
  value: 'true'
kind: compute#metadata

REST

Para consultar los metadatos de una VM específica, crea una solicitud GET para el método instances.get.

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

El resultado es similar al siguiente:

......
"metadata": {
"kind": "compute#metadata",
"fingerprint": "XXXXXXVo=",
"items": [
  {
    "key": "enable-oslogin",
    "value": "true"
  }
]
},....

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • ZONE: La zona donde se ubica la VM.
  • VM_NAME: El nombre de la VM

¿Qué sigue?