Create and run shutdown scripts that execute commands right before a virtualmachine (VM) instance is stopped or restarted. This is useful if yourely on automated scripts to start up and shut down instances, allowinginstances time to clean up or perform tasks, such as exporting logs, or syncingwith other systems.

Shutdown scripts are especially useful for VMs in amanaged instance group with anautoscaler. If the autoscaler shuts down aVM in the group, the shutdown script runs before the VMstops and the shutdown script performs any actions that you define.The script runs during the limitedshutdown period before theVM stops. For example, your shutdown script might copy processed datato Cloud Storage or back up any logs.

Shutdown scripts function very similarly to startup scripts. Much of thedocumentation forstartup scripts alsoapplies for shutdown scripts.

For both shutdown and reboot tasks, VMs always run shutdown scripts as follows:

• For Linux VMs, by using theroot user.
• For Windows VMs, by using theSystem account.

Prerequisites

To run scripts stored in metadata on a VM instance, theguest environment must be installed and running.

• The guest environment includes theguest agent (for example, google-guest-agent on Linux)that reads the script content or URL from the instance's metadata and initiates execution.
• All public Compute Engine images come with the guest environmentpreinstalled.
• If you create a custom image, you mustmanually install the Google Guest Environment to ensurescripts from metadata and other Google Cloud features function properly.

Before you begin

• Learn aboutStartup scripts.
• Understand what themetadata server is.
• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud 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 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. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  2. Set a default region and zone.

  Terraform

  To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloudauthapplication-defaultlogin

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  For more information, see Set up authentication for a local development environment.

  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.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Permissions required for this task

To perform this task, you must have the followingpermissions:

• All permissions required tocreate an instance
• compute.instances.setMetadata on the instance

Specifications

The following sections outline the specifications for shutdown scripts.

Limitations

There are some limitations to note when using shutdown scripts:

• Compute Engine executes shutdown scripts only on abest-effort basis. In rare cases, Compute Engine cannot guaranteethat the shutdown script will complete.
• On Windows, the Local Group Policy is used to launch the shutdown script.
  • The installation package configures the Local Group PolicyComputer Configuration/Windows Setting/Scripts (Startup/Shutdown)setting to launch the script upon system shutdown.

Shutdown script invocation

Shutdown scripts are triggered when the instance shuts down after any of thefollowing events happen:

• You do the following:

  • Stop orreboot theinstance from within the guest OS.

  • Stop ordelete theinstance.

• Compute Engine stops an instance as part of a programmed stop ordelete operation.

• Compute Engine stops a Spot VM or preemptibleinstance as part of thepreemption process.

A shutdown script can be of any file type. If there is a shutdown script presentin the instance, then Compute Engine does the following:

1. Copies the script to a local file in the instance.
2. Sets permissions on the file to make the script executable.
3. Executes the file when the instance shuts down.

You could, for example, provide a Python script instead of a bash script.Keep in mind that Compute Engine runs the script verbatim,regardless of the type of script.

To execute a script that is not bash, add a shebang line at the top of the fileto let the operating system know which interpreter to use. For example, for aPython script, you can add a shebang line like:

#!/usr/bin/python

Shutdown script running time

Your shutdown scripts start running when Compute Engine sets theinstance state toSTOPPING. Your scripts must complete before the instanceis fully stopped, which is when its state changes toTERMINATED. The time theinstance takes to reach theTERMINATED state varies depending on theinstance type.

If your scripts take longer than the time it takes for the instance to stop,then Compute Engine forcefully stops the scripts, which can lead todata loss or incomplete tasks. To prevent this,stop the instance from within its guest OS.This approach keeps the instance state toSTOPPING until your shutdown scriptsfinish running.

Use a local shutdown script

A local shutdown script is a script that lives on your local computer.Pass in a local shutdown script either as a file or by giving the contentsdirectly to Compute Engine.

Shutdown scripts can perform as many actions as you need, but if youare passing in the file locally, your script cannot exceed the metadata valuelength limit of 256 KB. To use a script that exceeds the length limit,store your file on Cloud Storage. SeeUse shutdown script from Cloud Storage formore information.

Provide a shutdown script file

You can only pass in a local shutdown script file through thegcloudcommand-line tool.

gcloud compute instances create example-instance \    --metadata-from-file shutdown-script=examples/scripts/install.sh

resource "google_compute_instance" "shutdown_content_from_file" {  name         = "instance-name-shutdown-content-from-file"  machine_type = "f1-micro"  zone         = "us-central1-c"  metadata = {    # Shuts down Apache server    shutdown-script = file("${path.module}/shutdown-script.sh")  }  boot_disk {    initialize_params {      image = "debian-cloud/debian-11"    }  }  network_interface {    # A default network is created for all Google Cloud projects    network = "default"    access_config {    }  }}

Provide shutdown script contents directly

Alternatively, you can pass in the contents of your shutdown script directly.

gcloud compute instances create example-instance --metadata shutdown-script="#! /bin/bash> # Shuts down Apache server> /etc/init.d/apache2 stop"

resource "google_compute_instance" "default" {  name         = "instance-name-shutdown-content-directly"  machine_type = "f1-micro"  zone         = "us-central1-c"  metadata = {    # Shuts down Apache server    shutdown-script = "#! /bin/bash /etc/init.d/apache2 stop"  }  boot_disk {    initialize_params {      image = "debian-cloud/debian-11"    }  }  network_interface {    # A default network is created for all Google Cloud projects    network = "default"    access_config {    }  }}

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances{...  "metadata": {    "items": [      {       "key": "shutdown-script",       "value": "#! /bin/bash\n\n# Shuts down Apache server\n/etc/init.d/apache2 stop"      }    ]  }...}

Provide a shutdown script on Windows instances

Run shutdown scripts on Windows instances using the following Windows-specificmetadata keys. Choose from any of the specialized keys listed below.Each key should match the type of script you want to run.

You can specify multiple shutdown scripts by passing in different keys to yourinstance but each key can only be specified once per virtual machine.

The following keys can be used with a local shutdown script, using thesame instructionsearlier in this document.

Use a shutdown script from Cloud Storage

You can store and use a shutdown script from Cloud Storage. Followthe instructions in theStartup scriptsdocumentation but replacestartup-script-url withshutdown-script-url.

For Windows instances, replacewindows-startup-script-url withwindows-shutdown-script-url.

Apply a shutdown script to running instances

To add a shutdown script to a running instance, follow the instructions in theApplying a startup script to running instancesdocumentation but replace the metadata keys with one of the following keys:

• shutdown-script: Supply the shutdown script contents directly withthis key. Using the Google Cloud CLI, you can provide the path to a shutdown scriptfile, using the--metadata-from-file flag and theshutdown-scriptmetadata key.
• shutdown-script-url: Supply a Cloud Storage URL to theshutdown script file with this key.

Viewing the output of a shutdown script