Configura y quita metadatos personalizados

Cada entrada de metadatos se almacena en el servidor de metadatos como pares clave-valor. Las claves de metadatos distinguen mayúsculas de minúsculas. Tus claves pueden ser claves predefinidas o personalizadas de metadatos.

Los metadatos personalizados te permiten crear y usar tus propios pares clave-valor de metadatos en una VM individual o en un proyecto. Puedes agregar nuevas claves de metadatos personalizados, actualizar los valores de tus claves existentes y quitar las entradas de metadatos personalizados cuando no las necesites. Establecer metadatos personalizados es útil para pasar valores arbitrarios a las VMs en un proyecto. También es útil para crear secuencias de comandos de inicio y cierre.

En este documento, se proporciona información sobre cómo hacer lo siguiente:

Antes de comenzar

  • 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 verifica tu identidad para acceder a los servicios y las APIs de Google Cloud . Para ejecutar código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

    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. Instala Google Cloud CLI. Después de la instalación, inicializa Google Cloud CLI con el siguiente comando: 

      gcloud init

      Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

    2. Set a default region and zone.

    REST

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

    Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de Google Cloud .

Roles obligatorios

Para obtener los permisos que necesitas para configurar o quitar los metadatos personalizados en las VMs, pídele a tu administrador que te otorgue los siguientes roles de IAM :

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para configurar o quitar metadatos personalizados en las VMs. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Los siguientes permisos son necesarios para configurar o quitar metadatos personalizados en las VMs:

  • Si tus VMs usan cuentas de servicio: iam.serviceAccounts.actAs en las cuentas de servicio o el proyecto
  • Para agregar, actualizar o quitar metadatos personalizados del proyecto, haz lo siguiente:
    • compute.projects.get en el proyecto
    • compute.projects.setCommonInstanceMetadata en el proyecto
  • Para agregar, actualizar o quitar metadatos zonales personalizados, haz lo siguiente:
    • compute.instanceSettings.get en la configuración de la instancia en la zona requerida del proyecto
    • compute.instanceSettings.update en la configuración de la instancia en la zona requerida del proyecto
  • Para agregar, actualizar o quitar metadatos de instancias personalizados, haz lo siguiente:
    • compute.instances.get en la VM
    • compute.instances.setMetadata en la VM

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Limitaciones

Las entradas de metadatos de la VM tienen las siguientes limitaciones.

Limitaciones de tamaño

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.

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

Además, si proporcionas directamente el contenido de la secuencia de comandos de inicio o de apagado, es posible que el contenido de esta secuencia de comandos también se almacene como metadatos personalizados y se tenga en cuenta para estos límites de tamaño. 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 VM. De esta manera, estos archivos se descargan en la VM, en lugar de almacenarse en el servidor de metadatos.

Limitaciones de mayúsculas y minúsculas de cadenas

  • Cada metadato key distingue mayúsculas de minúsculas.

  • Cada metadato value distingue entre mayúsculas y minúsculas, excepto los valores booleanos.

Limitaciones de los metadatos zonales

  • Solo puedes establecer y quitar metadatos zonales con gcloud CLI o REST.

  • No puedes crear dos claves de metadatos separadas con la misma cadena, incluso si las claves están escritas en casos diferentes. Por ejemplo, si ya existe una clave de metadatos personalizados llamada zonal-metadata-key para los metadatos zonales dentro de una zona específica, no puedes crear claves de metadatos zonales nuevas que sean variaciones de la misma cadena, como Zonal-Metadata-Key o ZONAL-METADATA-KEY.

  • No puedes establecer valores de metadatos zonales para las claves SSH, que se almacenan como metadatos personalizados en la clave ssh-keys.

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 Y, Yes, 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.

Configura metadatos personalizados en las VMs

En esta sección, se explica cómo agregar nuevos metadatos personalizados o actualizar valores de metadatos personalizados existentes para tus VMs de Compute Engine de una de las siguientes maneras:

Configura metadatos personalizados del proyecto

Puedes agregar o actualizar los metadatos personalizados para todas las instancias de un proyecto con la Google Cloud consola, Google Cloud CLI o REST.

