Managing the OpenShift Virtualization add-on

Virtual Private Cloud 4.21 and later Bare metal worker nodes only RHCOS only

The openshift-virtualization add-on provides a one-click experience to set up the virtualization platform on Red Hat OpenShift on IBM Cloud for VPC with Satellite-enabled services (ROVS) clusters. This add-on is automatically enabled by default on all ROVS clusters.

This service is currently available as a beta release. Access is controlled by an allowlist. During the beta period, only console-based cluster creation is supported.

Understanding the OpenShift Virtualization add-on

The OpenShift Virtualization add-on orchestrates the deployment and management of the following operators to enable virtual machine capabilities in your ROVS cluster:

OpenShift Virtualization Operator (Hyperconverged)
Provides the core virtualization capabilities for running and managing virtual machines. For more information, see Installing OpenShift Virtualization.
NMState Operator
Manages network configuration for virtual machines and nodes. For more information, see About the Kubernetes NMState Operator.
Node Maintenance Operator
Handles node maintenance operations for virtual machine workloads. For more information, see Node Maintenance Operator.

Installation of these operators from Red Hat OperatorHub is blocked on ROVS clusters. The add-on manages all operator installations and updates.

Add-on characteristics

The OpenShift Virtualization add-on has the following characteristics:

Automatic enablement
The add-on is automatically enabled when you create a ROVS cluster. You cannot manually enable the add-on through the CLI or console.
Cannot be disabled
Disabling the add-on is not supported. The option is not available in the console, and attempting to disable it through the CLI results in an error.
No configuration options
The add-on has no user-configurable parameters.
Version binding
The add-on version is bound to the ROVS cluster version (for example, 4.21). The add-on supports the current minor version and the next minor version (n+1). For example, add-on version 4.21 can be used with ROVS versions 4.21 and 4.22.
Automatic patch updates
Patch updates are applied automatically to your cluster using the Automatic Approval strategy. IBM notifies you at least one week before production rollout with change details. All dependent operators are updated automatically if new versions exist in the mirrored operator catalog. The add-on uses the stable channel for all operator updates.
Manual version upgrades
To upgrade the add-on to a newer version (for example, from 4.20 to 4.21), you must first upgrade your ROVS cluster to the target version, then manually update the add-on version using the CLI command ibmcloud ks cluster addon update openshift-virtualization --cluster <cluster_name_or_id> --version <version>.
Update channel
The add-on uses the stable channel for updates, which provides Z-stream updates for bug fixes and security issues.
Version compatibility
Each add-on version supports the current ROVS version (n) and the next minor version (n+1). For example, add-on version 4.20 supports ROVS versions 4.20 and 4.21.
Custom catalog
A custom catalog with mirrored dependent operators is set up automatically during add-on enablement and is placed in the openshift-marketplace namespace.

Installed resources

When the add-on is enabled, the following resources are created:

Parent operator namespace
The ibm-openshift-virt-operator namespace contains all resources related to the parent operator, including a custom resource of type ibmopenshiftvirtualizations.openshiftvirt.ibm.io.
Custom catalog
The custom catalog is placed in the openshift-marketplace namespace.
Dependent operators
The parent operator acts as a meta operator and installs the following dependent operators during reconciliation:
  • OpenShift Virtualization (in the openshift-cnv namespace)
  • NMState (in the openshift-nmstate namespace)
  • Node Maintenance Operator (in the openshift-operators namespace)

Viewing add-on information

If the feature flag is enabled for your account, you can view information about the OpenShift Virtualization add-on by using the CLI. If the feature flag is not enabled, use the console and cluster details to review add-on status instead.

Listing installed add-ons

List all add-ons that are installed in your ROVS cluster.

ibmcloud ks cluster addon ls --cluster <cluster_name_or_id>

Example output:

Name                       Version   Health State   Health Status
ibm-storage-operator       1.0       normal         Addon Ready. For more info: http://ibm.biz/addon-state (H1500)
openshift-virtualization   4.21      normal         Addon Ready. For more info: http://ibm.biz/addon-state (H1500)

Getting add-on details

If the feature flag is enabled for your account, get detailed information about the OpenShift Virtualization add-on.

ibmcloud ks cluster addon get --addon openshift-virtualization --cluster <cluster_name_or_id>

Example output:

name:            openshift-virtualization
Version:         4.21
Health State:    normal
Health Status:   Addon Ready. For more info: http://ibm.biz/addon-state (H1500)

