OTA-472: Reorganizing update book and removing redundancy #36015

shellyyang1989 · 2021-09-10T07:24:07Z

It's saying A channel can be switched from the web console, but we don't document how to change it from web console. I'd suggest to add the procedure for it.

shellyyang1989 · 2021-09-02T03:54:24Z

Do we make hardcoded 4.8 for instance in 4.6, 4.7 and 4.8? It would be better to have 4.6, 4.7, 4.8 instance in 4.6, 4.7, 4.8 page respectively.

For instance, {product-title} 4.8 upgrade channels recommend upgrades to 4.8 and upgrades within 4.8. They also recommend upgrades within 4.7 and from 4.7 to 4.8, to allow clusters on 4.7 to eventually upgrade to 4.8.

It's a bit complex. If it's what you want to express, how about changing it to 4.8 upgrade channels recommend upgrades from 4.7 to 4.7, from 4.7 to 4.8, from 4.8 to 4.8?

This strategy ensures that administrators explicitly decide to upgrade to the next minor version of {product-title}.

It also lets the admin decide the next z-stream version, right?

@LalatenduMohanty - Thoughts?

I like the existing text. Also 4.8 upgrade channels recommend upgrades from 4.7 to 4.7, from 4.7 to 4.8, from 4.8 to 4.8 gives the impression that 4.8 channel can be used for 4.7 z stream updates which is not correct. The reason we have some 4.7 releases in 4.8 channels because we want to provide edges so that clusters eventually move to 4.8.

@LalatenduMohanty Any suggestions on the text?

shellyyang1989 · 2021-09-02T05:49:22Z

oc adm upgrade channel is an ability of 4.9 oc binary. It's not applicable to 4.6, 4.7, 4.8.

@shellyyang1989 This content was just moved around so this content has been in our docs already, not newly added. I can do another PR to remove this content in areas that it's not applicable.

It's appropriate to have this content in the main branch. It will just have to be manually removed from any backports to 4.8 or earlier (and Git cherry-pick conflicts will make it hard to forget ;)

@wking Any suggestion on the text?

-Original file line number
+Diff line change
@@ Expand Up / @@ -470,6 +470,8 @@ Topics: @@
       File: understanding-the-update-service
     - Name: Installing and configuring the OpenShift Update Service
       File: installing-update-service
+    - Name: Understanding upgrade channels
+      File: understanding-upgrade-channels-releases
     # TODO: Remove below assembly for 4.10:
     - Name: Preparing to update to OpenShift Container Platform 4.10
       File: updating-cluster-prepare
@@ Expand All / @@ -478,7 +480,7 @@ Topics: @@
     - Name: Preparing to update to OKD 4.9
       File: updating-cluster-prepare
       Distros: openshift-origin
-    - Name: Updating a cluster between minor versions
+    - Name: Updating a cluster within a minor version from the web console
       File: updating-cluster-between-minor
     - Name: Updating a cluster within a minor version from the web console
       File: updating-cluster
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -942,20 +942,6 @@ spec: @@
     +
     Do not use `[...]`, `<snip>`, or any other variant.
-    * Do not use `jq` in commands (unless it is truly required), because this requires users to install the `jq` tool. Oftentimes, the same or similar result can be accomplished using `jsonpath` for `oc` commands.
-    +
-    For example, this command that uses `jq`:
-    +
-    ----
-    $ oc get clusterversion -o json|jq ".items[0].spec"
-    ----
-    +
-    can be updated to use `jsonpath` instead:
-    +
-    ----
-    $ oc get clusterversion -o jsonpath='{.items[0].spec}{"\n"}'
-    ----
     === Inline code or commands
     Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax.
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up @@
     Upgrade channels control only release selection and do not impact the version of the cluster that you install; the `openshift-install` binary file for a specific version of {product-title} always installs that version.
     ifndef::openshift-origin[]
-    {product-title} {product-version} offers the following upgrade channels:
-    * `candidate-{product-version}`
-    * `fast-{product-version}`
-    * `stable-{product-version}`
-    * `eus-4.6` (only available when running 4.6)
-    If you do not want the Cluster Version Operator to fetch available updates from the upgrade recommendation service, you can use the `oc adm upgrade channel` command in the OpenShift CLI to configure an empty channel. This configuration can be helpful if, for example, a cluster has restricted network access and there is no local, reachable upgrade recommendation service.
-    endif::openshift-origin[]
-    ifdef::openshift-origin[]
-    {product-title} {product-version} offers the following upgrade channel:
-    * `stable-4`
-    endif::openshift-origin[]
-    ifndef::openshift-origin[]
-    [discrete]
-    == candidate-{product-version} channel
+    = candidate-{product-version} channel
     The `candidate-{product-version}` channel contains candidate builds for a z-stream ({product-version}.z) and previous minor version releases. Release candidates contain all the features of the product but are not supported. Use release candidate versions to test feature acceptance and assist in qualifying the next version of {product-title}. A release candidate is any build that is available in the candidate channel, including ones that do not contain link:https://semver.org/spec/v2.0.0.html#spec-item-9[a pre-release version] such as `-rc` in their names. After a version is available in the candidate channel, it goes through more quality checks. If it meets the quality standard, it is promoted to the `fast-{product-version}` or `stable-{product-version}` channels. Because of this strategy, if a specific release is available in both the `candidate-{product-version}` channel and in the `fast-{product-version}` or `stable-{product-version}` channels, it is a Red Hat-supported version. The `candidate-{product-version}` channel can include release versions from which there are no recommended updates in any channel.
