Configura metadatos con estado en MIG

Los metadatos de instancia son útiles para configurar propiedades de las aplicaciones y comunicarse con ellas, todo esto a través del servidor de metadatos. Por ejemplo, puedes usar metadatos para configurar la identidad de la instancia de máquina virtual (VM), las variables de entorno, la información sobre la arquitectura del clúster o el rango de datos del que es responsable una VM.

Mediante la configuración de metadatos con estado en un grupo de instancias administrado (MIG), te aseguras de que los metadatos específicos de la instancia se conserven durante eventos de reparación automática, actualización y recreación de instancias administradas.

Puedes configurar los metadatos con estado de forma individual en las instancias de VM de un MIG si los estableces en opciones de configuración por instancia y, luego, aplicas la configuración. Puedes establecer una configuración por instancia en la etapa de creación de instancias o en instancias administradas existentes. Después de aplicar la configuración por instancia, el MIG almacena los metadatos con estado en el campo correspondiente al estado preservado de la configuración (preservedStateFromConfig) de una instancia administrada.

Antes de comenzar

Revisa cuándo usar MIG con estado y cómo funcionan los MIG con estado.
Configura la autenticación si aún no lo hiciste. 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:
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

Limitaciones

Un MIG con metadatos con estado tiene las siguientes limitaciones:

Un MIG con configuración con estado, un MIG con estado, tiene las siguientes limitaciones:

No puedes usar el ajuste de escala automático si tu MIG tiene una configuración con estado.
Si deseas usar actualizaciones progresivas automáticas, debes establecer el método de reemplazo en RECREATE.
Para los MIGs regionales con estado, debes inhabilitar la redistribución proactiva (establece el tipo de redistribución en NONE) para evitar la eliminación de instancias con estado por la redistribución automática entre zonas.
Si usas una configuración de todas las instancias para anular las propiedades de la plantilla de instancias, no puedes especificarlas en ninguna configuración por instancia y, al mismo tiempo, en todas las instancias del grupo de instancias.
Cuando borras una instancia de forma permanente (ya sea de forma manual o por cambio de tamaño), el MIG no conserva los metadatos con estado de la instancia.

Establece metadatos con estado durante la creación de instancias

Establece metadatos con estado cuando se crean instancias de forma manual en un MIG. Esto es útil para migrar una aplicación con estado en VM independientes a un MIG con estado y también, cuando se crean instancias con estado.

Cuando creas de forma manual una instancia en un MIG y proporcionas metadatos con estado, el MIG realiza las siguientes tareas:

Crea una instancia administrada a partir de la plantilla de instancia y usa el nombre proporcionado para la instancia.
Crea una configuración por instancia con los metadatos con estado proporcionados y establece esos metadatos en la instancia.
Almacena los metadatos con estado en el estado preservado de la configuración (preservedStateFromConfig) de la instancia administrada asociada.

gcloud

Para crear una instancia administrada con un nombre personalizado y establecer metadatos con estado en esa VM, usa el comando gcloud compute instance-groups managed create-instance con la marca --stateful-metadata.

gcloud compute instance-groups managed create-instance NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...]

Reemplaza lo siguiente:

NAME: Es el nombre del MIG en el que se creará una instancia.
INSTANCE_NAME: Es el nombre de la instancia que se creará.
KEY y VALUE: Son los pares clave-valor de metadatos con estado que deben establecerse de forma individual para las instancias, además de los metadatos definidos en la plantilla de instancia.
- Los valores de clave que establezcas aquí tendrán prioridad sobre los valores de clave en conflicto de la plantilla de instancia.

Ejemplo

Debes implementar un clúster de nodos, example-cluster, que pueda operar en uno de estos dos modos: active o standby. Debes establecer el modo de forma individual para cada VM en un clúster mediante el uso de metadatos, por ejemplo: mode:active. También puedes configurar qué tan detallado es el registro para cada nodo, mediante una clave de metadatos logging que se puede configurar como basic o elaborate. La aplicación en el nodo se configura mediante los valores de los metadatos de la instancia.

Para crear un nodo activo, node-12, con un registro detallado, ejecuta el siguiente comando:

gcloud compute instance-groups managed create-instance example-cluster \
  --instance node-12 \
  --stateful-metadata mode=active,logging=elaborate

El comando crea una VM, node-12, en el MIG example-cluster y establece dos pares clave-valor de metadatos, mode:active y logging:elaborate, para la instancia nueva.

Terraform

Para crear una instancia administrada con un nombre personalizado y establecer metadatos con estado en esa VM, usa el recurso google_compute_per_instance_config .

En el siguiente ejemplo, se usa un MIG zonal. Si aún no tienes un MIG zonal, crea un MIG zonal con VMs limitadas a una sola zona.

resource "google_compute_per_instance_config" "default" {
  instance_group_manager = google_compute_instance_group_manager.default.name
  zone                   = google_compute_instance_group_manager.default.zone
  name                   = "node-12"
  preserved_state {
    metadata = {
      mode    = "active"
      logging = "elaborate"
    }
  }
}

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.

