Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



Using Startup Scripts

This page discusses how to use startup scripts with Google Compute Engine.

Contents

Overview

You can choose to specify a startup script that will run when your instance boots up or restarts. Start up scripts can be used to install software and updates, and to ensure that services are running within the virtual machine. This can be a script on your local computer or a script stored on Google Storage or other URL-accessible location. This script will automatically run whenever your instance restarts.

The same mechanism that enables startup scripts also enables you to specify custom name/value pairs in the command-line that will be persistently available to your instance whenever it starts. See Storing and Retrieving Instance Metadata for information about passing arbitrary values to an instance on startup.

Using a startup script

To use a startup script, you just need to create the script and start an instance that uses the startup script. You can either store your startup script locally or you can store your startup script on Google Cloud Storage. Here is an example of creating and running a startup script that installs Apache and creates a custom homepage.

  1. Create the script

    The following script installs apache and creates a custom home page. Your script can perform as many actions as you would like. For this example, save the following file locally as install-apache.sh. Choose your operating system to view the correct startup script:

    Debian 
    #! /bin/bash
apt-get update
apt-get install -y apache2
cat <<EOF > /var/www/index.html
<html><body><h1>Hello World</h1>
<p>This page was created from a simple startup script!</p>
</body></html>
EOF
    CentOS 
    #! /bin/bash
yum install -y httpd
service httpd start
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>
EOF

  2. Optional: Store your script on Google Cloud Storage

    If you don't want to store your script locally, or if your script exceeds the metadata value length limit of 32768 bytes, you can choose to store your file on Google Cloud Storage. To do so, you need to:

    1. Sign up for Google Cloud Storage.
    2. Upload your file using the Google Cloud Storage manager .

    You can then run your startup script directly from Google Cloud Storage, as described in the next step.

  3. Start a VM with the startup script

    You can run a locally-stored startup script or startup script stored on Google Cloud Storage . Both methods are described below.

    Using a startup script from a local file

    To run a startup script from a local file, use the --metadata-from-file flag with gcloud compute instances create to specify the path to your script file. This flag uploads the file and installs it on the server in the same location relative to the path that you pass in. The default instance image looks for this parameter, and if present, will run the specified file. For example: 

    $ gcloud compute firewall-rules create http2 --description="Incoming http allowed." \
     --allow tcp:80
$ gcloud compute instances create simple-apache \
     --metadata-from-file startup-script=install-apache.sh

    The startup script will be stored in the instance's metadata server , and will automatically re-run if the server crashes and is automatically restarted.

    Using a startup script from Google Cloud Storage

    It is possible to store your script on Google Cloud Storage and specify the startup script URL when you start an instance, instead of uploading a local file. This is ideal if you don't want to store your script locally or if your script's metadata value exceeds the metadata value limit of 32768 bytes.

    When you specify a startup script URL, Google Compute Engine downloads the script to a temporary file and runs it. When you update your startup script, the instances using this startup script will automatically be able to use the updated script.

    To run a startup script from Google Cloud Storage:

    1. Set up your instance to have internet access.

      Your instance must have internet access to load a script by URL; to enable this, you must launch your instance with an external IP address .

    2. Set up permissions and run your startup script.

      Before you can specify a startup script from Google Cloud Storage, your Google Compute Engine instance needs permissions to the startup script. You can do this two ways:

      • Using service accounts (Recommended): Set up your instance to use service accounts with Google Cloud Storage scopes . Service accounts are ideal for server-to-server interactions that do not need explicit user authorization: 
        $ gcloud compute instances create simple-apache --scopes storage-ro \
     --metadata startup-script-url=URL

        Note: gcloud compute provides shorthand aliases for OAuth 2.0 scopes that may be useful for users. In this example, the shorthand for the read-only Google Cloud Storage scope is used, storage-ro . The full scope URI is https://www.googleapis.com/auth/devstorage.read_only , which you can also use if you prefer. For convenience, {{ product_name }} provides a list of aliases for common scopes which you can use with gcloud compute .


      • Using anonymous access: Set up public-read access on your script for anonymous access
        1. Set the access control list for your startup script to be publicly- accessible. To do this using gsutil , run: 
          gsutil setacl public-read <startup_script>

          Warning: Setting up your script for anonymous access means that anyone on the Internet can access it. If you don't want this, you should set up your instance to use service accounts instead (see above).

        2. Start your instance like so: 
          gcloud compute instances create simple-apache \
   --metadata startup-script-url=URL

      <url> can be any publicly readable URL, or, if the startup script is not publicly readable, it can be a Google Storage URL, in the format: 

      gs://<bucket>/<file>

      For example: 

      gs://mybucket/install-apache.sh

      *Although this command uses a read-only scope to Google Cloud Storage, you can set up the instance to use any of the Google Cloud Storage scopes .

    Using a startup script from a URL

    To run a startup script from a URL, use the --metadata startup-script-url=<url> flag with the gcloud compute instances create INSTANCE command: 

    gcloud compute instances create simple-apache --metadata startup-script-url=URL

    When you specify a startup script URL, Google Compute Engine downloads the script to a temporary file and runs it. When you update your startup script, the instances using this startup script will automatically be able to use the updated script.

    You can find startup script logging at /var/log/startupscript.log

    You can also view the logging information through the instance's serial console output for any image type: 

    $ gcloud compute instances get-serial-output INSTANCE

    The serial console port output can also be viewed at the Google Developers Console or through the getSerialOutput() method.

    If your startup script is less than 35000 bytes, you could choose to pass in your startup script as pure metadata, although this is generally not as convenient as saving your startup script in a file. To pass in script as pure metadata, perform the following command:

    Debian 
    $ gcloud compute instances create example-instance \
