Skip to content

Commit 0eaafc3

Browse files
ousleypousleyp
authored
Merge pull request #36774 from ousleyp/cnv-9800
CNV-9800: New upgrade behavior for 4.9+
2 parents 1afe930 + 879cf9f commit 0eaafc3

9 files changed

+171
-54
lines changed

‎modules/virt-about-upgrading-virt.adoc‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,7 @@ connection. Most automatic updates complete within fifteen minutes.
2424
[id="how-upgrades-affect-cluster_{context}"]
2525
== How {VirtProductName} upgrades affect your cluster
2626

27-
* Upgrading does not interrupt virtual machine workloads.
28-
** Virtual machine pods are not restarted or migrated during an upgrade. If you
29-
need to update the `virt-launcher` pod, you must restart or live migrate the
30-
virtual machine.
27+
* When you upgrade {VirtProductName}, virtual machine workloads including `libvirt`, `virt-launcher`, and `qemu` update automatically if they support live migration.
3128
+
3229
[NOTE]
3330
====
@@ -36,10 +33,21 @@ instance. The `virt-launcher` pod runs an instance of `libvirt`, which is
3633
used to manage the virtual machine process.
3734
====
3835

36+
** There are two supported workload update methods: `LiveMigrate` and `Evict`. By default, only `LiveMigrate` is enabled, which means that:
37+
38+
*** Virtual machine instances (VMIs) that support live migration are migrated during the upgrade process.
39+
40+
*** VMIs are not updated at all if the following conditions are both true:
41+
42+
**** The VMI does not support live migration.
43+
44+
**** The VMI is configured to use the `LiveMigrate` eviction strategy.
45+
46+
** You can configure how workloads are updated by editing the `spec.workloadUpdateStrategy` stanza of the `HyperConverged` custom resource (CR).
47+
3948
* Upgrading does not interrupt network connections.
4049

41-
* Data volumes and their associated persistent volume claims are preserved during
42-
upgrade.
50+
* Data volumes and their associated persistent volume claims are preserved during upgrade.
4351
+
4452
[IMPORTANT]
4553
====

‎modules/virt-configuring-workload-update-methods.adoc‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/upgrading-virt.adoc
4+
5+
[id="virt-configuring-workload-update-methods_{context}"]
6+
= Configuring workload update methods
7+
8+
When you upgrade {VirtProductName}, virtual machine instance (VMI) workloads, such as `virt-launcher` pods, update automatically if they support live migration. You can configure workload update strategies or opt out of workload updates by editing the `HyperConverged` custom resource (CR).
9+
10+
.Prerequisites
11+
12+
* To use live migration as an update method, you must first enable live migration in the cluster.
13+
+
14+
[NOTE]
15+
====
16+
If a `VirtualMachineInstance` CR contains `evictionStrategy: LiveMigrate` and the VMI does not support live migration, the VMI will not update.
17+
====
18+
19+
.Procedure
20+
21+
. To open the `HyperConverged` CR in your default editor, run the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc edit hco -n openshift-cnv kubevirt-hyperconverged
26+
----
27+
28+
. Edit the `workloadUpdateStrategy` stanza of the `HyperConverged` CR. For example:
29+
+
30+
[source,yaml]
31+
----
32+
apiVersion: hco.kubevirt.io/v1beta1
33+
kind: HyperConverged
34+
metadata:
35+
name: kubevirt-hyperconverged
36+
spec:
37+
workloadUpdateStrategy:
38+
workloadUpdateMethods: <1>
39+
- LiveMigrate <2>
40+
- Evict <3>
41+
batchEvictionSize: 10 <4>
42+
batchEvictionInterval: "1m0s" <5>
43+
----
44+
<1> The methods that can be used to perform automated workload updates. The supported values are `LiveMigrate` and `Evict`. By default, only `LiveMigrate` is enabled. 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, set `workloadUpdateMethods: []` to leave the array empty.
45+
<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. `LiveMigrate` is enabled by default.
46+
<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. `Evict` is not enabled by default.
47+
<4> The number of VMIs that can be forced to be updated at a time. The default value is `10`.
48+
<5> The interval to wait before evicting the next batch of workloads. The default value is `"1m0s"`.
49+
50+
. To apply your changes, save and exit the editor.

‎modules/virt-document-attributes.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
:VirtProductName: OpenShift Virtualization
1313
:ProductRelease:
1414
:ProductVersion:
15-
:VirtVersion: 4.8
15+
:VirtVersion: 4.9
1616
:KubeVirtVersion: v0.41.0
1717
:HCOVersion: 4.8.2
1818
// :LastHCOVersion:

