VDI Gateways

Advanced Enterprise — Not available in: Essentials

VDI Gateways require an Advanced or Enterprise license. Distributed Workers used for other supported use cases, including HVM quorum witnesses, are also available in VM Essentials.

Overview

VDI Gateways provide a secure connection point between end users and VDI desktop sessions. A gateway acts as a proxy, routing VDI traffic through a controlled network path. This is essential for environments where VDI desktops reside on isolated networks not directly accessible to end users.

VDI Gateways are managed from Tools > VDI Pools > VDI Gateways.

Note

VDI Gateways require the services-vdi-pools Role permission (Read or Full).

Gateway Architecture

The VDI Gateway sits between the user’s browser and the Guacamole session:

User Browser → VDI Gateway → Guacamole Server → VDI Desktop (RDP/VNC)

This architecture enables:

  • Network isolation — VDI desktops can be on a private network inaccessible to users directly

  • Load distribution — Multiple gateways can distribute connection load

  • Security — All VDI traffic routes through a controlled proxy with API key authentication

  • Geographic distribution — Place gateways closer to users for reduced latency

The same VDI Gateway registration can also route Instance and Host consoles. Assign it on a Network or Cloud, or select it as the Default Console Gateway in Administration > Settings > Appliance. VDI desktop routing is separate: assign the gateway to a VDI Pool in Tools > VDI Pools > VDI Pools. Both uses authenticate the Worker runtime with the VDI Gateway API key.

The same runtime can additionally act as a Distributed Worker when configured with a Distributed Worker key. See Distributed Workers for the role and key matrix and canonical package and container deployment instructions.

Creating a VDI Gateway

  1. Navigate to Tools > VDI Pools > VDI Gateways

  2. Click + ADD

  3. Configure:

    NAME

    Unique name for the gateway (must be unique per tenant)

    DESCRIPTION

    Optional description of the gateway’s purpose or location

    GATEWAY URL

    The URL where the gateway service is accessible (e.g., https://vdi-gw.example.com:8443)

  4. Click SAVE

Upon creation, HPE Morpheus Software generates an API Key for the gateway. This key is used by the gateway service to authenticate with the HPE Morpheus Software appliance.

Important

Copy the API Key immediately after creation. It is used to configure the gateway service and cannot be retrieved later (only regenerated).

Editing a VDI Gateway

  1. Navigate to Tools > VDI Pools > VDI Gateways

  2. Click the gateway name or select the edit action

  3. Modify the name, description, or gateway URL

  4. Click SAVE

Note

The API Key cannot be changed through the edit interface. To regenerate a key, delete and recreate the gateway.

Deleting a VDI Gateway

  1. Navigate to Tools > VDI Pools > VDI Gateways

  2. Select the gateway to delete

  3. Click DELETE

  4. Confirm deletion

Warning

A gateway cannot be deleted if it is currently assigned to one or more VDI Pools. Remove the gateway assignment from all pools before deleting.

Assigning Gateways to Pools

VDI Gateways are assigned at the Pool level:

  1. Navigate to Tools > VDI Pools > VDI Pools

  2. Edit or create a VDI Pool

  3. In the pool configuration, select the desired Gateway from the dropdown

  4. Save the pool

When a gateway is assigned to a pool, all user sessions for that pool route through the specified gateway.

Gateway Configuration Fields

Field

Description

Required

Default

Name

Unique identifier for the gateway

Yes

—

Description

Purpose or location note

No

null

Gateway URL

URL of the gateway service endpoint

No

null

API Key

Auto-generated authentication key

Auto

Generated on save

Enabled

Whether the gateway is active

No

true

Deploying the Gateway Service

The VDI Gateway service is a separate component that must be deployed on a server with network access to both:

  • The HPE Morpheus Software appliance (for API communication)

  • The VDI desktop network (for RDP/VNC proxying)

Configuration requirements:

  1. Install the gateway service package

  2. Configure the gateway URL to match what was entered in HPE Morpheus Software

  3. Set the API Key from the HPE Morpheus Software gateway configuration

  4. Ensure ports are open:

    • Inbound from users (typically 443 or 8443)

    • Outbound to VDI desktops (RDP 3389, VNC 5900+)

    • Outbound to HPE Morpheus Software appliance (443)

For current package and morpheusdata/morpheus-worker container procedures, TLS options, environment variables, combined-role configuration, logs, and upgrades, see Distributed Workers.

API Reference

VDI Gateways are manageable via the HPE Morpheus Software API:

  • GET /api/vdi-gateways — List all VDI Gateways

  • GET /api/vdi-gateways/:id — Get a specific gateway

  • POST /api/vdi-gateways — Create a gateway

  • PUT /api/vdi-gateways/:id — Update a gateway

  • DELETE /api/vdi-gateways/:id — Delete a gateway

Troubleshooting

  • Gateway unreachable: Verify the Gateway URL is accessible from the HPE Morpheus Software appliance and from end-user browsers

  • Authentication failed: Ensure the API Key configured on the gateway service matches the one generated in HPE Morpheus Software

  • Cannot delete gateway: Remove the gateway assignment from all VDI Pools first

  • Sessions not routing through gateway: Verify the pool has the gateway assigned and that the gateway service is running