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

    Selecciona la pestaña para saber cómo planeas usar las muestras en esta página:

    Consola

    Cuando usas la consola de Google Cloud para acceder a los servicios y las APIs de Google Cloud, no necesitas configurar la autenticación.

    gcloud

    1. Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando: 

      gcloud init
    2. Configura una región y una zona predeterminadas.

    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.

      Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando: 

      gcloud init

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:

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

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 en todo el proyecto, haz lo siguiente:
    • compute.projects.get en el proyecto
    • compute.projects.setCommonInstanceMetadata en el proyecto
  • Sigue estos pasos para agregar, actualizar o quitar metadatos zonales personalizados del proyecto:
    • 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 funciones personalizadas o con otras funciones predefinidas

Limitaciones

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 key distingue mayúsculas de minúsculas.

    Para los metadatos zonales de proyecto, Compute Engine no' te permite crear dos claves de metadatos separadas con la misma cadena, incluso si están escritas en casos diferentes. Por ejemplo, si tienes una clave de metadatos zonales del proyecto existente llamada project-zonal-metadata-key, no puedes crear nuevas claves de metadatos zonales del proyecto, como Project-Zonal-Metadata-Key, PROJECT-ZONAL-METADATA-KEY o cualquier otra variación de la misma cadena.

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

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

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.

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 proporciona información sobre cómo agregar nuevos metadatos personalizados o actualizar valores de metadatos personalizados existentes para las VMs de Compute Engine de una de las siguientes maneras:

Establece metadatos personalizados para todo el proyecto

Puedes agregar o actualizar los metadatos personalizados para todas las instancias de un proyecto mediante la consola de Google Cloud, 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 de baz=bat para todo el proyecto, este se aplica de forma automática a todas las VM del proyecto.

Consola

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

    Ir a la página de metadatos

  2. Haz clic en Editar.
  3. Agrega o edita una entrada de metadatos.
  4. Guarda los cambios.

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

Establece metadatos zonales del proyecto personalizados

Puedes agregar o actualizar las entradas de metadatos zonales del proyecto para tus VMs de una de las siguientes maneras:

  • Puedes agregar nuevas claves de metadatos personalizadas a nivel de proyecto y configurar los valores de metadatos para todas las VMs que se encuentran en una zona específica de un proyecto.
  • Puedes actualizar los valores de las claves de metadatos zonales de proyecto personalizados para todas las VMs que se encuentran en una zona específica de un proyecto.
  • Para las claves de metadatos del proyecto que ya tienen valores en todo el proyecto, puedes anular esos valores de todas las VMs en una zona específica y especificar esas VMs para que, en su lugar, usen valores zonales del proyecto.

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

Las entradas de metadatos zonales de proyectos y 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 de proyecto zonal, los valores de metadatos zonales del proyecto para esas claves tienen prioridad sobre los valores de metadatos de todo el proyecto en las zonas respectivas.

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

Procedimiento

Puedes agregar o actualizar los metadatos personalizados para todas las instancias de VM en una zona específica de un proyecto mediante Google Cloud CLI o REST.

gcloud

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

    gcloud beta 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 del proyecto.
    • KEY1, KEY2…: las claves de metadatos zonales del proyecto personalizado para las que deseas agregar o actualizar valores.

    • VALUE1, VALUE2…: Los valores de metadatos zonales del proyecto que deseas establecer para las claves de metadatos zonales del proyecto existentes y nuevos. Según tu clave y valor de metadatos personalizados, sucede una de las siguientes situaciones:

    • Si la clave de metadatos personalizados correspondiente es una clave existente en todo el proyecto, Compute Engine anula el valor de metadatos de todo el proyecto y usa el valor zonal del proyecto para todas las VMs de la zona especificada. Todas las VMs en la zona especificada heredan el valor zonal del proyecto nuevo. Si realizas algún cambio futuro en el valor de todo el proyecto para la misma clave, esas actualizaciones no afectarán a este valor zonal y las VMs en esta zona seguirán teniendo el valor zonal del proyecto como metadato del proyecto.

    • Si la clave de metadatos personalizados correspondiente es una clave de metadatos zonal del proyecto existente y el valor de metadatos especificado es un valor nuevo, Compute Engine actualiza el valor zonal del proyecto de la clave existente.

    • Si la clave de metadatos personalizados correspondiente es una clave nueva que no forma parte de los metadatos zonales o de todo el proyecto existentes, Compute Engine crea la clave de metadatos zonales del proyecto y agrega este valor de metadatos.

    • Si la clave de metadatos personalizados correspondiente es una clave de metadatos zonal del proyecto existente y el valor de metadatos especificado es el mismo que el valor existente, la entrada de metadatos zonales del proyecto permanece sin cambios.

