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.

## Pass a startup script

You can use either bash or non-bash scripts as startup scripts. To do so,
include `#!/bin/...` at the beginning of the script to indicate the script interpreter.
For example, to use a Python 3 startup script, add `#! /usr/bin/python3` to the
beginning of the script.

Google Distributed Cloud (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: "my-vm"
    spec:
      ...
      startupScripts:
      - name: hello-world
        script: |
          #!/bin/bash
          echo hello
      - name: add-user
        scriptSecretRef:
          name: add-user
    ---

    apiVersion: v1
    kind: Secret
    type: Opaque
    metadata:
      name: add-user
    data: 
      script:
        IyEvYmluL2Jhc2gKYWRkdXNlciB1c2VyCg==

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 startup script

These instructions apply regardless of what you use as the image to create your
VM. Complete the following:

1. To create a startup script as a Kubernetes secret, run:

       cat <<EOF >>FILE_NAME
       STARTUP_SCRIPT_CONTENT
       EOF

       kubectl --kubeconfig MANAGEMENT_API_SERVER create secret -n PROJECT generic SECRET_NAME --from-file=script=FILE_NAME

       rm FILE_NAME

2. Reference the steps to create a VM as described on the
   [create a VM](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/vms/create-a-vm/create-and-start) page.
   At [step one](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/vms/create-a-vm/create-and-start#create-vm-from-provided-image) add the startup script or scripts to the `spec` field before you run the command to
   create a VM.

   This example defines a startup script with both clear text and a Kubernetes
   secret:

       apiVersion: virtualmachine.gdc.goog/v1
       kind: VirtualMachine
       metadata:
       name: VM_NAME
       namespace: PROJECT
       spec:
       ...
       startupScripts:
       - name: CLEAR_TEXT_SCRIPT_NAME
         script: |
           #!/bin/bash
           CLEAR_TEXT_SCRIPT
       - name: SECRET_SCRIPT_NAME
         scriptSecretRef:
           name: SECRET_NAME

   These variables are defined as follows:

   | Variable | Definition |
   |---|---|
   | `MANAGEMENT_API_SERVER` | The Management API server `kubeconfig` file. |
   | `PROJECT` | The GDC air-gapped appliance project in which you want to create the VM. |
   | `VM_NAME` | The name of the VM. |
   | `FILE_NAME` | The name of the file to store the startup script. |
   | `STARTUP_SCRIPT_CONTENT` | The commands to run as part of the startup script |
   | `CLEAR_TEXT_SCRIPT_NAME` | The name of the clear text startup script. |
   | `CLEAR_TEXT_SCRIPT` | The clear text script you define. |
   | `SECRET_NAME` | The name of the Kubernetes secret. |
   | `SECRET_SCRIPT_NAME` | The name of the startup script as a Kubernetes secret. |

3. Proceed with the following steps to create a VM.

   The following is an example of how to create a VM with startup scripts
   that adds a new user using a Kubernetes secret and clear text.

       kubectl --kubeconfig MANAGEMENT_API_SERVER \
           apply -n PROJECT -f - <<EOF
       apiVersion: virtualmachine.gdc.goog/v1
       kind: VirtualMachineDisk
       metadata:
         name: VM_BOOT_DISK_NAME
       spec:
         source:
           image:
             name: BOOT_DISK_IMAGE_NAME
             namespace: vm-system
         size: BOOT_DISK_SIZE
       ---
       apiVersion: v1
       kind: Secret
       type: Opaque
       metadata:
         name: add-user
       data: 
         script:
           IyEvYmluL2Jhc2gKYWRkdXNlciB1c2VyCg==
       ---
       apiVersion: virtualmachine.gdc.goog/v1
       kind: VirtualMachine
       metadata:
         name: VM_NAME
       spec:
         compute:
           virtualMachineType: MACHINE_TYPE
         disks:
         - virtualMachineDiskRef:
             name: VM_BOOT_DISK_NAME
           boot: true
           autoDelete: BOOT_DISK_AUTO_DELETE
         startupScripts:
         - name: add-user
           scriptSecretRef:
             name: add-user
         - name: add-to-sudoers
           script: |
             #!/bin/bash
             usermod -aG sudo user
       EOF

   In the example the variables are defined as follows.

   | Variable | Definition |
   |---|---|
   | `MANAGEMENT_API_SERVER` | The Management API server `kubeconfig` file. |
   | `PROJECT` | The GDC air-gapped appliance project in which you want to create the VM. |
   | `VM_NAME` | The name of the new VM. |
   | `VM_BOOT_DISK_NAME` | The name of the new VM boot disk. |
   | `BOOT_DISK_IMAGE_NAME` | The name of the image to be used for the new VM boot disk. |
   | `BOOT_DISK_SIZE` | The size of the boot disk, such as `20G`. This value must always be greater than or equal to the `minimumDiskSize` of the boot disk image. |
   | `BOOT_DISK_AUTO_DELETE` | Either `true` or `false`, indicating whether the boot disk is automatically deleted when the VM instance gets deleted. |
   | `MACHINE_TYPE` | The predefined machine type for the new VM. To select an available machine type, run this command: ` kubectl --kubeconfig MANAGEMENT_API_SERVER get virtualmachinetype.virtualmachine.gdc.goog --namespace vm-system ` |

## Update an existing VM with a startup script

You can also update an existing VM with a startup script. The VM must be shut
down before you perform the update.

Follow the steps to [update VM properties](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/vms/manage-vms/operations-and-lifecycle/update-vm-properties#update-properties)
and update the `spec` field with the startup script that you would like to run.

## View the output of a startup script

1. Follow the steps to [connect to a VM](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/vms/connect-to-vm/connect-to-a-vm).
2. Run the following command inside the guest VM to get the logs of the
   startup script that you ran:

       sudo journalctl -u cloud-final

   The startup script logs begin with the following:

       Started to run the command: /var/lib/google/startup-scripts/<script-name> ...