1. Documentation
    2. history bug_report picture_as_pdf
×

Configuring SSH access to virtual machines

You can configure SSH access to virtual machines (VMs) by using the following methods:

  • virtctl ssh command

    You create an SSH key pair, add the public key to a VM, and connect to the VM by running the virtctl ssh command with the private key.

  • virtctl port-forward command

    You add the virtctl port-foward command to your .ssh/config file and connect to the VM by using OpenSSH.

  • Service

    You create a service, associate the service with the VM, and connect to the IP address and port exposed by the service.

  • Secondary network

    You configure a secondary network, attach a virtual machine (VM) to the secondary network interface, and connect to the DHCP-allocated IP address.

Access configuration considerations

Each method for configuring access to a virtual machine (VM) has advantages and limitations, depending on the traffic load and client requirements.

Services provide excellent performance and are recommended for applications that are accessed from outside the cluster.

If the internal cluster network cannot handle the traffic load, you can configure a secondary network.

virtctl ssh and virtctl port-forwarding commands

  • Simple to configure.

  • Recommended for troubleshooting VMs.

  • virtctl port-forwarding recommended for automated configuration of VMs with Ansible.

  • Not recommended for high-traffic applications like Rsync or Remote Desktop Protocol because of the burden on the API server.

  • The API server must be able to handle the traffic load.

  • The clients must be able to access the API server.

  • The clients must have access credentials for the cluster.

Cluster IP service

  • The internal cluster network must be able to handle the traffic load.

  • The clients must be able to access an internal cluster IP address.

Node port service

  • The internal cluster network must be able to handle the traffic load.

  • The clients must be able to access at least one node.

Load balancer service

  • A load balancer must be configured.

  • Each node must be able to handle the traffic load of one or more load balancer services.

Secondary network

  • Excellent performance because traffic does not go through the internal cluster network.

  • Allows a flexible approach to network topology.

  • Guest operating system must be configured with appropriate security because the VM is exposed directly to the secondary network. If a VM is compromised, an intruder could gain access to the secondary network.

Using virtctl ssh

You can add a public SSH key to a virtual machine (VM) and connect to the VM by running the virtctl ssh command.

This method is simple to configure. However, it is not recommended for high traffic loads because it places a burden on the API server.

Adding an SSH key to a virtual machine

You can add a static or dynamic public SSH key to a virtual machine (VM) by using the OpenShift Container Platform web console or the command line.

Static key

  • Added to the VM at startup.

  • Uses the cloud-init configuration drive and does not affect cloud-init user data.

  • Can be added when you create a VM by using the web console or the command line.

  • Can be added to a project by using the web console. Afterwards, the key is automatically added to the VMs that you create in this project.

Dynamic key

  • Can be added or revoked while the VM is running.

  • Can be disabled for security reasons. If the setting is disabled, the VM inherits the key setting of the image from which it was created.

  • Uses the QEMU guest agent.

  • Only supported by Red Hat Enterprise Linux (RHEL) 9.

Adding an SSH key when creating a virtual machine by using the web console

You can add a static public SSH key when you create a virtual machine (VM) by using the OpenShift Container Platform web console.

The key is added at startup as cloud-init metadata. This method does not affect cloud-init user data.

Prerequisites

  • You generated an SSH key pair by running the ssh-keygen command.

Procedure

  1. Navigate to Virtualization → Catalog in the web console.

  2. Click a template tile.

  3. Click Customize VirtualMachine.

  4. Click Next.

  5. On the Scripts tab, click the edit icon beside Authorized SSH key.

  6. Select an SSH key option:

    • Use existing: Select a secret from the secrets list.

    • Add new:

      1. Browse to the public SSH key file or paste the file in the key field.

      2. Enter the secret name.

      3. Optional: Select Automatically apply this key to any new VirtualMachine you create in this project.

  7. Click Save.

  8. Click Create VirtualMachine.

    The VirtualMachine details page displays the progress of the VM creation.

Verification

  1. Click the Scripts tab on the Configuration tab.

    The secret name is displayed in the Authorized SSH key section.

Adding an SSH key when creating a virtual machine by using the command line

You can add a static public SSH key when you create a virtual machine (VM) by using the command line. The key is added to the VM at startup.

The SSH key is added to the VM as generated cloud-init metadata, by using a cloud-init configuration disk. This method separates the access credentials from the application data in the cloud-init user data. This method does not affect cloud-init user data.

Prerequisites

  • You generated an SSH key pair by running the ssh-keygen command.

Procedure

  1. Create a manifest file for a VirtualMachine object and a Secret object:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: example-vm
  namespace: example-namespace
