Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Accessing virtual machine consoles

Accessing virtual machine consoles in the OKD web console

You can connect to virtual machines by using the serial console or the VNC console in the OKD web console.

You can connect to Windows virtual machines by using the desktop viewer console, which uses RDP (remote desktop protocol), in the OKD web console.

Connecting to the serial console

Connect to the serial console of a running virtual machine from the Console tab on the VirtualMachine details page of the web console.

Procedure

  1. In the OKD console, click Virtualization → VirtualMachines from the side menu.

  2. Select a virtual machine to open the VirtualMachine details page.

  3. Click the Console tab. The VNC console opens by default.

  4. Click Disconnect to ensure that only one console session is open at a time. Otherwise, the VNC console session remains active in the background.

  5. Click the VNC Console drop-down list and select Serial Console.

  6. Click Disconnect to end the console session.

  7. Optional: Open the serial console in a separate window by clicking Open Console in New Window.

Connecting to the VNC console

Connect to the VNC console of a running virtual machine from the Console tab on the VirtualMachine details page of the web console.

Procedure

  1. In the OKD console, click Virtualization → VirtualMachines from the side menu.

  2. Select a virtual machine to open the VirtualMachine details page.

  3. Click the Console tab. The VNC console opens by default.

  4. Optional: Open the VNC console in a separate window by clicking Open Console in New Window.

  5. Optional: Send key combinations to the virtual machine by clicking Send Key.

  6. Click outside the console window and then click Disconnect to end the session.

Connecting to a Windows virtual machine with RDP

The Desktop viewer console, which utilizes the Remote Desktop Protocol (RDP), provides a better console experience for connecting to Windows virtual machines.

To connect to a Windows virtual machine with RDP, download the console.rdp file for the virtual machine from the Console tab on the VirtualMachine details page of the web console and supply it to your preferred RDP client.

Prerequisites

  • A running Windows virtual machine with the QEMU guest agent installed. The qemu-guest-agent is included in the VirtIO drivers.

  • An RDP client installed on a machine on the same network as the Windows virtual machine.

Procedure

  1. In the OKD console, click Virtualization → VirtualMachines from the side menu.

  2. Click a Windows virtual machine to open the VirtualMachine details page.

  3. Click the Console tab.

  4. From the list of consoles, select Desktop viewer.

  5. Click Launch Remote Desktop to download the console.rdp file.

  6. Reference the console.rdp file in your preferred RDP client to connect to the Windows virtual machine.

Switching between virtual machine displays

If your Windows virtual machine (VM) has a vGPU attached, you can switch between the default display and the vGPU display by using the web console.

Prerequisites

  • The mediated device is configured in the HyperConverged custom resource and assigned to the VM.

  • The VM is running.

Procedure

  1. In the OKD console, click Virtualization → VirtualMachines

  2. Select a Windows virtual machine to open the Overview screen.

  3. Click the Console tab.

  4. From the list of consoles, select VNC console.

  5. Choose the appropriate key combination from the Send Key list:

    1. To access the default VM display, select Ctl + Alt+ 1.

    2. To access the vGPU display, select Ctl + Alt + 2.

Additional resources

Copying the SSH command using the web console

Copy the command to connect to a virtual machine (VM) terminal via SSH.

Procedure

  1. In the OKD console, click Virtualization → VirtualMachines from the side menu.

  2. Click the Options menu kebab for your virtual machine and select Copy SSH command.

  3. Paste it in the terminal to access the VM.

Accessing virtual machine consoles by using CLI commands

Accessing a virtual machine via SSH by using virtctl

You can use the virtctl ssh command to forward SSH traffic to a virtual machine (VM) by using your local SSH client. If you have previously configured SSH key authentication with the VM, skip to step 2 of the procedure because step 1 is not required.

Heavy SSH traffic on the control plane can slow down the API server. If you regularly need a large number of connections, use a dedicated Kubernetes Service object to access the virtual machine.
Prerequisites

  • You have installed the OpenShift CLI (oc).

  • You have installed the virtctl client.

  • The virtual machine you want to access is running.

  • You are in the same project as the VM.

Procedure

  1. Configure SSH key authentication:

    1. Use the ssh-keygen command to generate an SSH public key pair:

      $ ssh-keygen -f <key_file> (1)
      1 Specify the file in which to store the keys.

    2. Create an SSH authentication secret which contains the SSH public key to access the VM:

      $ oc create secret generic my-pub-key --from-file=key1=<key_file>.pub

    3. Add a reference to the secret in the VirtualMachine manifest. For example:

      apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: testvm
spec:
  running: true
  template:
    spec:
      accessCredentials:
      - sshPublicKey:
          source:
            secret:
              secretName: my-pub-key (1)
          propagationMethod:
            configDrive: {} (2)
