OTA-472: Reorganizing upgrade section

_javascripts/page-loader.js

@@ -115,8 +115,8 @@ function selectVersion(currentVersion) {
 
   // main file to edit is the file path after the version to the html at
   // the end.
-  // Example: https://docs.openshift.com/container-platform/4.4/updating/updating-cluster-between-minor.html
-  // file path is updating/updating-cluster-between-minor.adoc
+  // Example: https://docs.openshift.com/container-platform/4.4/updating/updating-cluster-within-minor.html
+  // file path is updating/updating-cluster-within-minor.adoc
 
   mainFileToEdit =
     window.location.pathname.substring(

_topic_map.yml

@@ -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-release
 # TODO: Remove below assembly for 4.10:
 - Name: Preparing to update to OpenShift Container Platform 4.10
   File: updating-cluster-prepare
@@ -478,11 +480,9 @@ Topics:
 - Name: Preparing to update to OKD 4.9
   File: updating-cluster-prepare
   Distros: openshift-origin
-- Name: Updating a cluster between minor versions
-  File: updating-cluster-between-minor
-- Name: Updating a cluster within a minor version from the web console
-  File: updating-cluster
-- Name: Updating a cluster within a minor version by using the CLI
+- Name: Updating a cluster within a minor version using the web console
+  File: updating-cluster-within-minor
+- Name: Updating a cluster within a minor version using the CLI
   File: updating-cluster-cli
 - Name: Performing update using canary rollout strategy
   File: update-using-custom-machine-config-pools

installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc

@@ -37,4 +37,4 @@ include::modules/ipi-install-verifying-static-ip-address-configuration.adoc[leve
 
 .Additional resources
 
-* See xref:../../updating/updating-cluster-between-minor.adoc#understanding-upgrade-channels_updating-cluster-between-minor[{product-title} upgrade channels and releases] for an explanation of the different release channels.
+* See xref:../../updating/updating-cluster-within-minor.adoc#understanding-upgrade-channels_updating-cluster-within-minor[{product-title} upgrade channels and releases] for an explanation of the different release channels.

installing/validating-an-installation.adoc

@@ -22,9 +22,9 @@ include::modules/getting-cluster-version-status-and-update-details.adoc[leveloff
 
 * See xref:../support/troubleshooting/troubleshooting-operator-issues.adoc#troubleshooting-operator-issues[Troubleshooting Operator issues] for information about investigating issues with Operators.
 
-* See xref:../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating a cluster between minor versions] for more information on updating your cluster.
+* See xref:../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[Updating a cluster between minor versions] for more information on updating your cluster.
 
-* See xref:../updating/updating-cluster-between-minor.adoc#understanding-upgrade-channels_updating-cluster-between-minor[OpenShift Container Platform upgrade channels and releases] for an overview about upgrade release channels.
+* See xref:../updating/updating-cluster-within-minor.adoc#understanding-upgrade-channels_updating-cluster-within-minor[OpenShift Container Platform upgrade channels and releases] for an overview about upgrade release channels.
 
 //Querying the status of the cluster nodes by using the CLI
 include::modules/querying-the-status-of-cluster-nodes-using-the-cli.adoc[leveloffset=+1]

migrating_from_ocp_3_to_4/planning-migration-3-4.adoc

@@ -66,7 +66,7 @@ For more information, see xref:../architecture/architecture-installation.adoc#in
 
 In {product-title} 3.11, you upgraded your cluster by running Ansible playbooks. In {product-title} {product-version}, the cluster manages its own updates, including updates to {op-system-first} on cluster nodes. You can easily upgrade your cluster by using the web console or by using the `oc adm upgrade` command from the OpenShift CLI and the Operators will automatically upgrade themselves. If your {product-title} {product-version} cluster has {op-system-base} worker machines, then you will still need to run an Ansible playbook to upgrade those worker machines.
 
-For more information, see xref:../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating clusters].
+For more information, see xref:../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[Updating clusters].
 
 [id="migration-considerations"]
 == Migration considerations

modules/machine-health-checks-pausing.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 
 // * updating/updating-cluster-cli.adoc
-// * updating/updating-cluster-between-minor.adoc
+// * updating/updating-cluster-within-minor.adoc
 // * updating/updating-restricted-network-cluster.adoc
 
 [id="machine-health-checks-pausing_{context}"]
@@ -66,4 +66,3 @@ Resume the machine health checks after updating the cluster. To resume the check
 $ oc -n openshift-machine-api annotate mhc <mhc-name> cluster.x-k8s.io/paused-
 ----
 ====
-

modules/understanding-upgrade-channels.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //
 // * updating/updating-cluster.adoc
-// * updating/updating-cluster-between-minor.adoc
+// * updating/updating-cluster-within-minor.adoc
 // * updating/updating-cluster-cli.adoc
 // * updating/updating-cluster-rhel-compute.adoc
 // * updating/updating-disconnected-cluster.adoc
@@ -80,7 +80,7 @@ ifndef::openshift-origin[]
 
 In addition to the stable channel, all even-numbered 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 Full and Maintenance support phases for customers with Standard and Premium Subscriptions to 18 months.
 
-Although there is no difference between `stable-4.y` and `eus-4.y` channels until {product-title} 4.y transitions to the EUS phase, you can switch to the `eus-4.y` channel as soon as it becomes available. 
+Although there is no difference between `stable-4.y` and `eus-4.y` channels until {product-title} 4.y transitions to the EUS phase, you can switch to the `eus-4.y` channel as soon as it becomes available.
 
 When upgrades to the next EUS channel are offered, you can switch to the next EUS channel and upgrade until you have reached the next EUS version.
 

modules/unmanaged-operators.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //
 // * architecture/architecture-installation.adoc
-// * updating/updating-cluster-between-minor.adoc
+// * updating/updating-cluster-within-minor.adoc
 
 [id="unmanaged-operators_{context}"]
 = Support policy for unmanaged Operators

modules/update-service-overview.adoc

@@ -2,7 +2,7 @@
 //
 // * architecture/architecture-installation.adoc
 // * architecture/control-plane.adoc
-// * updating/updating-cluster-between-minor.adoc
+// * updating/updating-cluster-within-minor.adoc
 // * updating/updating-cluster-cli.adoc
 // * updating/updating-cluster-rhel-compute.adoc
 // * updating/updating-cluster.adoc
@@ -44,4 +44,3 @@ If you use {op-system-base-full} machines as workers, the MCO does not update th
 With the specification for the new version applied to the old kubelet, the {op-system-base} machine cannot return to the `Ready` state. You cannot complete the update until the machines are available. However, the maximum number of unavailable nodes is set to ensure that normal cluster operations can continue with that number of machines out of service.
 
 The OpenShift Update Service is composed of an Operator and one or more application instances.
-

modules/update-upgrading-web.adoc

@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
 // * updating/updating-cluster.adoc
-// * updating/updating-cluster-between-minor.adoc
+// * updating/updating-cluster-within-minor.adoc
 
 ifeval::["{context}" == "updating-cluster"]
 :within:
 endif::[]
-ifeval::["{context}" == "updating-cluster-between-minor"]
+ifeval::["{context}" == "updating-cluster-within-minor"]
 :between:
 endif::[]
 ifeval::["{context}" == "updating-cluster-rhel-compute"]
@@ -25,7 +25,7 @@ link:https://access.redhat.com/downloads/content/290[in the errata section] of t
 .Prerequisites
 
 * Have access to the web console as a user with `admin` privileges.
-* Pause all `MachineHealthCheck` resources. 
+* Pause all `MachineHealthCheck` resources.
 
 .Procedure
 

modules/update-using-custom-machine-config-pools-canary.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * updating/updating-cluster-between-minor.adoc
+// * updating/updating-cluster-within-minor.adoc
 
 [id="update-using-custom-machine-config-pools-canary_{context}"]
 = Performing a canary rollout update
@@ -12,9 +12,9 @@ In some specific use cases, you might want a more controlled update process wher
 
 The rolling update process is *not* a typical update workflow. With larger clusters, it can be a time-consuming process that requires you execute multiple commands. This complexity can result in errors that can affect the entire cluster.  It is recommended that you carefully consider whether your organization wants to use a rolling update and carefully plan the implementation of the process before you start.
 
-The rolling update process described in this topic involves: 
+The rolling update process described in this topic involves:
 
-* Creating one or more custom machine config pools (MCPs). 
+* Creating one or more custom machine config pools (MCPs).
 * Labeling each node that you do not want to  update immediately to move those nodes to the custom MCPs.
 * Pausing those custom MCPs, which prevents updates to those nodes.
 * Performing the cluster update.
@@ -26,7 +26,7 @@ The rolling update process described in this topic involves:
 
 [NOTE]
 ====
-Pausing an MCP prevents the Machine Config Operator from applying any configuration changes on the associated nodes. Pausing an MCP also prevents any automatically-rotated certificates from being pushed to the associated nodes, including the automatic CA rotation of the `kube-apiserver-to-kubelet-signer` CA certificate. If the MCP is paused when the `kube-apiserver-to-kubelet-signer` CA certificate expires and the MCO attempts to automatically renew the certificate, the new certificate is created but not applied across the nodes in the respective machine config pool. This causes failure in multiple `oc` commands, including but not limited to `oc debug`, `oc logs`, `oc exec`, and `oc attach`. Pausing an MCP should be done with careful consideration about the `kube-apiserver-to-kubelet-signer` CA certificate expiration and for short periods of time only.  
+Pausing an MCP prevents the Machine Config Operator from applying any configuration changes on the associated nodes. Pausing an MCP also prevents any automatically-rotated certificates from being pushed to the associated nodes, including the automatic CA rotation of the `kube-apiserver-to-kubelet-signer` CA certificate. If the MCP is paused when the `kube-apiserver-to-kubelet-signer` CA certificate expires and the MCO attempts to automatically renew the certificate, the new certificate is created but not applied across the nodes in the respective machine config pool. This causes failure in multiple `oc` commands, including but not limited to `oc debug`, `oc logs`, `oc exec`, and `oc attach`. Pausing an MCP should be done with careful consideration about the `kube-apiserver-to-kubelet-signer` CA certificate expiration and for short periods of time only.
 ====
 
-//link that follows is in the assembly: updating-cluster-between-minor
+//link that follows is in the assembly: updating-cluster-within-minor

post_installation_configuration/cluster-tasks.adoc

@@ -142,7 +142,7 @@ You use these resources to retrieve information about the cluster. Some configur
 |`version`
 |In {product-title} {product-version}, you must not customize the `ClusterVersion`
 resource for production clusters. Instead, follow the process to
-xref:../updating/updating-cluster.adoc#updating-cluster[update a cluster].
+xref:../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[update a cluster].
 
 |`dns.config.openshift.io`
 |`cluster`

security/container_security/security-hosts-vms.adoc

@@ -28,7 +28,7 @@ ifndef::openshift-origin[]
 endif::[]
 * xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-encrypt-disk_installing-customizing[Disk encryption]
 * xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Chrony time service]
-* xref:../../updating/updating-cluster-between-minor.adoc#update-service-overview_updating-cluster-between-minor[{product-title} cluster updates]
+* xref:../../updating/updating-cluster-within-minor.adoc#update-service-overview_updating-cluster-within-minor[{product-title} cluster updates]
 
 // Virtualization versus containers
 include::modules/security-hosts-vms-vs-containers.adoc[leveloffset=+1]

support/remote_health_monitoring/about-remote-health-monitoring.adoc

@@ -13,7 +13,7 @@ A cluster that reports data to Red Hat through Telemetry and the Insights Operat
 
 The *Insights Operator* gathers {product-title} configuration data and sends it to Red Hat. The data is used to produce insights about potential issues that a cluster might be exposed to. These insights are communicated to cluster administrators on link:https://console.redhat.com/openshift[console.redhat.com/openshift].
 
-More information is provided in this document about these two processes. 
+More information is provided in this document about these two processes.
 
 .Telemetry and Insights Operator benefits
 
@@ -37,7 +37,7 @@ include::modules/telemetry-about-telemetry.adoc[leveloffset=+1]
 
 .Additional resources
 
-* See the xref:../../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[{product-title} update documentation] for more information about updating or upgrading a cluster.
+* See the xref:../../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[{product-title} update documentation] for more information about updating or upgrading a cluster.
 
 include::modules/telemetry-what-information-is-collected.adoc[leveloffset=+2]
 
@@ -80,11 +80,11 @@ As further described in the preceding sections of this document, Red Hat collect
 
 .Collection safeguards
 
-Red Hat employs technical and organizational measures designed to protect the telemetry and configuration data. 
+Red Hat employs technical and organizational measures designed to protect the telemetry and configuration data.
 
 .Sharing
 
-Red Hat may share the data collected through Telemetry and the Insights Operator internally within Red Hat to improve your user experience. Red Hat may share telemetry and configuration data with its business partners in an aggregated form that does not identify customers to help the partners better understand their markets and their customers’ use of Red Hat offerings or to ensure the successful integration of products jointly supported by those partners. 
+Red Hat may share the data collected through Telemetry and the Insights Operator internally within Red Hat to improve your user experience. Red Hat may share telemetry and configuration data with its business partners in an aggregated form that does not identify customers to help the partners better understand their markets and their customers’ use of Red Hat offerings or to ensure the successful integration of products jointly supported by those partners.
 
 .Third party service providers
 

updating/installing-update-service.adoc

@@ -16,8 +16,6 @@ To provide a similar upgrade experience in a restricted network, you can install
 
 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]
-
 [id="update-service-prereqs"]
 == Prerequisites
 

updating/understanding-upgrade-channels-release.adoc

@@ -0,0 +1,32 @@
+[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]