Listing available add-on versions

If the feature flag is enabled for your account, list the available versions of the OpenShift Virtualization add-on.

ibmcloud ks cluster addon versions --addon openshift-virtualization

Example output:

Name                       Version   Supported Kubernetes Range   Supported OpenShift Range   Kubernetes Default   OpenShift Default
openshift-virtualization   4.19      unsupported                  >=4.19.0 <4.21.0            -                    >=4.19.0 <4.21.0
openshift-virtualization   4.21      unsupported                  >=4.21.0 <4.23.0            -                    >=4.21.0 <4.23.0

This output shows which ROVS versions are supported by each add-on version.

Checking for configuration options

If the feature flag is enabled for your account, you can confirm that the OpenShift Virtualization add-on does not support configuration options.

ibmcloud ks cluster addon options --addon openshift-virtualization

Example output:

FAILED
No addon installation options are available for openshift-virtualization.

Updating the add-on

The OpenShift Virtualization add-on supports two types of updates:

Automatic patch updates

Patch updates (such as from 4.21.1 to 4.21.2) are applied automatically to all clusters. These updates include bug fixes and security patches. IBM provides at least one week advance notification before rolling out patch updates to production.

The automatic patch update process does the following:

  1. Restarts the parent operator
  2. Reconciles the catalog source
  3. Updates all child operators based on the stable channel subscription

Manual version upgrades

To upgrade the OpenShift Virtualization add-on to a newer minor version (such as from 4.20 to 4.21), you must first upgrade your ROVS cluster to the target version. If the feature flag is not enabled for your account, contact IBM Support before you attempt the CLI update.

  1. Upgrade your ROVS cluster to the target version. For more information, see Updating clusters.

  2. After the cluster upgrade is complete, update the add-on to the matching version.

    ibmcloud ks cluster addon update openshift-virtualization --cluster <cluster_name_or_id> --version <version>

    For example, to update to version 4.21:

    ibmcloud ks cluster addon update openshift-virtualization --cluster my-rovs-cluster --version 4.21

It is highly recommended to update the add-on version to match your cluster version for optimal compatibility and support.

Disabling the add-on

Disabling the OpenShift Virtualization add-on is not supported on ROVS clusters (Phase 1). The add-on is a core component of the Virtualization Service and cannot be removed. If the feature flag is enabled for your account and you attempt the CLI command, the command results in an error.

ibmcloud ks cluster addon disable openshift-virtualization --cluster <cluster_name_or_id>

Support for add-on uninstallation is planned for standard ROKS clusters in Phase 2.

Troubleshooting the add-on

If you encounter issues with the OpenShift Virtualization add-on, gather the following information before opening a support case.

Gathering add-on information

Run the following commands to gather details about the OpenShift Virtualization add-on and its dependent operators.

  1. Get the IBM OpenShift Virtualization custom resource.

    oc get ibmopenshiftvirtualizations.openshiftvirt.ibm.io -n ibm-openshift-virt-operator -o yaml

  2. List all resources in the parent operator namespace.

    oc get all -n ibm-openshift-virt-operator

  3. Check the OpenShift Virtualization operator status.

    oc get csv -n openshift-cnv

  4. Get the HyperConverged resource details.

    oc get hco -n openshift-cnv kubevirt-hyperconverged -o yaml

  5. List all resources in the OpenShift Virtualization namespace.

    oc get all -n openshift-cnv

  6. Check the NMState operator status.

    oc get csv -n openshift-nmstate

  7. List all resources in the NMState namespace.

    oc get all -n openshift-nmstate

  8. Get the NMState resource details.

    oc get nmstate nmstate -o yaml

  9. List NodeNetworkConfigurationPolicy resources.

    oc get nncp

  10. Check the Node Maintenance Operator status.

    oc get csv -n openshift-operators

  11. List all resources in the operators namespace.

    oc get all -n openshift-operators

  12. Check the custom catalog source.

    oc get catalogsource custom-redhat-operators-openshiftvirt -n openshift-marketplace

  13. List package manifests from the custom catalog.

    oc get packagemanifests -n openshift-marketplace | grep "Custom Redhat Operators for Openshift Virtualization"

Opening a support case

If your issue is not resolved, open a support case and include the output from the troubleshooting commands. For more information, see Getting support.

Next steps