Skip to content

Commit 93d8792

Browse files
sagidlowsagidlow
authored
Merge pull request #40619 from sagidlow/OSDOCS-3147
OSDOCS-3147: Adding EUS to EUS upgrade doc
2 parents 3c52791 + dcbbde7 commit 93d8792

File tree

3 files changed

+162
-0
lines changed

3 files changed

+162
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -436,6 +436,8 @@ Topics:
436436
File: installing-update-service
437437
- Name: Understanding upgrade channels
438438
File: understanding-upgrade-channels-release
439+
- Name: Preparing to perform an EUS to EUS upgrade
440+
File: preparing-eus-eus-upgrade
439441
- Name: Updating a cluster within a minor version using the web console
440442
File: updating-cluster-within-minor
441443
- Name: Updating a cluster within a minor version using the CLI

‎modules/updating-eus-to-eus-upgrade.adoc

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/preparing-eus-eus-upgrade.adoc
4+
5+
[id="updating-eus-to-eus-upgrade_{context}"]
6+
= EUS to EUS upgrade
7+
8+
The following procedure pauses all non-master MachineConfigPools and performs upgrades from {product-title} 4.8 to 4.9 to 4.10, then unpauses the previously paused MachineConfigPools.
9+
Following this procedure reduces the total upgrade duration and the number of times worker nodes are restarted.
10+
11+
.Prerequisites
12+
13+
* Review the release notes for {product-title} 4.9 and 4.10
14+
* Review the release notes and product lifecycles for any layered products and OLM Operators. Some may require updates either before or during an EUS to EUS upgrade.
15+
* Ensure that you are familiar with version-specific prerequisites, such as link:https://docs.openshift.com/container-platform/4.9/updating/updating-cluster-prepare.html#update-preparing-migrate_updating-cluster-prepare[administrator acknowledgement] that is required prior to upgrading from {product-title} 4.8 to 4.9.
16+
* Verify that your cluster is not running a version earlier than {product-title} 4.8.14.
17+
If your cluster is running a version than {product-title} 4.8.14, you must upgrade to a later 4.8.z version prior to upgrading to 4.9.
18+
The upgrade to 4.8.14 or later is necessary to fulfill the minimum version requirements that must be performed without pausing MachineConfigPools.
19+
* Verify that MachineConfigPools is unpaused.
20+
21+
.Procedure
22+
23+
. Upgrade any OLM Operators to versions that are compatible with both versions you are upgrading to.
24+
25+
. Verify that all MachineConfigPools display a status of `UPDATED` and no MachineConfigPools display a status of `UPDATING`.
26+
To view the status of all MachineConfigPools, run the following command:
27+
+
28+
[source,terminal]
29+
----
30+
$ oc get mcp
31+
----
32+
+
33+
.Example output
34+
+
35+
Output is trimmed for clarity:
36+
+
37+
[source,terminal]
38+
----
39+
NAME CONFIG UPDATED UPDATING
40+
master rendered-master-ecbb9582781c1091e1c9f19d50cf836c True False
41+
worker rendered-worker-00a3f0c68ae94e747193156b491553d5 True False
42+
----
43+
44+
. To pause the MachineConfigPools you wish to skip reboots on, run the following commands:
45+
+
46+
[NOTE]
47+
====
48+
You cannot pause the master pool.
49+
====
50+
+
51+
[source,terminal]
52+
----
53+
$ oc patch mcp/worker --type merge --patch '{"spec":{"paused":true}}'
54+
----
55+
56+
. To change to the `eus-4.10` channel and upgrade to 4.9, run the following commands:
57+
+
58+
[source,terminal]
59+
----
60+
$ oc adm upgrade channel eus-4.10
61+
$ oc adm upgrade --to-latest
62+
----
63+
+
64+
.Example output
65+
+
66+
[source,terminal]
67+
----
68+
Updating to latest version 4.9.18
69+
----
70+
71+
. To ensure the 4.9 upgrades are completed successfully retrieve the cluster version, run the following command:
72+
+
73+
[source,terminal]
74+
----
75+
$ oc get clusterversion
76+
----
77+
+
78+
.Example output
79+
+
80+
[source,terminal]
81+
----
82+
NAME VERSION AVAILABLE PROGRESSING SINCE STATUS
83+
version 4.9.18 True False 6m29s Cluster version is 4.9.18
84+
----
85+
86+
. If necessary, upgrade OLM operators using the Administrator perspective on the web console.
87+
88+
. To upgrade to 4.10, run the following command:
89+
+
90+
[source,terminal]
91+
----
92+
$ oc adm upgrade --to-latest
93+
----
94+
95+
. To ensure the 4.10 upgrade is completed successfully retrieve the cluster version, run the following command:
96+
+
97+
[source,terminal]
98+
----
99+
$ oc get clusterversion
100+
----
101+
+
102+
.Example output
103+
+
104+
[source,terminal]
105+
----
106+
NAME VERSION AVAILABLE PROGRESSING SINCE STATUS
107+
version 4.10.1 True False 6m29s Cluster version is 4.10.1
108+
----
109+
110+
. To unpause all previously paused MachineConfigPools, run the following command:
111+
+
112+
[source,terminal]
113+
----
114+
$ oc patch mcp/worker --type merge --patch '{"spec":{"paused":false}}'
115+
----
116+
+
117+
[NOTE]
118+
====
119+
If pools are not unpaused, the cluster is not permitted to upgrade to any future minors and maintenance tasks such as certificate rotation are inhibited. This puts the cluster at risk for future degradation.
120+
====
121+
122+
. To verify that your previously paused pools have updated and your cluster completed the upgrade to 4.10, run the following command:
123+
+
124+
[source,terminal]
125+
----
126+
$ oc get mcp
127+
----
128+
+
129+
.Example output
130+
+
131+
Output is trimmed for clarity:
132+
+
133+
[source,terminal]
134+
----
135+
NAME CONFIG UPDATED UPDATING
136+
master rendered-master-52da4d2760807cb2b96a3402179a9a4c True False
137+
worker rendered-worker-4756f60eccae96fb9dcb4c392c69d497 True False
138+
----

