diff --git a/modules/virt-about-eus-updates.adoc b/modules/virt-about-eus-updates.adoc new file mode 100644 index 0000000000..1f212a2c6f --- /dev/null +++ b/modules/virt-about-eus-updates.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * virt/upgrading-virt.adoc + +:_content-type: CONCEPT +[id="virt-about-eus-updates_{context}"] += About EUS-to-EUS updates + +Every even-numbered minor version of {product-title}, including 4.10 and 4.12, is an Extended Update Support (EUS) version. However, because Kubernetes design mandates serial minor version updates, you cannot directly update from one EUS version to the next. You must first update to the odd-numbered minor version before you can proceed to the target EUS version. + +When performing an EUS-to-EUS update, you must: + +* Pause worker nodes' machine config pools before you start an EUS-to-EUS update so that the workers are not rebooted twice. + +* Disable automatic workload updates before you begin the update process. This is to prevent {VirtProductName} from migrating or evicting your virtual machines (VMs) until you update to your target EUS version. + +[NOTE] +==== +By default, {VirtProductName} automatically updates workloads, such as the `virt-launcher` pod, when you update the {VirtProductName} Operator. You can configure this behavior in the `spec.workloadUpdateStrategy` stanza of the `HyperConverged` custom resource. +==== + +// link to EUS to EUS docs in assembly due to module limitations \ No newline at end of file diff --git a/modules/virt-preventing-workload-updates-during-eus-update.adoc b/modules/virt-preventing-workload-updates-during-eus-update.adoc new file mode 100644 index 0000000000..6fa009f3ef --- /dev/null +++ b/modules/virt-preventing-workload-updates-during-eus-update.adoc @@ -0,0 +1,165 @@ +// Module included in the following assemblies: +// +// * virt/upgrading-virt.adoc + +:_content-type: PROCEDURE +[id="virt-preventing-workload-updates-during-eus-update_{context}"] += Preventing workload updates during an EUS-to-EUS update + +Before you begin to update from one Extended Update Support (EUS) version to the next, you must manually disable automatic workload updates. + +.Prerequisites + +* You are running an EUS version of {product-title} and want to update to the next EUS version. You have not yet updated to the odd-numbered version in between. + +* You read "Preparing to perform an EUS-to-EUS update" and learned the caveats and requirements that pertain to your {product-title} cluster. + +* You paused the worker nodes' machine config pools as directed by the {product-title} documentation. + +.Procedure + +. Back up the current `workloadUpdateMethods` configuration by running the following command: ++ +[source,terminal] +---- +$ WORKLOAD_UPDATE_METHODS=$(oc get kv kubevirt-kubevirt-hyperconverged -n openshift-cnv -o jsonpath='{.spec.workloadUpdateStrategy.workloadUpdateMethods}') +---- + +. Turn off all workload update methods by running the following command: ++ +[source,terminal] +---- +$ oc patch hco kubevirt-hyperconverged -n openshift-cnv --type json -p '[{"op":"replace","path":"/spec/workloadUpdateStrategy/workloadUpdateMethods", "value":[]}]' +---- ++ +.Example output +[source,terminal] +---- +hyperconverged.hco.kubevirt.io/kubevirt-hyperconverged patched +---- + +. Ensure that the `HyperConverged` Operator is `Upgradeable` before you continue. Enter the following command and monitor the output: ++ +[source,terminal] +---- +$ kubectl get hco kubevirt-hyperconverged -n openshift-cnv -o json | jq ".status.conditions" +---- ++ +.Example output +[%collapsible] +==== +[source,json] +---- +[ + { + "lastTransitionTime": "2022-12-09T16:29:11Z", + "message": "Reconcile completed successfully", + "observedGeneration": 3, + "reason": "ReconcileCompleted", + "status": "True", + "type": "ReconcileComplete" + }, + { + "lastTransitionTime": "2022-12-09T20:30:10Z", + "message": "Reconcile completed successfully", + "observedGeneration": 3, + "reason": "ReconcileCompleted", + "status": "True", + "type": "Available" + }, + { + "lastTransitionTime": "2022-12-09T20:30:10Z", + "message": "Reconcile completed successfully", + "observedGeneration": 3, + "reason": "ReconcileCompleted", + "status": "False", + "type": "Progressing" + }, + { + "lastTransitionTime": "2022-12-09T16:39:11Z", + "message": "Reconcile completed successfully", + "observedGeneration": 3, + "reason": "ReconcileCompleted", + "status": "False", + "type": "Degraded" + }, + { + "lastTransitionTime": "2022-12-09T20:30:10Z", + "message": "Reconcile completed successfully", + "observedGeneration": 3, + "reason": "ReconcileCompleted", + "status": "True", + "type": "Upgradeable" <1> + } +] +---- +==== +<1> The {VirtProductName} Operator has the `Upgradeable` status. + +. Manually update your cluster from the source EUS version to the next minor version of {product-title}: ++ +[source,terminal] ++ +---- +$ oc adm upgrade +---- ++ +.Verification +* Check the current version by running the following command: ++ +[source,terminal] +---- +$ oc get clusterversion +---- ++ +[NOTE] +==== +Updating {product-title} to the next version is a prerequisite for updating {VirtProductName}. For more details, refer to the "Updating clusters" section of the {product-title} documentation. +==== + +. If you use the recommended *Automatic* approval strategy, which is enabled by default, {VirtProductName} automatically updates to the corresponding version after you update {product-title}. Monitor the {VirtProductName} update by running the following command: ++ +[source,terminal] +---- +$ oc get csv -n openshift-cnv +---- ++ +[NOTE] +==== +If you used the *Manual* approval strategy, you must approve the update in the web console. For more details, refer to the "Manually approving a pending Operator update" section. +==== + +. After you confirm that {VirtProductName} successfully updated to the non-EUS version, wait until the `HyperConverged` Operator has the `Upgradeable` status before you perform the next update. Enter the following command and monitor the output: ++ +[source,terminal] +---- +$ kubectl get hco kubevirt-hyperconverged -n openshift-cnv -o json | jq ".status.conditions" +---- + +. Update {product-title} and {VirtProductName} to the target EUS version, monitoring as in the preceding steps to ensure that the updates succeed. + +. Restore the workload update methods configuration that you backed up: ++ +[source,terminal] +---- +$ oc patch hco kubevirt-hyperconverged -n openshift-cnv --type json -p "[{\"op\":\"add\",\"path\":\"/spec/workloadUpdateStrategy/workloadUpdateMethods\", \"value\":$WORKLOAD_UPDATE_METHODS}]" +---- ++ +.Example output +[source,terminal] +---- +hyperconverged.hco.kubevirt.io/kubevirt-hyperconverged patched +---- ++ +.Verification + +* Check the status of VM migration by running the following command: ++ +[source,terminal] +---- +$ oc get vmim -A +---- + +.Next steps + +* You can now unpause the worker nodes' machine config pools. \ No newline at end of file diff --git a/virt/upgrading-virt.adoc b/virt/upgrading-virt.adoc index 64d286be55..a3bb8f7a5c 100644 --- a/virt/upgrading-virt.adoc +++ b/virt/upgrading-virt.adoc @@ -20,12 +20,15 @@ You must perform one of the following tasks before updating to {VirtProductName} include::modules/virt-about-upgrading-virt.adoc[leveloffset=+1] -[id="configuring-workload-updates_upgrading-virt"] -== Configuring automatic workload updates - include::modules/virt-about-workload-updates.adoc[leveloffset=+2] -include::modules/virt-configuring-workload-update-methods.adoc[leveloffset=+2] +include::modules/virt-about-eus-updates.adoc[leveloffset=+2] + +Learn more about xref:../updating/preparing-eus-eus-upgrade.adoc#preparing-eus-eus-upgrade[preparing to perform an EUS-to-EUS update]. + +include::modules/virt-preventing-workload-updates-during-eus-update.adoc[leveloffset=+1] + +include::modules/virt-configuring-workload-update-methods.adoc[leveloffset=+1] [id="approving-operator-upgrades_upgrading-virt"] == Approving pending Operator updates @@ -41,13 +44,15 @@ include::modules/virt-viewing-outdated-workloads.adoc[leveloffset=+2] [NOTE] ==== -xref:../virt/upgrading-virt.adoc#configuring-workload-updates_upgrading-virt[Configure workload updates] to ensure that VMIs update automatically. +Configure workload updates to ensure that VMIs update automatically. ==== [id="additional-resources_upgrading-virt"] [role="_additional-resources"] == Additional resources +* xref:../updating/preparing-eus-eus-upgrade.adoc#preparing-eus-eus-upgrade[Preparing to perform an EUS-to-EUS update] + * xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[What are Operators?] * xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager concepts and resources]