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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/resources/gdcloud-overview).
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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/iam/sign-in#cli) 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 IAM roles

To use startup scripts for a VM, contact your Project IAM Admin to request the
following roles on your project:

- **Project VirtualMachine Admin** (`project-vm-admin`): create, modify, list,
  and delete VMs in the project namespace.

- **Secret Admin** (`secret-admin`): get, list, create, update, delete, patch,
  and watch Kubernetes secrets in the project namespace. Use this role to specify
  startup script secrets. You don't need this role to specify plain text startup
  scripts.

All VM roles must bind to the namespace of the project where the VM resides.
Follow the steps to [verify](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/vms/preparation#verify-user-access)
your access.

## 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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/vms/manage-the-os/startup-script-vm-instance#create-new-vm-startup-script).