Enabling Virtual Displays on Instances

Beta

This product or feature is in a pre-release state and might change or have limited support. For more information, see Product launch stages.

If applications on your VM instances require a display device, but do not require the full power or cost of a GPU, you can configure your instances with 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 want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.

Restrictions

• Google supports virtual display devices only on Windows Server instances that use Windows Server 2012R2 or higher.
• You must install the virtual display driver to ensure that instances with virtual displays work properly in the Compute Engine environment.
• 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.

Creating an instance with a virtual display device

You can 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.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.instances.create on the project
• compute.instances.updateShieldedVmConfig if you plan to create a Shielded VM instance and you want to be able to change any of the Shielded VM settings.
• compute.networks.use on the project if using a legacy network
• compute.subnetworks.use either on the whole project or on the chosen subnet (VPC networks)
• compute.networks.useExternalIp on the project if you need to assign an external IP address (either ephemeral or static) to the instance using a legacy network
• compute.subnetworks.useExternalIp either on the whole project or on the chosen subnet if you need to assign an external IP address (either ephemeral or static) to the instance using a VPC network
• compute.address.use on the project if specifying a static address in the project
• compute.instances.setMetadata if setting metadata
• compute.instances.setTags on the instance if setting tags
• compute.instances.setLabels on the instance if setting labels
• compute.images.useReadOnly on the image if creating a new root persistent disk
• compute.disks.create on the project if creating a new root persistent disk with this instance
• compute.disks.useReadOnly on the disk if attaching an existing persistent disk in read-only mode
• compute.disks.use on the disk if attaching an existing disk in read-write mode
• compute.snapshots.create on the project to create a new snapshot if creating an instance from a snapshot
• compute.snapshots.use on the snapshot if creating an instance from a snapshot

Console

1. Go to the Instances page.

   Go to the Instances page

2. Click the Create instance button to create a new instance.
3. Define the properties for the new instance including the machine type, zone, disk, and networking settings.
4. In the Machine type section, click Customize to expand the machine type, GPU, and display device settings.
5. Click Turn on display device to enable the virtual display device.
6. At the bottom of the instance creation settings, click Create to create the instance.

gcloud

In the gcloud tool, use the compute instances create command and include the --enable-display-device flag:

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

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

API

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://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances

{
  "name": "[INSTANCE_NAME]",
  "machineType": "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, start the instance and install the virtual display driver.

Adding or removing a virtual display device on an existing instance

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

Before you can add or remove a virtual display device to a running instance, you must stop the instance.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.instances.updateDisplayDevice on the instance where you want to add or remove the virtual display device

Console

1. Go to the Instances page.

   Go to the Instances page

2. In the Name column, click the name of the instance where you want to add or remove the virtual display device.
3. At the top of the instance details page, click Edit.
4. In the Machine type section, click Customize to expand the machine type, GPU, and display device settings.
5. 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 to save the instance settings.

gcloud

To add a virtual display device, use the compute instances update command in the gcloud command-line tool and include the --enable-display-device flag:

 gcloud beta 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 command-line tool and include the --no-enable-display-device flag:

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

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

API

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://www.googleapis.com/compute/beta/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 add a virtual display device to the instance, start the instance and install the virtual display driver.

Configuring the virtual display driver

Google provides a display driver that allows Windows Server 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 Server on Compute Engine 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 Windows Server using the following process:

1. Connect to the Windows Server 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 that the driver is installed correctly.

Verifying the virtual display driver install

1. Connect to the Windows Server instance where the virtual display device is enabled.
2. Open the Run tool and run the devmgmt.msc Computer Management tool.
3. On the left 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.
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

• Learn about different methods for connecting to Windows Server instances.
• Learn how to stop and start an instance.