spec:
  dataVolumeTemplates:
  - apiVersion: cdi.kubevirt.io/v1beta1
    kind: DataVolume
    metadata:
      name: example-vm-disk
    spec:
      sourceRef:
        kind: DataSource
        name: rhel9
        namespace: openshift-virtualization-os-images
      storage:
        resources:
          requests:
            storage: 30Gi
  running: false
  template:
    metadata:
      labels:
        kubevirt.io/domain: example-vm
    spec:
      domain:
        cpu:
          cores: 1
          sockets: 2
          threads: 1
        devices:
          disks:
          - disk:
              bus: virtio
            name: rootdisk
          - disk:
              bus: virtio
            name: cloudinitdisk
          interfaces:
          - masquerade: {}
            name: default
          rng: {}
        features:
          smm:
            enabled: true
        firmware:
          bootloader:
            efi: {}
        resources:
          requests:
            memory: 8Gi
      evictionStrategy: LiveMigrate
      networks:
      - name: default
        pod: {}
      volumes:
      - dataVolume:
          name: example-volume
        name: example-vm-disk
        - cloudInitConfigDrive: (1)
            userData: |-
              #cloud-config
              user: cloud-user
              password: <password>
              chpasswd: { expire: False }
          name: cloudinitdisk
      accessCredentials:
        - sshPublicKey:
            propagationMethod:
              configDrive: {}
            source:
              secret:
                secretName: authorized-keys (2)
---
apiVersion: v1
kind: Secret
metadata:
  name: authorized-keys
data:
  key:  |
      MIIEpQIBAAKCAQEAulqb/Y... (3)
    1 Specify cloudInitConfigDrive to create a configuration drive.
    2 Specify the Secret object name.
    3 Paste the public SSH key.

  2. Create the VirtualMachine and Secret objects:

    $ oc create -f <manifest_file>.yaml

  3. Start the VM:

    $ virtctl start vm example-vm
Verification

  1. Get the VM configuration:

    $ oc describe vm example-vm -n example-namespace
    Example output
    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: example-vm
  namespace: example-namespace
spec:
  template:
    spec:
      accessCredentials:
        - sshPublicKey:
            propagationMethod:
              configDrive: {}
            source:
              secret:
                secretName: authorized-keys

Adding an SSH key to a project by using the web console

You can add a static public SSH key to a project by using the OpenShift Container Platform web console. Afterwards, this key is added to the virtual machines (VMs) that you create in the project.

A static public key is added to a VM at startup as cloud-init metadata. This method does not affect cloud-init user data.

Prerequisites

  • You generated an SSH key pair by running the ssh-keygen command.

Procedure

  1. Navigate to Virtualization → Overview in the web console.

  2. On the Settings tab, click the User tab.

  3. Expand Manage SSH keys.

  4. Select a project from the Project list and click the edit icon.

  5. Select an SSH key option:

    • Use existing: Select a secret from the secrets list.

    • Add new:

      1. Browse to the public SSH key file or paste the file in the key field.

      2. Enter the secret name.

  6. Click Save.

Verification

  1. Create a VM in the same project as the SSH key.

  2. Click the VM to view the VirtualMachine details page.

  3. Click the Scripts tab on the Configuration tab.

    The secret name is displayed in the Authorized SSH key section.

Running the virtctl ssh command

You can access a running virtual machine (VM) by using the virtcl ssh command.

Prerequisites

  • You installed the virtctl command line tool.

  • You added a public SSH key to the VM.

  • You have an SSH client installed.

  • 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

  • Run the virtctl ssh command:

    $ virtctl -n <namespace> ssh <username>@example-vm -i <ssh_key> (1)
    1 Specify the namespace, user name, and the SSH private key. The default SSH key location is /home/user/.ssh. If you save the key in a different location, you must specify the path.
    Example
    $ virtctl -n my-namespace ssh cloud-user@example-vm -i my-key

You can copy the virtctl ssh command in the web console by selecting Copy SSH command from the options kebab menu beside a VM on the VirtualMachines page.

Using OpenSSH and virtctl port-forward

You can access a running virtual machine (VM) by using a local OpenSSH client and the virtctl port-forward command. 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 OpenSSH installed.

  • You installed the virtctl command line tool.

  • The environment where you installed virtctl 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>

Using a service for SSH access

You can create a service for a virtual machine (VM) and connect to the IP address and port exposed by the service.

Services provide excellent performance and are recommended for applications that are accessed from outside the cluster or within the cluster. Ingress traffic is protected by firewalls.

If the cluster network cannot handle the traffic load, consider using a secondary network for VM access.

About services

A Kubernetes service exposes network access for clients to an application running on a set of pods. Services offer abstraction, load balancing, and, in the case of the NodePort and LoadBalancer types, exposure to the outside world.

ClusterIP

Exposes the service on an internal IP address and as a DNS name to other applications within the cluster. A single service can map to multiple virtual machines. When a client tries to connect to the service, the client’s request is load balanced among available backends. ClusterIP is the default service type.

NodePort

Exposes the service on the same port of each selected node in the cluster. NodePort makes a port accessible from outside the cluster, as long as the node itself is externally accessible to the client.

LoadBalancer

Creates an external load balancer in the current cloud (if supported) and assigns a fixed, external IP address to the service.

For on-premise clusters, you can configure a load balancing service by using the MetalLB Operator in layer 2 mode. The BGP mode is not supported. The MetalLB Operator is installed in the metallb-system namespace.

