Use startup scripts on Windows VMs

Windows

A startup script is a file that performs tasks during the startup process of avirtual machine (VM) instance. Startup scripts can apply to all VMs in a projector to a single VM. Startup scripts specified by VM-level metadata overridestartup scripts specified by project-level metadata, and startup scripts onlyrun when a network is available. This document describes how to use startupscripts on Windows Server VM instances. For information about how to add aproject-level startup script, seegcloud compute project-info add-metadata.

Windows startup scripts must be Command shell (.cmd), PowerShell (.ps1), orbatch file scripts (.bat), and must have the appropriate file extension.

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

Copies the startup script to the VM
Task Scheduler runs the startup script as theLocalSystemaccountwhen the VM boots

For information about the various tasks related to startup scripts and when toperform each one, see thestartup scripts overview document.

Prerequisites

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

The guest environment includes theguest 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 environmentpreinstalled.
If you create a custom image, you mustmanually install the Google Guest Environment to ensurescripts from metadata and other Google Cloud features function properly.

Before you begin

Read theoverview of startup scripts.
Read about the basics ofVM metadata.
If you haven't already, set upauthentication. 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:
  gcloudinit
  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
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.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Metadata keys for Windows startup scripts

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

The following table shows the metadata keys that you can use for Windows startupscripts, and provides information about which key to use based on the storagelocation, size, and file type of the startup script.

Metadata key	Use for
`sysprep-specialize-script-ps1`	Passing an unsigned PowerShell script that is stored locally or added directly and that is up to 256 KB in size
`sysprep-specialize-script-cmd`	Passing a command shell script that is stored locally or added directly and that is up to 256 KB in size
`sysprep-specialize-script-bat`	Passing a batch file script that is stored locally or added directly and that is up to 256 KB in size
`sysprep-specialize-script-url`	Passing a batch file, Command shell, signed/unsigned PowerShell script or executable that is stored in Cloud Storage and that is greater than 256 KB in size
`windows-startup-script-ps1`	Passing an unsigned PowerShell script that is stored locally or added directly and that is up to 256 KB in size
`windows-startup-script-cmd`	Passing a command shell script that is stored locally or added directly and that is up to 256 KB in size
`windows-startup-script-bat`	Passing a batch file script that is stored locally or added directly and that is up to 256 KB in size
`windows-startup-script-url`	Passing a batch file, Command shell, signed/unsigned PowerShell script or executable that is stored in Cloud Storage and that is greater than 256 KB in size

For more information about the order of execution of the various types ofstartup scripts, see theGoogleCloudPlatform/compute-image-windowsrepository on GitHub.

Order of execution of Windows startup scripts

You can use multiple startup scripts. Startup scripts stored locally or addeddirectly execute before startup scripts that are stored inCloud Storage. The type of file containing the script also impacts theorder of execution. The following table shows, based on the metadata key, theorder of execution of Windows startup scripts.

Metadata key	Order of execution
`sysprep-specialize-script-ps1`	First during the initial boot
`sysprep-specialize-script-cmd`	Second during the initial boot
`sysprep-specialize-script-bat`	Third during the initial boot
`sysprep-specialize-script-url`	Fourth during the initial boot
`windows-startup-script-ps1`	First during each boot after the initial boot
`windows-startup-script-cmd`	Second during each boot after the initial boot
`windows-startup-script-bat`	Third during each boot after the initial boot
`windows-startup-script-url`	Fourth during each boot after the initial boot

Passing a Windows startup script directly

Permissions required for this task

To perform this task, you must have the followingpermissions:

All permissions required tocreate a new VM.
compute.instances.setMetadata on the VM.

Pass the contents of a batch file, Command shell, or unsigned PowerShell startupscript directly to a Windows Server VM. The following procedures show how topass an unsigned PowerShell script.

Console

Passing a Windows startup script directly to a new VM

In the Google Cloud console, go to theCreate an instance page.
Go to Create an instance
ForBoot disk, selectChange, and do the following:
1. On thePublic images tab, choose a Windows Serveroperating system.
2. ClickSelect.

Expand theAdvanced options section, and do thefollowing:

Expand theManagement section.

In theMetadata section, clickAdd item to set theKeyandValue:

Key: set towindows-startup-script-ps1.
Startup scripts passed to the VM by using metadata keys beginningwithwindows-startup-script run on every boot after the VM'sinitial boot.

Value: add the following script:

# Installing IISImport-Module servermanagerInstall-WindowsFeature Web-Server -IncludeAllSubFeature# Ensure the directory existsif (-not (Test-Path("C:\inetpub\wwwroot"))) {New-Item "C:\inetpub\wwwroot" -Type Directory}# Write the expanded string out to the file, overwriting the file if it already exists."<html><body><p>Windows startup script added directly.</p></body></html>" | Out-File -FilePath C:\inetpub\wwwroot\index.html -Encoding ascii -Force

ClickCreate.

Passing a Windows startup script directly to an existing VM

In the Google Cloud console, go to theVM instances page.
Go to VM instances
Click theName of the VM.
ClickEdit.
UnderMetadata, specify the following:
- key:windows-startup-script-ps1
- value: the contents of the startup script

Verifying the startup script

After the VM starts, view the external IP in a web browser to verify thatthe startup script created the website. You might have to wait about 10minutes for the sample startup script to finish.

gcloud (Bash)

Passing a Windows startup script directly to a new VM

Pass the contents of a startup script directly to a Windows Server VM when you create it by using the followinggcloud compute instances create command:

gcloud compute instances createVM_NAME \  --image-project=windows-cloud \  --image-family=windows-2019-core \  --metadata=windows-startup-script-ps1='Import-Module servermanager  Install-WindowsFeature Web-Server -IncludeAllSubFeature  "<html><body><p>Windows startup script added directly.</p></body></html>" > C:\inetpub\wwwroot\index.html'

ReplaceVM_NAME with the name of the VM.

Passing a Windows startup script directly to an existing VM

Add the startup script directly to an existing VM by using the followinggcloud compute instances add-metadata command:

gcloud compute instances add-metadataVM_NAME \  --image-project=windows-cloud \  --image-family=windows-2019-core \  --metadata=windows-startup-script-ps1='Import-Module servermanager  Install-WindowsFeature Web-Server -IncludeAllSubFeature  "<html><body><p>Windows startup script added directly.</p></body></html>" > C:\inetpub\wwwroot\index.html'

ReplaceVM_NAME with the name of the VM.

Verifying the startup script

After the VM starts, view the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

gcloud (Command Prompt)

Passing a Windows startup script directly to a new VM

Pass the contents of a startup script directly to a Windows Server VM when you create it by using the followinggcloud compute instances create command:

gcloud compute instances createVM_NAME ^  --image-project=windows-cloud ^  --image-family=windows-2019-core ^  --metadata=windows-startup-script-ps1='Import-Module servermanager  Install-WindowsFeature Web-Server -IncludeAllSubFeature  "<html><body><p>Windows startup script added directly.</p></body></html>" > C:\inetpub\wwwroot\index.html'

ReplaceVM_NAME with the name of the VM.

Passing a Windows startup script directly to an existing VM

Add the startup script directly to an existing VM by using the followinggcloud compute instances add-metadata command:

gcloud compute instances add-metadataVM_NAME ^  --image-project=windows-cloud ^  --image-family=windows-2019-core ^  --metadata=windows-startup-script-ps1='Import-Module servermanager  Install-WindowsFeature Web-Server -IncludeAllSubFeature  "<html><body><p>Windows startup script added directly.</p></body></html>" > C:\inetpub\wwwroot\index.html'

ReplaceVM_NAME with the name of the VM.

Verifying the startup script

After the VM starts, view the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

gcloud (PowerShell)

Passing a Windows startup script directly to a new VM

Pass the contents of a startup script directly to a Windows Server VM when you create it by using the followinggcloud compute instances create command:

gcloud compute instances createVM_NAME `  --image-project=windows-cloud `  --image-family=windows-2019-core `  --metadata=windows-startup-script-ps1='Import-Module servermanager  Install-WindowsFeature Web-Server -IncludeAllSubFeature  "<html><body><p>Windows startup script added directly.</p></body></html>" > C:\inetpub\wwwroot\index.html'

ReplaceVM_NAME with the name of the VM.

Passing a Windows startup script directly to an existing VM

Add the startup script directly to an existing VM by using the followinggcloud compute instances add-metadata command:

gcloud compute instances add-metadataVM_NAME `  --image-project=windows-cloud `  --image-family=windows-2019-core `  --metadata=windows-startup-script-ps1='Import-Module servermanager  Install-WindowsFeature Web-Server -IncludeAllSubFeature  "<html><body><p>Windows startup script added directly.</p></body></html>" > C:\inetpub\wwwroot\index.html'