Usa estas instrucciones para aplicar la configuración de metadatos a todas las VM del proyecto. Por ejemplo, si defines un par de metadatos del proyecto de baz=bat, este se aplica de forma automática a todas las VM del proyecto.

Console

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

    Ir a la página Metadatos personalizados

  2. Haz clic en Editar, en la parte superior de la página.

  3. Para agregar nuevas entradas de metadatos de proyecto personalizados, haz lo siguiente:

    1. Navega hasta la parte inferior de la página y haz clic en Agregar elemento.
    2. En el campo Clave, ingresa el nombre de tu clave de metadatos personalizada.
    3. En el campo Valor, ingresa el valor de metadatos personalizados del proyecto.
    4. Opcional. Si deseas agregar más entradas de metadatos personalizados del proyecto, repite los pasos anteriores para cada entrada de metadatos que desees agregar.
    5. Para terminar de agregar las entradas de metadatos personalizados del proyecto, haz clic en Guardar.

  4. Para editar las entradas de metadatos personalizados del proyecto existentes, haz lo siguiente:

    1. Navega hasta la entrada de metadatos que quieras editar.
    2. Para actualizar el nombre de una clave de metadatos personalizados específica, en el campo Clave de esa entrada, ingresa el nombre nuevo.
    3. Para actualizar el valor de una entrada de metadatos personalizados del proyecto, en el campo Valor de esa entrada, ingresa el valor nuevo.
    4. Opcional. Para quitar una entrada específica de metadatos personalizados del proyecto, haz clic en el ícono de borrar junto a la entrada de metadatos.
    5. Si deseas editar varias entradas de metadatos personalizados del proyecto, repite los pasos anteriores para cada entrada de metadatos que desees editar.
    6. Para terminar de editar las entradas de metadatos personalizados del proyecto, haz clic en Guardar.

gcloud

Usa el comando project-info add-metadata

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

Reemplaza lo siguiente:

  • KEY: El nombre de la clave de metadatos.
  • VALUE: El valor almacenado para esta clave.

Ejemplo

Por ejemplo, para configurar dos entradas nuevas foo=bar y baz=bat en un proyecto, ejecuta el siguiente comando:

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

De manera opcional, con la marca --metadata-from-file, puedes especificar uno o más archivos desde los que se leerán metadatos.

REST

  1. Es opcional. Para realizar un bloqueo optimista, puedes proporcionar una huella digital.

    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 los métodos instances().setMetadata y instanceSettings().patch, en los que siempre se requiere una huella digital.

    Para obtener la huella digital actual de un proyecto, llama al método project().get.

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

    El resultado es similar a este:

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

  2. 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/PROJECT_ID/setCommonInstanceMetadata

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

Reemplaza PROJECT_ID por el ID del proyecto.

Configura metadatos zonales personalizados

Cuando configuras metadatos zonales personalizados, agregas o actualizas las entradas de metadatos zonales para tus VMs en una zona específica de un proyecto. Puedes hacer lo siguiente configurando metadatos zonales personalizados:

  • Crea nuevas claves de metadatos personalizados para una zona específica de un proyecto y configura los metadatos para todas las VMs de esa zona en ese proyecto.
  • Actualiza los valores de las entradas de metadatos zonales personalizados existentes para todas las VMs en una zona específica de un proyecto.
  • Para las claves de metadatos personalizados existentes que tienen valores de metadatos del proyecto, anula esos valores de metadatos del proyecto en zonas específicas y, en su lugar, configura metadatos zonales. Después de configurar los metadatos zonales para esas claves en una zona específica, todas las VMs de esa zona en ese proyecto usarán los valores de metadatos zonales para esas claves.

Aspectos que debes tener en cuenta antes de configurar metadatos zonales personalizados

