Create a MIG with stateful disks

This document describes how to create a managed instance group (MIG) that preserves the data on disks with a given device name for all of the MIG's VMs, even in the event of VM recreation—for example when a VM in the MIG is autohealed, updated, or recreated. Preserving disks is useful for certain workloads—for example, for databases or legacy applications.

In addition to preserving disks for all VMs in the group, you can also configure a stateful MIG for the following:

  • You can add and preserve instance-specific disks.
  • You can add and preserve instance-specific metadata.
  • You can add and preserve IP addresses.

For more information, see the stateful MIG overview.

You can also read about other basic scenarios for creating a MIG.

Before you begin

Limitations

A MIG with stateful configuration—a stateful MIG—has the following limitations:

  • You cannot use autoscaling if your MIG has stateful configuration.
  • If you want to use automated rolling updates, you must set the replacement method to RECREATE.
  • For stateful regional MIGs, you must disable proactive redistribution (set the redistribution type to NONE) to prevent deletion of stateful instances by automatic cross-zone redistribution.
  • If you use an all-instances configuration to override instance template properties, you cannot specify those properties in any per-instance configuration and at the same time in the group's all-instances configuration.

To see the full list of MIG limitations, which varies based on the configuration that you use, see MIG limitations.

Create a MIG with stateful disks

Use the Trusted Cloud console, the gcloud CLI, Terraform, or REST.

Console

  1. Go to the Instance groups page.

    Go to Instance groups

    The remaining steps appear in the Trusted Cloud console.

  2. Click Create instance group.
  3. Select the New managed instance group (stateful) option.
  4. Assign a name and optionally a description to your instance group.
  5. Choose an instance template for the instance group or create a new one.
  6. In the Number of instances field, specify the initial number of VMs you need in this group.
  7. In the Stateful configuration section, under Group config, click the disk you want to make stateful, then perform the following steps.
    1. In the Stateful section, select Yes.
    2. In the On permanent instance deletion list, choose whether you want to detach the disk or delete the disk when you permanently delete the VM.
    3. To save the settings, click Done.
  8. To create the MIG, click Create.

gcloud

To specify which disks from the instance template should be stateful on MIG creation, use the --stateful-disk flag with the gcloud compute instance-groups managed create command:

gcloud compute instance-groups managed create INSTANCE_GROUP_NAME \
    --template INSTANCE_TEMPLATE_URL \
    --size SIZE \
    --stateful-disk device-name=DEVICE_NAME[,auto-delete=DELETE_RULE]

Replace the following:

  • INSTANCE_GROUP_NAME: The name of the managed instance group to create.
  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want to use to create VMs in the MIG. The URL can contain either the ID or name of the instance template. Specify one of the following values:
    • For a regional instance template: projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_ID
    • For a global instance template: INSTANCE_TEMPLATE_ID
  • SIZE: The initial number of VMs you need in this group.
  • DEVICE_NAME: The device name of a disk specified in the instance template.

  • DELETE_RULE: A value that prescribes what should happen to a stateful disk when a VM is deleted. Available options are:

    • never: (Default.) Never delete the disk; instead, detach the disk when its VM is deleted.
    • on-permanent-instance-deletion: Delete the disk when its VM instance is permanently deleted from the instance group, for example, when the managed instance is deleted manually or when the group size is decreased.

    Regardless of the value of the delete rule, stateful disks are always preserved on VM autohealing, update, and recreation operations.

Terraform

If you haven't already created an instance template, which specifies the machine type, boot disk image, network, and other VM properties that you want for each VM in your MIG, create an instance template.

To specify which disks from the instance template should be stateful on MIG creation, include the stateful_disk block. The following sample creates a zonal MIG with stateful disks. For more information about the resource that is used in the sample, see google_compute_instance_group_manager resource.

resource "google_compute_instance_group_manager" "default" {
  name               = "igm-stateful-disk-basic"
  zone               = "us-central1-f"
  base_instance_name = "instance"
  target_size        = 1

  version {
    instance_template = google_compute_instance_template.default.id
  }

  stateful_disk {
    device_name = "example-disk"
    delete_rule = "NEVER"
  }

}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

REST

To specify which disks from the instance template should be stateful on MIG creation, include them in the statefulPolicy field in your request body. For a zonal MIG, use the instanceGroupManagers.insert method or for a regional MIG, use the regionInstanceGroupManagers.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT/zones/ZONE/instanceGroupManagers

{
  "name": "NAME",
  "versions": [
    {
      "instanceTemplate": "INSTANCE_TEMPLATE_URL"
    }
  ],
  "targetSize": SIZE,
  "statefulPolicy": {
    "preservedState": {
      "disks": {
        "DEVICE_NAME": {"autoDelete": "DELETE_RULE" },
        "DEVICE_NAME": {"autoDelete": "DELETE_RULE" }
      }
    }
  }
}

Replace the following:

  • PROJECT: The project ID for the request.
  • ZONE: The zone where the MIG is located (applies to a zonal MIG).
    • For a regional MIG, replace zones/ZONE with regions/REGION and specify the region of the MIG.
  • NAME: The name of the MIG to create.
  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want to use to create VMs in the MIG. The URL can contain either the ID or name of the instance template. Specify one of the following values:
    • For a regional instance template: projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_ID
    • For a global instance template: INSTANCE_TEMPLATE_ID
  • SIZE: The initial number of instances you need in this group.
  • DEVICE_NAME: The device name of a disk specified in the instance template.

  • DELETE_RULE: A value that prescribes what should happen to the stateful disk when the VM instance is deleted. The available options are:

    • never: (Default.) Never delete the disk; detach the disk when the VM is deleted.
    • on_permanent_instance_deletion: Delete the stateful disk when its VM is permanently deleted from the instance group, for example, when the managed instance is deleted manually or when the group size is decreased.

    Regardless of the value of the delete rule, stateful disks are always preserved on instance autohealing, update, and recreation operations.

What's next