1. Documentation
×

Connecting to virtual machine consoles

Connecting to the VNC console

You can connect to the Virtual Network Computing (VNC) console of a VM by using the OKD web console or the virtctl command-line tool.

Connecting to the VNC console by using the web console

You can connect to the VNC console of a virtual machine (VM) by using the OKD web console.

If you connect to a Windows VM with a vGPU assigned as a mediated device, you can switch between the default display and the vGPU display.
Procedure

  1. On the Virtualization → VirtualMachines page, click a VM to open the VirtualMachine details page.

  2. Click the Console tab. The VNC console session starts automatically.

    Only one connection to the VNC console is possible at a time. If you attempt to create a second connection to the same VNC console, a warning is displayed, and you are prompted to disconnect the existing session before you create the new session.

    vnc console warning

  3. Optional: To switch to the vGPU display of a Windows VM, select Ctl + Alt + 2 from the Send key list.

    • Select Ctl + Alt + 1 from the Send key list to restore the default display.

  4. To end the console session, click outside the console pane and then click Disconnect.

Connecting to the VNC console by using virtctl

You can use the virtctl command-line tool to connect to the VNC console of a running virtual machine.

If you run the virtctl vnc command on a remote machine over an SSH connection, you must forward the X session to your local machine by running the ssh command with the -X or -Y flags.
Prerequisites

  • You must install the virt-viewer package.

Procedure

  1. Run the following command to start the console session:

    $ virtctl vnc <vm_name> -n <namespace> --preserve-session

    where:

    <vm_name>

    The name of the VM.

    <namespace>

    The namespace that contains the VM.

    --preserve-session

    Prevents an existing VNC console connection from being disconnected if you attempt to start a new session.

    Only one connection to the VNC console is possible at a time. If you attempt to create a second connection to the same VNC console, an error is displayed and the connection fails.

    Example error message:

    can't access VMI example-vm: Internal error occurred: Can't connect to websocket (503): websocket: bad handshake: application info: Active VNC connection. Request denied.

    If you attempt to create a second connection to the same VNC console without using the --preserve-session flag, this forces the existing connection to disconnect to allow the new connection.

  2. If the connection fails, run the following command to collect troubleshooting information:

    $ virtctl vnc <vm_name> -v 4

Generating a temporary token for the VNC console

To access the VNC of a virtual machine (VM), generate a temporary authentication bearer token for the Kubernetes API.

Kubernetes also supports authentication using client certificates, instead of a bearer token, by modifying the curl command.
Prerequisites

  • A running VM with OKD Virtualization 4.14 or later and ssp-operator 4.14 or later.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Set the deployVmConsoleProxy field value in the HyperConverged (HCO) custom resource (CR) to true:

    $ oc patch hyperconverged kubevirt-hyperconverged -n kubevirt-hyperconverged --type json -p '[{"op": "replace", "path": "/spec/deployVmConsoleProxy", "value": true}]'

  2. Generate a token by entering the following command:

    $ curl --header "Authorization: Bearer ${TOKEN}" \
     "https://api.<cluster_fqdn>/apis/token.kubevirt.io/v1alpha1/namespaces/<namespace>/virtualmachines/<vm_name>/vnc?duration=<duration>"

    The <duration> parameter can be set in hours and minutes, with a minimum duration of 10 minutes. For example: 5h30m. If this parameter is not set, the token is valid for 10 minutes by default.

    Sample output:

    { "token": "eyJhb..." }

  3. Optional: Use the token provided in the output to create a variable:

    $ export VNC_TOKEN="<token>"

    You can now use the token to access the VNC console of a VM.

Verification

  1. Log in to the cluster by entering the following command:

    $ oc login --token ${VNC_TOKEN}

  2. Test access to the VNC console of the VM by using the virtctl command:

    $ virtctl vnc <vm_name> -n <namespace>

It is currently not possible to revoke a specific token.

To revoke a token, you must delete the service account that was used to create it. However, this also revokes all other tokens that were created by using the service account. Use the following command with caution:

$ virtctl delete serviceaccount --namespace "<namespace>" "<vm_name>-vnc-access"
Additional resources

Granting token generation permission for the VNC console by using the cluster role

As a cluster administrator, you can install a cluster role and bind it to a user or service account to allow access to the endpoint that generates tokens for the VNC console.

