1. Documentation
×

Upgrading OKD Virtualization

About upgrading OKD Virtualization

  • Operator Lifecycle Manager (OLM) manages the lifecycle of the OKD Virtualization Operator. The Marketplace Operator, which is deployed during OKD installation, makes external Operators available to your cluster.

  • OLM provides z-stream and minor version updates for OKD Virtualization. Minor version updates become available when you upgrade OKD to the next minor version. You cannot upgrade OKD Virtualization to the next minor version without first upgrading OKD.

  • OKD Virtualization subscriptions use a single update channel that is named stable. The stable channel ensures that your OKD Virtualization and OKD versions are compatible.

  • If your subscription’s approval strategy is set to Automatic, the upgrade process starts as soon as a new version of the Operator is available in the stable channel. It is highly recommended to use the Automatic approval strategy to maintain a supportable environment. Each minor version of OKD Virtualization is only supported if you run the corresponding OKD version. For example, you must run OKD Virtualization 4.9 on OKD 4.9.

    • Though it is possible to select the Manual approval strategy, this is not recommended because it risks the supportability and functionality of your cluster. With the Manual approval strategy, you must manually approve every pending update. If OKD and OKD Virtualization updates are out of sync, your cluster becomes unsupported.

  • The amount of time an update takes to complete depends on your network connection. Most automatic updates complete within fifteen minutes.

  • Upgrading does not interrupt network connections.

  • Data volumes and their associated persistent volume claims are preserved during upgrade.

If you have virtual machines running that cannot be live migrated, they might block an OKD cluster upgrade. This includes virtual machines that use hostpath provisioner storage or SR-IOV network interfaces that have the sriovLiveMigration feature gate disabled.

As a workaround, you can reconfigure the virtual machines so that they can be powered off automatically during a cluster upgrade. Remove the evictionStrategy: LiveMigrate field and set the runStrategy field to Always.

Configuring automatic workload updates

Configuring workload update methods

You can configure workload update methods by editing the HyperConverged custom resource (CR).

Prerequisites

  • To use live migration as an update method, you must first enable live migration in the cluster.

    If a VirtualMachineInstance CR contains evictionStrategy: LiveMigrate and the virtual machine instance (VMI) does not support live migration, the VMI will not update.
Procedure

  1. To open the HyperConverged CR in your default editor, run the following command:

    $ oc edit hco -n openshift-cnv kubevirt-hyperconverged

  2. Edit the workloadUpdateStrategy stanza of the HyperConverged CR. For example:

    apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
spec:
  workloadUpdateStrategy:
    workloadUpdateMethods: (1)
    - LiveMigrate (2)
    - Evict (3)
    batchEvictionSize: 10 (4)
    batchEvictionInterval: "1m0s" (5)
...
    1 The methods that can be used to perform automated workload updates. The available values are LiveMigrate and Evict. If you enable both options as shown in this example, updates use LiveMigrate for VMIs that support live migration and Evict for any VMIs that do not support live migration. To disable automatic workload updates, you can either remove the workloadUpdateStrategy stanza or set workloadUpdateMethods: [] to leave the array empty.
    2 The least disruptive update method. VMIs that support live migration are updated by migrating the virtual machine (VM) guest into a new pod with the updated components enabled. If LiveMigrate is the only workload update method listed, VMIs that do not support live migration are not disrupted or updated.
    3 A disruptive method that shuts down VMI pods during upgrade. Evict is the only update method available if live migration is not enabled in the cluster. If a VMI is controlled by a VirtualMachine object that has runStrategy: always configured, a new VMI is created in a new pod with updated components.
    4 The number of VMIs that can be forced to be updated at a time by using the Evict method. This does not apply to the LiveMigrate method.
    5 The interval to wait before evicting the next batch of workloads. This does not apply to the LiveMigrate method.

    You can configure live migration limits and timeouts by editing the spec.liveMigrationConfig stanza of the HyperConverged CR.

  3. To apply your changes, save and exit the editor.

Approving pending Operator upgrades

Manually approving a pending Operator update

If an installed Operator has the approval strategy in its subscription set to Manual, when new updates are released in its current update channel, the update must be manually approved before installation can begin.

Prerequisites

  • An Operator previously installed using Operator Lifecycle Manager (OLM).

Procedure

  1. In the Administrator perspective of the OKD web console, navigate to Operators → Installed Operators.

  2. Operators that have a pending update display a status with Upgrade available. Click the name of the Operator you want to update.

  3. Click the Subscription tab. Any update requiring approval are displayed next to Upgrade Status. For example, it might display 1 requires approval.

  4. Click 1 requires approval, then click Preview Install Plan.

  5. Review the resources that are listed as available for update. When satisfied, click Approve.

  6. Navigate back to the Operators → Installed Operators page to monitor the progress of the update. When complete, the status changes to Succeeded and Up to date.

Monitoring upgrade status

Monitoring OKD Virtualization upgrade status

To monitor the status of a OKD Virtualization Operator upgrade, watch the cluster service version (CSV) PHASE. You can also monitor the CSV conditions in the web console or by running the command provided here.

The PHASE and conditions values are approximations that are based on available information.
Prerequisites

  • Log in to the cluster as a user with the cluster-admin role.

  • Install the OpenShift CLI (oc).

Procedure

  1. Run the following command:

    $ oc get csv -n openshift-cnv

  2. Review the output, checking the PHASE field. For example:

    Example output
    VERSION  REPLACES                                        PHASE
4.9.0    kubevirt-hyperconverged-operator.v4.8.2         Installing
4.9.0    kubevirt-hyperconverged-operator.v4.9.0         Replacing

  3. Optional: Monitor the aggregated status of all OKD Virtualization component conditions by running the following command:

    $ oc get hco -n openshift-cnv kubevirt-hyperconverged \
-o=jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.message}{"\n"}{end}'

    A successful upgrade results in the following output:

    Example output
    ReconcileComplete  True  Reconcile completed successfully
Available          True  Reconcile completed successfully
Progressing        False Reconcile completed successfully
Degraded           False Reconcile completed successfully
Upgradeable        True  Reconcile completed successfully

Viewing outdated OKD Virtualization workloads

You can view a list of outdated workloads by using the CLI.

If there are outdated virtualization pods in your cluster, the OutdatedVirtualMachineInstanceWorkloads alert fires.
Procedure

  • To view a list of outdated virtual machine instances (VMIs), run the following command:

    $ kubectl get vmi -l kubevirt.io/outdatedLauncherImage --all-namespaces

Additional resources