Ejemplo: Agrega una nueva entrada de metadatos zonales del proyecto personalizado

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 del proyecto personalizado en la zona us-central1-a, ejecuta el siguiente comando:

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

Ejemplo: Actualiza los valores de una entrada de metadatos zonal de proyecto personalizado existente

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 del proyecto de key-1 y key-4 en la zona us-cerntral1-a con valores nuevos, ejecuta el siguiente comando.

gcloud beta 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 todo el proyecto para una clave de metadatos y usa un valor zonal de proyecto

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 de value-c para todo el proyecto. Supongamos que deseas establecer un valor de metadatos zonales de proyecto 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 todo el proyecto y usa los valores zonales del proyecto. Las VMs en todas las demás zonas del proyecto conservan sus valores de metadatos zonales o de todo el proyecto para key-3.

A fin de anular el valor de todo el proyecto para key-3 y establecer un valor zonal, ejecuta el siguiente comando:

gcloud beta 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 del proyecto, 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 del proyecto, realiza 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: la zona en la que deseas configurar los metadatos zonales del proyecto.

    El siguiente es un resultado de ejemplo para esta solicitud:

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

  2. Para agregar o actualizar los metadatos zonales del proyecto, 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 de proyecto personalizados que deseas agregar
      • Los metadatos zonales existentes del proyecto personalizado 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 nuevos del proyecto personalizado que deseas agregar
      • Las claves y valores de metadatos para los metadatos zonales existentes del proyecto personalizado que deseas actualizar
      • El valor actual de la huella digital

    PATCH https://compute.googleapis.com/compute/beta/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 del proyecto.

    • 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 de proyecto personalizados que deseas agregar
      • Los metadatos zonales existentes del proyecto personalizado para los que deseas actualizar valores

      Por ejemplo, supongamos que las claves de metadatos zonales de tu proyecto actual son key-1 y key-2. Si deseas agregar una clave de metadatos nueva key-3 y también actualizar una de las claves de metadatos actuales, 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 del proyecto personalizado para las que deseas agregar o actualizar valores. Especifica todas las claves de metadatos zonales del proyecto personalizados que especificaste en la máscara de actualización.

    • VALUE1, VALUE2…: Los valores de metadatos zonales del proyecto que deseas establecer para las claves de metadatos zonales del proyecto existentes y nuevos. Según tu clave y valor de metadatos personalizados, sucede una de las siguientes situaciones:

      • Si la clave de metadatos personalizados correspondiente es una clave existente en todo el proyecto, Compute Engine anula el valor de metadatos de todo el proyecto y usa el valor zonal del proyecto para todas las VMs de la zona especificada. Todas las VMs en la zona especificada heredan el valor zonal del proyecto nuevo. Si realizas algún cambio futuro en el valor de todo el proyecto para la misma clave, esas actualizaciones no afectarán a este valor zonal y las VMs en esta zona seguirán teniendo el valor zonal del proyecto como metadato del proyecto.
      • Si la clave de metadatos personalizados correspondiente es una clave de metadatos zonal del proyecto existente y el valor de metadatos especificado es un valor nuevo, Compute Engine actualiza el valor zonal del proyecto de la clave existente.
      • Si la clave de metadatos personalizados correspondiente es una clave nueva que no forma parte de los metadatos zonales o de todo el proyecto existentes, Compute Engine crea la clave de metadatos zonales del proyecto y agrega este valor de metadatos.
      • Si la clave de metadatos personalizados correspondiente es una clave de metadatos zonal del proyecto existente y el valor de metadatos especificado es el mismo que el valor existente, la entrada de metadatos zonales del proyecto permanece sin cambios.