Las entradas de metadatos zonales y de proyectos se almacenan en el mismo directorio project/. Si configuras valores diferentes para las mismas claves de metadatos personalizados para VMs a nivel de proyecto y a nivel zonal, los valores de metadatos zonales para esas claves tienen prioridad sobre los valores de metadatos del proyecto en las zonas respectivas.

  • Si agregas un valor de metadatos zonales para una clave de metadatos que ya tiene un valor de metadatos del proyecto, Compute Engine anula el valor de metadatos del proyecto para las VMs de esta zona especificada y actualiza el directorio /project con el valor zonal.
  • Si agregas un valor de metadatos nuevo del proyecto para una clave de metadatos que ya tiene un valor de metadatos zonales, no cambiará nada. Compute Engine conserva el valor de metadatos zonales en el directorio /project de la zona específica.
  • Si no especificas un valor de metadatos zonales para una clave de metadatos personalizada en una zona específica, pero la clave tiene un valor de metadatos del proyecto, las VMs seguirán teniendo los valores de metadatos del proyecto en esas zonas.

Procedimiento

Puedes agregar o actualizar los metadatos zonales personalizados en una zona específica de un proyecto mediante Google Cloud CLI o REST.

gcloud

  • Para agregar o actualizar metadatos zonales personalizados, usa el comando gcloud compute project-zonal-metadata add.

    gcloud compute project-zonal-metadata add \
  --zone=ZONE \
  --project=PROJECT_ID  \
  --metadata=KEY1=VALUE1,KEY2=VALUE2,...

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto
    • ZONE: la zona en la que deseas agregar o actualizar los metadatos zonales.
    • KEY1, KEY2…: Las claves de metadatos personalizados para las que deseas agregar o actualizar valores de metadatos zonales.

    • VALUE1, VALUE2...: Los valores de metadatos zonales que deseas configurar para las claves de metadatos personalizados existentes y nuevas. Según la clave y el valor de los metadatos personalizados, sucederá una de las siguientes situaciones:

    • Si la clave de metadatos personalizados correspondiente es una clave existente que tiene metadatos del proyecto, en la zona especificada, Compute Engine reemplaza el valor de metadatos del proyecto de la clave con el valor de metadatos zonales especificado. Todas las VMs en la zona especificada del proyecto heredan estos metadatos zonales recién especificados para esa clave, y las VMs en otras zonas continúan conservando sus valores de metadatos zonales o del proyecto predominantes. Si realizas alguna actualización futura en el valor de metadatos del proyecto para esta clave, las VMs de esta zona en el proyecto no se verán afectadas y seguirán usando el valor de metadatos zonales para esta clave.

    • Si la clave de metadatos personalizados correspondiente es una clave de metadatos nueva que no se usa para metadatos zonales o del proyecto existentes, Compute Engine crea la clave de metadatos personalizados y configura este valor como los metadatos zonales en la zona especificada.

    • Si la clave de metadatos personalizados correspondiente es una clave de metadatos existente con un valor de metadatos zonales en la zona especificada, sucede lo siguiente:

      • Si el valor de metadatos especificado es diferente del valor existente, Compute Engine actualiza la entrada de metadatos zonales con el valor nuevo.
      • Si el valor de metadatos especificado es el mismo que el valor existente, la entrada de metadatos zonales permanece sin cambios.

Ejemplo: Agrega una nueva entrada de metadatos zonales personalizados

Por ejemplo, considera un proyecto llamado my-project con los siguientes metadatos personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"value-1" y "key-2":"value-2"

Para agregar "key-4":"value-4" como un nuevo par de metadatos zonales personalizados en la zona us-central1-a, ejecuta el siguiente comando:

gcloud compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

Ejemplo: Actualiza los valores de una entrada existente de metadatos zonales personalizados

Considera el mismo proyecto de ejemplo my-project, que ahora tiene los siguientes metadatos personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"value-1", "key-2":"value-2" y "key-4":"value-4"

Para actualizar los valores de metadatos zonales de key-1 y key-4 en la zona us-cerntral1-a con valores nuevos, ejecuta el siguiente comando.

gcloud compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

Ejemplo: Anula el valor de metadatos del proyecto para una clave y usa un valor de metadatos zonales

Considera el mismo proyecto de ejemplo my-project, que ahora tiene los siguientes metadatos personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2" y "key-4":"new-value-4"

