Enable virtual displays


If applications on your VM instances require a display device, but don't require the full power or cost of a GPU, you can configure your instances to use a virtual display device. These devices allow you to run remote system management tools and remote desktop software that require a display device.

Configure a virtual display device when you create a new instance or add a virtual display device to an existing instance while it is stopped. There is no cost to enable your instances with a virtual display device.

Before you begin

  • If you haven't already, 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 as follows.

    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 from 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. Create local authentication credentials for your Google Account:

      gcloud auth application-default login

    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

Required roles

To get the permissions that you need to modify 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.

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

Required permissions

The following permissions are required to modify virtual displays on a VM:

  • To add or remove virtual display on an existing VM: compute.instances.updateDisplayDevice on the VM
  • To create a VM with a virtual display device:
    • compute.instances.create on the project
    • To use a custom image to create the VM: compute.images.useReadOnly on the image
    • To use a snapshot to create the VM: compute.snapshots.useReadOnly on the snapshot
    • To use an instance template to create the VM: compute.instanceTemplates.useReadOnly on the instance template
    • To assign a legacy network to the VM: compute.networks.use on the project
    • To specify a static IP address for the VM: compute.addresses.use on the project
    • To assign an external IP address to the VM when using a legacy network: compute.networks.useExternalIp on the project
    • To specify a subnet for the VM: compute.subnetworks.use on the project or on the chosen subnet
    • To assign an external IP address to the VM when using a VPC network: compute.subnetworks.useExternalIp on the project or on the chosen subnet
    • To set VM instance metadata for the VM: compute.instances.setMetadata on the project
    • To set tags for the VM: compute.instances.setTags on the VM
    • To set labels for the VM: compute.instances.setLabels on the VM
    • To set a service account for the VM to use: compute.instances.setServiceAccount on the VM
    • To create a new disk for the VM: compute.disks.create on the project
    • To attach an existing disk in read-only or read-write mode: compute.disks.use on the disk
    • To attach an existing disk in read-only mode: compute.disks.useReadOnly on the disk

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

Restrictions

  • Google supports virtual display devices on Linux instances and on Windows instances that use any x64-based Windows images v20190312 or later.
  • If your VM instance is running a Windows image that is older than v20190312, you must also manually install the device driver after enabling virtual displays for the instance. Images that are newer than v20190312 come preinstalled with the device drivers.
  • Virtual display devices are functional only after the guest operating system boots and initializes the virtual display driver. You cannot use virtual display devices during POST or while the guest operating system is booting.
  • Virtual display devices are not compatible with instances running the Sandy Bridge CPU platform.
  • Virtual display devices are not compatible with T2A Arm VMs.

Create an instance with a virtual display device

Enable a virtual display device on an instance when you create a new instance. Alternatively, you can add a virtual display device to an existing instance.

Console

  1. In the Google Cloud console, go to the Create an instance page.

    Go to Create an instance

  2. Define the properties for the VM, including the name, region, zone, and machine configuration.

  3. To turn on the virtual display device, select the Enable display device checkbox from the Machine configuration > Display device settings.

    The virtual display device allows you to use screen capturing.

  4. To create the VM, click Create.

gcloud

In the Google Cloud CLI, use the compute instances create command and include the --enable-display-device flag:

 gcloud compute instances create [INSTANCE_NAME] --enable-display-device

where [INSTANCE_NAME] is the name of the instance that you want to create.

Terraform

You can use the Terraform resource to create an instance with virtual display enabled by setting the enable_display argument to true.


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 {
    }
  }
}

REST

In the API, construct a POST request to the compute.instances.insert method. In the request body, include the instance properties as well as the displayDevice property with enableDisplay set to true.

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

{
  "name": "[INSTANCE_NAME]",
  "machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
  "displayDevice": {
    "enableDisplay": true
  },
⋮
}]

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [PROJECT_ID] is your project ID.
  • [ZONE] is the zone where your instance is located.

After you create an instance with a virtual display device, you can configure remote desktop to remotely manage your Windows instance.

Add or removing a virtual display device on an existing instance

You can enable a virtual display device on an existing instance. Alternatively, you can enable a virtual display device when you create a new instance.

Before you can enable or disable a virtual display device on a running instance, you must stop the instance.

Console

  1. Go to the VM instances page.

    Go to the VM instances page

  2. In the Name column, click the name of the instance to add or remove the virtual display device from.

  3. At the top of the VM instance details page, click Stop.

  4. At the top of the VM instance details page, click Edit.

  5. Under Display device, click Turn on display device to either enable or disable the virtual display device for this instance.

  6. At the bottom of the instance creation settings, click Save.

gcloud

To add a virtual display device, use the compute instances update command in the Google Cloud CLI and include the --enable-display-device flag:

 gcloud compute instances update [INSTANCE_NAME] --enable-display-device

where [INSTANCE_NAME] is the name of the instance that you want to create.

To remove a virtual display device, use the compute instances update command in the gcloud CLI and include the --no-enable-display-device flag:

 gcloud compute instances update [INSTANCE_NAME] --no-enable-display-device

where [INSTANCE_NAME] is the name of the instance that you want to create.

REST

In the API, construct a POST request to the compute.instances.updateDisplayDevice method. In the request body, include the enableDisplay property. To enable the virtual display device on this instance, set enableDisplay to true. To disable the virtual display device on the instance, set enableDisplay to false.

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/updateDisplayDevice

{
 "enableDisplay": [ENABLE_DISPLAY]
}

where:

  • [INSTANCE_NAME] is the name of the instance where you want to enable or disable the virtual display device.
  • [PROJECT_ID] is your project ID.
  • [ZONE] is the zone where your instance is located.
  • [ENABLE_DISPLAY] is either true to enable the virtual display device on the instance or false to disable the virtual display device on the instance.

After you create an instance with a virtual display device, you can configure remote desktop to remotely manage your Windows instance.

Install the virtual display driver

Google provides a display driver that allows Windows instances to use virtual display devices correctly. The driver is required for several Compute Engine features. Google provides and supports this display driver only for Windows instances.

After you create an instance with a virtual display device or add a virtual display device to an existing instance, you can install the virtual display device on the instance using the following process:

  1. Connect to the Windows instance where the virtual display device is enabled.
  2. Open a PowerShell terminal as an administrator.
  3. Run the googet installer to install the google-compute-engine-driver-gga component:

    googet install google-compute-engine-driver-gga
    
  4. Restart the instance.

After you restart the instance, confirm the driver was installed by following the instructions below.

Verify the virtual display driver install

If you had to manually install the device driver, follow these instructions to verify that the install was successful.

  1. Connect to the Windows instance where the virtual display device is enabled.
  2. Open the Run tool and run the devmgmt.msc Computer Management tool.
  3. In navigation for the Computer Management tool, click Device Manager to see a list of devices.
  4. Under the Display adapters list, check to ensure that the Google Graphics Array driver is listed. The Windows Computer Management window, which shows the Google Graphics Array listed as an installed display adapter.
  5. If the Microsoft Basic Display adapter is listed as a display adapter instead of the Google Graphics Array, repeat the driver install process and check the driver again.

What's next