GCP VM Startup Scripts Explained: How to Use, Debug, and Secure Them

Simple explanation

A startup script is a shell script attached to the VM’s metadata. Compute Engine reads the metadata and runs the script as root shortly after the OS finishes booting. It runs on every boot, not just the first one. That means if you restart a VM, or if a managed instance group replaces it with a fresh copy, the script runs again.

Common uses: installing a web server, pulling a config file from Cloud Storage, registering the VM with a service registry, or setting up environment variables before an application starts.

Because the script runs on every boot, you should write actions to be safe to repeat. This property is called idempotency. Installing a package with apt-get install -y nginx is idempotent by default: if nginx is already there, apt does nothing. Creating a file, seeding a database, or calling an external API to register the VM is not idempotent unless you add a guard condition first.

How startup scripts work in Compute Engine

When a Compute Engine VM boots, the guest OS starts a service called google-startup-scripts.service. This systemd unit reads the instance metadata server at http://metadata.google.internal and looks for one of two keys:

• startup-script — the script text stored directly in metadata

• startup-script-url — a Cloud Storage path from which the VM downloads and runs the script

The script executes as root. Both stdout and stderr are captured by the systemd journal and also streamed to the serial console, which is how you read the output when the VM is not yet accessible over SSH.

Ways to pass a startup script

There are three methods. The right one depends on how you are managing your VMs and whether the script changes frequently.

Inline script with metadata

Pass the script text directly on the command line using —metadata=startup-script=’…’. This is the fastest way to get started and works well for short scripts.

gcloud compute instances create my-web-server \
  --machine-type=e2-medium \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --zone=us-central1-a \
  --metadata=startup-script='#!/bin/bash
set -e
apt-get update -y
apt-get install -y nginx
systemctl enable nginx
systemctl start nginx
echo "Startup complete" > /tmp/startup-done'

Inline scripts are convenient for testing but become unwieldy for anything longer than a few lines. For scripts you want to version-control or reuse, use one of the file-based methods below.

Script from a local file

Keep the script in a file and reference it with —metadata-from-file. The script lives in source control alongside your infrastructure code, and the command stays readable.

gcloud compute instances create my-web-server \
  --machine-type=e2-medium \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --zone=us-central1-a \
  --metadata-from-file=startup-script=./startup.sh

The file path is local — it exists on the machine running the gcloud command. The contents are read and stored in the VM’s metadata at creation time. If you update the file later, existing VMs are not affected unless you update their metadata explicitly.

Script from Cloud Storage with startup-script-url

Upload the script to a Cloud Storage bucket and reference it with —metadata=startup-script-url=gs://…. The VM downloads and runs the script from GCS at each boot.

# Upload the script to Cloud Storage
gcloud storage cp startup.sh gs://my-config-bucket/startup.sh

# Create a VM that fetches the script from GCS at boot
gcloud compute instances create my-web-server \
  --machine-type=e2-medium \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --zone=us-central1-a \
  --metadata=startup-script-url=gs://my-config-bucket/startup.sh

This is the recommended approach for scripts shared across multiple VMs or used in instance templates. Update the script in Cloud Storage once and every subsequent boot picks up the new version, with no need to recreate templates or update instance metadata manually. The VM’s service account needs storage.objects.get permission on the bucket to download the file.

When to use startup scripts

Startup scripts work best for lightweight, repeatable setup tasks. Here are the most common situations where they shine:

• Installing a web server on boot. A fresh VM from a public Debian or Ubuntu image has no application server installed. A startup script installs nginx and starts it automatically, no SSH session required.

• Pulling config at runtime. Download an application config file from Cloud Storage or fetch a database connection string from Secret Manager. Config stays separate from the image, so you can update it without rebuilding anything.

• Bootstrapping stateless VMs in a managed instance group. Every VM the group creates is ephemeral. A startup script ensures each one installs the same version of your app and starts the same services, without human involvement.

• Basic fleet initialisation. Install monitoring agents, configure log forwarders, or register the VM with an internal service registry at boot.

• Lab and learning environments. Pre-configure a VM for a workshop or demo so participants arrive at a ready environment. Create the VM from scratch and have the script install tools and clone repos automatically.

Startup scripts vs custom VM images

Both startup scripts and custom VM images give you VMs that start in a known state. They solve the same problem in different ways, and understanding the trade-offs helps you pick the right one — or decide to use both.

Startup scripts are flexible. You update the script in Cloud Storage and the next boot picks it up with no build process. They work well for lightweight setup, runtime config, and logic that changes frequently. The downside: every boot runs setup from scratch, which adds time and can fail if a package repository or external API is temporarily unavailable.

Custom images bake software directly onto the disk before the VM is ever created. Boot time is fast and consistent. The trade-off is that building, testing, and maintaining images takes more effort. Every OS update or package change requires a new image build.