ReplaceVM_NAME with the name of the VM.

Verifying the startup script

After the VM starts, view the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

REST

Passing a Windows startup script directly to a new VM

Pass the contents of a startup script directly to a Windows Server VMwhen you create it by using the followinginstances.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  ...  "networkInterfaces": [    {      "accessConfigs": [        {          "type": "ONE_TO_ONE_NAT"        }      ]    }  ],  "metadata": {    "items": [      {        "key": "windows-startup-script-ps1",        "value": "Import-Module servermanager\nInstall-WindowsFeature Web-Server -IncludeAllSubFeature\necho '<html><body><p>Windows startup script added directly.</p></body></html>' > C:\\inetpub\\wwwroot\\index.html"      }    ]  },  ...}

Replace the following:

PROJECT_ID: the project ID.
ZONE: the zone to create the VM in.

Passing a Windows startup script directly to an existing VM

Get themetadata.fingerprint value of the VM by using theinstances.get method:
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
Replace the following:
- PROJECT_ID: the ID of the project where the VMexists.
- ZONE: the zone of the VM.
- VM_NAME: the name of the VM.

Pass the startup script by using thefingerprint value, along with themetadata key and value for the startup script, in a call to theinstances.setMetadata method:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata{ "fingerprint":FINGERPRINT, "items": [   {     "key": "windows-startup-script-ps1",     "value": "Import-Module servermanager\nInstall-WindowsFeature Web-Server -IncludeAllSubFeature\necho '<html><body><p>Windows startup script added directly.</p></body></html>' > C:\\inetpub\\wwwroot\\index.html"   } ], ...}

Replace the following:

PROJECT_ID: the ID of the project where the VMexists.
ZONE: the zone of the VM.
VM_NAME: the name of the VM.
FINGERPRINT: themetadata.fingerprint valueobtained by using theinstances.getmethod.

Verifying the startup script

After the VM starts, view the external IP in a web browser to verify thatthe startup script created the website. You might have to wait about 10minutes for the sample startup script to finish.

Passing a Windows startup script from a local file

Permissions required for this task

To perform this task, you must have the followingpermissions:

All permissions required tocreate a new VM.
compute.instances.setMetadata on the VM.

You can store a startup script in a local batch file, Command shell script, orunsigned PowerShell script on your workstation and pass the local file asmetadata to a VM when you create it. You cannot use files stored on VMs asstartup scripts.

Before passing a Windows startup script from a local file to a VM, do thefollowing:

Create a local (.ps1) file to store the startup script.
Note the relative path from gcloud CLI to the startup script.

Add the following startup script to the file:

# Installing IISImport-Module servermanagerInstall-WindowsFeature Web-Server -IncludeAllSubFeature# Ensure the directory existsif (-not (Test-Path("C:\inetpub\wwwroot"))) {New-Item "C:\inetpub\wwwroot" -Type Directory}# Write the expanded string out to the file, overwriting the file if it already exists."<html><body><p>Windows startup script passed from a file on your local workstation.</p></body></html>" | Out-File -FilePath C:\inetpub\wwwroot\index.html -Encoding ascii -Force

gcloud (Bash)

Passing a Windows startup script from a local file to a new VM

Create a VM and pass the contents of a local file to be used as the startup script by using thegcloud compute instances create command with the--metadata-from-file flag:

gcloud compute instances createVM_NAME \  --image-project=windows-cloud \  --image-family=windows-2019-core \  --metadata-from-file=windows-startup-script-ps1=FILE_PATH

Replace the following:

VM_NAME: the name of the VM
FILE_PATH: the relative path to the startupscript file

Passing a Windows startup script from a local file to an existing VM

Pass a startup script to an existing VM from a local file by using the followinggcloud compute instances add-metadata command:

gcloud compute instances add-metadataVM_NAME \  --metadata-from-file=windows-startup-script-ps1=FILE_PATH

Replace the following:

VM_NAME: the name of the VM
FILE_PATH: the relative path to the startupscript file

Verifying the startup script

View the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

gcloud (Command Prompt)

Passing a Windows startup script from a local file to a new VM

Create a VM and pass the contents of a local file to be used as the startup script by using thegcloud compute instances create command with the--metadata-from-file flag:

gcloud compute instances createVM_NAME ^  --image-project=windows-cloud ^  --image-family=windows-2019-core ^  --metadata-from-file=windows-startup-script-ps1=FILE_PATH