REST

Para crear una o varias instancias administradas en un MIG con nombres de VM personalizados y establecer metadatos con estado de forma individual en estas VM, usa el método instanceGroupManagers.createInstances. Para un MIG regional, usa el método regionInstanceGroupManagers.createInstances.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/createInstances
{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY" : "VALUE",
          ...
        }
      }
    },
    ...
  ]
}

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del proyecto de la solicitud.
ZONE: Es la zona en la que se encuentra el MIG (se aplica a un MIG zonal).
- En el caso de un MIG regional, reemplaza zones/ZONE por regions/REGION y especifica la región del MIG.
NAME: Es el nombre del MIG en el que se creará una instancia.
INSTANCE_NAME: Es el nombre de la instancia que se creará.
KEY y VALUE: Son los pares clave-valor de metadatos con estado que deben establecerse de forma individual para las instancias, además de los metadatos definidos en la plantilla de instancia.
- Los valores de clave que establezcas aquí tendrán prioridad sobre los valores de clave en conflicto de la plantilla de instancia.

Ejemplo

Para crear un nodo activo, node-12, con registros detallados, ejecuta el siguiente método:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/createInstances

{
  "instance": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode":"active",
          "logging":"elaborate"
        }
      }
    }
  ]
}

El método crea una VM, node-12, en el MIG example-cluster y establece dos pares clave-valor de metadatos, mode:active y logging:elaborate, para la instancia nueva.

Configura, modifica y quita metadatos con estado de forma individual en las instancias de VM existentes

Puedes configurar, modificar o quitar metadatos con estado de una instancia existente en un MIG si estableces estos ajustes en una configuración por instancia asociada y, luego, aplicas la configuración mediante la actualización de la instancia.

gcloud

A fin de configurar los metadatos con estado de forma individual para una instancia de VM en un MIG, establece o quita los metadatos con estado en la configuración por instancia asociada. Si aplicas la configuración a la instancia al mismo tiempo (--update-instance), puedes optar entre mantener la instancia en ejecución, reiniciarla o volver a crearla. Si no aplicas la configuración (--no-update-instance), los cambios no se aplicarán hasta que actualices o vuelvas a crear la instancia.

Si no existe una configuración por instancia para una instancia determinada, usa el comando gcloud compute instance-groups managed instance-configs create con una de las siguientes marcas:

gcloud compute instance-groups managed instance-configs create NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

Si ya existe una configuración por instancia para una instancia determinada, usa el comando gcloud compute instance-groups managed instance-configs update con lo siguiente:

La marca --stateful-metadata para configurar o modificar los metadatos
La marca --remove-stateful-metadata para quitar los metadatos con estado específicos de la instancia

gcloud compute instance-groups managed instance-configs update NAME \
  --instance INSTANCE_NAME \
  [--stateful-metadata KEY=VALUE[,KEY=VALUE,...]] \
  [--remove-stateful-metadata KEY[,KEY,...]] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

Reemplaza lo siguiente:

NAME: Es el nombre del grupo de instancias administrado.
INSTANCE_NAME: Es el nombre de la instancia para la que se configurarán los metadatos con estado.
KEY=VALUE: Son los pares clave-valor de metadatos con estado que se establecerán de forma individual en la instancia, además de los metadatos definidos en la plantilla de instancia. Los valores de clave que estableces aquí tienen prioridad sobre cualquier valor de clave en conflicto de la plantilla de instancia.
KEY: Son las claves de metadatos con estado específicos de la instancia que se quitarán de la configuración por instancia.
- Si en la plantilla de instancia no se define un valor para la clave, el par clave-valor se quita por completo de la instancia cuando se aplica el cambio.
- Si la plantilla de instancia define un valor para la clave, el valor de la plantilla de instancia se establece en la instancia cuando se aplica el cambio.
MINIMAL_ACTION: Realiza al menos la acción especificada cuando se aplique la actualización de la configuración por instancia a la instancia. El valor MINIMAL_ACTION solo se puede configurar cuando se usa la marca --update-instance. El valor debe ser uno de los siguientes:
- none: Ninguna acción
- refresh: Aplicar actualizaciones que no requieren que se detenga la instancia
- restart: Detener la instancia y volver a iniciarla
- replace: Volver a crear la instancia
Si se omite, se usa la acción menos perjudicial que requiere la actualización.

Ejemplo

Tienes un clúster de nodos, example-cluster, que puede funcionar en uno de estos dos modos: active o standby. Puedes configurar el modo de forma individual para cada VM en el clúster mediante el uso de metadatos, por ejemplo: mode:active. También puedes configurar qué tan detallado debe ser el registro para cada nodo, mediante una clave de metadatos logging que se puede establecer en basic o elaborate. La aplicación en cada nodo consume los valores de los metadatos de la instancia.

La plantilla de instancia define los metadatos mode:active y logging:basic para que se usen de forma predeterminada en todas las instancias. Estableciste logging:elaborate en una configuración por instancia para la VM node-12 en el clúster. Ahora, quieres cambiar node-12 al modo de espera y cambiar el registro a basic para esta VM.

