/

Console

• English
• Deutsch
• Español
• Español – América Latina
• Français
• Indonesia
• Italiano
• Português
• Português – Brasil
• עברית
• 中文 – 简体
• 中文 – 繁體
• 日本語
• 한국어

Sign in

• Compute Engine

Start free

Use startup scripts on Linux VMs

A startup script is a file that performs tasks during the startup process of a virtual machine (VM) instance. Startup scripts can apply to all VMs in a project or to a single VM. Startup scripts specified by VM-level metadata override startup scripts specified by project-level metadata, and startup scripts only run when a network is available. This document describes how to use startup scripts on Linux VM instances. For information about how to add a project-level startup script, see gcloud compute project-info add-metadata.

For Linux startup scripts, you can use bash or non-bash file. To use a non-bash file, designate the interpreter by adding a #! to the top of the file. For example, to use a Python 3 startup script, add #! /usr/bin/python3 to the top of the file.

If you specify a startup script by using one of the procedures in this document, Compute Engine does the following:

1. Copies the startup script to the VM

2. Sets run permissions on the startup script

3. Runs the startup script as the root user when the VM boots

For information about the various tasks related to startup scripts and when to perform each one, see the Overview.

Prerequisites

To run scripts stored in metadata on a VM instance, the guest environment must be installed and running.

• The guest environment includes the guest agent (for example, google-guest-agent on Linux) that reads the script content or URL from the instance's metadata and initiates execution.
• All public Compute Engine images come with the guest environment preinstalled.
• If you create a custom image, you must manually install the Google Guest Environment to ensure scripts from metadata and other Google Cloud features function properly.

Before you begin

• Read the overview of startup scripts.
• Read about the metadata server.
• If you haven't already, set up authentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Set a default region and zone.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Metadata keys for Linux startup scripts

A startup script is passed to a VM from a location that is specified by a metadata key. A metadata key specifies whether the startup script is stored locally, stored in Cloud Storage, or passed directly to the VM. The metadata key that you use might also depend on the size of the startup script.

The following table shows the metadata keys that you can use for Linux startup scripts, and provides information about which key to use based on the storage location and size of the startup script.

Order of execution of Linux startup scripts

You can use multiple startup scripts. Startup scripts stored locally or added directly execute before startup scripts that are stored in Cloud Storage. The following table shows, based on the metadata key, the order of execution of Linux startup scripts.

Passing a Linux startup script directly

You can add the contents of a startup script directly to a VM when you create the VM. The following procedures show how to create a VM with a startup script that installs Apache and creates a basic web page.

Permissions required for this task

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

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

gcloud compute instances create VM_NAME \
  --image-project=debian-cloud \
  --image-family=debian-10 \
  --metadata=startup-script='#! /bin/bash
  apt update
  apt -y install apache2
  cat <<EOF > /var/www/html/index.html
  <html><body><p>Linux startup script added directly.</p></body></html>
  EOF'

gcloud compute instances add-metadata VM_NAME \
    --zone=ZONE \
    --metadata=startup-script='#! /bin/bash
    apt update
    apt -y install apache2
    cat <<EOF > /var/www/html/index.html
    <html><body><p>Linux startup script added directly.</p></body></html>
    EOF'

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  ...
  "networkInterfaces": [
    {
      "accessConfigs": [
        {
          "type": "ONE_TO_ONE_NAT"
        }
      ]
    }
  ],
  "metadata": {
    "items": [
      {
        "key": "startup-script",
        "value": "#! /bin/bash\napt update\napt -y install apache2\ncat <<EOF > /var/www/html/index.html\n<html><body><p>Linux startup script added directly.</p></body></html>\nEOF"
      }
    ]
  },
  ...
}

Passing a Linux startup script from a local file

You can store a startup script in a local file on your workstation and pass the local file as metadata to a VM when you create it. You cannot use files stored on VMs as startup scripts.

Before passing a Linux startup script from a local file to a VM, do the following:

1. Create a local file to store the startup script.

2. Note the relative path from gcloud CLI to the startup script.

3. Add the following startup script to the file:

   #! /bin/bash
   apt update
   apt -y install apache2
   cat <<EOF > /var/www/html/index.html
   <html><body><p>Linux startup script from a local file.</p></body></html>
   EOF
   

gcloud compute instances create VM_NAME \
  --image-project=debian-cloud \
  --image-family=debian-10 \
  --metadata-from-file=startup-script=FILE_PATH

gcloud compute instances add-metadata VM_NAME \
  --zone=ZONE \
  --metadata-from-file startup-script=FILE_PATH

gcloud compute instances create VM_NAME \
  --image-project=debian-cloud \
  --image-family=debian-10 \
  --scopes=storage-ro \
  --metadata=startup-script-url=CLOUD_STORAGE_URL

gcloud compute instances add-metadata VM_NAME \
    --zone=ZONE \
    --metadata startup-script-url=CLOUD_STORAGE_URL

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  ...
  "networkInterfaces": [
    {
      "accessConfigs": [
        {
          "type": "ONE_TO_ONE_NAT"
        }
      ]
    }
  ],
  "serviceAccounts": [
    {
      "email": "default",
      "scopes": [
        "https://www.googleapis.com/auth/devstorage.read_only"
      ]
    }
  ],
  "metadata": {
    "items": [
      {
        "key": "startup-script-url",
        "value": "CLOUD_STORAGE_URL"
      }
    ]
  },
  ...
}