Troubleshoot Cloud Workstations

This page contains troubleshooting information to help you resolve issues with Cloud Workstations.

Pull system images onto VMs

When you create workstations using your workstation configuration, Cloud Workstations pulls system images onto your VM from Artifact Registry (or Container Registry). The error message that appears is similar to the following:

System images cannot be pulled onto workstation VMs using this configuration.
Ensure that you have set up Cloud NAT or enabled Private Google Access for
Artifact Registry (and Container Registry).

Failure to pull these images may prevent you from being able to start your workstations. Here are some recommendations:

• Set up Cloud NAT or enable Private Google Access.
• Make sure APIs are enabled and are VPC accessible.
• Update firewall rules to allow TCP egress.
• Examine your Compute Engine VM startup logs for possible errors.

Set up Cloud NAT or enable Private Google Access

If you disabled public IP addresses on your configuration, use one of the following options:

• Set up Cloud NAT to allow Cloud Workstations to pull images on to your workstation VMs.

• Enable Private Google Access on your subnet. If you use the private.googleapis.com or the restricted.googleapis.com domain names, create DNS records to direct traffic to the IP addresses associated with those domains. Specifically, you need ensure you enable access to the Artifact Registry and Container Registry domains, which correspond respectively to *.pkg.dev and *.gcr.io.

For more information, see Configure Private Google Access > Advanced network configuration.

Make sure APIs are enabled and are VPC accessible

If your project is inside a VPC Service Controls perimeter, make sure that Cloud Storage API, Container Registry API, and Artifact Registry API are Virtual Private Cloud (VPC) accessible within your service perimeter.

Update firewall rules to allow TCP egress

Ensure that you allow TCP egress in your network on ports 80 and 443 to allow Cloud Workstations to pull images to your workstation.

Examine your Compute Engine VM startup logs for possible errors

If none of the preceding steps resolve the issue, you might be able to find the reason for failure in your Compute Engine VM startup script logs. VM names created for your configuration begin with CONFIG_NAME- followed by a unique identifier.

Use the following filter to filter your stackdriver logs:

SEARCH("CONFIG_NAME")
sourceLocation.function="main.setupAndRunScript"

Replace the following:

• CONFIG_NAME: name of your workstation configuration.

Note: Errors in the startup script logs won't necessarily be logged at severity ERROR. Don't add a severity filter while looking for errors in the logs.

If you don't see any logs with this filter ensure that you have enabled serial port logging on your project. If you specified a service account on your workstation configuration, ensure the service account has logginglogEntries.create permission on the project so it can write logs out to Cloud Logging. Try starting your workstation again after enabling serial port logging and adding the necessary permissions to ensure that the Compute Engine VM startup script is run again to generate the logs.