Chapter 3. OpenShift Virtualization installation

3.1. Configuring your cluster for OpenShift Virtualization

Before you install OpenShift Virtualization, ensure that your OpenShift Container Platform cluster meets the following requirements:

  • Your cluster must be installed on bare metal infrastructure with Red Hat Enterprise Linux CoreOS workers.
  • Shared storage is required to enable live migration.
  • You must manage your Compute nodes according to the number and size of the virtual machines that you want to host in the cluster.
  • To deploy OpenShift Virtualization in a disconnected environment, you must configure Operator Lifecycle Manager on restricted networks.
  • To use proxy with OpenShift Virtualization, you must configure proxy support in Operator Lifecycle Manager.
  • If your cluster uses worker nodes from multiple CPU vendors, live migration failures can occur. For example, a virtual machine with an AMD CPU might attempt to live-migrate to a node with an Intel CPU and likely fail migration. To avoid this, label nodes with a vendor-specific label, such as Vendor=Intel or Vendor=AMD, and set node affinity on your virtual machines to ensure successful migration. See Configuring a required node affinity rule for more information.

OpenShift Virtualization works with OpenShift Container Platform by default, but the following installation configurations are recommended:

Note

To obtain an evaluation version of OpenShift Container Platform, download a trial from the OpenShift Container Platform home page.

3.2. Installing OpenShift Virtualization using the web console

Install OpenShift Virtualization to add virtualization functionality to your OpenShift Container Platform cluster.

You can use the OpenShift Container Platform 4.5 web console to subscribe to and deploy the OpenShift Virtualization Operators.

3.2.1. Prerequisites

  • Install OpenShift Container Platform 4.5 on your cluster.
  • Log in as a user with cluster-admin permissions.

3.2.2. Subscribing to the OpenShift Virtualization catalog

Before you install OpenShift Virtualization, subscribe to the OpenShift Virtualization catalog from the OpenShift Container Platform web console. Subscribing gives the openshift-cnv namespace access to the OpenShift Virtualization Operators.

Procedure

  1. Open a browser window and log in to the OpenShift Container Platform web console.
  2. Navigate to the OperatorsOperatorHub page.
  3. Search for OpenShift Virtualization and then select it.
  4. Read the information about the Operator and click Install.
  5. On the Install Operator page:

    1. 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.

    2. Select 2.4 from the list of available Update Channel options.
    3. For Approval Strategy, ensure that Automatic, which is the default value, is selected. OpenShift Virtualization automatically updates when a new z-stream release is available.
  6. Click Install to make the Operator available to the openshift-cnv namespace.

    On the Installed Operators screen, the Status displays Succeeded when OpenShift Virtualization finishes installation.

3.2.3. Deploying OpenShift Virtualization

After subscribing to the OpenShift Virtualization catalog, create the OpenShift Virtualization Operator Deployment custom resource to deploy OpenShift Virtualization.

Prerequisites

  • Subscribe to the OpenShift Virtualization catalog in the openshift-cnv namespace.

Procedure

  1. Navigate to the OperatorsInstalled Operators page.
  2. Click OpenShift Virtualization.
  3. Click the OpenShift Virtualization Operator Deployment tab and click Create HyperConverged Cluster.

    Warning

    To avoid deployment errors, do not rename the custom resource. Before you proceed to the next step, ensure that the custom resource is named the default kubevirt-hyperconverged.

  4. Click Create to launch OpenShift Virtualization.
  5. Navigate to the WorkloadsPods page and monitor the OpenShift Virtualization pods until they are all Running. After all the pods display the Running state, you can access OpenShift Virtualization.

3.2.4. Next steps

You might want to additionally configure the following components:

  • The KubeMacPool component provides a MAC address pool service for virtual machine NICs in designated namespaces. Enable a MAC address pool in a namespace by applying the KubeMacPool label to that namespace.
  • 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. Installing OpenShift Virtualization using the CLI

Install OpenShift Virtualization to add virtualization functionality to your OpenShift Container Platform cluster. You can subscribe to and deploy the OpenShift Virtualization Operators by using the command line to apply manifests to your cluster.

3.3.1. Prerequisites

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

3.3.2. Subscribing to the OpenShift Virtualization catalog by using the CLI

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.

Procedure

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

    apiVersion: v1
    kind: Namespace
    metadata:
      name: openshift-cnv
    ---
    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.v2.4.9
      channel: "2.4"
  2. Create the required Namespace, OperatorGroup, and Subscription objects for OpenShift Virtualization by running the following command:

    $ oc apply -f <file name>.yaml

3.3.3. Deploying the OpenShift Virtualization Operator by using the CLI

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

Prerequisites

  • An active subscription to the OpenShift Virtualization catalog in the openshift-cnv namespace.