--image debian-7 --metadata startup-script='#! /bin/bash
apt-get update
apt-get install -y apache2
cat <<EOF > /var/www/index.html
<html><body><h1>Hello World</h1>
<p>This page was created from a simple startup script!</p>
</body></html>
EOF'
    CentOS 
    $ gcloud compute instances create example-instance \
--image centos-6 --metadata startup-script='#! /bin/bash
yum install -y apache2
service httpd start
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>
EOF'

  4. View the page

    Check your instance's status, and when it is listed as RUNNING , browse to http:// /index.html to see your default page.

Rerunning a Startup Script

You can force your startup scripts to rerun on your VM by ssh'ing in and running the following command: 

$ sudo /usr/share/google/run-startup-scripts
google Running startup script...
google Finished running startup script...

You can view a log for all the times you have run your startup scripts at /var/log/startupscript.log .

Passing in Custom Values

When you run startup scripts across instances, there may be situations where you would like to use custom values for different instances. For example, say you want to run the previous startup script on different instances and have each instance print out a custom message. You can specify these custom values as custom metadata using key/value pairs during instance creation time. Your startup script can then use these custom values however you see fit.

For example, the following command creates an instance with a custom metadata key/value pair of foo:bar where foo is the key and bar is the value: 

$ gcloud compute instances create example-instance --metadata foo=bar

Now, you can access the value of foo from within an instance by connecting to the instance with ssh and querying the metadata server: 

user@example-instance:~$ curl http://metadata/computeMetadata/v1/instance/attributes/foo -H "Metadata-Flavor: Google"
bar

Similarly, you can also query the metadata server from within your startup script. To do so:

  1. Modify your startup script to query for custom metadata as shown here:

    Debian 
    #! /bin/bash
VALUE_OF_FOO=$(curl http://metadata/computeMetadata/v1/instance/attributes/foo -H "Metadata-Flavor: Google")
apt-get update
apt-get install -y apache2
cat <<EOF > /var/www/index.html
<html><body><h1>Hello World</h1>
<p>The value of foo: $VALUE_OF_FOO</p>
</body></html>
EOF
    CentOS 
    #! /bin/bash
VALUE_OF_FOO=$(curl http://metadata/computeMetadata/v1/instance/attributes/foo -H "Metadata-Flavor: Google")
yum install -y httpd
service httpd start
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

  2. Pass your metadata to your instance's metadata server in the startup script as shown here: 

$ gcloud compute instances create simple-apache  \
         --metadata-from-file startup-script=install-apache.sh \
         --metadata foo=bar

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.