Replace the following:

VM_NAME: the name of the VM
FILE_PATH: the relative path to the startupscript file

Passing a Windows startup script from a local file to an existing VM

Pass a startup script to an existing VM from a local file by using the followinggcloud compute instances add-metadata command:

gcloud compute instances add-metadataVM_NAME ^  --metadata-from-file=windows-startup-script-ps1=FILE_PATH

Replace the following:

VM_NAME: the name of the VM
FILE_PATH: the relative path to the startupscript file

Verifying the startup script

View the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

gcloud (PowerShell)

Passing a Windows startup script from a local file to a new VM

Create a VM and pass the contents of a local file to be used as the startup script by using thegcloud compute instances create command with the--metadata-from-file flag:

gcloud compute instances createVM_NAME `  --image-project=windows-cloud `  --image-family=windows-2019-core `  --metadata-from-file=windows-startup-script-ps1=FILE_PATH

Replace the following:

VM_NAME: the name of the VM
FILE_PATH: the relative path to the startupscript file

Passing a Windows startup script from a local file to an existing VM

Pass a startup script to an existing VM from a local file by using the followinggcloud compute instances add-metadata command:

gcloud compute instances add-metadataVM_NAME `  --metadata-from-file=windows-startup-script-ps1=FILE_PATH

Replace the following:

VM_NAME: the name of the VM
FILE_PATH: the relative path to the startupscript file

Verifying the startup script

View the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

Passing a Windows startup script from Cloud Storage

Permissions required for this task

To perform this task, you must have the followingpermissions:

All permissions required tocreate a new VM.
compute.instances.setMetadata on the VM.
Permission to access the bucket and script file in Cloud Storage. Check theaccess control settings on the bucket and file to ensure you have permission.

You can store a startup script as a batch file, Command shell script,signed/unsigned PowerShell script or executable in Cloud Storage andpass it to a VM when you create it. After you add a startup script toCloud Storage, you have a URL that you can use to reference the startupscript when you create a VM.

Before adding a startup script from a Cloud Storage bucket, do thefollowing:

Create a file to store the startup script. This example uses a PowerShell(.ps1) file.

Add the following PowerShell script to the file, which installs a web serverand creates a simple web page:

# Installing IISImport-Module servermanagerInstall-WindowsFeature Web-Server -IncludeAllSubFeature# Ensure the directory existsif (-not (Test-Path("C:\inetpub\wwwroot"))) {New-Item "C:\inetpub\wwwroot" -Type Directory}# Write the expanded string out to the file, overwriting the file if it already exists."<html><body><p>Windows startup script passed from Cloud Storage.</p></body></html>" | Out-File -FilePath C:\inetpub\wwwroot\index.html -Encoding ascii -Force

Create a Cloud Storage bucket.
Add the file to the Cloud Storage bucket.

Security implications

By default, project owners and project editors can accessCloud Storage files in the same project, unless there are explicitaccess controls that disallow it.
If the Cloud Storage bucket or object is less secure than metadata,there is a risk of privilege escalation if the startup script is modified andthe VM reboots. This is because after the VM reboots, the startup script runsasLocalSystem and can then use the permissions of the attached serviceaccount to access other resources.

Console

Passing a startup script that is stored in Cloud Storage to a new VM

In the Google Cloud console, go to theCreate an instance page.
Go to Create an instance
ForBoot disk, selectChange, and do the following:
1. On thePublic images tab, choose a Windows Serveroperating system.
2. ClickSelect.
In theIdentity and API access section, select a service account thathas theStorage Object Viewerrole.
Expand theAdvanced options section, and then do thefollowing:
1. Expand theManagement section.
2. In theMetadata section, add values for the following:
  - Key: the metadata key. Specify thewindows-startup-script-urlmetadata key so the script runs during every boot after the initialboot.
  - Value: the metadata value. Set to the Cloud Storagelocation of the startup script file using one of the following formats:
    - Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
    - gcloud storage URI:gs://BUCKET/FILE
    Replace the following:
    - BUCKET: the name of the bucket thatcontains the startup script file
    - FILE: the name of the startup scriptfile
To create the VM, clickCreate.

Passing a startup script that is stored in Cloud Storage to an existing VM

In the Google Cloud console, go to theVM instances page.
Go to VM instances
Click theName of the VM.
ClickEdit.
UnderMetadata, add the following values:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Verifying the startup script