Procedure

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

    apiVersion: hco.kubevirt.io/v1alpha1
    kind: HyperConverged
    metadata:
      name: kubevirt-hyperconverged
      namespace: openshift-cnv
    spec:
      BareMetalPlatform: true
  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 ClusterServiceVersion (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:

    Example output

    NAME                                      DISPLAY                    VERSION   REPLACES   PHASE
    kubevirt-hyperconverged-operator.v2.4.9   OpenShift Virtualization   2.4.9                Succeeded

3.3.4. Next steps

You might want to additionally configure the following components:

  • The KubeMacPool component provides a MAC address pool service for virtual machine NICs in designated namespaces. Enable a MAC address pool in a namespace by applying the KubeMacPool label to that namespace.
  • 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.4. Installing the virtctl client

The virtctl client is a command-line utility for managing OpenShift Virtualization resources.

Install the client to your system by enabling the OpenShift Virtualization repository and installing the kubevirt-virtctl package.

3.4.1. Enabling OpenShift Virtualization repositories

Red Hat offers OpenShift Virtualization repositories for both Red Hat Enterprise Linux 8 and Red Hat Enterprise Linux 7:

  • Red Hat Enterprise Linux 8 repository: cnv-2.4-for-rhel-8-x86_64-rpms
  • Red Hat Enterprise Linux 7 repository: rhel-7-server-cnv-2.4-rpms

The process for enabling the repository in subscription-manager is the same in both platforms.

Procedure

  • Enable the appropriate OpenShift Virtualization repository for your system by running the following command:

    # subscription-manager repos --enable <repository>

3.4.2. Installing the virtctl client

Install the virtctl client from the kubevirt-virtctl package.

Procedure

  • Install the kubevirt-virtctl package:

    # yum install kubevirt-virtctl

See also: Using the CLI tools for OpenShift Virtualization.

3.5. Uninstalling OpenShift Virtualization using the web console

You can uninstall OpenShift Virtualization by using the OpenShift Container Platform web console.

3.5.1. Prerequisites

3.5.2. Deleting the OpenShift Virtualization Operator Deployment custom resource

To uninstall OpenShift Virtualization, you must first delete the OpenShift Virtualization Operator Deployment custom resource.

Prerequisites

  • Create the OpenShift Virtualization Operator Deployment custom resource.

Procedure

  1. From the OpenShift Container Platform web console, select openshift-cnv from the Projects list.
  2. Navigate to the OperatorsInstalled Operators page.
  3. Click OpenShift Virtualization.
  4. Click the OpenShift Virtualization Operator Deployment tab.
  5. Click the Options menu kebab in the row containing the kubevirt-hyperconverged custom resource. In the expanded menu, click Delete HyperConverged Cluster.
  6. Click Delete in the confirmation window.
  7. Navigate to the WorkloadsPods page to verify that only the Operator Pods are running.
  8. Open a terminal window and clean up the remaining resources by running the following command:

    $ oc delete apiservices v1alpha3.subresources.kubevirt.io -n openshift-cnv

3.5.3. Deleting the OpenShift Virtualization catalog subscription

To finish uninstalling OpenShift Virtualization, delete the OpenShift Virtualization catalog subscription.

Prerequisites

  • An active subscription to the OpenShift Virtualization catalog

Procedure

  1. Navigate to the OperatorsOperatorHub page.
  2. Search for OpenShift Virtualization and then select it.
  3. Click Uninstall.
Note

You can now delete the openshift-cnv namespace.

3.5.4. Deleting a namespace using the web console

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

Note

If you do not have permissions to delete the namespace, the Delete Namespace option is not available.

Procedure

  1. Navigate to AdministrationNamespaces.
  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.

3.6. Uninstalling OpenShift Virtualization using the CLI

You can uninstall OpenShift Virtualization by using the OpenShift Container Platform CLI.

3.6.1. Prerequisites

3.6.2. Deleting OpenShift Virtualization

You can delete OpenShift Virtualization by using the CLI.

Prerequisites

  • Install the OpenShift CLI (oc).
  • Access to a OpenShift Virtualization cluster using an account with cluster-admin permissions.
Note

When you delete the subscription of the OpenShift Virtualization operator in the OLM by using the CLI, the ClusterServiceVersion (CSV) object is not deleted from the cluster. To completely uninstall OpenShift Virtualization, you must explicitly delete the CSV.

Procedure

  1. Delete the HyperConverged Custom Resource:

    $ oc delete HyperConverged kubevirt-hyperconverged -n openshift-cnv
  2. Delete the subscription of the OpenShift Virtualization operator in the Operator Lifecycle Manager (OLM):

    $ oc delete subscription kubevirt-hyperconverged -n openshift-cnv
  3. Set the ClusterServiceVersion (CSV) name for OpenShift Virtualization as an environment variable:

    $ CSV_NAME=$(oc get csv -n openshift-cnv -o=custom-columns=:metadata.name)
  4. Delete the CSV from the OpenShift Virtualization cluster by specifying the CSV name from the previous step:

    $ oc delete csv ${CSV_NAME} -n openshift-cnv

    OpenShift Virtualization is uninstalled when a confirmation message indicates that the CSV was deleted successfully:

    Example output

    clusterserviceversion.operators.coreos.com "kubevirt-hyperconverged-operator.v2.4.9" deleted