En este proyecto de ejemplo, considera key-3, que tiene un valor de metadatos del proyecto de value-c. Supongamos que deseas establecer un valor de metadatos zonales value-3 para esta clave para todas las VMs en la zona us-central1-a. Cuando realizas la operación, para todas las VMs en la zona us-central1-a, Compute Engine anula los valores de metadatos del proyecto y usa los valores de metadatos zonales. Las VMs en todas las demás zonas del proyecto conservan sus valores de metadatos zonales o del proyectos para key-3.

A fin de anular el valor de metadatos del proyecto para key-3 y configurar un valor de metadatos zonal, ejecuta el siguiente comando:

gcloud compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

  1. Obtén la huella digital actual y visualiza los pares clave-valor existentes para el proyecto en esa zona.

    Para realizar un bloqueo optimista, debes proporcionar una huella digital. Una huella digital es una string aleatoria de caracteres generada por Compute Engine. La huella digital cambia cada vez que realizas una solicitud para agregar, actualizar o quitar metadatos zonales, y si proporcionas una huella digital que no coincida, Compute Engine rechaza tu solicitud.

    Si no proporcionas una huella digital, se realizará una verificación de coherencia y tu solicitud de actualización no se realizará de forma correcta. Esto funciona de modo que solo se pueda realizar una solicitud a la vez, lo que evita colisiones. Este comportamiento coincide con instances().setMetadata, en el que siempre se requiere una huella digital.

    Para obtener la huella digital actual de los metadatos zonales, realiza una solicitud GET al método instanceSettings().get.

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

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto
    • ZONE: la zona en la que deseas configurar los metadatos zonales.

    El siguiente es un resultado de ejemplo para esta solicitud:

        {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }

  2. Para agregar o actualizar los metadatos zonales, realiza una solicitud PATCH al método instanceSettings().patch. Debes proporcionar lo siguiente con tu solicitud:

    • Una máscara de actualización. Usa el parámetro de consulta update_mask. La máscara de actualización debe contener las claves de metadatos para lo siguiente:

      • Los nuevos metadatos zonales personalizados que deseas agregar
      • Los metadatos zonales personalizados existentes para los que deseas actualizar valores

      Debes agregar la cadena metadata.items. como un prefijo para cada clave, por ejemplo, metadata.items.key1,metadata.items.key3.

    • En el cuerpo de la solicitud, proporciona lo siguiente:

      • Las claves y los valores de metadatos para los metadatos zonales personalizados nuevos que deseas agregar
      • Las claves y valores de metadatos para los metadatos zonales personalizados existentes que deseas actualizar
      • El valor actual de la huella digital

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
      "KEY1": "VALUE1",
      "KEY2": "VALUE2",
      ...
    }
  }
}

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID del proyecto.
    • ZONE: la zona en la que deseas configurar los metadatos zonales.

    • PREFIXED_METADATA_KEYS: la lista de claves de metadatos para lo siguiente, donde cada clave tiene como prefijo la cadena metadata.items.:

      • Los nuevos metadatos zonales personalizados que deseas agregar
      • Los metadatos zonales personalizados existentes para los que deseas actualizar valores

      Por ejemplo, supongamos que las claves de metadatos zonales actuales en una zona específica son key-1 y key-2. Si deseas agregar una clave nueva, key-3, para los metadatos zonales en esa zona y también actualizar los metadatos zonales de una de las claves existentes, key-1, la máscara de actualización debe tener la siguiente cadena:

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: el valor actual de la huella digital.

    • KEY1, KEY2…: las claves de metadatos zonales personalizados para las que deseas agregar o actualizar valores. Especifica todas las claves de metadatos zonales personalizados que especificaste en la máscara de actualización.

    • VALUE1, VALUE2...: Los valores de metadatos zonales que deseas configurar para las claves de metadatos personalizados existentes y nuevas. Según la clave y el valor de los metadatos personalizados, sucederá una de las siguientes situaciones:

      • Si la clave de metadatos personalizados correspondiente es una clave existente que tiene metadatos del proyecto, en la zona especificada, Compute Engine reemplaza el valor de metadatos del proyecto de la clave con el valor de metadatos zonales especificado. Todas las VMs en la zona especificada del proyecto heredan estos metadatos zonales recién especificados para esa clave, y las VMs en otras zonas continúan conservando sus valores de metadatos zonales o del proyecto predominantes. Si realizas alguna actualización futura en el valor de metadatos del proyecto para esta clave, las VMs de esta zona en el proyecto no se verán afectadas y seguirán usando el valor de metadatos zonales para esta clave.
      • Si la clave de metadatos personalizados correspondiente es una clave de metadatos nueva que no se usa para metadatos zonales o del proyecto existentes, Compute Engine crea la clave de metadatos personalizados y configura este valor como los metadatos zonales en la zona especificada.

      • Si la clave de metadatos personalizados correspondiente es una clave de metadatos existente con un valor de metadatos zonales en la zona especificada, sucede lo siguiente:

      • Si el valor de metadatos especificado es diferente del valor existente, Compute Engine actualiza la entrada de metadatos zonales con el valor nuevo.

      • Si el valor de metadatos especificado es el mismo que el valor existente, la entrada de metadatos zonales permanece sin cambios.