Para cambiar la instancia node-12 a modo de espera y su registro a básico, ejecuta el siguiente comando:

gcloud compute instance-groups managed instance-configs update example-cluster \
  --instance node-12 \
  --stateful-metadata mode=standby \
  --remove-stateful-metadata logging

El comando realiza lo siguiente:

Configura los metadatos mode:standby en la configuración por instancia asociada con la VM, node-12, en el MIG example-cluster.
Quita los metadatos logging:elaborate de la configuración por instancia correspondiente a la instancia node-12.
Aplica el cambio de configuración por instancia a la VM de node-12:
- Establece metadatos mode:standby, según la configuración.
- Configura los metadatos logging:basic de la plantilla de instancia, porque la configuración por instancia ya no define el valor de la clave logging.
El cambio se aplica a la VM de forma predeterminada y de inmediato, porque se omite la marca --no-update-instance.
La VM continúa ejecutándose durante la actualización, ya que se omite la marca --instance-update-minimal-action y se elige la acción menos perjudicial de forma predeterminada, que en este caso es refresh.

REST

Con el objetivo de configurar los metadatos con estado de manera individual en las instancias de VM existentes en un MIG, establece o quita los metadatos en los parámetros de configuración por instancia asociada. Luego, actualiza la instancia para aplicar la configuración.

Si aún no existe un parámetro de configuración por instancia para las instancias determinadas, usa el método instanceGroupManagers.updatePerInstanceConfigs con metadatos con estado:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/updatePerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

Si ya existen parámetros de configuración por instancia para las instancias dadas, usa el método instanceGroupManagers.patchPerInstanceConfigs

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto para la solicitud.
ZONE: La zona en la que se encuentra el MIG (se aplica a un MIG zonal).
- Para un MIG regional, reemplaza zones/ZONE por regions/REGION y especifica la región del MIG.
NAME: Es el nombre del MIG.
INSTANCE_NAME: Es el nombre de la VM para la que se configurarán los metadatos con estado.
KEY y VALUE: Son los pares clave-valor de metadatos con estado que se establecerán de forma individual para las instancias, además de los metadatos definidos en la plantilla de instancia.
- Los valores de metadatos con estado definidos para las claves que ya existen en la plantilla de instancia anulan los valores de la plantilla de instancia.
- Las demás entradas de metadatos de la plantilla de instancia no se ven afectadas ni están disponibles.
- Si se proporciona null como valor, se quita la clave de la configuración por instancia.
FINGERPRINT: La huella digital de la configuración determinada si ya existe (opcional). Se usa para el bloqueo optimista.

Los métodos updatePerInstanceConfigs y patchPerInstanceConfigs actualizan los parámetros de configuración especificada por instancia, pero no aplican las actualizaciones de configuración a las instancias de VM asociadas. Los cambios se aplican a una VM cuando actualizas o vuelves a crear la instancia. Para aplicar los cambios a una VM, puedes aplicar la actualización de forma manual o usar el actualizador en modo oportunista o proactivo.

Ejemplo

Para cambiar la VM node-12 a modo de espera y su registro a básico, aplica un parche a la configuración por instancia asociada mediante el método patchPerInstanceConfigs:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode": "standby",
          "logging": null
        }
      }
    }
  ]
}

El método hace lo siguiente:

Configura los metadatos mode:standby en la configuración por instancia asociada con la VM, node-12, en el MIG example-cluster.
Quita los metadatos logging:elaborate de la configuración por instancia porque el valor proporcionado es null.

La actualización de la configuración aún no se aplicó a la instancia de VM node-12. La actualización de la configuración se aplicará la próxima vez que vuelvas a crear o actualizar la instancia, o si usas una actualización automática proactiva.

Para aplicar la actualización de la configuración por instancia a la instancia de VM node-12, llama alinstanceGroupManagers.applyUpdatesToInstances método de la instancia:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/applyUpdatesToInstances

{
  "instances": ["/zones/us-east1-c/instances/node-12"],
  "minimalAction": "NONE"
}

El método aplica la configuración por instancia actualizada a la VM node-12:

Configura los metadatos mode:standby, según la configuración por instancia.
Configura los metadatos logging:basic de la plantilla de instancia, porque la configuración por instancia ya no define el valor de la clave logging.
La VM se sigue ejecutando durante la actualización porque minimalAction está establecido en NONE, lo que permite que el MIG use la acción menos perjudicial necesaria para la actualización. Una actualización de metadatos de instancia requiere la acción REFRESH, que no interrumpe una instancia en ejecución.

Comentarios

Queremos conocer tus casos de uso, desafíos y comentarios sobre los MIG con estado. Comparte tus comentarios con nuestro equipo en mig-discuss@google.com.

¿Qué sigue?

Para obtener más información, consulta Almacena y recupera metadatos de instancia.
Configura discos persistentes con estado para VM en un MIG.
Obtén más información sobre cómo aplicar, visualizar y quitar la configuración con estado.
Obtén más información sobre los MIG y cómo trabajar con instancias administradas.