Creating a service

You can create a service to expose a virtual machine (VM) by using the OpenShift Container Platform web console, virtctl command line tool, or a YAML file.

Creating a node port or load balancer service by using the web console

You can create a node port or load balancer service for a virtual machine (VM) by using the OpenShift Container Platform web console.

Prerequisites

  • You configured the cluster network to support either a load balancer or a node port.

Procedure

  1. For a load balancer service, enable the creation of load balancer services:

    1. Navigate to Virtualization → Overview.

    2. On the Settings tab, click Cluster.

    3. Expand LoadBalancer service and select Enable the creation of LoadBalancer services for SSH connections to VirtualMachines.

  2. Navigate to VirtualMachines and select a virtual machine to view the VirtualMachine details page.

  3. On the Details tab, select SSH over LoadBalancer or SSH over NodePort from the SSH service type list.

  4. Optional: Click the copy icon to copy the SSH command to your clipboard.

Verification

  • Check the Services pane on the Details tab for the new service.

Creating a service by using virtctl

You can create a service for a virtual machine (VM) by using the virtctl command line tool.

Prerequisites

  • You installed the virtctl command line tool.

  • You configured the cluster network to support the service.

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

Procedure

  • Create a service by running the following command:

    $ virtctl expose vm <vm_name> --name <service_name> --type <service_type> --port <port> (1)
    1 Specify the ClusterIP, NodePort, or LoadBalancer service type.
    Example
    $ virtctl expose vm example-vm --name example-service --type NodePort --port 22
Verification

  • Verify the service by running the following command:

    $ oc get service
Next steps

After you create a service with virtctl, you must add special: key to the spec.template.metadata.labels stanza of the VirtualMachine manifest. See Creating a service by using the command line.

Creating a service by using the command line

You can create a service and associate it with a virtual machine (VM) by using the command line.

Prerequisites

  • You configured the cluster network to support the service.

Procedure

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

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

    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: example-service
  namespace: example-namespace
spec:
# ...
  selector:
    special: key (1)
  type: NodePort (2)
    1 Specify the label that you added to the spec.template.metadata.labels stanza of the VirtualMachine manifest.
    2 Specify ClusterIP, NodePort, or LoadBalancer.

  4. Save the Service manifest file.

  5. Create the service by running the following command:

    $ oc create -f example-service.yaml

  6. Restart the VM to apply the changes.

Verification

  • Query the Service object to verify that it is available:

    $ oc get service -n example-namespace

Connecting to a virtual machine by using SSH and a service

You can connect to a virtual machine (VM) by using SSH and a service.

Prerequisites

  • You created a service to expose a VM.

  • You have an SSH client installed.

  • You are logged in to the cluster.

Procedure

  • Run the following command to access the VM:

    $ ssh <user_name>@<ip_address> -p <port> (1)
    1 Specify the cluster IP for a cluster IP service, the node IP for a node port service, or the external IP address for a load balancer service.

Using a secondary network for SSH access

You can configure a secondary network, attach a virtual machine (VM) to the secondary network interface, and connect to the DHCP-allocated IP address by using SSH.

Secondary networks provide excellent performance because the traffic is not handled by the cluster network stack. However, the VMs are exposed directly to the secondary network and are not protected by firewalls. If a VM is compromised, an intruder could gain access to the secondary network. You must configure appropriate security within the operating system of the VM if you use this method.

See the Multus and SR-IOV documentation in the OpenShift Virtualization Tuning & Scaling Guide for additional information about networking options.

Prerequisites

Configuring a network interface for a virtual machine by using the web console

You can configure a network interface for a virtual machine (VM) by using the OpenShift Container Platform web console.

Prerequisites

  • You created a network attachment definition for the network.

Procedure

  1. Navigate to Virtualization → VirtualMachines.

  2. Click a VM to view the VirtualMachine details page.

  3. On the Configuration tab, click the Network interfaces tab.

  4. Click Add network interface.

  5. Enter the interface name and select the network attachment definition from the Network list.

  6. Click Save.

  7. Restart the VM to apply the changes.

Connecting to a virtual machine attached to a secondary network by using SSH

You can connect to a virtual machine (VM) attached to a secondary network by using SSH.

Prerequisites

  • You attached a VM to a secondary network with a DHCP server.

  • You have an SSH client installed.

Procedure

  1. Obtain the IP address of the VM by running the following command:

    $ oc describe vm <vm_name>
    Example output
    # ...
Interfaces:
  Interface Name:  eth0
  Ip Address:      10.244.0.37/24
  Ip Addresses:
    10.244.0.37/24
    fe80::858:aff:fef4:25/64
  Mac:             0a:58:0a:f4:00:25
  Name:            default
# ...

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

    $ ssh <user_name>@<ip_address> -i <ssh_key>
    Example
    $ ssh cloud-user@10.244.0.37 -i ~/.ssh/id_rsa_cloud-user

You can also access a VM attached to a secondary network interface by using the cluster FQDN.