This document explains how to use automatic termination to limit the runtime of new or existing virtual machine (VM) instances and how to subsequently monitor the runtime of those VMs.
You can optimize temporary workloads by automatically limiting VM runtimes, which helps minimize costs and free up quota. Automatic termination lets you schedule a VM to be terminated (stopped or deleted) when it reaches a specific time limit (duration or time).
To learn more about stopping a VM, see Stop and start a VM. To learn more about deleting a VM, see Delete a VM.
Alternatively, to schedule VM runtimes for recurring workloads, see Schedule a VM to start and stop instead.
Before you begin
-
To get the permissions that you need to automatic termination, ask your administrator to grant you the Compute Instance Admin (v1) (
roles/compute.instanceAdmin.v1
) IAM role on the project. For more information about granting roles, see Manage access.You might also be able to get the required permissions through custom roles or other predefined roles.
-
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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
-
Restrictions
Automatic termination has the following restrictions:
Automatic termination is automatically cleared any time that the VM is stopped or suspended. This restriction is intended to prevent accidental termination of a VM that has either finished running or been interrupted, then started again without being updated.
Automatic termination has a minimum time limit of 30 seconds and a maximum time limit of 120 days.
Automatic termination might take up to 30 seconds longer than the duration or time you specify to begin stopping or deleting the VM.
You cannot use automatic termination with legacy preemptible VMs. Instead, use automatic termination with Spot VMs.
If you want to schedule a VM to be stopped regardless of interruptions or for a larger maximum time limit, use instance schedules instead.
Limit the runtime of a new VM
The following sections describe how to configure automatic termination while creating a new VM.
Specify when you want the VM to be terminated by setting the time limit as either a duration or time.
Set a duration
A duration represents the total desired runtime for a VM. To create a VM that is automatically terminated after the VM runs for a specific duration, use the Google Cloud console, Google Cloud CLI, or Compute Engine API.
Console
In the Google Cloud console, go to the Create an instance page.
In the Availability policies section, expand VM provisioning model advanced settings.
To enable automatic termination, select the Set a time limit for the VM checkbox. The Time limit type field appears.
In the Time limit type field, select By hours (default) to specify the time limit as a duration. In the following field, enter the duration in hours.
In the On VM termination list, select what happens when the runtime of the VM reaches the specified time limit:
- To automatically stop the VM, select Stop (default).
- To delete the VM, select Delete.
Optional: Specify other VM options. For more information, see Creating and starting a VM instance.
To create and start the VM, click Create.
gcloud
To create a VM from the gcloud CLI, use the
gcloud beta compute instances create
command.
To create a VM that is automatically terminated after a specific duration,
you must include the --max-run-duration
flag. To specify the
termination action, include the --instance-termination-action
flag, which is optional for Spot VMs.
gcloud beta compute instances create VM_NAME \ --max-run-duration=DURATION \ --instance-termination-action=TERMINATION_ACTION
Replace the following:
VM_NAME
: The name of the new VM.DURATION
: The duration you want this VM to run before being automatically terminated. Format the duration as the number of days, hours, minutes, and seconds followed byd
,h
,m
, ands
respectively. For example, specify30m
for a duration of 30 minutes, or specify1d2h3m4s
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
).TERMINATION_ACTION
: The termination action for this VM, which can be either stop (STOP
) or delete (DELETE
). Whether this field is required or has a default value varies based on the VM's provisioning model:- If this is a Spot VM (if the VM uses the
--provisioning-model=SPOT
flag), the--instance-termination-action=TERMINATION_ACTION
flag is optional. If this flag is omitted, the default termination action is stop. - Otherwise (default), the
--instance-termination-action=TERMINATION_ACTION
flag is required.
- If this is a Spot VM (if the VM uses the
For more information about other options you can specify when creating a VM, see Creating and starting a VM instance.
REST
To create a VM from the Compute Engine API, use the
beta instances.insert
method.
You must specify a name, machine type, and boot disk for the VM.
To create a VM that is automatically terminated after a specific duration,
you must include the maxRunDuration
field. To specify the
termination action, include the instanceTerminationAction
field, which is optional for Spot VMs.
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID
/zones/ZONE
/instances { "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE", "name": "VM_NAME
", "disks": [ { "initializeParams": { "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE" }, "boot": true } ] "scheduling": { "maxRunDuration": { "seconds": DURATION }, "instanceTerminationAction": "TERMINATION_ACTION" }, }
Replace the following:
PROJECT_ID
: The project id of the project to create the VM in.ZONE
: The zone to create the VM in. The zone must also support the machine type to use for the new VM.MACHINE_TYPE
: The predefined or custom machine type for the new VM.VM_NAME
: The name of the new VM.IMAGE_PROJECT
: The project containing the image. For example, if you specifyfamily/debian-10
as the image, specifydebian-cloud
as the image project.IMAGE
: The image for the new VM. You can specify either a specific version of a public image or an image family. For example, if you specifyfamily/debian-10
as the image anddebian-cloud
as the image project, Compute Engine creates a VM from the latest version of the OS image in the Debian 10 image family.DURATION
: The duration in seconds that you want this VM to run before being automatically terminated. The minimum duration is 30 seconds (30s
) and the maximum duration is 120 days (120d
).TERMINATION_ACTION
: The termination action for this VM, which can be either stop (STOP
) or delete (DELETE
). Whether this field is required or has a default value varies based on the VM's provisioning model:- If this is a Spot VM (if the VM uses the
"provisioningModel": "SPOT"
field), the"instanceTerminationAction": "TERMINATION_ACTION"
field is optional. If this field is omitted, the default termination action is stop. - Otherwise (default), the
"instanceTerminationAction": "TERMINATION_ACTION"
field is required.
- If this is a Spot VM (if the VM uses the
For more information about the options you can specify when creating a VM, see Creating and starting a VM instance.
Set a time
A time represents the date, time, and timezone when you want a VM to be terminated. To create a VM that is automatically terminated at a specific time, use the Google Cloud console, Google Cloud CLI, or Compute Engine API.
Console
In the Google Cloud console, go to the Create an instance page.
In the Availability policies section, expand VM provisioning model advanced settings.
To enable automatic termination, select the Set a time limit for the VM checkbox. The Time limit type field appears.
In the Time limit type field, select By date to specify the time limit as a time and date. In the following field, click
Select date and time and select the date, time, and timezone for automatic termination.In the On VM termination list, select what happens when the runtime of the VM reaches the specified time limit:
- To automatically stop the VM, select Stop (default).
- To delete the VM, select Delete.
Optional: Specify other VM options. For more information, see Creating and starting a VM instance.
To create and start the VM, click Create.
gcloud
To create a VM from the gcloud CLI, use the
gcloud beta compute instances create
command.
To create a VM that is automatically terminated at a specific time,
you must include the --termination-time
flag. To specify the
termination action, include the --instance-termination-action
flag, which is optional for Spot VMs.
gcloud beta compute instances create VM_NAME \ --termination-time=TIME \ --instance-termination-action=TERMINATION_ACTION
Replace the following:
VM_NAME
: The name of the new VM.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), specifyZ
.
TERMINATION_ACTION
: The termination action for this VM, which can be either stop (STOP
) or delete (DELETE
). Whether this field is required or has a default value varies based on the VM's provisioning model:- If this is a Spot VM (if the VM uses the
--provisioning-model=SPOT
flag), the--instance-termination-action=TERMINATION_ACTION
flag is optional. If this flag is omitted, the default termination action is stop. - Otherwise (default), the
--instance-termination-action=TERMINATION_ACTION
flag is required.
- If this is a Spot VM (if the VM uses the
For more information about other options you can specify when creating a VM, see Creating and starting a VM instance.
REST
To create a VM from the Compute Engine API, use the
beta instances.insert
method.
You must specify a name, machine type, and boot disk for the VM.
To create a VM that is automatically terminated at a specific time,
you must include the terminationTime
field. To specify the
termination action, include the instanceTerminationAction
field, which is optional for Spot VMs.
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID
/zones/ZONE
/instances { "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE", "name": "VM_NAME
", "disks": [ { "initializeParams": { "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE" }, "boot": true } ] "scheduling": { "terminationTime": "TIME", "instanceTerminationAction": "TERMINATION_ACTION" }, }
Replace the following:
PROJECT_ID
: The project id of the project to create the VM in.ZONE
: The zone to create the VM in. The zone must also support the machine type to use for the new VM.MACHINE_TYPE
: The predefined or custom machine type for the new VM.VM_NAME
: The name of the new VM.IMAGE_PROJECT
: The project containing the image. For example, if you specifyfamily/debian-10
as the image, specifydebian-cloud
as the image project.IMAGE
: The image for the new VM. You can specify either a specific version of a public image or an image family. For example, if you specifyfamily/debian-10
as the image anddebian-cloud
as the image project, Compute Engine creates a VM from the latest version of the OS image in the Debian 10 image family.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), specifyZ
.
TERMINATION_ACTION
: The termination action for this VM, which can be either stop (STOP
) or delete (DELETE
). Whether this field is required or has a default value varies based on the VM's provisioning model::- If this is a Spot VM (if the VM uses the
"provisioningModel": "SPOT"
field), the"instanceTerminationAction": "TERMINATION_ACTION"
field is optional. If this field is omitted, the default termination action is stop. - Otherwise (default), the
"instanceTerminationAction": "TERMINATION_ACTION"
field is required.
- If this is a Spot VM (if the VM uses the
For more information about the options you can specify when creating a VM, see Creating and starting a VM instance.
Limit the runtime of an existing VM
You can limit the runtime of an existing VM by updating the VM's schedule. If you do not already understand how to configure settings for automatic termination, consider reviewing the previous sections about how to limit the runtime of a new VM first.
You can use the Google Cloud console, Google Cloud CLI, or Compute Engine API to update the VM's schedule, as described in this section; but this method requires that you first stop your VM, then set its schedule, then restart it. Alternatively, if you want to update multiple VM properties at once and automatically stop and restart a VM while setting its properties, see Update instance properties instead.
Console
In the Google Cloud console, go to the VM instances page.
In the Name column, click the name of the VM that you want to update.
From the VM instance details page, complete the following steps:
- If the VM is running, click Stop to stop the VM.
- To edit the VM, click Edit.
On the Edit instance page, complete the following steps:
In the Availability policies section, modify the Set a time limit for the VM checkbox and any fields below it as desired.
For more information about how to configure the properties for automatic termination, see limit the runtime of a new VM.
To save your changes, click Save.
Optional: If you want to start running the VM now, click Start.
gcloud
To update a VM's schedule for automatic termination by using the gcloud CLI, complete the following steps:
If the VM is running, stop the VM by using the
gcloud compute instances stop
command:gcloud compute instances stop VM_NAME
Replace
VM_NAME
with the name of VM that you want to update.Update the VM's settings for automatic termination by using the
gcloud beta compute instances set-scheduling
command. You must include either the--max-run-duration
flag or the--termination-time
flag to set the time limit as either a duration or time, respectively:To set a duration, use the following command:
gcloud beta compute instances set-scheduling VM_NAME \ --max-run-duration=DURATION \ --instance-termination-action=TERMINATION_ACTION
To set a time, use the following command:
gcloud beta compute instances set-scheduling VM_NAME \ --termination-time=TIME \ --instance-termination-action=TERMINATION_ACTION
Replace the following:
VM_NAME
: The name of the VM that you want to update.DURATION
: The duration you want this VM to run before being automatically terminated. Format the duration as the number of days, hours, minutes, and seconds followed byd
,h
,m
, ands
respectively. For example, specify30m
for a duration of 30 minutes, or specify1d2h3m4s
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
).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), specifyZ
.
TERMINATION_ACTION
: The termination action for this VM, which can be either stop (STOP
) or delete (DELETE
). Whether this field is required or has a default value varies based on the VM's provisioning model:- If this is a Spot VM (if the VM uses the
--provisioning-model=SPOT
flag), the--instance-termination-action=TERMINATION_ACTION
flag is optional. If this flag is omitted, the default termination action is stop. - Otherwise (default), the
--instance-termination-action=TERMINATION_ACTION
flag is required.
- If this is a Spot VM (if the VM uses the
If you want the VM to start running, start the VM by using the
gcloud compute instances start
command:gcloud compute instances start VM_NAME
Replace
VM_NAME
with the name of the VM.
REST
To update a VM's schedule for automatic termination by using the Compute Engine API, complete the following steps:
If the VM is running, stop the VM by using the
instances.stop
method:POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/stop
Replace the following:
PROJECT_ID
: The project id of the project that contains the VM.ZONE
: The zone that contains the VM.VM_NAME
: The name of the VM that you want to update.
Update the VM's
scheduling
property, including fields for automatic termination by using the betainstances.setScheduling
method. Include either themaxRunDuration
field or theterminationTime
field to set the time limit as either a duration or time, respectively:To set a duration, use the following request:
POST https://compute.googleapis.com/compute/beta/projects/
PROJECT_ID
/zones/ZONE
/instances/VM_NAME/setScheduling { "maxRunDuration": { "seconds": DURATION }, "instanceTerminationAction": "TERMINATION_ACTION" }To set a time, use the following request:
POST https://compute.googleapis.com/compute/beta/projects/
PROJECT_ID
/zones/ZONE
/instances/VM_NAME/setScheduling { "terminationTime": "TIME", "instanceTerminationAction": "TERMINATION_ACTION" }
Replace the following:
PROJECT_ID
: The project id of the project to create the VM in.ZONE
: The zone to create the VM in. The zone must also support the machine type to use for the new VM.MACHINE_TYPE
: The predefined or custom machine type for the new VM.VM_NAME
: The name of the new VM.IMAGE_PROJECT
: The project containing the image. For example, if you specifyfamily/debian-10
as the image, specifydebian-cloud
as the image project.IMAGE
: The image for the new VM. You can specify either a specific version of a public image or an image family. For example, if you specifyfamily/debian-10
as the image anddebian-cloud
as the image project, Compute Engine creates a VM from the latest version of the OS image in the Debian 10 image family.DURATION
: The duration in seconds that you want this VM to run before being automatically terminated. The minimum duration is 30 seconds (30s
) and the maximum duration is 120 days (120d
).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), specifyZ
.
TERMINATION_ACTION
: The termination action for this VM, which can be either stop (STOP
) or delete (DELETE
). Whether this field is required or has a default value varies based on the VM's provisioning model:- If this is a Spot VM (if the VM uses the
"provisioningModel": "SPOT"
field), the"instanceTerminationAction": "TERMINATION_ACTION"
field is optional. If this field is omitted, the default termination action is stop. - Otherwise (default), the
"instanceTerminationAction": "TERMINATION_ACTION"
field is required.
- If this is a Spot VM (if the VM uses the
If you want the VM to start running, start the VM by using the
instances.start
method:POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/start
Replace the following:
PROJECT_ID
: the project id of the project that contains the VM.ZONE
: the zone that contains the VM.VM_NAME
: the name of the VM.
Monitor the runtime of a VM
To monitor a VM's runtime—for example, to see if a VM was interrupted before it is scheduled for automatic termination—view VM operations. To identify VM operations that are caused by automatic termination, look for the following operation types:
compute.instances.deferredStop
for a termination action of stopcompute.instances.deferredDelete
for a termination action of delete
What's next
- Learn how to further optimize VMs:
- If your workloads are fault-tolerant, you can use Spot VMs to get significant discounts and optional dedicated quota.
- Learn about other Compute Engine features for scheduling VMs: