Chapter 3. Installing
3.1. Preparing your cluster for OpenShift Virtualization Copy linkLink copied to clipboard!
Review platform compatibility information before you install OpenShift Virtualization. For detailed system requirements, see "Hardware, software, and operational requirements" in the Additional resources section.
3.1.1. OpenShift Virtualization on AWS bare metal Copy linkLink copied to clipboard!
You can run OpenShift Virtualization on an Amazon Web Services (AWS) bare metal OpenShift Dedicated cluster.
OpenShift Virtualization is also supported on Red Hat OpenShift Service on AWS (ROSA) Classic clusters, which have the same configuration requirements as AWS bare-metal clusters.
Before you set up your cluster, review the following summary of supported features and limitations:
- 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
c5n.metaltype value for a machine based on x86_64 architecture. You specify bare-metal instance types by editing theinstall-config.yamlfile.For more information, see the OpenShift Dedicated documentation about installing on AWS.
- Accessing virtual machines (VMs)
-
There is no change to how you access VMs by using the
virtctlCLI tool or the OpenShift Dedicated web console. You can expose VMs by using a
NodePortorLoadBalancerservice.NoteThe load balancer approach is preferable because OpenShift Dedicated automatically creates the load balancer in AWS 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.
-
There is no change to how you access VMs by using the
- Networking
- You cannot use Single Root I/O Virtualization (SR-IOV) or bridge Container Network Interface (CNI) networks, including virtual LAN (VLAN). If your application requires a flat layer 2 network or control over the IP pool, consider using OVN-Kubernetes secondary overlay networks.
-
If your application requires a flat layer 2 network that does not need egress traffic, consider using OVN-Kubernetes secondary overlay networks with a
Layer2topology.
- Storage
You can use any storage solution that is certified by the storage vendor to work with the underlying platform.
ImportantAWS bare metal, Red Hat OpenShift Service on AWS, and Red Hat OpenShift Service on AWS classic architecture clusters might have different supported storage solutions. Ensure that you confirm support with your storage vendor.
- Hosted control planes (HCPs)
- You can run OpenShift Virtualization on HCP clusters that use AWS bare-metal nodes. However, using OpenShift Virtualization VMs as HCP nodes is not currently supported on AWS.
3.2. Installing OpenShift Virtualization Copy linkLink copied to clipboard!
Install OpenShift Virtualization to add virtualization functionality to your OpenShift Dedicated cluster.
3.2.1. Install the OpenShift Virtualization Operator by using the web console Copy linkLink copied to clipboard!
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-adminpermissions. - 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
-
From the Administrator perspective, click Ecosystem
Software Catalog. - In the Filter by keyword field, type Virtualization.
- Select the OpenShift Virtualization Operator tile with the Red Hat source label.
- Read the information about the Operator and click Install.
On the Install Operator page:
- 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.
For Installed Namespace, ensure that the Operator recommended namespace option is selected. This installs the Operator in the mandatory
openshift-cnvnamespace, which is automatically created if it does not exist.WarningAttempting to install the OpenShift Virtualization Operator in a namespace other than
openshift-cnvcauses the installation to fail.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.
WarningBecause OpenShift Virtualization is only supported when used with the corresponding OpenShift Dedicated version, missing OpenShift Virtualization updates can cause your cluster to become unsupported.
-
Click Install to make the Operator available to the
openshift-cnvnamespace. - When the Operator installs successfully, click Create HyperConverged.
- Optional: Configure Infra and Workloads node placement options for OpenShift Virtualization components.
- 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.
3.2.2. Subscribe to the OpenShift Virtualization catalog by using the CLI Copy linkLink copied to clipboard!
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
- You have installed OpenShift Dedicated 4 on your cluster.
-
You have installed the OpenShift CLI (
oc). -
You have logged in as a user with
cluster-adminprivileges. - You have created a machine pool based on a bare metal compute node instance type.
Procedure
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.22.9 channel: "stable"Using the
stablechannel ensures that you install the version of OpenShift Virtualization that is compatible with your OpenShift Dedicated version.Create the required
Namespace,OperatorGroup, andSubscriptionobjects 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.
Check that the
ClusterServiceVersion(CSV) object was created successfully. Run the following command and verify the output:$ oc get csv -n openshift-cnvIf the CSV was created successfully, the output shows an entry that contains a
NAMEvalue ofkubevirt-hyperconverged-operator-*, aDISPLAYvalue ofOpenShift Virtualization, and aPHASEvalue ofSucceeded, as shown in the following example output:Example output:
NAME DISPLAY VERSION REPLACES PHASE kubevirt-hyperconverged-operator.v4.22.9 OpenShift Virtualization 4.22.9 kubevirt-hyperconverged-operator.v4.21.0 SucceededCheck that the
HyperConvergedcustom resource (CR) has the correct version. Run the following command and verify the output:$ oc get hyperconvergeds.v1beta1.hco.kubevirt.io -n openshift-cnv kubevirt-hyperconverged -o json | jq .status.versionsExample output:
{ "name": "operator", "version": "4.22.9" }Verify the
HyperConvergedCR conditions. Run the following command and check the output:$ oc get hyperconvergeds.v1beta1.hco.kubevirt.io 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" }
3.2.3. Deploy the OpenShift Virtualization Operator by using the CLI Copy linkLink copied to clipboard!
You can deploy the OpenShift Virtualization Operator by using the oc CLI.
Prerequisites
-
You have installed the OpenShift CLI (
oc). -
You have logged in as a user with
cluster-adminprivileges. -
You have subscribed to the OpenShift Virtualization catalog in the
openshift-cnvnamespace. - You have created a machine pool based on a bare metal compute node instance type.
Procedure
Create a YAML file that contains the following manifest:
apiVersion: hco.kubevirt.io/v1beta1 kind: HyperConverged metadata: name: kubevirt-hyperconverged namespace: openshift-cnv spec: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
PHASEof the cluster service version (CSV) in theopenshift-cnvnamespace. Run the following command:$ watch oc get csv -n openshift-cnvThe following output displays if deployment was successful:
NAME DISPLAY VERSION REPLACES PHASE kubevirt-hyperconverged-operator.v4.22.9 OpenShift Virtualization 4.22.9 Succeeded
3.3. Uninstalling OpenShift Virtualization Copy linkLink copied to clipboard!
You can uninstall OpenShift Virtualization by using the web console or the command-line interface (CLI) to delete OpenShift Virtualization workloads, the Operator, and its resources.
To uninstall OpenShift Virtualization, perform the following tasks:
-
Delete the
HyperConvergedCR. - Delete the OpenShift Virtualization Operator.
-
Delete the
openshift-cnvnamespace. - Delete the OpenShift Virtualization custom resource definitions (CRDs).
3.3.1. Prerequisites Copy linkLink copied to clipboard!
- Delete all virtual machine instances. You cannot uninstall OpenShift Virtualization while its workloads remain on the cluster.
3.3.2. Delete the HyperConverged custom resource Copy linkLink copied to clipboard!
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-adminpermissions.
Procedure
-
Navigate to the Ecosystem
Installed Operators page. - Select the OpenShift Virtualization Operator.
- Click the OpenShift Virtualization Deployment tab.
-
Click the Options menu
beside kubevirt-hyperconvergedand select Delete HyperConverged. - Click Delete in the confirmation window.
3.3.3. Deleting Operators from a cluster using the web console Copy linkLink copied to clipboard!
Cluster administrators can delete installed Operators from a selected namespace by using the web console.
Failed Operator installations do not automatically remove created permissions. Audit and remove remaining permissions to secure the namespace.
For more information, see Audit and secure delegated Operator installations (Red Hat Knowledgebase).
Prerequisites
-
You have access to the OpenShift Dedicated cluster web console using an account with
dedicated-adminpermissions.
Procedure
-
Navigate to the Ecosystem
Installed Operators page. - Scroll or enter a keyword into the Filter by name field to find the Operator that you want to remove. Then, click on it.
On the right side of the Operator Details page, select Uninstall Operator from the Actions list.
An Uninstall Operator? dialog box is displayed.
Select Uninstall to remove the Operator, Operator deployments, and pods. Following this action, the Operator stops running and no longer receives updates.
NoteThis 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.
3.3.4. Delete a namespace using the web console Copy linkLink copied to clipboard!
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-adminpermissions.
Procedure
-
Navigate to Administration
Namespaces. - Locate the namespace that you want to delete in the list of namespaces.
-
On the far right side of the namespace listing, select Delete Namespace from the Options menu
.
- When the Delete Namespace pane opens, enter the name of the namespace that you want to delete in the field.
- Click Delete.
3.3.5. Delete OpenShift Virtualization custom resource definitions Copy linkLink copied to clipboard!
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-adminpermissions.
Procedure
-
Navigate to Administration
CustomResourceDefinitions. -
Select the Label filter and enter
operators.coreos.com/kubevirt-hyperconverged.openshift-cnvin the Search field to display the OpenShift Virtualization CRDs. -
Click the Options menu
beside each CRD and select Delete CustomResourceDefinition.
3.3.6. Uninstall OpenShift Virtualization by using the CLI Copy linkLink copied to clipboard!
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-adminpermissions. -
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
Delete the
HyperConvergedcustom resource:$ oc delete HyperConverged kubevirt-hyperconverged -n openshift-cnvDelete the OpenShift Virtualization Operator subscription:
$ oc delete subscription hco-operatorhub -n openshift-cnvDelete the OpenShift Virtualization
ClusterServiceVersionresource:$ oc delete csv -n openshift-cnv -l operators.coreos.com/kubevirt-hyperconverged.openshift-cnvDelete the OpenShift Virtualization namespace:
$ oc delete namespace openshift-cnvList the OpenShift Virtualization custom resource definitions (CRDs) by running the
oc delete crdcommand with thedry-runoption:$ oc delete crd --dry-run=client -l operators.coreos.com/kubevirt-hyperconverged.openshift-cnvExample 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)Delete the CRDs by running the
oc delete crdcommand without thedry-runoption:$ oc delete crd -l operators.coreos.com/kubevirt-hyperconverged.openshift-cnv