Chapter 3. Getting started 3.1. Getting started with OpenShift Virtualization You can explore the features and functionalities of OpenShift Virtualization by installing and configuring a basic environment. Note Cluster configuration procedures require cluster-admin privileges. 3.1.1. Tours and quick starts You can start exploring OpenShift Virtualization by taking tours in the OpenShift Container Platform web console. Getting started tour This short guided tour introduces several key aspects of using OpenShift Virtualization. There are two ways to start the tour: On the Welcome to OpenShift Virtualization dialog, click Start Tour . Go to Virtualization Overview Settings User Getting started resources and click Guided tour . Quick starts Quick start tours are available for several OpenShift Virtualization features. To access quick starts, complete the following steps: Click the Help icon ? in the menu bar on the header of the OpenShift Container Platform web console. Select Quick Starts . You can filter the available tours by entering the keyword virtual in the Filter field. 3.1.2. Planning and installing OpenShift Virtualization Plan and install OpenShift Virtualization on an OpenShift Container Platform cluster: Plan your bare metal cluster for OpenShift Virtualization . Prepare your cluster for OpenShift Virtualization . Install the OpenShift Virtualization Operator . Install the virtctl command line interface (CLI) tool . Planning and installation resources About storage volumes for virtual machine disks . Using a CSI-enabled storage provider . Configuring local storage for virtual machines . Installing the Kubernetes NMState Operator . Specifying nodes for virtual machines . Virtctl commands . 3.1.3. Creating and managing virtual machines Create a virtual machine (VM): Create a VM from a Red Hat image . You can create a VM by using a Red Hat template or an instance type . Create a VM from a custom image . You can create a VM by importing a custom image from a container registry or a web page, by uploading an image from your local machine, or by cloning a persistent volume claim (PVC). Connect a VM to a secondary network: Linux bridge network . Open Virtual Network (OVN)-Kubernetes secondary network . Single Root I/O Virtualization (SR-IOV) network . Note VMs are connected to the pod network by default. Connect to a VM: Connect to the serial console or VNC console of a VM. Connect to a VM by using SSH . Connect to the desktop viewer for Windows VMs . Manage a VM: Manage a VM by using the web console . Manage a VM by using the virtctl CLI tool . Export a VM . 3.1.4. Migrating to OpenShift Virtualization To migrate virtual machines from an external provider such as VMware vSphere, Red Hat OpenStack Platform (RHOSP), Red Hat Virtualization, or another OpenShift Container Platform cluster, use the Migration Toolkit for Virtualization (MTV). You can also migrate Open Virtual Appliance (OVA) files created by VMware vSphere. Note Migration Toolkit for Virtualization is not part of OpenShift Virtualization and requires separate installation. For this reason, all links in this procedure lead outside of OpenShift Virtualization documentation. Prerequisites The Migration Toolkit for Virtualization Operator is installed . Procedure Configure the source provider . Select the source provider and enter any required information, such as the URL of the API endpoint or credentials needed to access the virtual machines. Create a migration plan . Select from the list of available virtual machines, configure the target provider, and define storage and network mappings. Run the migration plan . Watch the progress, view migration logs, or cancel the migration. Optional: Archive the migration plan . After confirming that the migration has completed successfully, you can archive the migration plan to delete the logs and clean up all temporary resources created during migration. You can permanently delete an archived migration plan. 3.1.5. steps Review postinstallation configuration options . Configure storage options and automatic boot source updates . Learn about monitoring and health checks . Learn about live migration . Back up and restore VMs by using the OpenShift API for Data Protection (OADP) . Tune and scale your cluster . 3.2. Using the CLI tools You can manage OpenShift Virtualization resources by using the virtctl command line tool. You can access and modify virtual machine (VM) disk images by using the libguestfs command line tool. You deploy libguestfs by using the virtctl libguestfs command. 3.2.1. Installing virtctl To install virtctl on Red Hat Enterprise Linux (RHEL) 9, Linux, Windows, and MacOS operating systems, you download and install the virtctl binary file. To install virtctl on RHEL 8, you enable the OpenShift Virtualization repository and then install the kubevirt-virtctl package. 3.2.1.1. Installing the virtctl binary on RHEL 9, Linux, Windows, or macOS You can download the virtctl binary for your operating system from the OpenShift Container Platform web console and then install it. Procedure Navigate to the Virtualization Overview page in the web console. Click the Download virtctl link to download the virtctl binary for your operating system. Install virtctl : For RHEL 9 and other Linux operating systems: Decompress the archive file: USD tar -xvf <virtctl-version-distribution.arch>.tar.gz Run the following command to make the virtctl binary executable: USD chmod +x <path/virtctl-file-name> Move the virtctl binary to a directory in your PATH environment variable. You can check your path by running the following command: USD echo USDPATH Set the KUBECONFIG environment variable: USD export KUBECONFIG=/home/<user>/clusters/current/auth/kubeconfig For Windows: Decompress the archive file. Navigate the extracted folder hierarchy and double-click the virtctl executable file to install the client. Move the virtctl binary to a directory in your PATH environment variable. You can check your path by running the following command: C:\> path For macOS: Decompress the archive file. Move the virtctl binary to a directory in your PATH environment variable. You can check your path by running the following command: echo USDPATH 3.2.1.2. Installing the virtctl RPM on RHEL 8 You can install the virtctl RPM package on Red Hat Enterprise Linux (RHEL) 8 by enabling the OpenShift Virtualization repository and installing the kubevirt-virtctl package. Prerequisites Each host in your cluster must be registered with Red Hat Subscription Manager (RHSM) and have an active OpenShift Container Platform subscription. Procedure Enable the OpenShift Virtualization repository by using the subscription-manager CLI tool to run the following command: # subscription-manager repos --enable cnv-4.17-for-rhel-8-x86_64-rpms Install the kubevirt-virtctl package by running the following command: # yum install kubevirt-virtctl 3.2.2. virtctl commands The virtctl client is a command-line utility for managing OpenShift Virtualization resources. Note The virtual machine (VM) commands also apply to virtual machine instances (VMIs) unless otherwise specified. 3.2.2.1. virtctl information commands You use virtctl information commands to view information about the virtctl client. Table 3.1. Information commands Command Description virtctl version View the virtctl client and server versions. virtctl help View a list of virtctl commands. virtctl <command> -h|--help View a list of options for a specific command. virtctl options View a list of global command options for any virtctl command. 3.2.2.2. VM information commands You can use virtctl to view information about virtual machines (VMs) and virtual machine instances (VMIs). Table 3.2. VM information commands Command Description virtctl fslist <vm_name> View the file systems available on a guest machine. virtctl guestosinfo <vm_name> View information about the operating systems on a guest machine. virtctl userlist <vm_name> View the logged-in users on a guest machine. 3.2.2.3. VM manifest creation commands You can use virtctl create commands to create manifests for virtual machines, instance types, and preferences. Table 3.3. VM manifest creation commands Command Description virtctl create vm Create a VirtualMachine (VM) manifest. virtctl create vm --name <vm_name> Create a VM manifest, specifying a name for the VM. virtctl create vm --instancetype <instancetype_name> Create a VM manifest that uses an existing cluster-wide instance type. virtctl create vm --instancetype=virtualmachineinstancetype/<instancetype_name> Create a VM manifest that uses an existing namespaced instance type. virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name> Create a manifest for a cluster-wide instance type. virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name> --namespace <namespace_value> Create a manifest for a namespaced instance type. virtctl create preference --name <preference_name> Create a manifest for a cluster-wide VM preference, specifying a name for the preference. virtctl create preference --namespace <namespace_value> Create a manifest for a namespaced VM preference. 3.2.2.4. VM management commands You use virtctl virtual machine (VM) management commands to manage and migrate virtual machines (VMs) and virtual machine instances (VMIs). Table 3.4. VM management commands Command Description virtctl start <vm_name> Start a VM. virtctl start --paused <vm_name> Start a VM in a paused state. This option enables you to interrupt the boot process from the VNC console. virtctl stop <vm_name> Stop a VM. virtctl stop <vm_name> --grace-period 0 --force Force stop a VM. This option might cause data inconsistency or data loss. virtctl pause vm <vm_name> Pause a VM. The machine state is kept in memory. virtctl unpause vm <vm_name> Unpause a VM. virtctl migrate <vm_name> Migrate a VM. virtctl migrate-cancel <vm_name> Cancel a VM migration. virtctl restart <vm_name> Restart a VM. 3.2.2.5. VM connection commands You use virtctl connection commands to expose ports and connect to virtual machines (VMs) and virtual machine instances (VMIs). Table 3.5. VM connection commands Command Description virtctl console <vm_name> Connect to the serial console of a VM. virtctl expose vm <vm_name> --name <service_name> --type <ClusterIP|NodePort|LoadBalancer> --port <port> Create a service that forwards a designated port of a VM and expose the service on the specified port of the node. Example: virtctl expose vm rhel9_vm --name rhel9-ssh --type NodePort --port 22 virtctl scp -i <ssh_key> <file_name> <user_name>@<vm_name> Copy a file from your machine to a VM. This command uses the private key of an SSH key pair. The VM must be configured with the public key. virtctl scp -i <ssh_key> <user_name@<vm_name>:<file_name> . Copy a file from a VM to your machine. This command uses the private key of an SSH key pair. The VM must be configured with the public key. virtctl ssh -i <ssh_key> <user_name>@<vm_name> Open an SSH connection with a VM. This command uses the private key of an SSH key pair. The VM must be configured with the public key. virtctl vnc <vm_name> Connect to the VNC console of a VM. You must have virt-viewer installed. virtctl vnc --proxy-only=true <vm_name> Display the port number and connect manually to a VM by using any viewer through the VNC connection. virtctl vnc --port=<port-number> <vm_name> Specify a port number to run the proxy on the specified port, if that port is available. If a port number is not specified, the proxy runs on a random port. 3.2.2.6. VM export commands Use virtctl vmexport commands to create, download, or delete a volume exported from a VM, VM snapshot, or persistent volume claim (PVC). Certain manifests also contain a header secret, which grants access to the endpoint to import a disk image in a format that OpenShift Virtualization can use. Table 3.6. VM export commands Command Description virtctl vmexport create <vmexport_name> --vm|snapshot|pvc=<object_name> Create a VirtualMachineExport custom resource (CR) to export a volume from a VM, VM snapshot, or PVC. --vm : Exports the PVCs of a VM. --snapshot : Exports the PVCs contained in a VirtualMachineSnapshot CR. --pvc : Exports a PVC. Optional: --ttl=1h specifies the time to live. The default duration is 2 hours. virtctl vmexport delete <vmexport_name> Delete a VirtualMachineExport CR manually. virtctl vmexport download <vmexport_name> --output=<output_file> --volume=<volume_name> Download the volume defined in a VirtualMachineExport CR. --output specifies the file format. Example: disk.img.gz . --volume specifies the volume to download. This flag is optional if only one volume is available. Optional: --keep-vme retains the VirtualMachineExport CR after download. The default behavior is to delete the VirtualMachineExport CR after download. --insecure enables an insecure HTTP connection. virtctl vmexport download <vmexport_name> --<vm|snapshot|pvc>=<object_name> --output=<output_file> --volume=<volume_name> Create a VirtualMachineExport CR and then download the volume defined in the CR. virtctl vmexport download export --manifest Retrieve the manifest for an existing export. The manifest does not include the header secret. virtctl vmexport download export --manifest --vm=example Create a VM export for a VM example, and retrieve the manifest. The manifest does not include the header secret. virtctl vmexport download export --manifest --snap=example Create a VM export for a VM snapshot example, and retrieve the manifest. The manifest does not include the header secret. virtctl vmexport download export --manifest --include-secret Retrieve the manifest for an existing export. The manifest includes the header secret. virtctl vmexport download export --manifest --manifest-output-format=json Retrieve the manifest for an existing export in json format. The manifest does not include the header secret. virtctl vmexport download export --manifest --include-secret --output=manifest.yaml Retrieve the manifest for an existing export. The manifest includes the header secret and writes it to the file specified. 3.2.2.7. VM memory dump commands You can use the virtctl memory-dump command to output a VM memory dump on a PVC. You can specify an existing PVC or use the --create-claim flag to create a new PVC. Prerequisites The PVC volume mode must be FileSystem . The PVC must be large enough to contain the memory dump. The formula for calculating the PVC size is (VMMemorySize + 100Mi) * FileSystemOverhead , where 100Mi is the memory dump overhead. You must enable the hot plug feature gate in the HyperConverged custom resource by running the following command: USD oc patch hyperconverged kubevirt-hyperconverged -n openshift-cnv \ --type json -p '[{"op": "add", "path": "/spec/featureGates", \ "value": "HotplugVolumes"}]' Downloading the memory dump You must use the virtctl vmexport download command to download the memory dump: USD virtctl vmexport download <vmexport_name> --vm|pvc=<object_name> \ --volume=<volume_name> --output=<output_file> Table 3.7. VM memory dump commands Command Description virtctl memory-dump get <vm_name> --claim-name=<pvc_name> Save the memory dump of a VM on a PVC. The memory dump status is displayed in the status section of the VirtualMachine resource. Optional: --create-claim creates a new PVC with the appropriate size. This flag has the following options: --storage-class=<storage_class> : Specify a storage class for the PVC. --access-mode=<access_mode> : Specify ReadWriteOnce or ReadWriteMany . virtctl memory-dump get <vm_name> Rerun the virtctl memory-dump command with the same PVC. This command overwrites the memory dump. virtctl memory-dump remove <vm_name> Remove a memory dump. You must remove a memory dump manually if you want to change the target PVC. This command removes the association between the VM and the PVC, so that the memory dump is not displayed in the status section of the VirtualMachine resource. The PVC is not affected. 3.2.2.8. Hot plug and hot unplug commands You use virtctl to add or remove resources from running virtual machines (VMs) and virtual machine instances (VMIs). Table 3.8. Hot plug and hot unplug commands Command Description virtctl addvolume <vm_name> --volume-name=<datavolume_or_PVC> [--persist] [--serial=<label>] Hot plug a data volume or persistent volume claim (PVC). Optional: --persist mounts the virtual disk permanently on a VM. This flag does not apply to VMIs. --serial=<label> adds a label to the VM. If you do not specify a label, the default label is the data volume or PVC name. virtctl removevolume <vm_name> --volume-name=<virtual_disk> Hot unplug a virtual disk. virtctl addinterface <vm_name> --network-attachment-definition-name <net_attach_def_name> --name <interface_name> Hot plug a Linux bridge network interface. virtctl removeinterface <vm_name> --name <interface_name> Hot unplug a Linux bridge network interface. 3.2.2.9. Image upload commands You use the virtctl image-upload commands to upload a VM image to a data volume. Table 3.9. Image upload commands Command Description virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create Upload a VM image to a data volume that already exists. virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image> Upload a VM image to a new data volume of a specified requested size. 3.2.3. Deploying libguestfs by using virtctl You can use the virtctl guestfs command to deploy an interactive container with libguestfs-tools and a persistent volume claim (PVC) attached to it. Procedure To deploy a container with libguestfs-tools , mount the PVC, and attach a shell to it, run the following command: USD virtctl guestfs -n <namespace> <pvc_name> 1 1 The PVC name is a required argument. If you do not include it, an error message appears. 3.2.3.1. Libguestfs and virtctl guestfs commands Libguestfs tools help you access and modify virtual machine (VM) disk images. You can use libguestfs tools to view and edit files in a guest, clone and build virtual machines, and format and resize disks. You can also use the virtctl guestfs command and its sub-commands to modify, inspect, and debug VM disks on a PVC. To see a complete list of possible sub-commands, enter virt- on the command line and press the Tab key. For example: Command Description virt-edit -a /dev/vda /etc/motd Edit a file interactively in your terminal. virt-customize -a /dev/vda --ssh-inject root:string:<public key example> Inject an ssh key into the guest and create a login. virt-df -a /dev/vda -h See how much disk space is used by a VM. virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list' See the full list of all RPMs installed on a guest by creating an output file containing the full list. virt-cat -a /dev/vda /rpm-list Display the output file list of all RPMs created using the virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list' command in your terminal. virt-sysprep -a /dev/vda Seal a virtual machine disk image to be used as a template. By default, virtctl guestfs creates a session with everything needed to manage a VM disk. However, the command also supports several flag options if you want to customize the behavior: Flag Option Description --h or --help Provides help for guestfs . -n <namespace> option with a <pvc_name> argument To use a PVC from a specific namespace. If you do not use the -n <namespace> option, your current project is used. To change projects, use oc project <namespace> . If you do not include a <pvc_name> argument, an error message appears. --image string Lists the libguestfs-tools container image. You can configure the container to use a custom image by using the --image option. --kvm Indicates that kvm is used by the libguestfs-tools container. By default, virtctl guestfs sets up kvm for the interactive container, which greatly speeds up the libguest-tools execution because it uses QEMU. If a cluster does not have any kvm supporting nodes, you must disable kvm by setting the option --kvm=false . If not set, the libguestfs-tools pod remains pending because it cannot be scheduled on any node. --pull-policy string Shows the pull policy for the libguestfs image. You can also overwrite the image's pull policy by setting the pull-policy option. The command also checks if a PVC is in use by another pod, in which case an error message appears. However, once the libguestfs-tools process starts, the setup cannot avoid a new pod using the same PVC. You must verify that there are no active virtctl guestfs pods before starting the VM that accesses the same PVC. Note The virtctl guestfs command accepts only a single PVC attached to the interactive pod. 3.2.4. Using Ansible To use the Ansible collection for OpenShift Virtualization, see Red Hat Ansible Automation Hub (Red Hat Hybrid Cloud Console).

Commands:
tar -xvf <virtctl-version-distribution.arch>.tar.gz
chmod +x <path/virtctl-file-name>
echo USDPATH
export KUBECONFIG=/home/<user>/clusters/current/auth/kubeconfig
C:\> path
echo USDPATH
subscription-manager repos --enable cnv-4.17-for-rhel-8-x86_64-rpms
yum install kubevirt-virtctl
oc patch hyperconverged kubevirt-hyperconverged -n openshift-cnv --type json -p '[{"op": "add", "path": "/spec/featureGates", "value": "HotplugVolumes"}]'
virtctl vmexport download <vmexport_name> --vm|pvc=<object_name> --volume=<volume_name> --output=<output_file>
virtctl guestfs -n <namespace> <pvc_name> 1