Configura y quita metadatos personalizados

Linux Windows

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:

Agrega o actualiza metadatos personalizados en las VMs
Quita metadatos personalizados de las VMs

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.

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 y, luego, inicializa la ejecución del siguiente comando:
```
gcloud init
```
  Nota: Si ya instalaste la CLI de gcloud, asegúrate de que tienes la versión más reciente mediante la ejecución de gcloud components update.
2. Set a default region and zone.

Funciones obligatorias

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:

Administrador de instancias de Compute (v1) (roles/compute.instanceAdmin.v1) en la VM o el proyecto
Si tus VMs usan cuentas de servicio: Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio o el proyecto.

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 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 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, 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 personalizados existente para metadatos zonales llamada project-zonal-metadata-key, entonces, para los metadatos zonales en esa zona, no puedes crear claves de metadatos nuevas, 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:

Configura metadatos personalizados del proyecto a fin de agregar o actualizar metadatos personalizados del proyecto en todas las VMs del proyecto.
Configura metadatos zonales personalizados a fin de agregar o actualizar metadatos personalizados con un permiso zonal para VMs dentro del proyecto.
Configura metadatos de instancia personalizados a fin de agregar o actualizar metadatos de instancia personalizados para una VM específica.

Configura metadatos personalizados del 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 del proyecto de baz=bat, este se aplica de forma automática a todas las VM del proyecto.

Console

En la consola de Google Cloud, ve a la página Metadatos.
Ir a la página Metadatos personalizados
Haz clic en Editar, en la parte superior de la página.
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 personalizados.
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.
Para editar las entradas de metadatos personalizados del proyecto existentes, haz lo siguiente:
1. Navega a la entrada de metadatos que deseas 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

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=",
    ...
  }
}
```

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 si configuras metadatos zonales personalizados:

Crea nuevas claves de metadatos personalizados para una zona específica de un proyecto y configura 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.
En el caso de 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 metadatos zonales para esas claves en una zona específica, todas las VMs de esa zona en ese proyecto usan 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 a nivel de 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 el valor y la clave de metadatos personalizados, ocurre 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 del valor de metadatos del proyecto para esta clave, las VMs de esta zona del 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 no se modifica.

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

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": {
        ...
      }
    }
```
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.
  
  Importante: La máscara de actualización debe estar en minúsculas.
- 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
Precaución: Si especificas claves de metadatos zonales personalizados existentes en la máscara de actualización, pero no las incluyes en el cuerpo de la solicitud, Compute Engine quitará esas entradas de metadatos zonales. Para obtener más información, consulta Quita metadatos zonales personalizados.
```
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 tus 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.
  
  Precaución: Si especificas claves de metadatos zonales personalizados existentes en la máscara de actualización, pero no las incluyes en el cuerpo de la solicitud, Compute Engine quitará esas entradas de metadatos zonales. Para obtener más información, consulta Quita metadatos zonales personalizados.
- VALUE1, VALUE2...: Los valores de metadatos zonales que deseas configurar para las claves de metadatos personalizados existentes y nuevas. Según el valor y la clave de metadatos personalizados, ocurre 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 del valor de metadatos del proyecto para esta clave, las VMs de esta zona del 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 no se modifica.

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"

A fin de anular el valor de metadatos del proyecto para key-3 y usar el valor de metadatos zonales 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 mediante la consola de Google Cloud, Google Cloud CLI o REST.

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

Para VMs nuevas, puedes agregar metadatos personalizados cuando se crea la VM.
Para VMs existentes, puedes agregar o actualizar metadatos personalizados cuando la VM se está ejecutando.

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

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

Ir a Crear una instancia
Especifica los detalles de la VM.
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.
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

En la consola de Google Cloud, ve a la página Instancias de VM.
Ir a la página Instancias de VM
Haz clic en la instancia para la que deseas actualizar los metadatos.
Haz clic en el botón Editar en la parte superior de la página.
En Metadatos personalizados, haz clic en Agregar elemento o edita las entradas de metadatos existentes.
Guarda los cambios.

gcloud

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

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"
      }
    ]
    },
  ...
}
```
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 los metadatos del proyecto personalizados a fin de quitar los metadatos personalizados que se configuraron para todas las VMs de un proyecto.
Quita los metadatos zonales personalizados a fin de quitar los metadatos personalizados que se configuraron para todas las VMs en una zona específica de un proyecto.
Quita los metadatos de la instancia personalizados a fin de quitar los metadatos de VM que se configuraron para una VM específica.

Quita metadatos del proyecto personalizados

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

Console

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

Ir a la página de metadatos
Haz clic en Editar, en la parte superior de la página.
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.
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

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": {
        ...
      }
    }
```
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 de 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.
  
  Importante: La máscara de actualización debe estar en minúsculas.
- 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 de 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 de 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 instancia personalizados con la consola de Google Cloud, Google Cloud CLI o REST.

Consola

En la consola de Google Cloud, ve a la página Instancias de VM.
Ir a la página Instancias de VM
En la columna Nombre, haz clic en el nombre de la VM de la que deseas quitar los metadatos.
Haz clic en Editar, en la parte superior de la página.
En la sección Metadatos haz clic en Borrar elemento para cada una de las entradas de metadatos que deseas quitar.
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

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"
    }
    ]
  },
  ...
}
```
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?

Obtén más información sobre los metadatos de VM.
Obtén información sobre cómo ver y consultar metadatos.
Obtén más información sobre cómo ejecutar secuencias de comandos de inicio o de cierre en el servidor de metadatos.