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

• Create an instance template, which is required in order to create a managed instance group.
• If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.
  

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

  Terraform

  To use the Terraform samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. Create local authentication credentials for your Google Account:

     gcloud auth application-default login

  For more information, see Set up authentication for a local development environment.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

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 Google Cloud console , the gcloud CLI, Terraform, or REST.

Pro Tip: Consider storing data on an additional persistent disk and keeping the boot disk, containing the application, stateless. Such a configuration makes your application resilient to boot disk file system corruption. This configuration also simplifies VM updates because the MIG can recreate boot disks based on the immutable source image that you specify in the MIG's instance template.

Permissions required for this task

To perform this task, you must have the following permissions:

• All permissions required to call theinstanceGroupManagers.insert method (for zonal MIGs)
• All permissions required to call theregionInstanceGroupManagers.insert method (for regional MIGs)

Console

1. Go to the Instance groups page.

   Go to Instance groups

   The remaining steps will appear automatically in the Google 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 \
    --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: The name of the instance template to use when creating instances. For a regional instance template, you must specify the full or partial URL of the template. An example of a full URL is https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/instanceTemplates/example-regional-instance-template and a partial URL is projects/example-project/regions/us-central1/instanceTemplates/example-regional-instance-template.
• 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.

Note: You can see the device names of disks that are defined in an instance template by running the gcloud compute instance-templates describe command.

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": "global/instanceTemplates/TEMPLATE"
    }
  ],
  "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.
• TEMPLATE: The name of the instance template to use when creating instances.
• 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.

Note: You can see the device names of disks that are defined in an instance template by calling the instanceTemplates.get method and reading the instanceTemplates.disks[].deviceName field in the response.

What's next

• Learn more about stateful MIGs and when to use them.
• Learn more about configuring stateful disks in MIGs.
• Learn How stateful MIGs work.
• Learn more about configuring stateful MIGs for disks, metadata, and IP addresses.