Running Startup Scripts

Create and run your own startup scripts on your virtual machines 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 virtual machine 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:

Permissions required for this task

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:

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 Google 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. Include the --metadata-from-file flag, followed by a
metadata key pair, startup-script=PATH/TO/FILE, where PATH/TO/FILE is
a relative path to the startup script:

Console

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 pair, where [CONTENTS] is 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.

Note: If you are running gcloud on a Windows computer, it can be tricky
determining where and how to escape characters in a startup script. Google
strongly recommends providing your startup script using a
local file instead.

API

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

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 keys listed below.
Each key should match the type of script you want to run. You can also specify
multiple scripts by passing in different keys to your instance. Each key can
only be specified once per instance.

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

Providing a startup script stored on Google Cloud Storage

You can store your script on Google 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.

Note: This section assumes that you have signed up for and are familiar with
Google Cloud Storage. To learn more, read about Google Cloud Storage.

Setting access permissions to your script

In order to use a startup script from Google 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.

Console

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
Metadata section, provide startup-script-url
as the metadata key.

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.

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.

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 Google Cloud Storage to download the startup
script. You can provide the Google Cloud Storage URL to the script in either
gs://bucket/file or https://storage.googleapis.com/bucket/file format.

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 Google Cloud Storage scope so the virtual
machine can access the startup script file:

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 Google Cloud Storage to download the startup
script. You can provide the Google Cloud Storage URL to the script in either
gs://bucket/file or https://storage.googleapis.com/bucket/file format.

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://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

On Container-Optimized OS, you can also use the journalctl 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 14.04, 16.04, and 16.10: /var/log/syslog

SLES 11 and 12: /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 on creating custom metadata keys, read
Set custom metadata.

Once 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 such:

Troubleshooting

Network connectivity to the metadata server

Specific to Linux virtual machines, Compute Engine will wait 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 will not finish booting up.

Specific to Linux virtual machines with images older than v20160606, the serial
port output will show "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.