Limit the run time of VMs in a MIG

This document describes how to automatically terminate virtual machines (VMs) in a managed instance group (MIG) by specifying a time limit for the VMs. It also describes how time limit works for VMs in a MIG.

You can optimize temporary workloads by specifying a time limit for the VMs in a MIG. When a VM reaches its time limit, the MIG automatically terminates (deletes) that VM. Limiting the run time of VMs in a MIG by a time limit helps to minimize costs and free up quota.

To learn about specifying a time limit for a standalone VM, see Limit the run time of a VM. If you want a MIG to automatically add or delete VMs based on your workloads, see Autoscaling groups of instances.

Before you begin

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

Limit the run time of VMs in a MIG

You can limit the run time of VMs in a MIG by specifying a time limit in the instance template used for the MIG. When the MIG creates VMs based on the template, the time limit is applied to each VM.

You can specify one of two types of time limits:

Time limit as a run duration
Time limit as a termination time

To specify a time limit for the VMs in a MIG, follow these steps:

Create an instance template with a run duration for VMs or with a termination time for VMs.
Use the instance template to create a MIG or update an existing MIG.

Limitations

When you create an instance template to specify a time limit for VMs in a MIG, the following limitations apply:
- You can't set the termination action to STOP. MIGs support only DELETE.
- You can't use Spot VMs.
You can't create a resize request in a MIG that uses an instance template which limits VM run time.
You can't limit the run time of VMs in a regional MIG with EVEN target distribution shape and proactive instance redistribution enabled.

Create an instance template with a run duration for VMs

To automatically terminate VMs in a MIG after they run for a certain duration, set a maximum run duration (maxRunDuration) in the instance template.

Console

In the Google Cloud console, go to the Instance templates page.

Go to Instance templates
Click Create instance template.
Select the Location as follows:
- If you want to use the instance template across regions, choose Global.
- If you want to reduce cross-region dependency, choose Regional.
If you chose regional, then select the Region where you want to create your instance template.
In the Availability policies section, expand VM provisioning model advanced settings.
Select the Set a time limit for the VM checkbox.
In the Time limit type field, select By hours (default) to specify the time limit as a duration. In the next field, enter the duration in hours.
In the On VM termination list, select Delete.
For the other fields, either accept the default values or modify them as required.
Click Create.

gcloud

Use the beta instance-templates create command. To automatically delete VMs after a specific duration, include the --max-run-duration flag and set the--instance-termination-action flag to DELETE as follows:

  gcloud beta compute instance-templates create INSTANCE_TEMPLATE_NAME \
      --max-run-duration=DURATION \
      --instance-termination-action=DELETE

Replace the following:

INSTANCE_TEMPLATE_NAME: the name of the instance template.
DURATION: the duration you want the VMs to run. The MIG automatically deletes the VM after the specified duration.

Format the duration as the number of days, hours, minutes, and seconds followed by d, h, m, and s respectively. For example, specify 30m for a duration of 30 minutes, or specify 1d2h3m4s for a duration of 1 day, 2 hours, 3 minutes, and 4 seconds. The minimum duration is 30 seconds (30s) and the maximum duration is 120 days (120d).

REST

Use the beta instanceTemplates.insert method. To automatically delete VMs after a specific duration, include the maxRunDuration field and set theinstanceTerminationAction field to DELETE as follows:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/instanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "machineType": "MACHINE_TYPE",
    "networkInterfaces": [
      {
        "network": "global/networks/default",
        "accessConfigs": [
          {
            "name": "external-IP",
            "type": "ONE_TO_ONE_NAT"
          }
        ]
      }
    ],
    "disks": [
      {
        "type": "PERSISTENT",
        "boot": true,
        "mode": "READ_WRITE",
        "initializeParams":
        {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ]
    "scheduling": {
      "maxRunDuration":
      {
        "seconds": DURATION
      },
      "instanceTerminationAction": "DELETE"
    }
  }
}

Replace the following:

PROJECT_ID: the ID of the project in which you want to create the instance template.
INSTANCE_TEMPLATE_NAME: the name of the instance template.
MACHINE_TYPE: the predefined or custom machine type for the VMs in the group.
IMAGE_PROJECT: the image project that contains the image; for example, debian-cloud.
IMAGE or IMAGE_FAMILY: specify one of the following:
- IMAGE: a specific version of the OS image; for example, debian-10-buster-v20200309.
- IMAGE_FAMILY: an image family. This specifies the most recent, non-deprecated OS image. For example, if you specify debian-10, the latest version in the Debian 10 image family is used.
DURATION: the duration you want the VMs to run. The MIG automatically deletes the VM after the specified duration.

Format the duration as the number of days, hours, minutes, and seconds followed by d, h, m, and s respectively. For example, specify 30m for a duration of 30 minutes, or specify 1d2h3m4s for a duration of 1 day, 2 hours, 3 minutes, and 4 seconds. The minimum duration is 30 seconds (30s) and the maximum duration is 120 days (120d).

Create an instance template with a termination time for VMs

To automatically terminate VMs in a MIG at a specific time, set a termination time (terminationTime) in the instance template. You can set a date and time at which you want a MIG to terminate the VMs.

Console

In the Google Cloud console, go to the Instance templates page.

Go to Instance templates
Click Create instance template.
Select the Location as follows:
- If you want to use the instance template across regions, choose Global.
- If you want to reduce cross-region dependency, choose Regional.
If you chose regional, then select the Region where you want to create your instance template.
In the Availability policies section, expand VM provisioning model advanced settings.
In the Time limit type field, select By date to specify the time limit as a time and date. In the next field, click Select date and time and select the date, time, and timezone for automatic termination.
In the On VM termination list, select Delete.
For the other fields, either accept the default values or modify them as required.
Click Create.