Ejemplo: Agrega una nueva entrada de metadatos zonales personalizados

Por ejemplo, considera un proyecto llamado my-project con los siguientes metadatos personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"value-1" y "key-2":"value-2"

Para agregar "key-4":"value-4" como un nuevo par de metadatos zonales personalizados en la zona us-central1-a, haz la siguiente solicitud PATCH:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

Ejemplo: Actualiza los valores de una entrada existente de metadatos zonales personalizados

Considera el mismo proyecto de ejemplo my-project, que ahora tiene los siguientes metadatos personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"value-1", "key-2":"value-2" y "key-4":"value-4"

Para actualizar los valores de metadatos zonales de key-1 y key-4 en la zona us-cerntral1-a con valores nuevos, realiza la siguiente solicitud PATCH:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

Ejemplo: Anula el valor de metadatos del proyecto para una clave y configura un valor de metadatos zonales

Considera el mismo proyecto de ejemplo my-project, que ahora tiene los siguientes metadatos personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2" y "key-4":"new-value-4"

En este proyecto de ejemplo, considera key-3, que tiene un valor de metadatos del proyecto de value-c. Supongamos que deseas establecer un valor de metadatos zonales value-3 para esta clave para todas las VMs en la zona us-central1-a. Cuando realizas la operación, para todas las VMs en la zona us-central1-a, Compute Engine anula los valores de metadatos del proyecto y usa los valores de metadatos zonales. Las VMs en todas las demás zonas del proyecto conservan sus valores de metadatos zonales o del proyectos para key-3.

Para anular el valor de metadatos del proyecto para key-3 y usar el valor de metadatos zonal value-3 en su lugar, realiza la siguiente solicitud PATCH:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

Configura metadatos de instancias personalizados

Puedes agregar o actualizar los metadatos personalizados para una sola instancia de VM con la Google Cloud consola, Google Cloud CLI o REST.

Puedes configurar los metadatos de instancia personalizados de una de las siguientes maneras:

Agrega metadatos de instancia personalizados durante la creación de VMs

Usa estas instrucciones para agregar metadatos en una instancia de VM específica en el momento de su creación.

Console

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

    Ir a Crear una instancia

  2. Especifica los detalles de la VM.

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

    1. Expande la sección Administración.
    2. Si deseas agregar varios pares clave-valor para tus metadatos personalizados, haz clic en Agregar elemento en la sección Metadatos.

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

gcloud

Para configurar metadatos personalizados, usa el comando gcloud compute instances create con la marca --metadata.

gcloud compute instances create VM_NAME \
--zone=ZONE \
--image-project=IMAGE_PROJECT \
IMAGE_FLAG \
--metadata=KEY=VALUE

Reemplaza lo siguiente:

  • VM_NAME: El nombre de tu VM.
  • ZONE: Es la zona en la que se creará la VM.
  • IMAGE_PROJECT: Es el proyecto que contiene la imagen que se usará para la VM.

  • IMAGE_FLAG: especifica una de las siguientes opciones:

    • Usa la marca --image IMAGE_NAME para especificar una versión específica de una imagen pública.

      Por ejemplo, --image debian-12-bookworm-v20241112.

    • Usa la marca --image-family IMAGE_FAMILY_NAME para especificar una familia de imágenes.

      Esto crea la VM a partir de la imagen de SO no obsoleta más reciente de la familia de imágenes. Por ejemplo, si especificas --image-family debian-12, Compute Engine usa la versión más reciente de la imagen de SO en la familia de imágenes Debian 12.

  • KEY: El nombre de la clave de metadatos.

  • VALUE: El valor almacenado para esta clave.

