Setting Up a Console Proxy

Private Cloud Director allows you to proxy all of the VM console connections in a region through one or more servers. You can configure this in the cluster blueprint using the field VNC Proxy IP or Domain Name, and set it to a domain name or an IP address. The proxy must always point to a hypervisor node in the same region. Using any other server or VM is not supported.

How console proxy traffic works

When a user opens a VM console, the connection does not go directly to the hypervisor running the VM. Every console session in the region first reaches the hypervisor that the console proxy endpoint resolves to (the authoritative node), and that host then proxies the session to the hypervisor that actually runs the VM.

In the example below, the endpoint resolves to Hyp1, which acts as the VNC proxy and forwards the session to Hyp2, where the VM runs. Hyp3 is not involved in this session.

    ┌────────────────┐
    │     User /     │
    │    Browser     │
    └────────┬───────┘
             │  VNC console request
             ▼
   ┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
   │       Hyp1       │      │       Hyp2       │      │       Hyp3       │
   │ (VNC proxy node) │      │                  │      │                  │
   │                  │      │   ┌──────────┐   │      │                  │
   │                  │─────▶│   │    VM    │   │      │                  │
   │                  │      │   └──────────┘   │      │                  │
   └──────────────────┘      └──────────────────┘      └──────────────────┘

Hyp1 is the resolved host and acts as the VNC proxy. It forwards the
session to Hyp2, which runs the requested VM. Hyp3 and any other
hosts can stay isolated from direct user access.

1. Request. The user opens a VM console from the UI or API. Private Cloud Director returns a console URL that points to the console proxy endpoint — the IP or domain name set in the blueprint — on port 6080, together with a one-time token that identifies the target VM and the hypervisor running it.
2. Resolve the endpoint to a hypervisor. The console proxy endpoint always resolves to a hypervisor in the region (never a standalone server or VM). Which host becomes the authoritative node depends on how you configured the proxy:

   • A hypervisor's IP — every session is routed through that one fixed host.
   • A floating IP / VIP — the session reaches whichever host currently holds the VIP (for example, managed by keepalived).
   • A domain name — the name can map to one or more hypervisors. See Using a domain name below.
3. Forward to the correct hypervisor. The noVNC proxy service on the authoritative node uses the token to identify the hypervisor running the target VM, opens a backend connection to it over the internal host-to-host network, and relays the console stream back to the user.

Only the authoritative node needs to be reachable by users. Every other hypervisor can have external access blocked, as long as hypervisor-to-hypervisor traffic on the console port is allowed.

Using a domain name

A domain name can map to more than one hypervisor. In that case your DNS, VPN, or /etc/hosts decides which host the request lands on, and that host then proxies the session to the hypervisor running the VM. In the example below the name resolves to either Hyp1 or Hyp3, and from there the session reaches Hyp2:

                         ┌──────────────────┐
                         │      User /      │
                         │     Browser      │
                         └─────────┬────────┘
                                   │  console.example.com
                                   │  (DNS resolves to Hyp1 or Hyp3)
             ┌─────────────────────┴─────────────────────┐
             ▼                                           ▼
   ┌──────────────────┐                        ┌──────────────────┐
   │ Hyp1 (VNC proxy) │                        │ Hyp3 (VNC proxy) │
   └─────────┬────────┘                        └─────────┬────────┘
             │                                           │
             └─────────────────────┬─────────────────────┘
                                   ▼
                         ┌──────────────────┐
                         │       Hyp2       │
                         │                  │
                         │   ┌──────────┐   │
                         │   │    VM    │   │
                         │   └──────────┘   │
                         └──────────────────┘

The domain name maps to more than one hypervisor (here Hyp1 and Hyp3).
Your DNS, VPN, or /etc/hosts decides which one the request lands on;
that host then proxies the session to Hyp2, which runs the VM.

Options for configuring the console proxy

1. Use a hypervisor’s IP address

If you have multiple hypervisors, you can route all console connections through a single host by setting that hypervisor’s IP as the proxy IP in the blueprint. This allows you to restrict public access to all other hypervisors.

2. Use a public / floating IP

If your hypervisor nodes can route a public or floating IP, you can set that floating IP in the blueprint. Traffic will then flow through whichever host currently holds the floating IP. Tools like keepalived can be used to manage this.

3. Use a domain name

You can also provide a domain name instead of an IP. To make this work, map the domain name to one or more hypervisor hosts either:

• locally in your /etc/hosts, or
• through your organization’s DNS or VPN configuration.

Limitations

The console proxy is not a standalone, externally hosted gateway. It must be one (or more) of the hypervisors in the same region. Using any other server or VM is not supported. As a result:

• At least one hypervisor must remain reachable by users to act as the proxy (the jump point). A configuration where all hypervisors are isolated from direct user access, with only an external proxy exposed, is not supported today.
• The remaining hypervisors can be fully isolated from direct user access. They only need to accept console (host-to-host) traffic from the authoritative node.