Questo contenuto non è disponibile nella lingua selezionata.
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.
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 virtualization
in the Filter field.
3.1.2. Planning and installing OpenShift Virtualization
Plan and install OpenShift Virtualization on an OpenShift Container Platform cluster:
Planning and installation resources
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.
NoteVMs 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:
3.1.4. Next steps
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:
$ tar -xvf <virtctl-version-distribution.arch>.tar.gz
Run the following command to make the
virtctl
binary executable:$ chmod +x <path/virtctl-file-name>
Move the
virtctl
binary to a directory in yourPATH
environment variable.You can check your path by running the following command:
$ echo $PATH
Set the
KUBECONFIG
environment variable:$ 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 yourPATH
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 yourPATH
environment variable.You can check your path by running the following command:
echo $PATH
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.
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.
Command | Description |
---|---|
|
View the |
|
View a list of |
| View a list of options for a specific command. |
|
View a list of global command options for any |
3.2.2.2. VM information commands
You can use virtctl
to view information about virtual machines (VMs) and virtual machine instances (VMIs).
Command | Description |
---|---|
| View the file systems available on a guest machine. |
| View information about the operating systems on a guest machine. |
| 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.
Command | Description |
---|---|
|
Create a |
| Create a VM manifest, specifying a name for the VM. |
| Create a VM manifest that uses an existing cluster-wide instance type. |
| Create a VM manifest that uses an existing namespaced instance type. |
| Create a manifest for a cluster-wide instance type. |
| Create a manifest for a namespaced instance type. |
| Create a manifest for a cluster-wide VM preference, specifying a name for the preference. |
| 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).
Command | Description |
---|---|
| Start a VM. |
| Start a VM in a paused state. This option enables you to interrupt the boot process from the VNC console. |
| Stop a VM. |
| Force stop a VM. This option might cause data inconsistency or data loss. |
| Pause a VM. The machine state is kept in memory. |
| Unpause a VM. |
| Migrate a VM. |
| Cancel a VM migration. |
| 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).
Command | Description |
---|---|
| Connect to the serial console of a VM. |
| Create a service that forwards a designated port of a VM and expose the service on the specified port of the node.
Example: |
| 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. |
| 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. |
| 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. |
| Connect to the VNC console of a VM.
You must have |
| Display the port number and connect manually to a VM by using any viewer through the VNC connection. |
| 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.
Command | Description |
---|---|
|
Create a
|
|
Delete a |
|
Download the volume defined in a
Optional:
|
|
Create a |
| Retrieve the manifest for an existing export. The manifest does not include the header secret. |
| Create a VM export for a VM example, and retrieve the manifest. The manifest does not include the header secret. |
| Create a VM export for a VM snapshot example, and retrieve the manifest. The manifest does not include the header secret. |
| Retrieve the manifest for an existing export. The manifest includes the header secret. |
| Retrieve the manifest for an existing export in json format. The manifest does not include the header secret. |
| 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
, where100Mi
is the memory dump overhead.You must enable the hot plug feature gate in the
HyperConverged
custom resource by running the following command:$ 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:
$ virtctl vmexport download <vmexport_name> --vm|pvc=<object_name> \ --volume=<volume_name> --output=<output_file>
Command | Description |
---|---|
|
Save the memory dump of a VM on a PVC. The memory dump status is displayed in the Optional:
|
|
Rerun the This command overwrites the previous memory dump. |
| 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 |
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).
Command | Description |
---|---|
| Hot plug a data volume or persistent volume claim (PVC). Optional:
|
| Hot unplug a virtual disk. |
| Hot plug a Linux bridge network interface. |
| 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.
Command | Description |
---|---|
| Upload a VM image to a data volume that already exists. |
| 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:$ 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 |
---|---|
| Edit a file interactively in your terminal. |
| Inject an ssh key into the guest and create a login. |
| See how much disk space is used by a VM. |
| See the full list of all RPMs installed on a guest by creating an output file containing the full list. |
|
Display the output file list of all RPMs created using the |
| 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 |
---|---|
|
Provides help for |
| To use a PVC from a specific namespace.
If you do not use the
If you do not include a |
|
Lists the
You can configure the container to use a custom image by using the |
|
Indicates that
By default,
If a cluster does not have any
If not set, the |
|
Shows the pull policy for the
You can also overwrite the image’s pull policy by setting the |
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.
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).