Ejemplo

Por ejemplo, para configurar una nueva clave env que tiene un valor test en una VM llamada example-instance, ejecuta el siguiente comando:

 gcloud compute instances create example-instance \
   --zone=us-central1-a --image-project=debian-cloud \
   --image-family=debian-12 \
   --metadata=env=test

REST

Usa el método instances.insert y proporciona los metadatos personalizados como parte de la propiedad metadata en tu solicitud:

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

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • ZONE: Zona en la que se creará la VM
  • MACHINE_TYPE: Tipo de máquina, predefinido o personalizado, de la VM nueva
  • VM_NAME: Nombre de la VM nueva
  • KEY: El nombre de la clave de metadatos.
  • VALUE: El valor almacenado para esta clave.

Agrega o actualiza los metadatos de instancia personalizados en una VM existente

Usa estas instrucciones para actualizar los metadatos en una instancia de VM específica que ya existe.

Console

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

    Ir a la página Instancias de VM

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

gcloud

La actualización de los metadatos de la VM con la CLI 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.

Usa el comando instances add-metadata:

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

Reemplaza lo siguiente:

  • VM_NAME: El nombre de tu VM.
  • KEY: El nombre de la clave de metadatos.
  • VALUE: El valor almacenado para esta clave.

Ejemplos

Si deseas agregar la entrada foo=bar, usa lo siguiente:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

Si deseas cambiar la entrada foo=bar a foo=bat, usa este comando:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

  1. Obtén la huella digital actual y visualiza los pares clave-valor existentes de la VM. Para ello, llama al método instances().get.

    Una huella digital es una string aleatoria de caracteres que genera Compute Engine y se usa para realizar un bloqueo optimista. Para actualizar la VM, debes proporcionar el valor de huella digital que coincida. La huella digital cambia después de cada solicitud, y si proporcionas una huella digital que no coincida, se rechaza tu solicitud. Esto funciona de modo que solo se pueda realizar una actualización a la vez, y se evitan colisiones.

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

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto
    • ZONE: La zona en la que se encuentra la VM.
    • VM_NAME: El nombre de tu VM.

    El resultado es similar a este:

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

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

    Si la VM tiene pares clave-valor existentes que deseas conservar, debes incluirlos en esta solicitud con los nuevos:

    Ejemplo

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

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

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto
    • ZONE: La zona en la que se encuentra la VM.
    • VM_NAME: El nombre de tu VM.

Quita metadatos personalizados de las VMs

En esta sección, se proporciona información sobre cómo quitar las entradas de metadatos personalizados de las VMs de Compute Engine de una de las siguientes maneras:

Quita metadatos del proyecto personalizados

Puedes quitar metadatos del proyecto personalizados con la Google Cloud consola o Google Cloud CLI.

Console

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

    Ir a la página de Metadatos

  2. Haz clic en Editar, en la parte superior de la página.

  3. Navega hasta la entrada de metadatos que deseas quitar y haz clic en el botón borrar junto a esa entrada.

    Repite este paso para cada entrada de metadatos que desees quitar.

  4. Para terminar de quitar las entradas de metadatos de proyecto personalizados, haz clic en Guardar.

gcloud

Para quitar metadatos del proyecto personalizados, usa el comando gcloud compute project-info remove-metadata.

  • Si deseas quitar las entradas de metadatos personalizados para claves específicas, especifica esas claves mediante la marca --keys y excluye los valores de esas claves.
gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...
  • Si deseas quitar todos los metadatos personalizados para la VM, especifica la marca --all.
gcloud compute project-info remove-metadata \
    --all

Reemplaza lo siguiente:

  • KEY1, KEY2…: las claves de metadatos personalizados de la instancia que deseas quitar.

