Google Compute Engine

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 VM. 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 be run whenever your instance is restarted.

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.

Note: Google Compute Engine enforces a metadata value length limit of 32768 bytes. If your startup script exceeds this limit, you won't be able to load it locally. Instead, you should save your file to Google Cloud Storage and specify the script URL on instance creation time. See Storing Your Script on Google Cloud Storage for more information.

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
    # Installs apache and a custom homepage
    
    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
    # Installs apache and a custom homepage
    
    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 gcutil addinstance 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.

    $ gcutil addfirewall http2 --description="Incoming http allowed." --allowed="tcp:http" --project=<project-id>
    $ gcutil addinstance simple-apache --metadata_from_file=startup-script:install-apache.sh --project=<project-id>

    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. Use the --external_ip_address flag to assign 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:
        gcutil addinstance simple-apache --service_account_scope=storage-ro \
         --metadata=startup-script-url:<url> --project=<project-id>

        Note: gcutil 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, Google Compute Engine provides a list of aliases for common scopes which you can use with gcutil.


      • 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 may be able to 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:
          gcutil addinstance simple-apache \
           --metadata=startup-script-url:<url>  --project=<project-id>

      <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.

    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:

    gcutil --project=<project-id> getserialportoutput <instance-name>

    The serial console port output can also be viewed at the Google Compute Engine 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
    gcutil addinstance mystartupscript --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
    gcutil addinstance mystartupscript --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'
    Note: If you specify both the startup-script-url and startup-script metadata values, Google Compute Engine only uses the startup script specified by the startup-script-url and ignores the startup script specified by the startup-script value.

  4. View the page

    Check your instance's status, and when it is listed as RUNNING, browse to http://<your_external_ip>/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:

gcutil addinstance example-instance --metadata='foo:bar' --project=<project-id>

Now, you can access the value of foo from within an instance by ssh'ing into the instance and querying the metadata server:

user@example-instance:~$ curl http://metadata/computeMetadata/v1beta1/instance/attributes/foo
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
    # Installs apache and a custom homepage
    VALUE_OF_FOO=$(curl http://metadata/computeMetadata/v1beta1/instance/attributes/foo)
    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
    # Installs apache and a custom homepage
    VALUE_OF_FOO=$(curl http://metadata/computeMetadata/v1beta1/instance/attributes/foo)
    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:
    $ gcutil addinstance simple-apache --metadata_from_file=startup-script:install-apache.sh --metadata='foo:bar' --project=<project-id>

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.