View the external IP in a web browser to verify that the startup scriptcreated the website. You might have to wait about 10 minutes for the samplestartup script to finish.

gcloud (Bash)

Passing a startup script that is stored in Cloud Storage to a new VM

Pass a startup script that is stored in Cloud Storage to a WindowsServer VM by using the followinggcloud compute instances createcommand. For the value of the--scopes flag, usestorage-ro so the VM can accessCloud Storage.

gcloud compute instances createVM_NAME \  --image-project=windows-cloud \  --image-family=windows-2019-core \  --scopes=storage-ro \  --metadata=windows-startup-script-url=CLOUD_STORAGE_URL

Replace the following:

VM_NAME: the name of the VM.
CLOUD_STORAGE_URL: the metadata values. Set tothe location of the startup script file by using one of the followingformats:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Passing a startup script that is stored in Cloud Storage to an existing VM

Pass a startup script that is stored in Cloud Storage to anexisting VM by using the followinggcloud compute instances add-metadatacommand:

gcloud compute instances add-metadataVM_NAME \  --metadata=windows-startup-script-url=CLOUD_STORAGE_URL

Replace the following:

VM_NAME: the name of the VM.
CLOUD_STORAGE_URL: the metadata values. Set tothe location of the startup script file by using one of the followingformats:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Verifying the startup script

View the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

gcloud (Command Prompt)

Passing a startup script that is stored in Cloud Storage to a new VM

gcloud compute instances createVM_NAME ^  --image-project=windows-cloud ^  --image-family=windows-2019-core ^  --scopes=storage-ro ^  --metadata=windows-startup-script-url=CLOUD_STORAGE_URL

Replace the following:

VM_NAME: the name of the VM.
CLOUD_STORAGE_URL: the metadata values. Set tothe location of the startup script file by using one of the followingformats:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Passing a startup script that is stored in Cloud Storage to an existing VM

Pass a startup script that is stored in Cloud Storage to anexisting VM by using the followinggcloud compute instances add-metadatacommand:

gcloud compute instances add-metadataVM_NAME ^  --metadata=windows-startup-script-url=CLOUD_STORAGE_URL

Replace the following:

VM_NAME: the name of the VM.
CLOUD_STORAGE_URL: the metadata values. Set tothe location of the startup script file by using one of the followingformats:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Verifying the startup script

View the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

gcloud (PowerShell)

Passing a startup script that is stored in Cloud Storage to a new VM

gcloud compute instances createVM_NAME `  --image-project=windows-cloud `  --image-family=windows-2019-core `  --scopes=storage-ro `  --metadata=windows-startup-script-url=CLOUD_STORAGE_URL

Replace the following:

VM_NAME: the name of the VM.
CLOUD_STORAGE_URL: the metadata values. Set tothe location of the startup script file by using one of the followingformats:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Passing a startup script that is stored in Cloud Storage to an existing VM

Pass a startup script that is stored in Cloud Storage to anexisting VM by using the followinggcloud compute instances add-metadatacommand:

gcloud compute instances add-metadataVM_NAME `  --metadata=windows-startup-script-url=CLOUD_STORAGE_URL

Replace the following:

VM_NAME: the name of the VM.
CLOUD_STORAGE_URL: the metadata values. Set tothe location of the startup script file by using one of the followingformats:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Verifying the startup script

View the external IP in a web browser to verify that the startup script created the web site. You might have to wait about 10 minutes for the sample startup script to finish.

REST

Passing a startup script that is stored in Cloud Storage to a new VM

Pass a startup script that is stored in Cloud Storage to a WindowsServer VM by using the followinginstances.insertmethod. Tothescopes field, addhttps://www.googleapis.com/auth/devstorage.read_only so the VM can accessCloud Storage.

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": "windows-startup-script-url",        "value": "CLOUD_STORAGE_URL"      },      ...    ]  },  ...}

Replace the following:

PROJECT_ID: the project ID.
ZONE: the zone to create the VM in.
CLOUD_STORAGE_URL: the metadata value. Set tothe Cloud Storage location of the startup script file using oneof the following formats:
- Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
- gcloud storage URI:gs://BUCKET/FILE

Passing a startup script that is stored in Cloud Storage to an existing VM

Get themetadata.fingerprint value of the VM by using theinstances.get method:
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
Replace the following:
- PROJECT_ID: the ID of the project where the VMexists.
- ZONE: the zone of the VM.
- VM_NAME: the name of the VM
Pass the startup script by using thefingerprint value, along with themetadata key and value for the startup script, in a call to theinstances.setMetadata method:
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata{  "fingerprint":FINGERPRINT,  "items": [    {        "key": "windows-startup-script-url",        "value": "CLOUD_STORAGE_URL"    }  ],  ...}
```
Replace the following:
- PROJECT_ID: the ID of the project where the VMexists.
- ZONE: the zone of the VM.
- VM_NAME: the name of the VM.
- FINGERPRINT: themetadata.fingerprint valueobtained by using theinstances.getmethod.
- CLOUD_STORAGE_URL: the metadata value. Set tothe Cloud Storage location of the startup script file using oneof the following formats:
  - Authenticated URL:https://storage.googleapis.com/BUCKET/FILE
  - gcloud storage URI:gs://BUCKET/FILE

