Running startup scripts

Create and run your own startup scripts on your virtual machines (VMs) to perform automated tasks every time your instance boots up. Startup scripts can perform many actions, such as installing software, performing updates, turning on services, and any other tasks defined in the script. You can use startup scripts to easily and programmatically customize your VM instances, including on new instances at creation time.

For example, a simple startup script that installs and starts an Apache server could look like this:

#! /bin/bash
apt-get update
apt-get install -y apache2
cat <<EOF > /var/www/html/index.html
<html><body><h1>Hello World</h1>
<p>This page was created from a simple startup script!</p>
</body></html>

A startup script is specified through the metadata server, using startup script metadata keys. You can use the gcloud command-line tool, the API, or the Google Cloud Console to provide a startup script.

Before you begin

If you want to use the command-line examples in this guide:
1. Install or update to the latest version of the gcloud command-line tool.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.
Understand what the metadata server is.

Permissions required for this task

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

All permissions required to create a new instance
compute.instances.setMetadata on the instance

Startup script execution

The instance always executes startup scripts as root after the network is available.

A startup script can be of any file type. If there is a startup script present, Compute Engine will do the following:

Copy the startup script to a local file in the instance.
Set permissions on the file to make it executable.
Execute the file.

You could, for example, provide a Python script instead of a bash script. Keep in mind that Compute Engine will run 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

Using a local startup script

A local startup script is a script located on your local computer. To use a local startup script, pass a local startup script file to the instance or provide the contents of a startup script directly to the metadata server. The examples in the following subsections show how to add startup-script metadata from a local file or by direct input.

Local startup scripts are subject to the metadata value length limit of 256 KB. If your startup script exceeds this limit, you will not be able to load it locally. Instead, save your file to Cloud Storage and specify the script URL during instance creation time. See Use a startup script stored on Cloud Storage for more information.

Providing a startup script file

You can only pass a local startup script file by using the gcloud command-line tool command-line tool. Include the --metadata-from-file flag, followed by a metadata key pair, startup-script=path-to-file, replacing path-to-file with a relative path to the startup script:

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

Providing startup script contents directly

Alternatively, you can use the console, the gcloud command-line tool, or the API to type or paste in the contents of your startup script directly.

Console

In Cloud Console, specify a startup script directly in the Startup script section:

In the Cloud Console, go to the VM Instances page.
Go to the VM Instances page
Click Create instance.
On the Create a new instance page, fill in the properties for your instance. For advanced configuration options, expand the Management, security, disks, networking, sole tenancy section.
In the Automation section, supply the contents of your startup script under Startup script.
Click Create to create the instance.

gcloud

With the gcloud command-line tool, specify the --metadata flag to supply the contents of your startup script, using the startup-script=contents key-value pair, replacing contents with the content of your startup script.

For example, the following command creates an instance that, on startup, performs some system updates, installs Apache, and launches a single web page. You can run this command and then visit the instance's external IP address to see the contents of the index.html page.

On a Linux desktop, run the command like so:

gcloud compute instances create example-instance --tags http-server \
--metadata startup-script='#! /bin/bash
# Installs apache and a custom homepage
sudo su -
apt-get update
apt-get install -y apache2
cat <<EOF > /var/www/html/index.html
<html><body><h1>Hello World</h1>
<p>This page was created from a simple start up script!</p>
</body></html>
EOF'

If you are on a Windows desktop, you can run this command on a cmd terminal:

gcloud compute instances create example-instance --tags http-server --metadata startup-script="
apt-get update;
apt-get install -y apache2;
echo \"This page was created from a simple start up script!\" ^> /var/www/html/index.html"

Similarly, if you are using PowerShell, you can run this command using the --% marker to pass in exact command to the gcloud tool:

gcloud --% compute instances create example-instance --tags http-server --metadata startup-script="
apt-get update;
apt-get install -y apache2;
echo \"This page was created from a simple start up script!\" ^> /var/www/html/index.html"

API

In the API, provide a startup script as part of the metadata property in your request, using startup-script as the metadata key:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{
  ...
  "metadata": {
    "items": [
      {
       "key": "startup-script",
       "value": "#! /bin/bash\n\n# Installs apache and a custom homepage\napt-get update\napt-get install -y apache2\ncat <<EOF > /var/www/html/index.html\n<html><body><h1>Hello World</h1>\n<p>This page was created from a simple start up script!</p>\n</body></html>"
      }
    ]
  }
  ...
}

Providing a startup script for Windows instances

