Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Installing

Before you install OpenShift Virtualization, review this section to ensure that your cluster meets the requirements.

You can run OpenShift Virtualization on an OpenShift Dedicated cluster.

Installing
  • You can install the cluster by using installer-provisioned infrastructure, ensuring that you specify bare-metal instance types for the worker nodes. For example, you can use the c3-standard-192-metal type value for a machine based on x86_64 architecture.
Note

OpenShift Virtualization on Google Cloud requires OpenShift Dedicated 4.21.5 and OpenShift Virtualization Operator 4.21.1 or later.

Accessing virtual machines (VMs)
  • There is no change to how you access VMs by using the virtctl CLI tool or the OpenShift Dedicated web console.

  • You can expose VMs by using a NodePort or LoadBalancer service.

    Note

    The load balancer approach is preferable because OpenShift Dedicated automatically creates the load balancer in Google Cloud and manages its lifecycle. A security group is also created for the load balancer, and you can use annotations to attach existing security groups. When you remove the service, OpenShift Dedicated removes the load balancer and its associated resources.

Storage

3.1.2. Hardware and operating system requirements
Copy link

Review the following hardware and operating system requirements for OpenShift Virtualization.

3.1.2.1. CPU requirements
Copy link

  • Supported by Red Hat Enterprise Linux (RHEL) 9.

    See Red Hat Ecosystem Catalog for supported CPUs.

    Note

    If your worker nodes have different CPUs, live migration failures might occur because different CPUs have different capabilities. You can mitigate this issue by ensuring that your worker nodes have CPUs with the appropriate capacity and by configuring node affinity rules for your virtual machines.

    See Configuring a required node affinity rule for details.

  • Supports AMD64, Intel 64-bit (x86-64-v2), IBM Z® (s390x), or ARM64-based (arm64 or aarch64) architectures and their respective CPU extensions.
  • Intel VT-x, AMD-V, or ARM virtualization extensions are enabled, or s390x virtualization support is enabled.
  • NX (no execute) flag is enabled.
  • If you use s390x architecture, the default CPU model is set to gen15b.

3.1.2.2. Operating system requirements
Copy link

  • Red Hat Enterprise Linux CoreOS (RHCOS) installed on worker nodes.

3.1.2.3. Storage requirements
Copy link

  • Supported by OpenShift Dedicated.
  • If the storage provisioner supports snapshots, you must associate a VolumeSnapshotClass object with the default storage class.

If you use the storage API with known storage providers, the volume and access modes are selected automatically. However, if you use a storage class that does not have a storage profile, you must configure the volume and access mode.

For a list of known storage providers for OpenShift Virtualization, see the Red Hat Ecosystem Catalog.

For best results, use the Block volume mode. This is important for the following reasons:

  • Shared storage that supports live migration is required to migrate virtual machines between nodes.
  • The Block volume mode performs significantly better than the Filesystem volume mode. This is because the Filesystem volume mode uses more storage layers, including a file system layer and a disk image file. These layers are not necessary for VM disk storage.
Important

You cannot live migrate virtual machines with the following configurations:

  • Storage volume with ReadWriteOnce (RWO) access mode
  • Passthrough features such as GPUs

Set the evictionStrategy field to None for these virtual machines. The None strategy powers down VMs during node reboots.

3.1.3. Live migration requirements
Copy link

  • Shared storage that supports live migration.

  • Sufficient RAM and network bandwidth.

    Note

    You must ensure that there is enough memory request capacity in the cluster to support node drains that result in live migrations. You can determine the approximate required spare memory by using the following calculation: 

    Product of (Maximum number of nodes that can drain in parallel) and (Highest total VM memory request allocations across nodes)

    The default number of migrations that can run in parallel in the cluster is 5.

  • If the virtual machine uses a host model CPU, the nodes must support the virtual machine’s host model CPU.
Note

A dedicated Multus network for live migration is highly recommended. A dedicated network minimizes the effects of network saturation on tenant workloads during migration.