@@ Expand All / @@ -51,32 +33,32 @@ endif::[] @@
     for more build information.
     ====
-    [discrete]
-    == fast-{product-version} channel
+    = fast-{product-version} channel
     The `fast-{product-version}` channel is updated with new and previous minor versions of {product-version} as soon as Red Hat declares the given version as a general availability release. As such, these releases are fully supported, are production quality, and have performed well while available as a release candidate in the `candidate-{product-version}` channel from where they were promoted. Some time after a release appears in the `fast-{product-version}` channel, it is added to the `stable-{product-version}` channel. Releases never appear in the `stable-{product-version}` channel before they appear in the `fast-{product-version}` channel.
     You can use the `fast-{product-version}` channel to upgrade from a previous minor version of {product-title}.
     endif::openshift-origin[]
     ifndef::openshift-origin[]
-    [discrete]
-    == stable-{product-version} channel
+    = stable-{product-version} channel
     While the `fast-{product-version}` channel contains releases as soon as their errata are published, releases are added to the `stable-{product-version}` channel after a delay. During this delay, data is collected from Red Hat SRE teams, Red Hat support services, and pre-production and production environments that participate in connected customer program about the stability of the release.
     You can use the `stable-{product-version}` channel to upgrade from a previous minor version of {product-title}.
     endif::openshift-origin[]
     ifdef::openshift-origin[]
-    [discrete]
-    == stable-4 channel
+    = stable-4 channel
     Releases are added to the `stable-4` channel after passing all tests.
     You can use the `stable-4` channel to upgrade from a previous minor version of {product-title}.
     endif::openshift-origin[]
     ifndef::openshift-origin[]
-    [discrete]
-    == eus-4.6 channel
+    = eus-4.6 channel
     In addition to the stable channel, certain minor versions of {product-title} offer an link:https://access.redhat.com/support/policy/updates/openshift#ocp4_phases[Extended Update Support] (EUS). These EUS versions extend the maintenance phase for customers with Premium Subscriptions to 14 months. {product-title} 4.6 is currently the only minor version with EUS.
@@ Expand All @@
     Finally, if you install a 4.6 version that is exclusive to EUS, you will similarly not be able to upgrade to a later minor version until upgrades are provided to 4.10.
     endif::openshift-origin[]
-    [discrete]
-    == Upgrade version paths
+    = Upgrade version paths
     {product-title} maintains an upgrade recommendation service that understands the version of {product-title} you have installed as well as the path to take within the channel you choose to get you to the next release.
@@ Expand Down Expand Up @@
     endif::openshift-origin[]
     ifndef::openshift-origin[]
-    [discrete]
-    == Fast and stable channel use and strategies
+    = Fast and stable channel use and strategies
     The `fast-{product-version}` and `stable-{product-version}` channels present a choice between receiving general availability releases as soon as they are available or allowing Red Hat to control the rollout of those updates. If issues are detected during rollout or at a later time, upgrades to that version might be blocked in both the `fast-{product-version}` and `stable-{product-version}` channels, and a new version might be introduced that becomes the new preferred upgrade target.
     Customers can improve this process by configuring pre-production systems on the `fast-{product-version}` channel, configuring production systems on the `stable-{product-version}` channel, and participating in the Red Hat connected customer program. Red Hat uses this program to observe the impact of updates on your specific hardware and software configurations. Future releases might improve or alter the pace at which updates move from the `fast-{product-version}` to the `stable-{product-version}` channel.
     endif::openshift-origin[]
-    [discrete]
-    == Restricted network clusters
+    = Restricted network clusters
     If you manage the container images for your {product-title} clusters yourself, you must consult the Red Hat errata that is associated with product releases and note any comments that impact upgrades. During upgrade, the user interface might warn you about switching between these versions, so you must ensure that you selected an appropriate version before you bypass those warnings.
     ifndef::openshift-origin[]
-    [discrete]
-    == Switching between channels
+    = Switching between channels
     A channel can be switched from the web console or through the `adm upgrade channel` command:
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up @@
     The following sections describe how to provide over-the-air updates for your disconnected cluster and its underlying operating system.