gcloud

Use the beta instance-templates create command. To automatically delete VMs at a specific time, include the --termination-time flag and set the--instance-termination-action flag to DELETE as follows:

  gcloud beta compute instance-templates create INSTANCE_TEMPLATE_NAME \
      --termination-time=TIME \
      --instance-termination-action=DELETE

Replace the following:

INSTANCE_TEMPLATE_NAME: the name of the instance template.
TIME: the time you want this VM to be automatically terminated. The time you specify must be at least 30 seconds in the future and at most 120 days in the future. Format the time as a RFC 3339 timestamp:
```
YYYY-MM-DDTHH:MM:SSOFFSET
```
Replace the following:
- YYYY-MM-DD: A date formatted as a 4-digit year, 2-digit month, and 2-digit day of the month separated by hyphens.
- HH:MM:SS: A time formatted as a 2-digit hour using 24-hour time, 2-digit minute, and 2-digit second separated by colons.
- OFFSET: The time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use Pacific Standard Time (PST), which is 8 hours earlier than UTC, specify -08:00. Alternatively, to use no offset (UTC+0), specify Z.

REST

Use the beta instanceTemplates.insert method. To automatically delete VMs at a specific time, include the terminationTime field and set theinstanceTerminationAction field to DELETE as follows:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/instanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "machineType": "MACHINE_TYPE",
    "networkInterfaces": [
      {
        "network": "global/networks/default",
        "accessConfigs": [
          {
            "name": "external-IP",
            "type": "ONE_TO_ONE_NAT"
          }
        ]
      }
    ],
    "disks": [
      {
        "type": "PERSISTENT",
        "boot": true,
        "mode": "READ_WRITE",
        "initializeParams":
        {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ]
    "scheduling": {
      "terminationTime": TIME,
      "instanceTerminationAction": "DELETE"
    }
  }
}

Replace the following:

PROJECT_ID: the ID of the project in which you want to create the instance template.
INSTANCE_TEMPLATE_NAME: the name of the instance template.
MACHINE_TYPE: the predefined or custom machine type for the VMs in the group.
IMAGE_PROJECT: the image project that contains the image; for example, debian-cloud.
IMAGE or IMAGE_FAMILY: specify one of the following:
- IMAGE: a specific version of the OS image; for example, debian-10-buster-v20200309.
- IMAGE_FAMILY: an image family. This specifies the most recent, non-deprecated OS image. For example, if you specify debian-10, the latest version in the Debian 10 image family is used.
TIME: The time you want this VM to be automatically terminated. The time you specify must be at least 30 seconds in the future and at most 120 days in the future. Format the time as a RFC 3339 timestamp:
```
YYYY-MM-DDTHH:MM:SSOFFSET
```
Replace the following:
- YYYY-MM-DD: A date formatted as a 4-digit year, 2-digit month, and 2-digit day of the month separated by hyphens.
- HH:MM:SS: A time formatted as a 2-digit hour using 24-hour time, 2-digit minute, and 2-digit second separated by colons.
- OFFSET: The time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use Pacific Standard Time (PST), which is 8 hours earlier than UTC, specify -08:00. Alternatively, to use no offset (UTC+0), specify Z.

How time limit works for VMs in a MIG

When you specify a time limit for VMs in a MIG, the time at which a MIG will terminate a VM is automatically set in the termination timestamp (terminationTimestamp) field of the VM.

Based on the type of time limit that you specify, the termination timestamp of a VM is set as follows:

Time limit as a run duration (maxRunDuration):

terminationTimestamp of a VM = VM's latest creation or start time + maxRunDuration

When you specify a duration, the termination timestamp is set relative to the VM's latest creation or start time. If the VM is recreated, restarted, resumed, or replaced, then the termination timestamp is recalculated. The termination timestamp can vary across the VMs in a MIG based on the time that each VM was last created or started. For example, if a VM is repaired, the termination timestamp of the VM is recalculated by adding the duration to the time the VM was recreated during the repair.
Time limit as a termination time (terminationTime):

terminationTimestamp of a VM = terminationTime

When you specify a time, the termination timestamp is set to that time, provided the time is in the future. If the termination time has passed, any MIG action that attempts to create, restart, or replace a VM fails with an error. To resolve such an error, you must create a new instance template with a termination time in the future and apply that template to the MIG. If you want to use the existing template properties in the new template, then create an instance template based on the existing template.

During a VM refresh, the termination timestamp doesn't change. For example, if you set the disruption level for updates to REFRESH, then the termination timestamp is retained whenever the MIG updates the VM.

When you suspend or stop a VM in a MIG, the termination timestamp is automatically cleared irrespective of the type of time limit. When you resume or start a VM, the termination timestamp is set again based on the type of time limit as explained earlier in this section.

How autoscaling works when a time limit is set

Autoscaling lets your MIG automatically add or remove VMs based on increases or decreases in load. When a MIG deletes VMs that have reached their termination timestamps, the MIG creates new VMs to maintain the recommended size by the autoscaler. The new VMs run for the specified time limit. If the autoscaler recommendation is to reduce the number of VMs, then the MIG deletes VMs even before they reach their time limits.

If you've configured scaling schedules, the VMs run only until the end of a schedule or until a VM reaches its termination timestamp, whichever comes first.

What's next

Learn about the basic scenarios for creating MIGs.
Learn about applying a new instance template to an existing MIG.