3.1.4. Physical resource overhead requirements
Copy link

OpenShift Virtualization is an add-on to OpenShift Dedicated and imposes additional overhead that you must account for when planning a cluster.

Each cluster machine must accommodate the following overhead requirements in addition to the OpenShift Dedicated requirements. Oversubscribing the physical resources in a cluster can affect performance.

Important

The numbers noted in this documentation are based on Red Hat’s test methodology and setup. These numbers can vary based on your own individual setup and environments.

3.1.4.1. Memory overhead
Copy link

Calculate the memory overhead values for OpenShift Virtualization by using the equations below.

Cluster memory overhead
Memory overhead per infrastructure node ≈ 150 MiB
 
Memory overhead per worker node ≈ 360 MiB

Additionally, OpenShift Virtualization environment resources require a total of 2179 MiB of RAM that is spread across all infrastructure nodes.

Virtual machine memory overhead
Memory overhead per virtual machine ≈ (0.002 × requested memory) \
              + 218 MiB \
              + 8 MiB × (number of vCPUs) \
              + 16 MiB × (number of graphics devices) \
              + (additional memory overhead)
  • 218 MiB is required for the processes that run in the virt-launcher pod.
  • 8 MiB × (number of vCPUs) refers to the number of virtual CPUs requested by the virtual machine.
  • 16 MiB × (number of graphics devices) refers to the number of virtual graphics cards requested by the virtual machine.

  • Additional memory overhead:

    • If your environment includes a Single Root I/O Virtualization (SR-IOV) network device or a Graphics Processing Unit (GPU), allocate 1 GiB additional memory overhead for each device.
    • If Secure Encrypted Virtualization (SEV) is enabled, add 256 MiB.
    • If Trusted Platform Module (TPM) is enabled, add 53 MiB.

3.1.4.2. CPU overhead
Copy link

Calculate the cluster processor overhead requirements for OpenShift Virtualization by using the equation below. The CPU overhead per virtual machine depends on your individual setup.

Cluster CPU overhead
CPU overhead for infrastructure nodes ≈ 4 cores

OpenShift Virtualization increases the overall utilization of cluster level services such as logging, routing, and monitoring. To account for this workload, ensure that nodes that host infrastructure components have capacity allocated for 4 additional cores (4000 millicores) distributed across those nodes. 

CPU overhead for worker nodes ≈ 2 cores + CPU overhead per virtual machine

Each worker node that hosts virtual machines must have capacity for 2 additional cores (2000 millicores) for OpenShift Virtualization management workloads in addition to the CPUs required for virtual machine workloads.

Virtual machine CPU overhead
If dedicated CPUs are requested, there is a 1:1 impact on the cluster CPU overhead requirement. Otherwise, there are no specific rules about how many CPUs a virtual machine requires.

3.1.4.3. Storage overhead
Copy link

Use the guidelines below to estimate storage overhead requirements for your OpenShift Virtualization environment.

Cluster storage overhead
Aggregated storage overhead per node ≈ 10 GiB

10 GiB is the estimated on-disk storage impact for each node in the cluster when you install OpenShift Virtualization.

Virtual machine storage overhead
Storage overhead per virtual machine depends on specific requests for resource allocation within the virtual machine. The request could be for ephemeral storage on the node or storage resources hosted elsewhere in the cluster. OpenShift Virtualization does not currently allocate any additional ephemeral storage for the running container itself.
Example
As a cluster administrator, if you plan to host 10 virtual machines in the cluster, each with 1 GiB of RAM and 2 vCPUs, the memory impact across the cluster is 11.68 GiB. The estimated on-disk storage impact for each node in the cluster is 10 GiB and the CPU impact for worker nodes that host virtual machine workloads is a minimum of 2 cores.

3.2. Installing OpenShift Virtualization
Copy link

Install OpenShift Virtualization to add virtualization functionality to your OpenShift Dedicated cluster.

Install the OpenShift Virtualization Operator by using the OpenShift Dedicated web console or the command line.