Many teams use both. A custom image handles the base OS, security hardening, and heavy dependencies like language runtimes or databases. A startup script handles lighter, environment-specific work: pulling a config file, fetching a secret, and starting the application.

Debugging a startup script

When a startup script fails, the VM often boots normally from the OS perspective. Health checks may pass while your application is not running. Knowing where to look makes the difference between a 2-minute fix and 30 minutes of guessing.

Serial console output

The serial console captures everything the startup script prints to stdout and stderr, even before SSH is available. Check this first.

gcloud compute instances get-serial-port-output my-web-server \
  --zone=us-central1-a

Scroll to the section starting with Starting Google Compute Engine Startup Scripts. The last line before output cuts off is usually where the script failed.

journalctl after SSH

Once you can SSH into the VM, view the full startup script service log:

sudo journalctl -u google-startup-scripts.service

This shows complete output with timestamps. Use —no-pager to print everything at once, or pipe to grep -i error to filter for failures.

Checking syslog

sudo grep -i startup /var/log/syslog

On Debian and Ubuntu, syslog captures startup script messages alongside other system events. Useful when you want a wider picture of what was happening on the system when the script ran.

Common reasons scripts fail

• Package manager not yet ready. The script ran before the network was fully up, so apt-get update failed. Add a short retry before the first package install if you see this on fresh VMs.

• Bad shebang line. A script starting with #!/bin/sh may break on bash-specific syntax. Use #!/bin/bash unless you have tested for POSIX compatibility.

• Syntax errors. Run bash -n script.sh locally to check for syntax problems before uploading the script.

• Permission denied. Mounted Cloud Storage FUSE paths or network shares may not be writable as root. Check the error message for the exact path.

• Missing APIs or IAM roles. Calls to gcloud secrets fail if the Secret Manager API is not enabled or the VM’s service account lacks the required role. The error is usually a clear 403 or “API not enabled” message in the log.

Security considerations

Startup scripts are powerful, but their default storage mechanism creates a real security risk if you are not careful.

The correct pattern is to fetch secrets at runtime from Secret Manager using the VM’s attached service account. The VM authenticates automatically. No key file is needed in the script:

#!/bin/bash
set -e

# Fetch the database password at boot using the VM's service account identity
DB_PASSWORD=$(gcloud secrets versions access latest \
  --secret="my-db-password" \
  --project="my-project-id")

# Use the secret to configure the application
echo "DB_PASSWORD=${DB_PASSWORD}" >> /etc/app/config.env
systemctl restart my-app

Additional security practices to follow:

• Scope service account permissions narrowly. Avoid attaching the broad cloud-platform scope unless the script genuinely needs it. Grant only the IAM roles the script actually calls. The principle of least privilege applies here as much as anywhere else.

• Restrict the GCS bucket holding the script. If you use startup-script-url, the bucket should not be publicly readable. Grant the VM’s service account storage.objects.get on that bucket only.

• Grant Secret Manager access at the secret level. The VM’s service account needs roles/secretmanager.secretAccessor on the specific secret, not on all secrets in the project.

Shutdown scripts

A shutdown script is the counterpart to a startup script. It runs when the VM is stopped or restarted, before the OS shuts down. Use it to drain active connections, flush logs to a persistent store, or deregister the VM from a service registry so traffic stops routing to it before it disappears.

A Linux shutdown script has roughly 90 seconds to complete. Keep it short and focused on cleanup, not heavy processing.

gcloud compute instances create my-web-server \
  --machine-type=e2-medium \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --zone=us-central1-a \
  --metadata=shutdown-script='#!/bin/bash
systemctl stop nginx
echo "Shutdown complete at $(date)" >> /var/log/shutdown.log'

Startup scripts in instance templates and managed instance groups

When you run a fleet of VMs with a managed instance group, the startup script belongs in the instance template. Every VM the group creates — whether to meet a minimum size, respond to autoscaling, or replace an unhealthy instance — inherits the template and runs the same script automatically.

# Create a template that fetches its script from Cloud Storage
gcloud compute instance-templates create web-server-template \
  --machine-type=e2-medium \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --metadata=startup-script-url=gs://my-config-bucket/startup.sh \
  --service-account=my-sa@my-project.iam.gserviceaccount.com \
  --scopes=cloud-platform

Using startup-script-url in the template rather than embedding the script inline has a practical advantage: you can update the script in Cloud Storage without creating a new template version. The next VM boot picks up the updated script automatically.

Instance templates are immutable once created. If you embed the script inline and later need to change it, you must create a new template version. The GCS URL approach avoids this for script changes, though it does not help for other settings like machine type or disk size, which always require a new template.