‎modules/virt-monitoring-upgrade-status.adoc‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,9 @@
33
// * virt/upgrading-virt.adoc
44

55
[id="virt-monitoring-upgrade-status_{context}"]
6-
= Monitoring upgrade status
6+
= Monitoring {VirtProductName} upgrade status
77

8-
The best way to monitor {VirtProductName} upgrade status is to watch the
9-
cluster service version (CSV) `PHASE`. You can also monitor the CSV conditions
10-
in the web console or by running the command provided here.
8+
To monitor the status of a {VirtProductName} 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.
119

1210
[NOTE]
1311
====
@@ -35,8 +33,8 @@ $ oc get csv -n openshift-cnv
3533
[source,terminal,subs="attributes+"]
3634
----
3735
VERSION REPLACES PHASE
38-
4.8.0 kubevirt-hyperconverged-operator.v2.6.5 Installing
39-
4.8.1 kubevirt-hyperconverged-operator.v4.8.0 Replacing
36+
4.9.0 kubevirt-hyperconverged-operator.v4.8.2 Installing
37+
4.9.0 kubevirt-hyperconverged-operator.v4.9.0 Replacing
4038
----
4139

4240
. Optional: Monitor the aggregated status of all {VirtProductName} component

‎modules/virt-opting-out-workload-updates.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/upgrading-virt.adoc
4+
5+
[id="virt-opting-out-workload-updates_{context}"]
6+
= Opting out of automatic workload updates before you upgrade to {VirtProductName} {VirtVersion}
7+
8+
Automatic workload updates are enabled by default as of {VirtProductName} {VirtVersion}. If you plan to disable this feature, you can do so _before_ upgrading by following this workaround.
9+
10+
[NOTE]
11+
====
12+
If you already upgraded to {VirtProductName} {VirtVersion}, you can disable automatic workload updates by setting the value of `spec.workloadUpdateStrategy.workloadUpdateMethods` to `[]` in the `HyperConverged` CR.
13+
====
14+
15+
.Prerequisites
16+
17+
* You have not yet upgraded to {VirtProductName} {VirtVersion}.
18+
19+
.Procedure
20+
21+
. Annotate the `HyperConverged` CR by running the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc -n openshift-cnv annotate hco kubevirt-hyperconverged --overwrite kubevirt.kubevirt.io/jsonpatch='[{"op": "replace", "path": "/spec/workloadUpdateStrategy/workloadUpdateMethods", "value": []}]'
26+
----
27+
28+
. Upgrade {VirtProductName} to version {VirtVersion}. If you use the *Automatic* approval strategy, upgrading {product-title} triggers the {VirtProductName} update. Ensure that the {VirtProductName} upgrade completes before moving to the next step.
29+
30+
. Patch the `HyperConverged` CR by running the following command:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc -n openshift-cnv patch hco kubevirt-hyperconverged --type='json' -p='[{"op": "replace", "path": "/spec/workloadUpdateStrategy/workloadUpdateMethods", "value":[]}]'
35+
----
36+
37+
. Delete the annotation by running the following command:
38+
+
39+
[source,terminal]
40+
----
41+
$ oc -n kubevirt-hyperconverged annotate hco kubevirt-hyperconverged kubevirt.kubevirt.io/jsonpatch-
42+
----

‎modules/virt-understanding-live-migration.adoc‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,19 @@
11
// Module included in the following assemblies:
22
//
33
// * virt/live_migration/virt-live-migration.adoc
4+
// * virt/upgrading-virt.adoc
45

56
[id="virt-understanding-live-migration_{context}"]
67
= Understanding live migration
78

8-
Live migration is the process of moving a running virtual machine instance (VMI) to
9-
another node in the cluster without interrupting the virtual workload or access.
10-
If a VMI uses the `LiveMigrate` eviction strategy, it automatically migrates
11-
when the node that the VMI runs on is placed into maintenance mode. You can also
12-
manually start live migration by selecting a VMI to migrate.
9+
Live migration is the process of moving a running virtual machine instance (VMI) to another node in the cluster without interrupting the virtual workload or access. If a VMI uses the `LiveMigrate` eviction strategy, it automatically migrates when the node that the VMI runs on is placed into maintenance mode. You can also manually start live migration by selecting a VMI to migrate.
1310