Ejemplo: Agrega una nueva entrada de metadatos zonales del proyecto personalizado

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 del proyecto personalizado en la zona us-central1-a, haz la siguiente solicitud PATCH:

PATCH https://compute.googleapis.com/compute/beta/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 de metadatos zonal de proyecto personalizado existente

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 del proyecto 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/beta/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 todo el proyecto para una clave de metadatos y usa un valor zonal de proyecto

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 de value-c para todo el proyecto. Supongamos que deseas establecer un valor de metadatos zonales de proyecto 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 todo el proyecto y usa los valores zonales del proyecto. Las VMs en todas las demás zonas del proyecto conservan sus valores de metadatos zonales o de todo el proyecto para key-3.

A fin de anular el valor de metadatos de nivel de proyecto para key-3 y usar el valor zonal de proyecto personalizado value-3 en su lugar, 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-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 mediante la consola de Google Cloud, 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.

Consola

  1. En la consola de Google Cloud, ve a la página Crea 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 \
    --metadata=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.

Ejemplo

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

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

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.

Consola

  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

Puedes quitar metadatos personalizados de las VM de Compute Engine de una de las siguientes maneras:

Quita metadatos personalizados de todo el proyecto

Puedes quitar metadatos personalizados de todo el proyecto mediante la consola de Google Cloud o Google Cloud CLI.

Consola

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

    Ir a la página de metadatos

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

gcloud

Para quitar metadatos personalizados de todo el proyecto, 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 los metadatos zonales del proyecto personalizado

Puedes quitar los metadatos zonales de proyecto personalizados con Google Cloud CLI o la API de Compute Engine.

gcloud

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

gcloud beta 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 configurar los metadatos zonales del proyecto.
  • KEY1, KEY2…: las claves de metadatos zonales del proyecto personalizados que deseas quitar.

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

Ejemplo:

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 del proyecto de la zona us-central1-a, ejecuta el siguiente comando.

gcloud beta 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 los siguientes metadatos de 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 del proyecto, 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 del proyecto.

    El siguiente es un resultado de ejemplo para esta solicitud:

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

  2. Para quitar los metadatos zonales personalizados del proyecto, 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 proyecto 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 zonales del proyecto personalizados existentes de los que deseas quitar los metadatos. 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 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 del proyecto 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 del proyecto.

    • PREFIXED_METADATA_KEYS: la lista de todas las claves de metadatos zonales del proyecto personalizado existente que deseas quitar, en las 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 del proyecto para esas claves.

      Por ejemplo, supongamos que las claves de metadatos zonales de tu proyecto actual son key-1, key-2, key-3 y key-4, y deseas quitar las entradas de metadatos zonales del proyecto 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 de nivel de proyecto disponibles, las VMs en la zona especificada heredan esos valores de nivel de proyecto. Si la clave de metadatos se configuró solo a nivel de proyecto y no hay una clave para todo el proyecto correspondiente, las VMs pierden esa información de metadatos.

Ejemplo:

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

  • Metadatos de todo el proyecto: "key-1":"value-a", "key-2":"value-b" y "key-3":"value-c"
  • Metadatos zonales del proyecto 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 del proyecto 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 de proyecto personalizados. Las VMs heredan los valores de metadatos de todo el proyecto para key-1 y key-2, pero conservan el valor zonal del proyecto para key-3.

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

Quita metadatos de instancia personalizados

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

Consola

  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 Editar, en la parte superior de la página.
  4. En la sección Metadatos haz clic enborrar 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?