Procedure

  • Choose to bind the cluster role to either a user or service account.

    • Run the following command to bind the cluster role to a user:

      $ kubectl create rolebinding "${ROLE_BINDING_NAME}" --clusterrole="token.kubevirt.io:generate" --user="${USER_NAME}"

    • Run the following command to bind the cluster role to a service account:

      $ kubectl create rolebinding "${ROLE_BINDING_NAME}" --clusterrole="token.kubevirt.io:generate" --serviceaccount="${SERVICE_ACCOUNT_NAME}"

Connecting to the serial console

You can connect to the serial console of a virtual machine by using the OKD web console or the virtctl command-line tool.

Running concurrent VNC connections to a single virtual machine is not currently supported.

Connecting to the serial console by using the web console

You can connect to the serial console of a virtual machine (VM) by using the OKD web console.

If you connect to a Windows VM with a vGPU assigned as a mediated device, you can switch between the default display and the vGPU display.
Procedure

  1. On the Virtualization → VirtualMachines page, click a VM to open the VirtualMachine details page.

  2. Click the Console tab. The VNC console session starts automatically.

    Only one connection to the VNC console is possible at a time. If you attempt to create a second connection to the same VNC console, a warning is displayed, and you are prompted to disconnect the existing session before you create the new session.

    vnc console warning

  3. Click Disconnect to end the VNC console session. Otherwise, the VNC console session continues to run in the background.

  4. Select Serial console from the console list.

  5. Optional: To switch to the vGPU display of a Windows VM, select Ctl + Alt + 2 from the Send key list.

    • Select Ctl + Alt + 1 from the Send key list to restore the default display.

  6. To end the console session, click outside the console pane and then click Disconnect.

Connecting to the serial console by using virtctl

You can use the virtctl command-line tool to connect to the serial console of a running virtual machine.

If you run the virtctl vnc command on a remote machine over an SSH connection, you must forward the X session to your local machine by running the ssh command with the -X or -Y flags.
Prerequisites

  • You must install the virt-viewer package.

Procedure

  1. Run the following command to start the console session:

    $ virtctl console <vm_name>

  2. Press Ctrl+] to end the console session.

    $ virtctl vnc <vm_name> -n <namespace> --preserve-session

    where:

    <vm_name>

    The name of the VM.

    <namespace>

    The namespace that contains the VM.

    --preserve-session

    Prevents an existing VNC console connection from being disconnected if you attempt to start a new session.

    Only one connection to the VNC console is possible at a time. If you attempt to create a second connection to the same VNC console, an error is displayed and the connection fails.

    Example error message:

    can't access VMI example-vm: Internal error occurred: Can't connect to websocket (503): websocket: bad handshake: application info: Active VNC connection. Request denied.

    If you attempt to create a second connection to the same VNC console without using the --preserve-session flag, this forces the existing connection to disconnect to allow the new connection.

  3. If the connection fails, run the following command to collect troubleshooting information:

    $ virtctl vnc <vm_name> -v 4

Connecting to the desktop viewer

You can connect to a Windows virtual machine (VM) by using the desktop viewer and the Remote Desktop Protocol (RDP).

Connecting to the desktop viewer by using the web console

You can connect to the desktop viewer of a virtual machine (VM) by using the OKD web console.

You can connect to the desktop viewer of a Windows virtual machine (VM) by using the OKD web console.

If you connect to a Windows VM with a vGPU assigned as a mediated device, you can switch between the default display and the vGPU display.
Prerequisites

  • You installed the QEMU guest agent on the Windows VM.

  • You have an RDP client installed.

Procedure

  1. On the Virtualization → VirtualMachines page, click a VM to open the VirtualMachine details page.

  2. Click the Console tab. The VNC console session starts automatically.

    Only one connection to the VNC console is possible at a time. If you attempt to create a second connection to the same VNC console, a warning is displayed, and you are prompted to disconnect the existing session before you create the new session.

    vnc console warning

  3. Click Disconnect to end the VNC console session. Otherwise, the VNC console session continues to run in the background.

  4. Select Desktop viewer from the console list.

  5. Click Create RDP Service to open the RDP Service dialog.

  6. Select Expose RDP Service and click Save to create a node port service.

  7. Click Launch Remote Desktop to download an .rdp file and launch the desktop viewer.

  8. Optional: To switch to the vGPU display of a Windows VM, select Ctl + Alt + 2 from the Send key list.

    • Select Ctl + Alt + 1 from the Send key list to restore the default display.

  9. To end the console session, click outside the console pane and then click Disconnect.