14-
Virtual machines must have a persistent volume claim (PVC) with a shared
15-
ReadWriteMany (RWX) access mode to be live migrated.
11+
You can use live migration if the following conditions are met:
1612

17-
[NOTE]
18-
====
19-
Live migration is supported for virtual machines that are attached to an SR-IOV network interface only if the `sriovLiveMigration` feature gate is enabled in the HyperConverged Cluster custom resource (CR). When the `spec.featureGates.sriovLiveMigration` field is set to `true`, the `virt-launcher` pod runs with the `SYS_RESOURCE` capability. This might degrade its security.
20-
====
13+
* Virtual machines must have a persistent volume claim (PVC) with a shared `ReadWriteMany` (RWX) access mode to be live migrated.
14+
15+
* The pod network binding must not be of the bridge interface type `()`.
16+
17+
* Ports `49152` and `49153` must be available in the `virt-launcher` pod. If these ports are specified in the `masquerade` interface, live migration does not function.
18+
19+
* Live migration is supported for virtual machines that are attached to an SR-IOV network interface only if the `sriovLiveMigration` feature gate is enabled in the `HyperConverged` custom resource (CR). When the `spec.featureGates.sriovLiveMigration` field is set to `true`, the `virt-launcher` pod runs with the `SYS_RESOURCE` capability. This might degrade its security.

‎modules/virt-upgrade-pathways.adoc‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎modules/virt-viewing-outdated-workloads.adoc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/upgrading-virt.adoc
4+
5+
[id="virt-viewing-outdated-workloads_{context}"]
6+
= Viewing outdated {VirtProductName} workloads
7+
8+
You can view a list of outdated workloads by using the CLI.
9+
10+
[NOTE]
11+
====
12+
If there are outdated virtualization pods in your cluster, the `OutdatedVirtualMachineInstanceWorkloads` alert fires.
13+
====
14+
15+
.Procedure
16+
17+
* To view a list of outdated virtual machine instances (VMIs), run the following command:
18+
+
19+
[source,terminal]
20+
----
21+
$ kubectl get vmi -l kubevirt.io/outdatedLauncherImage --all-namespaces
22+
----

‎virt/upgrading-virt.adoc‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,34 @@ Learn how Operator Lifecycle Manager (OLM) delivers z-stream and minor version u
1010

1111
include::modules/virt-about-upgrading-virt.adoc[leveloffset=+1]
1212

13-
//include::modules/virt-upgrade-pathways.adoc[leveloffset=+1]
13+
[id="configuring-workload-updates_upgrading-virt"]
14+
== Configuring workload updates
1415

15-
include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+1]
16+
[NOTE]
17+
====
18+
Automatic workload updates are enabled by default in {VirtProductName} {VirtVersion}. You can opt out by following a xref:../virt/upgrading-virt.adoc#virt-opting-out-workload-updates_upgrading-virt[workaround to disable this feature] before you upgrade to {VirtVersion}.
19+
====
1620

17-
include::modules/virt-monitoring-upgrade-status.adoc[leveloffset=+1]
21+
include::modules/virt-configuring-workload-update-methods.adoc[leveloffset=+2]
22+
23+
include::modules/virt-opting-out-workload-updates.adoc[leveloffset=+2]
24+
25+
[id="approving-operator-upgrades_upgrading-virt"]
26+
== Approving pending Operator upgrades
27+
28+
include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+2]
29+
30+
[id="monitoring-upgrade-status_upgrading-virt"]
31+
== Monitoring upgrade status
32+
33+
include::modules/virt-monitoring-upgrade-status.adoc[leveloffset=+2]
34+
35+
include::modules/virt-viewing-outdated-workloads.adoc[leveloffset=+2]
36+
37+
[NOTE]
38+
====
39+
xref:../virt/upgrading-virt.adoc#configuring-workload-updates_upgrading-virt[Configure workload updates] to ensure that VMIs update automatically.
40+
====
1841

1942
[id="additional-resources_upgrading-virt"]
2043
== Additional resources
@@ -25,4 +48,6 @@ include::modules/virt-monitoring-upgrade-status.adoc[leveloffset=+1]
2548

2649
* xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-csv_olm-understanding-olm[Cluster service versions (CSVs)]
2750

51+
* xref:../virt/live_migration/virt-live-migration.adoc#virt-live-migration[Virtual machine live migration]
52+
2853
* xref:../virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc#virt-configuring-vmi-eviction-strategy[Configuring virtual machine eviction strategy]

0 commit comments

Comments
 (0)