Run custom startup scripts

Cloud Workstations lets you run custom startup scripts on the host workstation VM before your workstation container starts. This is useful for performing VM-level configuration or installing additional software that needs to run outside the main workstation container.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

gcloud init

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

gcloud init

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Prepare your startup script

Create the startup script that you want to run on the host workstation VM. When writing your script, adhere to the following guidelines:

  1. Cloud Workstations runs your specified workstation container as well as several system containers on the host workstation VM to ensure your workstation functions properly. All containers run using the containerd runtime and the crictl client.
  2. Run any additional containers launched by your startup script using containerd. Docker is disabled on the host VM to prevent interference with the Docker daemon running inside your workstation container.
  3. Host-level containers launched by your startup script can't interact with the main workstation container. These direct interactions are unsupported because they bypass Identity and Access Management (IAM) checks.

Store your startup script in Cloud Storage

Upload your script to a Cloud Storage bucket and ensure the script is accessible by the service account associated with your workstation.

  1. Upload your script to a bucket:

    gcloud storage cp LOCAL_SCRIPT_PATH gs://BUCKET_NAME/SCRIPT_NAME

    Replace the following:

    • LOCAL_SCRIPT_PATH: the local path to your startup script file.
    • BUCKET_NAME: the name of your Cloud Storage bucket.
    • SCRIPT_NAME: the name you want to give the script file in the bucket.

  2. Ensure the service account used by your workstation configuration has permissions to access the bucket and script file. Alternatively, the script can be publicly accessible.

Create a workstation configuration

To use a custom startup script, create a workstation configuration and set the startupScriptUri field in a host.gceInstance message to the Cloud Storage URI of your script.

Create the workstation configuration using the REST API:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "host": {
         "gceInstance": {
           "poolSize": 1,
           "startupScriptUri": "gs://BUCKET_NAME/SCRIPT_NAME",
           "serviceAccount": "SERVICE_ACCOUNT"
         }
       }
     }' \
     https://workstations.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/workstationClusters/CLUSTER_ID/workstationConfigs?workstation_config_id=CONFIG_ID

Replace the following:

  • SERVICE_ACCOUNT: the email address of the service account associated with the workstation configuration.
  • PROJECT_ID: your Google Cloud project ID.
  • LOCATION: the region where your workstation cluster is located.
  • CLUSTER_ID: the ID of your workstation cluster.
  • CONFIG_ID: the ID you want to assign to the new workstation configuration.

Verify script execution

To verify that your script ran correctly, use one of the following methods:

  • Serial port 3 output logs: output logs generated by your script are automatically sent to serial port 3 output. To find the name of the VM assigned to your workstation, see the platform logs.
  • SSH into your VM: you can SSH into your workstation VM to further debug your script if needed.
  • Readiness checks: startup scripts are best-effort and don't block your workstation from starting. If your script takes a long time to run or fails, the workstation might still be marked as ready. To ensure the workstation is not marked ready until your script completes, consider implementing readiness checks.

What's next