Enable graceful shutdown in a Compute Engine instance

This document explains how to enable graceful shutdown in a new or existing Compute Engine instance.

When you enable graceful shutdown in a compute instance, you can give its guest OS up to six hours to cleanly shut down when you stop or delete the compute instance. This action helps prevent data loss or corrupted file systems when your applications need more time to finish running tasks. To learn more about the requirements and limitations that you apply when you gracefully shutdown a compute instance, see About graceful shutdown.

Before you begin

  • If you haven't already, set up authentication. Authentication verifies your identity for access to Cloud de Confiance by S3NS services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Cloud de Confiance console to access Cloud de Confiance by S3NS services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity. After signing in, initialize the Google Cloud CLI by running the following command: 

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

      Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity.

    For more information, see Authenticate for using REST in the Cloud de Confiance authentication documentation.

Required roles

To get the permissions that you need to enable graceful shutdown in a compute instance, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, see Manage 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 the Required permissions section:

Required permissions

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

  • To create compute 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 a legacy 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 compute instance: compute.instances.update on the compute instance

You might also be able to get these permissions with custom roles or other predefined roles.

Enable graceful shutdown

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

Enable graceful shutdown in an existing compute instance

If you enable graceful shutdown in an existing compute instance, then you must restart the compute instance as described in this section.

To enable graceful shutdown in an existing compute instance, select one of the following options:

Console

  1. In the Cloud de Confiance console, go to the VM instances page.

    Go to VM instances

  2. In the Name column, click the name of the compute instance in which you want to enable graceful shutdown. The details page of the compute instance opens.

  3. Click Edit.

  4. In the Management section, do the following:

    1. Select the Gracefully shut down the VM checkbox.

    2. In the Maximum duration field that appears, enter the number of minutes or seconds that you want your graceful shutdown to last. The value must be between one second and 360 minutes (six hours).

  5. Click Save.

gcloud

To enable graceful shutdown in an existing compute instance, use the gcloud compute instances update command with the --graceful-shutdown and --graceful-shutdown-max-duration flags:

gcloud compute instances update INSTANCE_NAME \
    --graceful-shutdown \
    --graceful-shutdown-max-duration=MAX_DURATION \
    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the compute instance.

  • MAX_DURATION: the maximum duration of the graceful shutdown. The value must be formatted as the number of hours, minutes, or seconds followed by h, m, and s respectively. For example, specify 1h for one hour, or 20m10s for 20 minutes and 10 seconds. The value must be between one second and six hours.

  • ZONE: the zone where the compute instance exists.

REST

  1. Create an empty JSON file.

  2. To view the properties of an existing compute instance, make a GET request to the instances.get method:

    GET https://compute.s3nsapis.fr/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    Replace the following:

    • PROJECT_ID: the ID of the project where the compute instance exists.

    • ZONE: the zone where the compute instance exists.

    • INSTANCE_NAME: the name of an existing compute instance.

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

    1. Enter the compute instance configuration details from the GET request output.

    2. In the scheduling field, add the gracefulShutdown field as follows:

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

      Replace MAX_DURATION with the maximum duration of the graceful shutdown, in seconds. The value must be between 1 (one second) and 21600 (21,600 seconds, or six hours).

  4. To update the compute instance and restart it, make a PUT request to the instances.update method. In the request, do the following:

    • In the request URL, include the mostDisruptiveAllowedAction query parameter set to RESTART.

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

    The PUT request to update the compute instance is similar to the following:

    PUT https://compute.s3nsapis.fr/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?mostDisruptiveAllowedAction=RESTART

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

For more information about updating the properties of a compute instance, see Update instance properties.

Enable graceful shutdown while creating a compute instance

To create a compute instance that has graceful shutdown enabled, select one of the following options:

Console

  1. In the Cloud de Confiance console, go to the VM instances page.

    Go to VM instances

  2. Click Create instance. The Create an instance page opens.

  3. In the Name field, enter a name for the compute instance.

  4. In the Region and Zone lists, enter the region and zone in which to create your compute instance.

  5. Specify the machine type for your compute instance.

  6. Expand the VM provisioning model advanced settings section, and then do the following:

    1. Select the Gracefully shut down the VM checkbox.

    2. In the Maximum duration field that appears, enter the number of minutes or seconds that you want your graceful shutdown to last. The value must be between one second and 360 minutes (six hours).

  7. Click Create.