Quita metadatos zonales personalizados

Puedes quitar los metadatos zonales personalizados con Google Cloud CLI o REST.

gcloud

Para quitar los metadatos zonales personalizados, usa el comando gcloud compute project-zonal-metadata remove y especifica todas las claves de metadatos que deseas quitar mediante la marca --keys.

gcloud compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • ZONE: la zona en la que deseas quitar los metadatos zonales.
  • KEY1, KEY2…: las claves de metadatos zonales personalizados que deseas quitar.

Después de ejecutar el comando, si alguna de las claves especificadas tiene valores de metadatos del proyecto disponibles, las VMs en la zona especificada heredan esos valores de metadatos del proyecto. Si la entrada de metadatos se configuró solo a nivel zonal y no hay un valor de metadatos del proyecto correspondiente para esa clave, las VMs de esa zona pierden esa información de metadatos.

Ejemplo:

Considera un proyecto de ejemplo my-project, que tiene los siguientes metadatos de proyecto personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" y "key-4":"new-value-4"

Para quitar todos los metadatos zonales de la zona us-central1-a, ejecuta el siguiente comando.

gcloud compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

Después de ejecutar el comando, las VMs en la zona us-central1-a poseen las siguientes entradas de metadatos del proyecto personalizados:

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-c"

REST

  1. Obtén la huella digital actual y visualiza los pares clave-valor existentes para el proyecto en esa zona.

    Para realizar un bloqueo optimista, debes proporcionar una huella digital. Una huella digital es una string aleatoria de caracteres generada por Compute Engine. La huella digital cambia cada vez que realizas una solicitud para agregar, actualizar o quitar metadatos zonales, y si proporcionas una huella digital que no coincida, Compute Engine rechaza tu solicitud.

    Si no proporcionas una huella digital, se realizará una verificación de coherencia y tu solicitud de eliminación no se realizará de forma correcta. Esto funciona de modo que solo se pueda realizar una solicitud a la vez, lo que evita colisiones. Este comportamiento coincide con instances().setMetadata, en el que siempre se requiere una huella digital.

    Para obtener la huella digital actual de un proyecto, realiza una llamada 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: la zona en la que deseas quitar los metadatos zonales.

    El siguiente es un resultado de ejemplo para esta solicitud:

        {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }

  2. Para quitar los metadatos zonales personalizados, realiza una solicitud PATCH al método instanceSettings().patch mediante la exclusión de las claves de metadatos para las que deseas quitar los metadatos zonales del cuerpo de la solicitud. Debes proporcionar lo siguiente con tu solicitud:

    • Una máscara de actualización. Usa el parámetro de consulta update_mask. La máscara de actualización debe contener todas las claves de metadatos personalizados existentes para las que deseas quitar los metadatos zonales. Debes agregar la cadena metadata.items. como un prefijo para cada clave, por ejemplo, metadata.items.key1,metadata.items.key3.

    • En el cuerpo de la solicitud, proporciona solo el valor de la huella digital actual. Excluye todas las claves de metadatos personalizados que especificaste en la máscara de actualización. Si incluyes alguna de las claves de metadatos en la máscara de actualización y el cuerpo de la solicitud, Compute Engine no quita los metadatos zonales para esas claves. 

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
    }
  }
}

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID del proyecto.
    • ZONE: la zona en la que deseas quitar los metadatos zonales.

    • PREFIXED_METADATA_KEYS: la lista de todas las claves de metadatos personalizados existentes para las que deseas quitar los metadatos zonales, en la que cada clave tiene el prefijo de la cadena metadata.items.. Para asegurarte de que tu solicitud de eliminación sea exitosa, excluye estas claves de metadatos del cuerpo de la solicitud. Si incluyes alguna de las claves de metadatos en la máscara de actualización y el cuerpo de la solicitud, Compute Engine no quita los metadatos zonales para esas claves.

      Por ejemplo, supongamos que tus claves de metadatos actuales con metadatos zonales son key-1, key-2, key-3 y key-4, y deseas quitar las entradas de metadatos zonales para key-1 y key-2, la máscara de actualización debe tener la siguiente cadena:

      metadata.items.key1,metadata.items.key2

    • FINGER_PRINT: el valor actual de la huella digital.

