Enable graceful shutdown in a Compute Engine instance

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This document explains how to enable graceful shutdown in a new or existingCompute Engine instance. To learn more about graceful shutdown, seeGraceful shutdown overview.

When you enable graceful shutdown in an instance, you can give its guest OS upto one hour to cleanly shut down when you stop or delete the instance. Thishelps prevent potential data loss or corrupt file systems.

Before you begin

Required roles

To get the permissions that you need to enable graceful shutdown in a compute instance, ask your administrator to grant you theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to enable graceful shutdown in a compute instance. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to enable graceful shutdown in a compute instance:

  • To create instances:
    • compute.instances.create on the project
    • To use a custom image to create the VM:compute.images.useReadOnly on the image
    • To use a snapshot to create the VM:compute.snapshots.useReadOnly on the snapshot
    • To use an instance template to create the VM:compute.instanceTemplates.useReadOnly on the instance template
    • To assign alegacy network to the VM:compute.networks.use on the project
    • To specify a static IP address for the VM:compute.addresses.use on the project
    • To assign an external IP address to the VM when using a legacy network:compute.networks.useExternalIp on the project
    • To specify a subnet for the VM:compute.subnetworks.use on the project or on the chosen subnet
    • To assign an external IP address to the VM when using a VPC network:compute.subnetworks.useExternalIp on the project or on the chosen subnet
    • To set VM instance metadata for the VM:compute.instances.setMetadata on the project
    • To set tags for the VM:compute.instances.setTags on the VM
    • To set labels for the VM:compute.instances.setLabels on the VM
    • To set a service account for the VM to use:compute.instances.setServiceAccount on the VM
    • To create a new disk for the VM:compute.disks.create on the project
    • To attach an existing disk in read-only or read-write mode:compute.disks.use on the disk
    • To attach an existing disk in read-only mode:compute.disks.useReadOnly on the disk
  • To create an instance template:compute.instanceTemplates.create on the project
  • To enable graceful shutdown in an existing instance:compute.instances.update on the instance

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Enable graceful shutdown

To enable graceful shutdown in a compute instance, use one of the followingmethods:

Enable graceful shutdown in an existing instance

You can enable graceful shutdown in an existing compute instance withoutstopping or restarting it. The default graceful shutdown period is 10 minutes,but you can specify a custom shutdown period between one second and one hour.

To enable graceful shutdown in an existing instance, select one of the followingoptions:

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. In theName column, click the name of the instance in which you wantto enable graceful shutdown.

    The details page of the instance opens.

  3. ClickEdit.

  4. In theManagement section, do the following:

    1. Select theGracefully shut down the VM checkbox.

    2. Optional: To specify a custom graceful shutdown period, specify aduration in theMaximum duration field.

  5. ClickSave.

gcloud

To enable graceful shutdown in an existing instance, use thegcloud beta compute instances update commandwith the--graceful-shutdown flag:

gcloud beta compute instances updateINSTANCE_NAME \    --graceful-shutdown \    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the instance.

  • ZONE: the zone where the instance is located.

Optionally, to specify a custom graceful shutdown period, include the--graceful-shutdown-max-duration flag:

gcloud beta compute instances updateINSTANCE_NAME \    --graceful-shutdown \--graceful-shutdown-max-duration=MAX_DURATION \    --zone=ZONE

ReplaceMAX_DURATION with a duration for the shutdownperiod. The value must be formatted as the number of hours, minutes, orseconds followed byh,m, ands respectively. For example, specify1h for one hour, or20m10s for 20 minutes and 10 seconds.