-    include::modules/update-service-overview.adoc[leveloffset=+1]
+    // include::modules/update-service-overview.adoc[leveloffset=+1]
     [id="update-service-prereqs"]
     == Prerequisites
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -0,0 +1,30 @@
+    [id="understanding-upgrade-channels"]
+    = Understanding upgrade channels and releases
+    include::modules/common-attributes.adoc[]
+    :context: understanding-upgrade-channels-releases
+    toc::[]
+    In {product-title} 4.1, Red Hat introduced the concept of channels for recommending the appropriate release versions for cluster upgrades. By controlling the pace of upgrades, these upgrade channels allow you to choose an upgrade strategy. Upgrade channels are tied to a minor version of {product-title}. For instance, {product-title} 4.8 upgrade channels recommend upgrades to 4.8 and upgrades within 4.8. They also recommend upgrades within 4.7 and from 4.7 to 4.8, to allow clusters on 4.7 to eventually upgrade to 4.8. They do not recommend upgrades to 4.9 or later releases. This strategy ensures that administrators explicitly decide to upgrade to the next minor version of {product-title}.
+    Upgrade channels control only release selection and do not impact the version of the cluster that you install; the `openshift-install` binary file for a specific version of {product-title} always installs that version.
+    ifndef::openshift-origin[]
+    {product-title} {product-version} offers the following upgrade channels:
+    * `candidate-{product-version}`
+    * `fast-{product-version}`
+    * `stable-{product-version}`
+    * `eus-4.6` (only available when running 4.6)
+    If you do not want the Cluster Version Operator to fetch available updates from the upgrade recommendation service, you can use the `oc adm upgrade channel` command in the OpenShift CLI to configure an empty channel. This configuration can be helpful if, for example, a cluster has restricted network access and there is no local, reachable upgrade recommendation service.
+    endif::openshift-origin[]
+    ifdef::openshift-origin[]
+    {product-title} {product-version} offers the following upgrade channel:
+    * `stable-4`
+    endif::openshift-origin[]
+    include::modules/understanding-upgrade-channels.adoc[leveloffset=+1]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OTA-472: Reorganizing update book and removing redundancy #36015

Uh oh!

Diff view

Diff view

There are no files selected for viewing

shellyyang1989 Sep 10, 2021 •

edited

Loading

Uh oh!

shellyyang1989 Sep 2, 2021 •

edited

Loading

Uh oh!

sagidlow Sep 2, 2021

Uh oh!

LalatenduMohanty Sep 2, 2021

Uh oh!

sagidlow Sep 9, 2021

Uh oh!

shellyyang1989 Sep 2, 2021

Uh oh!

sagidlow Sep 2, 2021

Uh oh!

wking Sep 7, 2021

Uh oh!

sagidlow Sep 9, 2021

Uh oh!

Uh oh!

-Original file line number
+Diff line change
@@ -1,5 +1,5 @@
     [id="updating-cluster-between-minor"]
-    = Updating a cluster between minor versions
+    = Updating a cluster within a minor version from the web console
     include::modules/common-attributes.adoc[]
     :context: updating-cluster-between-minor
@@ Expand Down Expand Up @@
     If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061].
     ====
-    include::modules/update-service-overview.adoc[leveloffset=+1]
+    // include::modules/update-service-overview.adoc[leveloffset=+1]
     .Additional resources
     * xref:../architecture/architecture-installation.adoc#unmanaged-operators_architecture-installation[Support policy for unmanaged Operators]
-    include::modules/understanding-upgrade-channels.adoc[leveloffset=+1]
+    // include::modules/understanding-upgrade-channels.adoc[leveloffset=+1]
     include::modules/update-using-custom-machine-config-pools-canary.adoc[leveloffset=+1]
@@ Expand Down @@

OTA-472: Reorganizing update book and removing redundancy #36015

Uh oh!

OTA-472: Reorganizing update book and removing redundancy #36015

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

shellyyang1989 Sep 10, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shellyyang1989 Sep 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sagidlow Sep 2, 2021

Choose a reason for hiding this comment

Uh oh!

LalatenduMohanty Sep 2, 2021

Choose a reason for hiding this comment

Uh oh!

sagidlow Sep 9, 2021

Choose a reason for hiding this comment

Uh oh!

shellyyang1989 Sep 2, 2021

Choose a reason for hiding this comment

Uh oh!

sagidlow Sep 2, 2021

Choose a reason for hiding this comment

Uh oh!

wking Sep 7, 2021

Choose a reason for hiding this comment

Uh oh!

sagidlow Sep 9, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shellyyang1989 Sep 10, 2021 •

edited

Loading

shellyyang1989 Sep 2, 2021 •

edited

Loading