Running shutdown scripts

Create and run shutdown scripts that execute commands right before a virtual machine (VM) instance is stopped or restarted. This is useful if you rely on automated scripts to start up and shut down instances, allowing instances time to clean up or perform tasks, such as exporting logs, or syncing with other systems.

Shutdown scripts are especially useful for VMs in a managed instance group with an autoscaler. If the autoscaler shuts down a VM in the group, the shutdown script runs before the VM stops and the shutdown script performs any actions that you define. The script runs during the limited shutdown period before the VM stops. For example, your shutdown script might copy processed data to Cloud Storage or back up any logs.

Shutdown scripts function very similarly to startup scripts. Much of the documentation for startup scripts also applies for shutdown scripts.

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

• For Linux VMs, by using the root user.
• For Windows VMs, by using the System account.

Before you begin

• Learn about Startup scripts.
• Understand what the metadata server is.
• If you haven't already, then 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 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, then initialize it by running the following command:

     gcloud init

  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.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

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

     gcloud auth application-default login

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

  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, then initialize it by running the following command:

  gcloud init

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

Permissions required for this task

To perform this task, you must have the following permissions:

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

Specifications

Limitations

There are some limitations to note when using shutdown scripts:

• Shutdown scripts have a limited amount of time to finish running before the instance stops:
  • On-demand instances: 90 seconds after you stop or delete an instance
  • Preemptible instances: 30 seconds after instance preemption begins
• Compute Engine executes shutdown scripts only on a best-effort basis. In rare cases, Compute Engine cannot guarantee that 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 Policy Computer Configuration/Windows Setting/Scripts (Startup/Shutdown) setting to launch the script upon system shutdown.

Shutdown script invocation

Shutdown scripts are triggered by certain Advanced configuration and power interface (ACPI) events. such as restarts or stops. There are many ways to restart or stop an instance, but only some ways trigger the shutdown script to run. A shutdown script runs as part of the following actions:

• When an instance shuts down due to an instances.delete request or an instances.stop request to the API.
• When Compute Engine stops a preemptible instance as part of the preemption process.
• When an instance shuts down through a request to the guest operating system, such as sudo shutdown or sudo reboot.
• When you shut down an instance manually through the Google Cloud console or the gcloud compute tool.

The shutdown script won't run if the instance is reset using instances().reset.

A shutdown script can be of any file type. If there is a shutdown script present, Compute Engine will:

1. Copy the script to a local file in the instance.
2. Set permissions on the file to make it executable.
3. Execute the file when the instance is stopped.

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 file to let the operating system know which interpreter to use. For example, for a Python script, you can add a shebang line like:

#!/usr/bin/python

Shutdown script running time

Before an instance shuts down or restarts, the shutdown script has a limited time period to run. During this period, Compute Engine attempts to run your shutdown script. If the script takes longer than this time period to complete, the instance automatically stops and all running tasks are ended. If you shut down or restart an instance by making a request to the guest operating system with the sudo shutdown command, the limit does not apply.

The length of the shutdown period is different depending on type of the instance. Preemptible instances have a shorter shutdown period than normal instances. For more information about the shutdown time limits on each instance type, see Shutdown period.

In general, your shutdown script must finish running within its shutdown period so that the operating system has time to complete its shutdown process and flush buffers to disk.

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 contents directly to Compute Engine.

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

Provide a shutdown script file

You can only pass in a local shutdown script file through the gcloud command-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-specific metadata 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 your instance but each key can only be specified once per virtual machine.

The following keys can be used with a local shutdown script, using the same instructions above.

Use a shutdown script from Cloud Storage

You can store and use a shutdown script from Cloud Storage. Follow the instructions in the Startup scripts documentation but replace startup-script-url with shutdown-script-url.

For Windows instances, replace windows-startup-script-url with windows-shutdown-script-url.

Apply a shutdown script to running instances

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

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

Viewing the output of a shutdown script