View 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 view the settings and progress of a gracefulshutdown in a Compute Engine instance. To learn more about graceful shutdown,seeGraceful shutdown overview.

When you view the details of an instance, you can do the following:

  • View graceful shutdown settings. You can verify if graceful shutdown isenabled and how long it lasts.

  • Monitor graceful shutdown. When a graceful shutdown is in progress, youcan check the following:

    • When the graceful shutdown process times out.

    • If a stop or delete operation is in progress.

Before you begin

Required roles

To get the permission that you need to view the graceful shutdown of 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 thecompute.instances.get on the project permission, which is required to view the graceful shutdown of a compute instance.

You might also be able to get this permission withcustom roles or otherpredefined roles.

View graceful shutdown settings

To view the graceful shutdown settings in a compute instance, select one of thefollowing options:

Console

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

    Go to VM instances

  2. In theName column, click the name of your instance.

    The details page of the instance opens on theDetails tab.

  3. To check the graceful shutdown settings, in theAvailability policies section, check the value of theGraceful shutdown maximum duration field. This field shows thegraceful shutdown period. If it shows a hyphen (-), then gracefulshutdown is disabled.

gcloud

To view the graceful shutdown settings in an instance, use thegcloud beta compute instances describe command:

gcloud beta compute instances describeINSTANCE_NAME \    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the instance.

  • ZONE: the zone where the instance exists.

If graceful shutdown is enabled, then the output is similar to thefollowing:

...scheduling:  ...  gracefulShutdown:    enabled: true    maxDuration:      seconds: 'MAX_DURATION'  ......

The output includes theMAX_DURATION value. This valueindicates how long the graceful shutdown period lasts in seconds. If youdidn't specify a custom shutdown period when you enabled graceful shutdownin the instance, then Compute Engine omits themaxDuration fieldand sets the graceful shutdown period to 10 minutes.

REST

To view the graceful shutdown settings in an instance, make aGET requesttobetainstances.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 you createdthe instance.

  • ZONE: the zone where the instance exists.

  • INSTANCE_NAME: the name of the instance.

If graceful shutdown is enabled, then the output is similar to thefollowing:

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

The output includes theMAX_DURATION value. This valueindicates how long the graceful shutdown period lasts in seconds. If youdidn't specify a custom shutdown period when you enabled graceful shutdownin the instance, then Compute Engine omits themaxDuration fieldand sets the graceful shutdown period to 10 minutes.

Monitor graceful shutdown

To monitor an ongoing graceful shutdown in a compute instance, select one of thefollowing options:

Console

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

    Go to VM instances

  2. In theName column, click the name of your instance.

    The details page of the instance opens on theDetails tab.

  3. If a graceful shutdown is in progress, then, in theBasic information section, check the following fields:

    • Status: this field shows thestate of your instance.During a graceful shutdown, this field displaysPending stop anda countdown timer. The timer counts down to the moment when thegraceful shutdown ends.

    • Target state: this field shows whether Compute Engine isstopping (Stopped) or deleting (Deleted) the instance.

gcloud

To monitor an ongoing graceful shutdown in an instance, use thegcloud beta compute instances describe command:

gcloud beta compute instances describeINSTANCE_NAME \    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the instance.

  • ZONE: the zone where the instance exists.

If a graceful shutdown is in progress, then the output is similar to thefollowing:

...resourceStatus:  ...  shutdownDetails:    maxDuration:      seconds: 'MAX_DURATION'    requestTimestamp: 'REQUEST_TIMESTAMP'    stopState:STOP_STATE    targetState:TARGET_STATE...status: PENDING_STOP...

This output includes the following values:

  • MAX_DURATION: the duration of the graceful shutdownperiod in seconds. After Compute Engine setsSTOP_STATE toSTOPPING, it deletes themaxDuration field.

  • REQUEST_TIMESTAMP: the timestamp when theSTOP_STATE started.

  • STOP_STATE: the stopping phase of the instance. Thevalue can be one of the following:

    • PENDING_STOP: Compute Engine has started the gracefulshutdown. The instance remains in this state until you manually endthe graceful shutdown or the graceful shutdown period times out.

    • STOPPING: the graceful shutdown has ended, andCompute Engine continues with the stop or delete operation.

  • TARGET_STATE: whether Compute Engine isstopping (STOPPED) or deleting (DELETED) the instance.

If a stop operation is running, then, after Compute Engine sets thestatus field toTERMINATE, it deletes theshutdownDetails field.

REST

To monitor an ongoing graceful shutdown in an instance, make aGET requestto thebetainstances.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 you createdthe instance.

  • ZONE: the zone where the instance exists.

  • INSTANCE_NAME: the name of the instance.

If a graceful shutdown is in progress, then the output is similar to thefollowing:

{  ...  "resourceStatus": {    ...    "shutdownDetails": {      "maxDuration": {        "seconds": "MAX_DURATION"      },      "requestTimestamp": "REQUEST_TIMESTAMP",      "stopState": "STOP_STATE",      "targetState": "TARGET_STATE"    }  },  ...  "status": "PENDING_STOP",  ...}

This output includes the following values:

  • MAX_DURATION: the duration of the graceful shutdownperiod in seconds. After Compute Engine setsSTOP_STATE toSTOPPING, it deletes themaxDuration field.

  • REQUEST_TIMESTAMP: the timestamp when theSTOP_STATE started.

  • STOP_STATE: the stopping phase of the instance. Thevalue can be one of the following:

    • PENDING_STOP: Compute Engine has started the gracefulshutdown. The instance remains in this state until you manually endthe graceful shutdown or the graceful shutdown period times out.

    • STOPPING: the graceful shutdown has ended, andCompute Engine continues with the stop or delete operation.

  • TARGET_STATE: whether Compute Engine isstopping (STOPPED) or deleting (DELETED) the instance.

If a stop operation is running, then, after Compute Engine sets thestatus field toTERMINATE, it deletes theshutdownDetails field.

Metadata server

  1. Connect to the instance.

  2. Query the metadata server:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/shutdown-details/?recursive=true?alt=json" \-H "Metadata-Flavor: Google"

    If a graceful shutdown is in progress, then the output is similar to thefollowing:

    {  "maxDuration": "MAX_DURATION",  "requestTimestamp": "REQUEST_TIMESTAMP",  "stopState": "STOP_STATE",  "targetState": "TARGET_STATE"}

    The output includes the following values:

    • MAX_DURATION: the duration of the gracefulshutdown period in seconds. After Compute Engine setsSTOP_STATE toSTOPPING, it deletes themaxDuration field.

    • REQUEST_TIMESTAMP: the timestamp when theSTOP_STATE started.

    • STOP_STATE: the stopping phase of the instance.The value can be one of the following:

      • PENDING_STOP: Compute Engine has started thegraceful shutdown. The instance remains in this state until youmanually end the graceful shutdown or the graceful shutdownperiod times out.

      • STOPPING: the graceful shutdown has ended, andCompute Engine continues with the stop or deleteoperation.

    • TARGET_STATE: whether Compute Engine isstopping (STOPPED) or deleting (DELETED) the instance.

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 2026-02-18 UTC.