You can run startup scripts on Windows instances using unique Windows-specific metadata keys. Choose from any of the specialized metadata keys listed in the table below. Each metadata key should match the type of script you want to run. You can also specify multiple scripts by passing in different metadata keys to your instance. You can only specify each metadata key once for each VM instance.

If you need to manually run the startup scripts on a VM instance after the VM instance has started, an administrator can do so by using the following command:

C:\Program Files\Google\Compute Engine\metadata_scripts\run_startup_scripts.cmd

The following table shows the types of startup scripts that are supported, when they run, and which metadata key to use to specify the script. For information about how to use these metadata keys, see Using a local startup script. Note that these scripts only run if you prepare your image with the GCESysprep command.

Type of script	Runs: During GCESysprep² Before boot	Runs: After GCESysprep² completes On every subsequent boot
`url` startup scripts	metadata key: `sysprep-specialize-script-url`	metadata key: `windows-startup-script-url`
`cmd` startup scripts	metadata key: `sysprep-specialize-script-cmd`	metadata key: `windows-startup-script-cmd`
`bat` startup scripts	metadata key: `sysprep-specialize-script-bat`	metadata key: `windows-startup-script-bat`
`ps1`¹ startup scripts	metadata key: `sysprep-specialize-script-ps1`	metadata key: `windows-startup-script-ps1`

¹ Windows PowerShell
² GCESysprep

Providing a startup script stored on Cloud Storage

You can store your script on Cloud Storage and provide the URL to the script when creating your instance. This allows you to access your startup script from anywhere and also bypasses the metadata server limit.

Setting access permissions to your script

Before you can use a startup script from Cloud Storage, you must have permission to access the script. Check the access control settings on the bucket and file to ensure you have permission.

By default, if you are a project owner or editor, you should be able to access files from the same project, unless there are explicit access controls that disallow it.

Providing a startup script

Create a bucket. You can create a new bucket or use an existing bucket. For instructions about creating a new bucket, see Creating a bucket in the Google Cloud Console or Creating a bucket in gsutil.
Upload the file to the bucket. Follow the instructions to use gsutil or the Cloud Console to upload an object.
Give the URL to the startup script file when you create a new instance.
Console
1. In the Google Cloud Console, go to the VM instances page.
  Go to the VM instances page
2. Click Create Instance.
3. On the Create a new instance page, fill in the properties for your instance.
4. In the Identity and API access section, select a service account that has access to read your startup script file in Cloud Storage. For example, the service account should have permissions of the Storage Object Viewer role.
5. Expand the Management, security, disks, networking, sole tenancy section.
6. In the Metadata section, provide startup-script-url as the metadata key.
7. In the Value box, provide a URL to the startup script file, either in the gs://[BUCKET]/[FILE] or https://storage.googleapis.com/[BUCKET]/[FILE] format.
  1. Click Create to create the instance.
gcloud
Using the gcloud command-line tool, create an instance with the --scopes and --metadata flags, and specify the startup-script-url key. The --scopes flag gives the virtual machine access to Cloud Storage to download the startup script. You can provide the Cloud Storage URL to the script in either gs://bucket/file or https://storage.googleapis.com/bucket/file format.
```
gcloud compute instances create example-instance --scopes storage-ro \
    --metadata startup-script-url=gs://bucket/startupscript.sh
```
API
In the API, provide a startup script as part of the metadata property in your request, using startup-script-url as the metadata key. Also, provide a list of scopes, with a Cloud Storage scope so the virtual machine can access the startup script file:
```
POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{
  ...
  "serviceAccounts": [
    {
      "email": "default",
      "scopes": [
        "https://www.googleapis.com/auth/devstorage.read_only"
      ]
    }
  ],
  "metadata": {
    "items": [
      {
       "key": "startup-script-url",
       "value": "gs://bucket/myfile"
      }
    ]
  },
  "tags": {
    "items": []
  },
  "machineType": "zones/us-central1-a/machineTypes/n1-standard-1",
  "name": "example-instance"
}
```
Windows
Using the gcloud command-line tool, create an instance with the --scopes and --metadata flags, and specify the windows-startup-script-url key. The --scopes flag gives the virtual machine access to Cloud Storage to download the startup script. You can provide the Cloud Storage URL to the script in either gs://bucket/file or https://storage.googleapis.com/bucket/file format.
```
gcloud compute instances create example-windows-instance --scopes storage-ro \
    --metadata windows-startup-script-url=gs://bucket/startupscript.ps1
```

Applying a startup script to running instances

