Hide
Google Compute Engine

Startup Scripts

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.

This page discusses startup scripts for Linux virtual machines; to use startup scripts with Windows instances, see the Windows documentation.

Contents

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, Google Compute Engine 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-port-output INSTANCE
    

    The serial console port output can also be viewed at the Google Developers Console or through the getSerialPortOutput() 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, your instance has started. This particular startup script will execute quickly, and Apache should be up and running within a few seconds. To check, browse to http://<your_external_ip>/index.html to see your default page. Note that other startup scripts can take longer to execute and might still be executing even though the instance status is RUNNING.

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.

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