REST

  1. Create an empty JSON file.

  2. To view the properties of an existing instance, make aGET request tothebetainstances.get method:

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    Replace the following:

    • PROJECT_ID: the ID of the project where theinstance is located.

    • ZONE: the zone where the instance is located.

    • INSTANCE_NAME: the name of an existing instance.

  3. In the empty JSON file that you created in the previous steps, do thefollowing:

    1. Enter the instance configuration details from theGET requestoutput.

    2. In thescheduling field, add thegracefulShutdown field asfollows:

      {  ...  "scheduling": {    ...    "gracefulShutdown": {      "enabled": true    }  },  ...}

      Optionally, to specify a custom graceful shutdown period, includethemaxDuration field:

      {  ...  "scheduling": {    ...    "gracefulShutdown": {      ...      "enabled": true,"maxDuration": {        "seconds": "MAX_DURATION"      }    }  },  ...}

      ReplaceMAX_DURATION with a duration in secondsfor the graceful shutdown period. The value must be between1 and3600, which is 3,600 seconds (one hour).

  4. To update the instance and restart it, make aPUT request to thebetainstances.update method.In the request, do the following:

    • In the request URL, include themostDisruptiveAllowedAction queryparameter set toRESTART.

    • In the request body, include the instance properties from the JSONfile that you created and updated in the previous steps.

    ThePUT request to update the instance is similar to the following:

    PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?mostDisruptiveAllowedAction=RESTART{  ...  "scheduling": {    ...    "gracefulShutdown": {      "enabled": true    }  },  ...}

For more information about updating the properties of an instance, seeUpdate instance properties.

Enable graceful shutdown while creating an instance

When you create a compute instance that has graceful shutdown enabled, thedefault shutdown period is 10 minutes. Optionally, you can specify a customshutdown period between one second and one hour.

To create an instance that has graceful shutdown enabled, select one of thefollowing options:

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. ClickCreate instance.

    TheCreate an instance page opens.

  3. Specify aName for the instance.

  4. Specify theRegion andZone in which to create the instance.

  5. Specify a machine type for the instance.

  6. In the navigation menu, clickAdvanced.

  7. Expand theVM provisioning model advanced settings section, and then do thefollowing:

    1. Select theGracefully shut down the VM checkbox.

    2. Optional: To specify a custom graceful shutdown period, specify aduration in theMaximum duration field.

  8. ClickCreate.

gcloud

To create an instance that has graceful shutdown enabled, use thegcloud beta compute instances create commandwith the--graceful-shutdown flag:

gcloud beta compute instances createINSTANCE_NAME \    --graceful-shutdown \    --machine-type=MACHINE_TYPE \    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the instance.

  • MACHINE_TYPE: the machine type to use for theinstance.

  • ZONE: the zone in which to create the instance.

Optionally, to specify a custom graceful shutdown period, include the--graceful-shutdown-max-duration flag:

gcloud beta compute instances createINSTANCE_NAME \    --graceful-shutdown \--graceful-shutdown-max-duration=MAX_DURATION \    --machine-type=MACHINE_TYPE \    --zone=ZONE

ReplaceMAX_DURATION with a duration for the gracefulshutdown period. The value must be formatted as the number of hours,minutes, or seconds followed byh,m, ands respectively. For example,specify1h for one hour, or20m10s for 20 minutes and 10 seconds.

REST