You can deploy the OpenShift Virtualization Operator by using the OpenShift Dedicated web console.

Prerequisites

  • Install OpenShift Dedicated 4 on your cluster.
  • Log in to the OpenShift Dedicated web console as a user with cluster-admin permissions.
  • Create a machine pool based on a bare metal compute node instance type. For more information, see "Creating a machine pool" in the Additional resources of this section.

Procedure

  1. From the Administrator perspective, click Ecosystem Software Catalog.
  2. In the Filter by keyword field, type Virtualization.
  3. Select the OpenShift Virtualization Operator tile with the Red Hat source label.
  4. Read the information about the Operator and click Install.

  5. On the Install Operator page:

    1. Select stable from the list of available Update Channel options. This ensures that you install the version of OpenShift Virtualization that is compatible with your OpenShift Dedicated version.

    2. For Installed Namespace, ensure that the Operator recommended namespace option is selected. This installs the Operator in the mandatory openshift-cnv namespace, which is automatically created if it does not exist.

      Warning

      Attempting to install the OpenShift Virtualization Operator in a namespace other than openshift-cnv causes the installation to fail.

    3. For Approval Strategy, it is highly recommended that you select Automatic, which is the default value, so that OpenShift Virtualization automatically updates when a new version is available in the stable update channel.

      Selecting the Manual approval strategy is not recommended, as it poses a high risk to cluster support and functionality. Only select Manual if you fully understand these risks and cannot use Automatic.

      Warning

      Because OpenShift Virtualization is only supported when used with the corresponding OpenShift Dedicated version, missing OpenShift Virtualization updates can cause your cluster to become unsupported.

  6. Click Install to make the Operator available to the openshift-cnv namespace.
  7. When the Operator installs successfully, click Create HyperConverged.
  8. Optional: Configure Infra and Workloads node placement options for OpenShift Virtualization components.
  9. Click Create to launch OpenShift Virtualization.

Verification

  • Navigate to the Workloads Pods page and monitor the OpenShift Virtualization pods until they are all Running. After all the pods display the Running state, you can use OpenShift Virtualization.

Subscribe to the OpenShift Virtualization catalog and install the OpenShift Virtualization Operator by applying manifests to your cluster.

Before you install OpenShift Virtualization, you must subscribe to the OpenShift Virtualization catalog. Subscribing gives the openshift-cnv namespace access to the OpenShift Virtualization Operators.

To subscribe, configure Namespace, OperatorGroup, and Subscription objects by applying a single manifest to your cluster.

Prerequisites

  • Install OpenShift Dedicated 4 on your cluster.
  • Install the OpenShift CLI (oc).
  • Log in as a user with cluster-admin privileges.

Procedure

  1. Create a YAML file that contains the following manifest: 

    apiVersion: v1
kind: Namespace
metadata:
  name: openshift-cnv
  labels:
    openshift.io/cluster-monitoring: "true"
---
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: kubevirt-hyperconverged-group
  namespace: openshift-cnv
spec:
  targetNamespaces:
    - openshift-cnv
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: hco-operatorhub
  namespace: openshift-cnv
spec:
  source: redhat-operators
  sourceNamespace: openshift-marketplace
  name: kubevirt-hyperconverged
  startingCSV: kubevirt-hyperconverged-operator.v4.21.1
  channel: "stable"

    Using the stable channel ensures that you install the version of OpenShift Virtualization that is compatible with your OpenShift Dedicated version.

  2. Create the required Namespace, OperatorGroup, and Subscription objects for OpenShift Virtualization by running the following command: 

    $ oc apply -f <filename>.yaml

Verification

You must verify that the subscription creation was successful before you can proceed with installing OpenShift Virtualization.

  1. Check that the ClusterServiceVersion (CSV) object was created successfully. Run the following command and verify the output: 

    $ oc get csv -n openshift-cnv

    If the CSV was created successfully, the output shows an entry that contains a NAME value of kubevirt-hyperconverged-operator-*, a DISPLAY value of OpenShift Virtualization, and a PHASE value of Succeeded, as shown in the following example output:

    Example output: 

    NAME                                       DISPLAY                    VERSION   REPLACES                                   PHASE
