Enable virtual displays on a VM

This document describes how to enable or disable virtual displays on a virtual machine (VM) instance.

If an application running on your VM requires a display device, but you don't need the performance of a GPU, then configure your VM to use virtual display devices. By enabling virtual displays on a VM, you can run virtual display devices on the VM, such as remote system management tools, remote desktop software, and screen capturing.

Before you begin

• If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

  2. Set a default region and zone.

  Terraform

  To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  For more information, see Set up authentication for a local development environment.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to enable or disable virtual displays on a VM, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to enable or disable virtual displays on a VM. To see the exact permissions that are required, expand the Required permissions section:

You might also be able to get these permissions with custom roles or other predefined roles.

Pricing

There are no costs associated with enabling or disabling virtual displays on a VM.

Restrictions

For VMs with virtual displays enabled, the following limitations apply:

• If your VM is running an x64-based Windows OS image earlier than version v20190312, then, after enabling virtual displays on your VM, you must install the virtual display driver as described in this document. If your VM is running a later OS image version, then the driver is already installed on the OS image.

• You can use a virtual display device on the VM only after the guest OS boots and initializes the virtual display driver.

• You can't use virtual display devices on VMs that run the Sandy Bridge CPU platform.

• You can't use virtual display devices on T2A Arm VMs.

Enable virtual displays on a VM

To enable virtual displays on a VM, select one of the following methods described in this document:

• Create a VM with virtual displays enabled.

• Enable virtual displays on an existing VM.

If your VM is running an x64-based Windows OS image earlier than version v20190312, then, after you enable virtual displays on the VM, install the virtual display driver as described in this document.

Create a VM with virtual displays enabled

To create a VM with virtual displays enabled, select one of the following options:

gcloud compute instances create VM_NAME \
    --enable-display-device \
    --machine-type=MACHINE_TYPE \
    --zone=ZONE

resource "google_compute_instance" "instance_virtual_display" {
  name         = "instance-virtual-display"
  machine_type = "f1-micro"
  zone         = "us-central1-c"

  # Set the below to true to enable virtual display
  enable_display = true

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }
  network_interface {
    # A default network is created for all GCP projects
    network = "default"
    access_config {
    }
  }
}

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "VM_NAME",
  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "project/IMAGE_PROJECT/global/images/IMAGE"
      }
    }
  ],
  "displayDevice": {
    "enableDisplay": true
  },
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ]
}

For more information about creating a VM, see Create and start a Compute Engine instance.

Enable virtual displays on an existing VM

Before enabling virtual displays on a VM, make sure to stop the VM.

To enable virtual displays on an existing VM, select one of the following options:

gcloud compute instances update VM_NAME \
    --enable-display-device \
    --zone=ZONE

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/updateDisplayDevice

{
  "enableDisplay": true
}

Disable virtual displays on an existing VM

Before disabling virtual displays on a VM, make sure to stop the VM.

To disable virtual displays on an existing VM, select one of the following options:

gcloud compute instances update VM_NAME \
    --no-enable-display-device \
    --zone=ZONE

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/updateDisplayDevice

{
  "enableDisplay": false
}

Install the virtual display driver

If you've enabled virtual displays on a Windows VM that runs a Windows OS image earlier than version v20190312, then, to use a virtual display device on the VM, you must install the virtual display driver provided by Google Cloud. If the VM runs a more recent OS image version, then the driver is already installed and you can skip this section.

To install the virtual display driver on a VM with virtual displays enabled, do the following:

1. Connect to the Windows VM.

2. Open a PowerShell terminal as an administrator.

3. Install the google-compute-engine-driver-gga component:

   googet install google-compute-engine-driver-gga
   

4. Restart the VM.

After you restart the VM, you can verify that the driver was correctly installed as described in the next section.

Verify the virtual display driver installation

If you had to manually install the virtual display driver on a Windows VM as described in the previous section, then you can verify that the installation was successful by doing the following:

1. If you haven't already, connect to the Windows VM.

2. Open Device Manager.

3. In the Device Manager list, in the Display adapters list, make sure that the Google Graphics Array (GGA) driver is listed.

   If the driver isn't listed, then reinstall the virtual display driver as described in this document.

What's next

• Learn how to set up Chrome Remote Desktop on Linux VMs.

• Learn how to connect to Windows VMs using RDP.