Después de realizar la solicitud, si alguna de las claves especificadas tiene valores de metadatos del proyecto disponibles, las VMs en la zona especificada heredan esos valores de metadatos del proyecto. Si la clave de metadatos se configuró solo a nivel zonal y no hay un valor de metadatos del proyecto correspondiente para esa clave, las VMs de esa zona pierden esa información de metadatos.

Ejemplo:

Considera un proyecto de ejemplo my-project, que tiene los siguientes metadatos de proyecto personalizados:

  • Metadatos del proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales en la zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" y "key-4":"new-value-4"

Para quitar los metadatos zonales de key-1 y key-2 en la zona us-central1-a, realiza la siguiente solicitud PATCH.

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

Después de que se complete esta solicitud, las VMs en la zona us-central1-a poseen los siguientes metadatos personalizados. Las VMs heredan los valores de metadatos del proyecto para key-1 y key-2, pero conservan los metadatos zonales para key-3 y key-4.

  • Metadatos del proyecto: "key-1":"value-a" y "key-2":"value-b"
  • Metadatos zonales en la zona us-central1-a: "key-3":"value-3" y "key-4":"new-value-4"

Quita metadatos de instancia personalizados

Puedes quitar los metadatos de instancias personalizados con la Google Cloud consola, Google Cloud CLI o REST.

Console

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

    Ir a la página Instancias de VM

  2. En la columna Nombre, haz clic en el nombre de la VM de la que deseas quitar los metadatos.
  3. Haz clic en Editar, en la parte superior de la página.
  4. En la sección Metadatos haz clic en Borrar elemento para cada una de las entradas de metadatos que deseas quitar.
  5. Para confirmar los cambios y quitar los metadatos de instancia personalizados, haz clic en Guardar.

gcloud

Para quitar los metadatos de instancias personalizados, usa el comando gcloud compute instances remove-metadata.

  • Si deseas quitar las entradas de metadatos personalizados para claves específicas, especifica esas claves mediante la marca --keys y excluye los valores de esas claves.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...
  • Si deseas quitar todos los metadatos personalizados para la VM, especifica la marca --all.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto.
  • ZONE: la zona de tu VM.
  • VM_NAME: El nombre de tu VM.
  • KEY1, KEY2…: las claves de metadatos personalizados de la instancia que deseas quitar.

REST

  1. Obtén la huella digital actual y visualiza los pares clave-valor existentes de la VM. Para ello, llama al método instances().get.

    Una huella digital es una string aleatoria de caracteres que genera Compute Engine y se usa para realizar un bloqueo optimista. Para actualizar la VM, debes proporcionar el valor de huella digital que coincida. La huella digital cambia después de cada solicitud, y si proporcionas una huella digital que no coincida, se rechaza tu solicitud. Esto funciona de modo que solo se pueda realizar una actualización a la vez, y se evitan colisiones.

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

    Reemplaza lo siguiente:

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

    El resultado es similar a este:

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

  2. Realiza una solicitud al método instances().setMetadata. Debes incluir el valor de huella digital de metadatos actual para que tu solicitud se realice correctamente.

    • Para quitar todos los pares clave-valor de metadatos personalizados de una VM, en la propiedad items, excluye las claves de metadatos de las que deseas quitar los valores de metadatos.

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

{
"fingerprint": "FINGER_PRINT"
"items": [
  {
    "key": "KEY1"
    "value": "VALUE1"
  }
  {
    "key": "KEY2"
    "value": "VALUE2"
  }
  ...
]
}

    • Para quitar todos los metadatos de instancias personalizados en la VM, excluye la propiedad items por completo.

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

{
"fingerprint": FINGER_PRINT
}

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • ZONE: la zona de tu VM.
    • VM_NAME: El nombre de tu VM.
    • FINGER_PRINT: el valor actual de la huella digital.
    • KEY1, KEY2…: las claves de metadatos personalizados de la instancia que deseas quitar.
    • VALUE1, VALUE2…: los valores de las claves de metadatos de instancia personalizados que deseas quitar.

¿Qué sigue?