gcloud

To create a compute instance that has graceful shutdown enabled, use the gcloud compute instances create command with the --graceful-shutdown flag:

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

Replace the following:

  • INSTANCE_NAME: the name of the compute instance.

  • MAX_DURATION: the maximum duration of the graceful shutdown. The value must be formatted as the number of hours, minutes, or seconds followed by h, m, and s respectively. For example, specify 1h for one hour, or 20m10s for 20 minutes and 10 seconds. The value must be between one second and six hours.

  • MACHINE_TYPE: the machine type to use for the compute instance.

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

REST

To create a compute instance that has graceful shutdown enabled, make a POST request to the instances.insert method. In the request body, include the gracefulShutdown field:

POST https://compute.s3nsapis.fr/compute/v1/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"
      }
    }
  }
}

Replace the following:

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

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

  • INSTANCE_NAME: the name of the compute instance.

  • MACHINE_TYPE: the machine type for the compute instance.

  • IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public images.

  • IMAGE: specify one of the following:

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

    • An image family, which must be formatted as family/IMAGE_FAMILY. This formatting specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.

  • MAX_DURATION: the maximum duration of the graceful shutdown, in seconds. The value must be between 1 (one second) and 21600 (21,600 seconds, or six hours).

For more information about creating a compute instance, see Create and start a Compute Engine instance.

Enable graceful shutdown while creating an instance template

When you create an instance template that has graceful shutdown enabled, the default period for graceful shutdown is 10 minutes. Optionally, you can specify a custom period between one second and six hours. All compute instances that you create by using the instance template have graceful shutdown enabled.

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

Console

  1. In the Cloud de Confiance console, go to the Instance templates page.

    Go to Instance templates

  2. Click Create instance template. The Create an instance template page appears.

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

  4. In the Location section, select whether you want to create a regional or global instance template based on your use case:

    • To reduce cross-region dependency, create a regional instance template by completing the following steps:

      1. Select Regional.

      2. In the Region field, select the region in which to create your instance template.

    • To use the instance template across regions, select Global.

  5. In the Machine configuration section, specify a machine type.

  6. Expand the VM provisioning model advanced settings section, and then do the following:

    1. Select the Gracefully shut down the VM checkbox.

    2. In the Maximum duration field that appears, enter the number of minutes or seconds that you want your graceful shutdown to last. The value must be between one second and 360 minutes (six hours).

  7. Click Create.

gcloud

To create an instance template that has graceful shutdown enabled, use the gcloud compute instance-templates create command with the --graceful-shutdown flag.

For example, to create a regional instance template that has graceful shutdown enabled, run the following command. If you want to create a global instance template, then use the same command without the --instance-template-region flag.

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

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the compute instance template.

  • MAX_DURATION: the maximum duration of the graceful shutdown. The value must be formatted as the number of hours, minutes, or seconds followed by h, m, and s respectively. For example, specify 1h for one hour, or 20m10s for 20 minutes and 10 seconds. The value must be between one second and six hours.

  • REGION: the region in which to create the compute instance template.

  • MACHINE_TYPE: the machine type for the compute instances that you create by using the instance template.

REST

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

For example, to create a regional instance template that has graceful shutdown enabled, make a POST request as follows:

POST https://compute.s3nsapis.fr/compute/v1/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,
        "maxDuration": {
          "seconds": "MAX_DURATION"
        }
      }
    }
  }
}

Replace the following:

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

  • REGION: the region where to create the compute instance template.

  • INSTANCE_TEMPLATE_NAME: the name of the compute instance template.

  • IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public images.

  • IMAGE: specify one of the following:

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

    • An image family, which must be formatted as family/IMAGE_FAMILY. This formatting specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.

  • MACHINE_TYPE: the machine type for the compute instances that you create by using the instance template.

  • MAX_DURATION: the maximum duration of the graceful shutdown, in seconds. The value must be between 1 (one second) and 21600 (21,600 seconds, or six hours).

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

What's next