Use a startup script on Windows VMs

A startup script performs tasks during the start-up process for a virtual machine (VM). This page provides you with the steps to follow for using startup scripts on VM instances.

Before you begin

To use gdcloud command-line interface (CLI) commands, ensure that you have downloaded, installed, and configured the gdcloud CLI. All commands for GDC air-gapped appliance use the gdcloud or kubectl CLI, and require an operating system (OS) environment.

Get the kubeconfig file path

To run commands against the Management API server, ensure you have the following resources:

  1. Locate the Management API server name, or ask your Platform Administrator (PA) what the server name is.

  2. Sign in and generate the kubeconfig file for the Management API server if you don't have one.

  3. Use the path to replace MANAGEMENT_API_SERVER{"</var>"}} in these instructions.

Request permissions and access

To perform the tasks listed in this page, you must have the Project VirtualMachine Admin role. Follow the steps to either verify your access or have your Project IAM Admin assign you the Project VirtualMachine Admin (project-vm-admin) role in the namespace of the project where the VM resides.

Format Windows startup script names

Startup scripts for Windows VMs must follow a specific naming format with the script name and the file extension appended, separated by dashes. For example, create-directory-ps1, with create-directory as the script name and ps1 as the file extension. Incorrect formats include using periods in place of dashes and omitting the file extension, such as create-directory.ps1 and create-directory.

The following shows the file extensions to use for Windows startup scripts:

  • ps1: Contains PowerShell commands.
  • cmd: Contains batch commands for the Command Prompt interpreter.
  • bat: Contains batch commands.

Run Windows startup scripts in order

You can use multiple startup scripts. The type of file containing the script impacts the order of running each script. The following table shows the order of running Windows startup scripts:

Windows script Order to run
Powershell script First on every boot.
Batch script Second on every boot.
Command script Third on every boot.

If two startup scripts have the same file extension, the scripts are run based on the file extension and name in alphabetical order. For example, if your startup script names are alpha-script-ps1 and beta-script-ps1, alpha-script-ps1 runs before beta-script-ps1.

The following example VM specification shows the Windows startup script order and structure in the startupScripts field:

...
  startupScripts:
  - name: create-directory-ps1
    script: |-
      New-Item -ItemType Directory -Path C:\ -Name NewDir
      Get-ChildItem -Path C:\
  - name: hello-world-bat
    script: |-
      ECHO "Hello World!"
  - name: list-directories-cmd
    script: |-
      dir C:\Windows  > files.txt
...

Pass a startup script

GDC air-gapped appliance runs startup scripts in alphabetical order, based on the name of each startup script.

The following table shows the script format to use based on your script size:

Script size Script format
Scripts up to 2048 bytes Clear text
Scripts greater than 2048 bytes Kubernetes secret

Define a startup script

To use a startup script you must add the startupScripts field to the VM spec field. Within this field you can specify multiple startup scripts as clear text or as a Kubernetes secret.

The following example specifies the startup scripts as clear text and a Kubernetes secret:

apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachine
metadata:
  name: "vm-test"
spec:
  ...
  startupScripts:
  - name: create-directory-ps1
    script: |-
      New-Item -ItemType Directory -Path C:\ -Name NewDir
      Get-ChildItem -Path C:\
  - name: list-directories-cmd
    scriptSecretRef:
      name: list-directories
---

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: list-directories
data: 
  script:
    ZGlyIEM6XFdpbmRvd3MgID4gZmlsZXMudHh0Cg==

Review the following considerations:

  • The startup script runs on every boot.
  • The startup script has default root privileges.
  • In the Kubernetes secret, the name of the scriptSecretRef in the VM spec must match the metadata.name field.
  • In the Kubernetes secret, specify the startup script content by adding a key script to the data field.

Create a new VM with a Windows startup script

To create a VM with a Windows startup script, follow the steps in Create a new VM with a startup script.