kubevirt-hyperconverged-operator.v4.21.1   OpenShift Virtualization   4.21.1    kubevirt-hyperconverged-operator.v4.20.0   Succeeded

  2. Check that the HyperConverged custom resource (CR) has the correct version. Run the following command and verify the output: 

    $ oc get hco -n openshift-cnv kubevirt-hyperconverged -o json | jq .status.versions

    Example output: 

    {
"name": "operator",
"version": "4.21.1"
}

  3. Verify the HyperConverged CR conditions. Run the following command and check the output: 

    $ oc get hco kubevirt-hyperconverged -n openshift-cnv -o json | jq -r '.status.conditions[] | {type,status}'

    Example output: 

    {
  "type": "ReconcileComplete",
  "status": "True"
}
{
  "type": "Available",
  "status": "True"
}
{
  "type": "Progressing",
  "status": "False"
}
{
  "type": "Degraded",
  "status": "False"
}
{
  "type": "Upgradeable",
  "status": "True"
}
Note

You can configure certificate rotation parameters in the YAML file.

You can deploy the OpenShift Virtualization Operator by using the oc CLI.

Prerequisites

  • Install the OpenShift CLI (oc).
  • Subscribe to the OpenShift Virtualization catalog in the openshift-cnv namespace.
  • Log in as a user with cluster-admin privileges.
  • Create a machine pool based on a bare metal compute node instance type.

Procedure

  1. Create a YAML file that contains the following manifest: 

    apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
  namespace: openshift-cnv
spec:

  2. Deploy the OpenShift Virtualization Operator by running the following command: 

    $ oc apply -f <file_name>.yaml

Verification

  • Ensure that OpenShift Virtualization deployed successfully by watching the PHASE of the cluster service version (CSV) in the openshift-cnv namespace. Run the following command: 

    $ watch oc get csv -n openshift-cnv

    The following output displays if deployment was successful: 

    NAME                                      DISPLAY                    VERSION   REPLACES   PHASE
kubevirt-hyperconverged-operator.v4.21.1   OpenShift Virtualization   4.21.1                Succeeded

3.2.2. Next steps
Copy link

  • The hostpath provisioner is a local storage provisioner designed for OpenShift Virtualization. If you want to configure local storage for virtual machines, you must enable the hostpath provisioner first.

3.3. Uninstalling OpenShift Virtualization
Copy link

You uninstall OpenShift Virtualization by using the web console or the command-line interface (CLI) to delete the OpenShift Virtualization workloads, the Operator, and its resources.

You uninstall OpenShift Virtualization by using the web console to perform the following tasks:

  1. Delete the HyperConverged CR.
  2. Delete the OpenShift Virtualization Operator.
  3. Delete the openshift-cnv namespace.
  4. Delete the OpenShift Virtualization custom resource definitions (CRDs).
Important

You must first delete all virtual machines, and virtual machine instances.

You cannot uninstall OpenShift Virtualization while its workloads remain on the cluster.

To uninstall OpenShift Virtualization, you first delete the HyperConverged custom resource (CR).

Prerequisites

  • You have access to an OpenShift Dedicated cluster using an account with cluster-admin permissions.

Procedure

  1. Navigate to the Ecosystem Installed Operators page.
  2. Select the OpenShift Virtualization Operator.
  3. Click the OpenShift Virtualization Deployment tab.
  4. Click the Options menu kebab beside kubevirt-hyperconverged and select Delete HyperConverged.
  5. Click Delete in the confirmation window.

Cluster administrators can delete installed Operators from a selected namespace by using the web console.

Prerequisites

  • You have access to the OpenShift Dedicated cluster web console using an account with dedicated-admin permissions.