Verifying the startup script

View the external IP in a web browser to verify that the startup scriptcreated the website. You might have to wait about 10 minutes for the samplestartup script to finish.

Accessing metadata from a Windows startup script

In a startup script you can access metadata values. For example, you can use thesame script for multiple VMs, and parameterize each script individually bypassing different metadata values to each VM.

To access a custom metadata value from a startup script, do the following:

Create a startup script that queries the value of a metadata key. Forexample, the following PowerShell (.ps1) startup script queries the value of thefoo metadata key.

$METADATA_VALUE = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'} -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes/foo")# Installing IISImport-Module servermanagerInstall-WindowsFeature Web-Server -IncludeAllSubFeature# Ensure the directory existsif (-not (Test-Path("C:\inetpub\wwwroot"))) {New-Item "C:\inetpub\wwwroot" -Type Directory}# Write the expanded string out to the file, overwriting the file if it already exists."<html><body><p>Accessing metadata value of foo: $METADATA_VALUE</p></body></html>" | Out-File -FilePath C:\inetpub\wwwroot\index.html -Encoding ascii -Force

Set the value of thefoo metadata key when creating a VM by using thefollowinggcloud compute instances createcommand. For this example,the startup script is passed to the VM from a local file.
gcloud
```
gcloud compute instances createVM_NAME \  --image-project=windows-cloud \  --image-family=windows-2019 \  --metadata-from-file=windows-startup-script-ps1=FILE_PATH \  --metadata=foo=bar
```
Replace the following:
- VM_NAME: the name of the VM
- FILE_PATH: the relative path to the startupscript file
For more information about how to specify a metadata key-value pair, seeSet and remove custom metadata.
View the external IP in a web browser to verify that the startup scriptoutputs the value offoo. You might have to wait about 10 minutes for thesample startup script to finish.

Rerunning a Windows startup script

Rerun a startup script on a Windows VM by doing the following:

Connecting to the VM.

Running the following command:

C:\Program Files\Google\Compute Engine\metadata_scripts\run_startup_scripts.cmd

Viewing the output from a Windows startup script

View the output from a Windows Server startup script by using any of thefollowing and checking forGCEMetadataScripts events:

Serial port 1 in the Google Cloud console. For more information, seeViewing serial port output.
Windows Event Viewer's Application Log.
IAP Desktop from a Windows workstation. For more information, see theGoogleCloudPlatform/iap-desktoprepository on GitHub.

What's next

Learn how touse startup scripts on Linux VMs.
Learn how toadd a shutdown script.
Learn more aboutVM metadata.
Learn how torun startup scripts on Windows VMs and join aManaged Microsoft AD domain.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.

Movatterモバイル変換

Use startup scripts on Windows VMs Stay organized with collections Save and categorize content based on your preferences.

Prerequisites

Before you begin

Console

gcloud

REST

Metadata keys for Windows startup scripts

Order of execution of Windows startup scripts

Passing a Windows startup script directly

Permissions required for this task

Console

gcloud (Bash)

gcloud (Command Prompt)

gcloud (PowerShell)

REST

Passing a Windows startup script from a local file

Permissions required for this task

gcloud (Bash)

gcloud (Command Prompt)

gcloud (PowerShell)

Passing a Windows startup script from Cloud Storage

Permissions required for this task

Security implications

Console

gcloud (Bash)

gcloud (Command Prompt)

gcloud (PowerShell)

REST

Accessing metadata from a Windows startup script

gcloud

Rerunning a Windows startup script

Viewing the output from a Windows startup script

What's next

Use startup scripts on Windows VMs