# ...
      1 Reference to the SSH authentication Secret object.
      2 The SSH public key is injected into the VM as cloud-init metadata using the configDrive provider.

    4. Restart the VM to apply your changes.

  2. Connect to the VM via SSH:

    1. Run the following command to access the VM via SSH:

      $ virtctl ssh -i <key_file> <vm_username>@<vm_name>

    2. Optional: To securely transfer files to or from the VM, use the following commands:

      Copy a file from your machine to the VM
      $ virtctl scp -i <key_file> <filename> <vm_username>@<vm_name>:
      Copy a file from the VM to your machine
      $ virtctl scp -i <key_file> <vm_username@<vm_name>:<filename> .
Additional resources

Using OpenSSH and virtctl port-forward

You can use your local OpenSSH client and the virtctl port-forward command to connect to a running virtual machine (VM). You can use this method with Ansible to automate the configuration of VMs.

This method is recommended for low-traffic applications because port-forwarding traffic is sent over the control plane. This method is not recommended for high-traffic applications such as Rsync or Remote Desktop Protocol because it places a heavy burden on the API server.

Prerequisites

  • You have installed the virtctl client.

  • The virtual machine you want to access is running.

  • The environment where you installed the virtctl tool has the cluster permissions required to access the VM. For example, you ran oc login or you set the KUBECONFIG environment variable.

Procedure

  1. Add the following text to the ~/.ssh/config file on your client machine:

    Host vm/*
  ProxyCommand virtctl port-forward --stdio=true %h %p

  2. Connect to the VM by running the following command:

    $ ssh <user>@vm/<vm_name>.<namespace>

Accessing the serial console of a virtual machine instance

The virtctl console command opens a serial console to the specified virtual machine instance.

Prerequisites

  • The virt-viewer package must be installed.

  • The virtual machine instance you want to access must be running.

Procedure

  • Connect to the serial console with virtctl:

    $ virtctl console <VMI>

Accessing the graphical console of a virtual machine instances with VNC

The virtctl client utility can use the remote-viewer function to open a graphical console to a running virtual machine instance. This capability is included in the virt-viewer package.

Prerequisites

  • The virt-viewer package must be installed.

  • The virtual machine instance you want to access must be running.

If you use virtctl via SSH on a remote machine, you must forward the X session to your machine.
Procedure

  1. Connect to the graphical interface with the virtctl utility:

    $ virtctl vnc <VMI>

  2. If the command failed, try using the -v flag to collect troubleshooting information:

    $ virtctl vnc <VMI> -v 4

Connecting to a Windows virtual machine with an RDP console

Create a Kubernetes Service object to connect to a Windows virtual machine (VM) by using your local Remote Desktop Protocol (RDP) client.

Prerequisites

  • A running Windows virtual machine with the QEMU guest agent installed. The qemu-guest-agent object is included in the VirtIO drivers.

  • An RDP client installed on your local machine.

Procedure

  1. Edit the VirtualMachine manifest to add the label for service creation:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: vm-ephemeral
  namespace: example-namespace
spec:
  running: false
  template:
    metadata:
      labels:
        special: key (1)
# ...
    1 Add the label special: key in the spec.template.metadata.labels section.

    Labels on a virtual machine are passed through to the pod. The special: key label must match the label in the spec.selector attribute of the Service manifest.

  2. Save the VirtualMachine manifest file to apply your changes.

  3. Create a Service manifest to expose the VM:

    apiVersion: v1
kind: Service
metadata:
  name: rdpservice (1)
  namespace: example-namespace (2)
spec:
  ports:
  - targetPort: 3389 (3)
    protocol: TCP
  selector:
    special: key (4)
  type: NodePort (5)
# ...
    1 The name of the Service object.
    2 The namespace where the Service object resides. This must match the metadata.namespace field of the VirtualMachine manifest.
    3 The VM port to be exposed by the service. It must reference an open port if a port list is defined in the VM manifest.
    4 The reference to the label that you added in the spec.template.metadata.labels stanza of the VirtualMachine manifest.
    5 The type of service.

  4. Save the Service manifest file.

  5. Create the service by running the following command:

    $ oc create -f <service_name>.yaml

  6. Start the VM. If the VM is already running, restart it.

  7. Query the Service object to verify that it is available:

    $ oc get service -n example-namespace
    Example output for NodePort service
    NAME        TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)            AGE
rdpservice   NodePort    172.30.232.73   <none>       3389:30000/TCP    5m

  8. Run the following command to obtain the IP address for the node:

    $ oc get node <node_name> -o wide
    Example output
    NAME    STATUS   ROLES   AGE    VERSION  INTERNAL-IP      EXTERNAL-IP
node01  Ready    worker  6d22h  v1.24.0  192.168.55.101   <none>

  9. Specify the node IP address and the assigned port in your preferred RDP client.

  10. Enter the user name and password to connect to the Windows virtual machine.