To create an instance that has graceful shutdown enabled, make aPOSTrequest to thebeta.instances.insert method.In the request body, include thegracefulShutdown field:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances{  "name": "INSTANCE_NAME",  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"      }    }  ],  "networkInterfaces": [    {      "network": "global/networks/default"    }  ],  "scheduling": {    "gracefulShutdown": {      "enabled": true    }  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createthe instance.

  • ZONE: the zone in which to create the instance.

  • INSTANCE_NAME: the name of the instance.

  • MACHINE_TYPE: the machine type for the instance.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This formattingspecifies the most recent, non-deprecated OS image. For example, ifyou specifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

Optionally, to specify a custom graceful shutdown period, include themaxDuration field in the request body:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances{  "name": "INSTANCE_NAME",  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"      }    }  ],  "networkInterfaces": [    {      "network": "global/networks/default"    }  ],  "scheduling": {    "gracefulShutdown": {      "enabled": true,"maxDuration": {        "seconds": "MAX_DURATION"      }    }  }}

ReplaceMAX_DURATION with a duration in seconds for thegraceful shutdown period. The value must be between1 and3600, which is3,600 seconds (one hour).

For more configuration options when creating an instance, seeCreate and start a Compute Engine instance.

Enable graceful shutdown while creating instances in bulk

When you create compute instances in bulk that have graceful shutdown enabled,the default shutdown period is 10 minutes. Optionally, you can specify a customshutdown period between one second and one hour.

Important: You must wait for Compute Engine to finish creating allinstances before you can gracefully shut down or modify graceful shutdownsettings for these instances.

To create instances in bulk that have graceful shutdown enabled, select one ofthe following options:

gcloud

To create instances in bulk that have graceful shutdown enabled, use thegcloud beta compute instances bulk create commandwith the--graceful-shutdown flag.

For example, to create instances in bulk in a single zone and specify a namepattern for the instances, run the following command:

gcloud beta compute instances bulk create \    --count=COUNT \    --graceful-shutdown \    --machine-type=MACHINE_TYPE \    --name-pattern="NAME_PATTERN" \    --zone=ZONE

Replace the following:

  • COUNT: the number of instances to create.

  • MACHINE_TYPE: the machine type for the instances.

  • NAME_PATTERN: the name pattern for the instances. Toreplace a sequence of numbers in an instance name, use a sequence ofhash (#) characters. For example, usinginstance-# for the namepattern generates instances with names starting withinstance-1,instance-2, and continuing up to the number of instances specified byCOUNT.

  • ZONE: the zone in which to create instances in bulk.

Optionally, to specify a custom graceful shutdown period, include the--graceful-shutdown-max-duration flag:

gcloud beta compute instances bulk create \    --count=COUNT \    --graceful-shutdown \--graceful-shutdown-max-duration=MAX_DURATION \    --machine-type=MACHINE_TYPE \    --name-pattern="NAME_PATTERN" \    --zone=ZONE

ReplaceMAX_DURATION with a duration for the gracefulshutdown period. The value must be formatted as the number of hours,minutes, or seconds followed byh,m, ands respectively. For example,specify1h for one hour, or20m10s for 20 minutes and 10 seconds.

REST

To create instances in bulk that have graceful shutdown enabled, make aPOST request to thebetainstances.bulkInsert method.In the request body, include thegracefulShutdown field.

For example, to create instances in bulk in a single zone and specify a namepattern for the instances, make aPOST request as follows:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert{  "count":COUNT,  "namePattern": "NAME_PATTERN",  "instanceProperties": {    "machineType": "MACHINE_TYPE",    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "scheduling": {      "gracefulShutdown": {        "enabled": true      }    }  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createinstances in bulk.

  • ZONE: the zone in which to create instances in bulk.

  • COUNT: the number of instances to create.

  • NAME_PATTERN: the name pattern for the instances. Toreplace a sequence of numbers in an instance name, use a sequence ofhash (#) characters. For example, usinginstance-# for the namepattern generates instances with names starting withinstance-1,instance-2, and continuing up to the number of instances specified byCOUNT.

  • MACHINE_TYPE: the machine type for the instances.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This formattingspecifies the most recent, non-deprecated OS image. For example, ifyou specifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • ZONE: the zone in which to create instances in bulk.

Optionally, to specify a custom graceful shutdown period, include themaxDuration field in the request body:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert{  "count":COUNT,  "namePattern": "NAME_PATTERN",  "instanceProperties": {    "machineType": "MACHINE_TYPE",    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "scheduling": {      "gracefulShutdown": {        "enabled": true,"maxDuration": {          "seconds": "MAX_DURATION"        }      }    }  }}

ReplaceMAX_DURATION with a duration in seconds for thegraceful shutdown period. The value must be between1 and3600, which is3,600 seconds (one hour).

For more configuration options when creating instances in bulk, seeCreate VMs in bulk.

Enable graceful shutdown while creating an instance template

When you create an instance template that has graceful shutdown enabled, thedefault shutdown period is 10 minutes. Optionally, you can specify a customshutdown period between one second and one hour.

All compute instances created using the instance template have graceful shutdownenabled.

To create an instance template that has graceful shutdown enabled, select one ofthe following options:

Console

  1. In the Google Cloud console, go to theInstance templates page.

    Go to Instance templates

  2. ClickCreate instance template.

    TheCreate an instance template page opens.

  3. In theName field, enter a name for the instance template.

  4. Select theLocation as follows:

    • To reduce cross-region dependency by creating a regional instancetemplate, do the following:

      1. ChooseRegional, if it isn't already selected.

      2. In theRegion field, select the region in which to createthe instance template.

    • Otherwise, to use the instance template across regions, chooseGlobal.

  5. In theMachine configuration section, specify a machine type.

  6. Expand theVM provisioning model advanced settings section, and then do thefollowing:

    1. Select theGracefully shut down the VM checkbox.

    2. Optional: To specify a custom graceful shutdown period, specify aduration in theMaximum duration field.

  7. ClickCreate.

gcloud

To create an instance template that has graceful shutdown enabled, use thegcloud beta compute instance-templates create commandwith the--graceful-shutdown flag.

For example, to create a regional instance template that has gracefulshutdown enabled, run the following command:

gcloud beta compute instance-templates createINSTANCE_TEMPLATE_NAME \    --graceful-shutdown \    --instance-template-region=REGION \    --machine-type=MACHINE_TYPE

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the instancetemplate.

  • REGION: the region in which to create the instancetemplate.

  • MACHINE_TYPE: the machine type for the instancescreated using the instance template.

Optionally, to specify a custom graceful shutdown period, include the--graceful-shutdown-max-duration flag.

gcloud beta compute instance-templates createINSTANCE_TEMPLATE_NAME \    --graceful-shutdown \--graceful-shutdown-max-duration=MAX_DURATION \    --instance-template-region=REGION \    --machine-type=MACHINE_TYPE

ReplaceMAX_DURATION with a duration for the shutdownperiod. The value must be formatted as the number of hours, minutes, orseconds followed byh,m, ands respectively. For example, specify1h for one hour, or20m10s for 20 minutes and 10 seconds.

REST

To create an instance template that has graceful shutdown enabled, make aPOST request to one of the following methods:

For example, to create a regional instance template that has gracefulshutdown enabled, make aPOST request as follows:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceTemplates{  "name": "INSTANCE_TEMPLATE_NAME",  "properties": {    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "machineType": "MACHINE_TYPE",    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "scheduling": {      "gracefulShutdown": {        "enabled": true      }    }  }}

Replace the following:

  • PROJECT_ID: the ID of the project where to create theinstance template.

  • REGION: the region where to create the instancetemplate.

  • INSTANCE_TEMPLATE_NAME: the name of the instancetemplate.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This formattingspecifies the most recent, non-deprecated OS image. For example, ifyou specifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • MACHINE_TYPE: the machine type for the instancescreated using the instance template.

Optionally, to specify a custom graceful shutdown period, include themaxDuration field in the request body.

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/instanceTemplates{  "name": "INSTANCE_TEMPLATE_NAME",  "properties": {    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "machineType": "MACHINE_TYPE",    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "scheduling": {      "gracefulShutdown": {        "enabled": true,"maxDuration": {          "seconds": "MAX_DURATION"        }      }    }  }}

ReplaceMAX_DURATION with a duration in seconds for theshutdown period. The value must be between1 and3600, which is 3,600seconds (one hour).

For more configuration options when creating an instance template, seeCreate instance templates.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-09 UTC.