If you have a running instance, add a startup script to the instance and the next time the instance restarts, the startup script will run. The startup script will also run on all subsequent reboots.

Follow these instructions to set a startup script on a running instance.

Console

In the Google Cloud Console, go to the VM instances page.
Go to the VM instances page
Click the instance for which you want to add a startup script. The instance details page displays.
From the instance details page, complete the following steps:
1. Click the Edit button at the top of the page.
2. Under Custom metadata, click Add item.
3. Add your startup script using one of the following keys:
  - startup-script: Supply the startup script contents directly with this key.
  - startup-script-url: Supply a Cloud Storage URL to the start script file with this key.

gcloud

Using the gcloud command-line tool, use the instances add-metadata to add metadata to the instance. Use any of the available startup script keys:

--metadata startup-script=CONTENTS: Supply the startup script contents directly with this key.
--metadata startup-script-url=URL: Supply a Cloud Storage URL to the start script file with this key.
--metadata-from-file startup-script=FILE: Supply a locally stored start up script file.

For example:

gcloud compute instances add-metadata example-instance \
    --metadata-from-file startup-script=path/to/file

gcloud compute instances add-metadata example-instance \
    --metadata startup-script-url=gs://bucket/file

API

In the API, make a request to the instances().setMetadata method, providing the new metadata and a fingerprint value.

A fingerprint is a random string of characters generated by Compute Engine and is used to perform optimistic locking. Provide the matching fingerprint value in order to perform your request. The fingerprint changes after each request and if you provide a mismatched fingerprint, your request is rejected. In this way, only one update can be made at a time, preventing collisions.

To get the current fingerprint of an instance, perform a instances().get request and copy the fingerprint value:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

{

 ...
 "name": "example-instance",
 "metadata": {
  "kind": "compute#metadata",
  "fingerprint": "zhma6O1w2l8="
 },
 "...
}

Next, make a request to the instances().setMetadata method, using one of the following metadata keys and the fingerprint value:

startup-script: Supply the startup script contents directly with this key.
startup-script-url: Supply a Cloud Storage URL to the start script file with this key.

For example:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

    {
     "fingerprint": "zhma6O1w2l8=",
     "items": [
      {
       "key": "startup-script-url",
       "value": "gs://bucket/file"
      }
     ]
    }

Rerunning a startup script

You can rerun your startup scripts on your VM instance by connecting to the instance and running one of the following commands:

On Debian, CentOS, RHEL, SLES, Container-Optimized OS, and Ubuntu images

sudo google_metadata_script_runner --script-type startup --debug

startup-script: INFO Starting startup scripts.
startup-script: INFO startup-script: Return code 0.
startup-script: INFO Finished running startup scripts.

On the Container-Optimized OS, you can also use the journalctl command to view startup script output.

sudo journalctl -u google-startup-scripts.service

Startup script output is written to the following log files:

CentOS and RHEL: /var/log/messages
Debian: /var/log/daemon.log
Ubuntu: /var/log/syslog
SLES: /var/log/messages

Setting custom values in startup scripts

When you run startup scripts across instances, there may be situations where you would like to use custom values in your startup script. For example, you may want to run a startup script on different instances and have each instance print out a custom message.

You can specify these custom values as custom metadata key/value pairs during instance creation time and reference them in your startup scripts. For more information about creating custom metadata keys, read Set custom metadata.

After you have set a custom metadata key pair, you can modify your startup script to query for the new metadata. For example, the same script above can be modified as follows:

#! /bin/bash
VALUE_OF_FOO=$(curl http://metadata.google.internal/computeMetadata/v1/instance/attributes/foo -H "Metadata-Flavor: Google")
apt-get update
apt-get install -y apache2
cat <<EOF > /var/www/html/index.html
<html><body><h1>Hello World</h1>
<p>The value of foo: $VALUE_OF_FOO</p>
</body></html>
EOF

Troubleshooting

Network connectivity to the metadata server

Specific to Linux virtual machines, Compute Engine waits for a connection to the metadata server before attempting to get information such as a custom startup or shutdown script from the metadata server. If the metadata server is not responding or the network is not yet configured, the virtual machine doesn't finish booting up.

Specific to Linux virtual machines with images earlier than v20160606, the serial port output shows "Waiting for metadata server, attempt N" where N is the number of attempts that have been made.

This issue can last for up to seven minutes due to a transient network issue which should resolve on its own. If the issue does not resolve itself after seven minutes, recreate your virtual machine instance.

What's next

Add a shutdown script.
Use the interactive serial console to troubleshoot instances.