‎updating/preparing-eus-eus-upgrade.adoc

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
[id="preparing-eus-eus-upgrade"]
2+
= Performing to perform an EUS to EUS upgrade
3+
include::modules/common-attributes.adoc[]
4+
:context: eus-to-eus-upgrade
5+
6+
toc::[]
7+
8+
Due to fundamental Kubernetes design, all {product-title} upgrades between minor versions must be serialized.
9+
You must upgrade from {product-title} 4.8 to 4.9 and then to 4.10. You cannot upgrade from {product-title} 4.8 to 4.10 directly.
10+
However, beginning with the upgrade from {product-title} 4.8 to 4.9 to 4.10, administrators who wish to upgrade between two Extended Update Support (EUS) versions can do so incurring only a single reboot of non-master hosts.
11+
12+
There are a number of caveats to consider when attempting an EUS to EUS upgrade.
13+
14+
* EUS to EUS upgrades are only offered after upgrades between all versions involved have been made available in `stable` channels.
15+
* If you encounter issues during or after upgrading to the odd-numbered minor version but before upgrading to the next even-numbered version, then remediation of those issues may require that non-master hosts complete the upgrade to the odd-numbered version before moving forward.
16+
* You can complete the upgrade process during multiple maintenance windows by pausing at intermediate steps. However, plan to complete the entire upgrade within 60 days. This is critical to ensure that normal cluster automation processes are completed including those associated with certificate rotation.
17+
* You must be running at least {product-title} 4.8.14 before starting the EUS-to-EUS upgrade procedure. If you do not meet this minimum requirement, upgrade to a later 4.8.z before attempting the EUS-to-EUS upgrade.
18+
* Support for RHEL7 workers was removed in {product-title} 4.10 and replaced with RHEL8 workers, therefore EUS to EUS upgrades are not available for clusters with RHEL7 workers.
19+
* Node components are not updated to {product-title} 4.9. Do not expect all features and bugs fixed in {product-title} 4.9 to be made available until you complete the upgrade to {product-title} 4.10 and enable all MachineConfigPools to update.
20+
21+
22+
include::modules/updating-eus-to-eus-upgrade.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)