Procedure

  1. Navigate to the Ecosystem Installed Operators page.
  2. Scroll or enter a keyword into the Filter by name field to find the Operator that you want to remove. Then, click on it.

  3. On the right side of the Operator Details page, select Uninstall Operator from the Actions list.

    An Uninstall Operator? dialog box is displayed.

  4. Select Uninstall to remove the Operator, Operator deployments, and pods. Following this action, the Operator stops running and no longer receives updates.

    Note

    This action does not remove resources managed by the Operator, including custom resource definitions (CRDs) and custom resources (CRs). Dashboards and navigation items enabled by the web console and off-cluster resources that continue to run might need manual clean up. To remove these after uninstalling the Operator, you might need to manually delete the Operator CRDs.

You can delete a namespace by using the OpenShift Dedicated web console.

Prerequisites

  • You have access to the OpenShift Dedicated cluster using an account with cluster-admin permissions.

Procedure

  1. Navigate to Administration Namespaces.
  2. Locate the namespace that you want to delete in the list of namespaces.
  3. On the far right side of the namespace listing, select Delete Namespace from the Options menu kebab .
  4. When the Delete Namespace pane opens, enter the name of the namespace that you want to delete in the field.
  5. Click Delete.

You can delete the OpenShift Virtualization custom resource definitions (CRDs) by using the web console.

Prerequisites

  • You have access to the OpenShift Dedicated cluster using an account with cluster-admin permissions.

Procedure

  1. Navigate to Administration CustomResourceDefinitions.
  2. Select the Label filter and enter operators.coreos.com/kubevirt-hyperconverged.openshift-cnv in the Search field to display the OpenShift Virtualization CRDs.
  3. Click the Options menu kebab beside each CRD and select Delete CustomResourceDefinition.

You can uninstall OpenShift Virtualization by using the OpenShift CLI (oc).

Prerequisites

  • You have access to the OpenShift Dedicated cluster using an account with cluster-admin permissions.
  • You have installed the OpenShift CLI (oc).
  • You have deleted all virtual machines and virtual machine instances. You cannot uninstall OpenShift Virtualization while its workloads remain on the cluster.

Procedure

  1. Delete the HyperConverged custom resource: 

    $ oc delete HyperConverged kubevirt-hyperconverged -n openshift-cnv

  2. Delete the OpenShift Virtualization Operator subscription: 

    $ oc delete subscription hco-operatorhub -n openshift-cnv

  3. Delete the OpenShift Virtualization ClusterServiceVersion resource: 

    $ oc delete csv -n openshift-cnv -l operators.coreos.com/kubevirt-hyperconverged.openshift-cnv

  4. Delete the OpenShift Virtualization namespace: 

    $ oc delete namespace openshift-cnv

  5. List the OpenShift Virtualization custom resource definitions (CRDs) by running the oc delete crd command with the dry-run option: 

    $ oc delete crd --dry-run=client -l operators.coreos.com/kubevirt-hyperconverged.openshift-cnv

    Example output: 

    customresourcedefinition.apiextensions.k8s.io "cdis.cdi.kubevirt.io" deleted (dry run)
customresourcedefinition.apiextensions.k8s.io "hostpathprovisioners.hostpathprovisioner.kubevirt.io" deleted (dry run)
customresourcedefinition.apiextensions.k8s.io "hyperconvergeds.hco.kubevirt.io" deleted (dry run)
customresourcedefinition.apiextensions.k8s.io "kubevirts.kubevirt.io" deleted (dry run)
customresourcedefinition.apiextensions.k8s.io "networkaddonsconfigs.networkaddonsoperator.network.kubevirt.io" deleted (dry run)
customresourcedefinition.apiextensions.k8s.io "ssps.ssp.kubevirt.io" deleted (dry run)
customresourcedefinition.apiextensions.k8s.io "tektontasks.tektontasks.kubevirt.io" deleted (dry run)

  6. Delete the CRDs by running the oc delete crd command without the dry-run option: 

    $ oc delete crd -l operators.coreos.com/kubevirt-hyperconverged.openshift-cnv
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top