diff --git a/_javascripts/page-loader.js b/_javascripts/page-loader.js index 9b04ded6476d..c1b6578e4f3d 100644 --- a/_javascripts/page-loader.js +++ b/_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( diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 0ce40b88a0f3..befa3cda8180 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -433,11 +433,11 @@ Topics: File: understanding-the-update-service - Name: Installing and configuring the OpenShift Update Service File: installing-update-service -- 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: Understanding upgrade channels + File: understanding-upgrade-channels-release +- Name: Updating a cluster within minor versions 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 diff --git a/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc b/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc index 621cd9756e9f..5c7efe61377a 100644 --- a/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc +++ b/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. diff --git a/installing/validating-an-installation.adoc b/installing/validating-an-installation.adoc index 3dcdb9fc209b..8023bbdbb804 100644 --- a/installing/validating-an-installation.adoc +++ b/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 within a minor version using the web console] 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] diff --git a/migrating_from_ocp_3_to_4/planning-migration-3-4.adoc b/migrating_from_ocp_3_to_4/planning-migration-3-4.adoc index c722830acb1f..f4ec01b43203 100644 --- a/migrating_from_ocp_3_to_4/planning-migration-3-4.adoc +++ b/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 diff --git a/modules/machine-health-checks-pausing.adoc b/modules/machine-health-checks-pausing.adoc index 1f4131e1b9bf..60ea6caadd6b 100644 --- a/modules/machine-health-checks-pausing.adoc +++ b/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 cluster.x-k8s.io/paused- ---- ==== - diff --git a/modules/understanding-upgrade-channels.adoc b/modules/understanding-upgrade-channels.adoc index 6a9d72a8cb60..775d3466c361 100644 --- a/modules/understanding-upgrade-channels.adoc +++ b/modules/understanding-upgrade-channels.adoc @@ -1,38 +1,10 @@ // Module included in the following assemblies: // -// * updating/updating-cluster.adoc -// * updating/updating-cluster-between-minor.adoc -// * updating/updating-cluster-cli.adoc -// * updating/updating-cluster-rhel-compute.adoc -// * updating/updating-disconnected-cluster.adoc +// * updating/understanding-upgrade-channels-release.adoc [id="understanding-upgrade-channels_{context}"] -= {product-title} upgrade channels and releases -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.9 upgrade channels recommend upgrades to 4.9 and upgrades within 4.9. They also recommend upgrades within 4.8 and from 4.8 to 4.9, to allow clusters on 4.8 to eventually upgrade to 4.9. They do not recommend upgrades to 4.10 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.y` (only when running an even-numbered 4.y cluster release, like 4.10) - -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 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. @@ -51,7 +23,7 @@ endif::[] for more build information. ==== -[discrete] + == 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. @@ -60,14 +32,14 @@ You can use the `fast-{product-version}` channel to upgrade from a previous mino endif::openshift-origin[] ifndef::openshift-origin[] -[discrete] + == 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 Releases are added to the `stable-4` channel after passing all tests. @@ -75,19 +47,19 @@ You can use the `stable-4` channel to upgrade from a previous minor version of { endif::openshift-origin[] ifndef::openshift-origin[] -[discrete] + == eus-4.y channel 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. This upgrade process does not apply for the `eus-4.6` channel. endif::openshift-origin[] -[discrete] + == 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. @@ -117,7 +89,7 @@ The presence of an update recommendation in the `stable-4` channel at any point endif::openshift-origin[] ifndef::openshift-origin[] -[discrete] + == 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. @@ -125,13 +97,13 @@ The `fast-{product-version}` and `stable-{product-version}` channels present a c 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 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 A channel can be switched from the web console or through the `adm upgrade channel` command: diff --git a/modules/unmanaged-operators.adoc b/modules/unmanaged-operators.adoc index c24934067f9d..19e45d20f221 100644 --- a/modules/unmanaged-operators.adoc +++ b/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 diff --git a/modules/update-service-overview.adoc b/modules/update-service-overview.adoc index 5b1014e66310..e046d56322ce 100644 --- a/modules/update-service-overview.adoc +++ b/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. - diff --git a/modules/update-upgrading-web.adoc b/modules/update-upgrading-web.adoc index 36c55a93f21e..48311c0be998 100644 --- a/modules/update-upgrading-web.adoc +++ b/modules/update-upgrading-web.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 ifeval::["{context}" == "updating-cluster"] :within: @@ -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 diff --git a/modules/update-using-custom-machine-config-pools-canary.adoc b/modules/update-using-custom-machine-config-pools-canary.adoc index fd6288eb8d15..2b80a2983f30 100644 --- a/modules/update-using-custom-machine-config-pools-canary.adoc +++ b/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 diff --git a/modules/updating-sno.adoc b/modules/updating-sno.adoc index 9adeef9e4cf8..82184db3f5f0 100644 --- a/modules/updating-sno.adoc +++ b/modules/updating-sno.adoc @@ -1,29 +1,29 @@ // Module included in the following assemblies: // -// * updating/updating-cluster-between-minor.adoc +// * updating/updating-cluster-within-minor.adoc // * updating/updating-cluster-cli.adoc // * updating/updating-cluster.adoc [id="update-single-node-openshift_{context}"] = About updating single node {product-title} -You can update, or upgrade, a single-node {product-title} cluster by using either the console or CLI. +You can update, or upgrade, a single-node {product-title} cluster by using either the console or CLI. -However, note the following limitations: +However, note the following limitations: * The prerequisite to pause the `MachineHealthCheck` resources is not required because there is no other node to perform the health check. -* Restoring a single-node {product-title} cluster using an etcd backup is not officially supported. However, it is good practice to perform the etcd backup in case your upgrade fails. If your control plane is healthy, you might be able to restore your cluster to a previous state by using the backup. +* Restoring a single-node {product-title} cluster using an etcd backup is not officially supported. However, it is good practice to perform the etcd backup in case your upgrade fails. If your control plane is healthy, you might be able to restore your cluster to a previous state by using the backup. -* Updating a single-node {product-title} cluster requires downtime and can include an automatic reboot. The amount of downtime depends on the update payload, as described in the following scenarios: +* Updating a single-node {product-title} cluster requires downtime and can include an automatic reboot. The amount of downtime depends on the update payload, as described in the following scenarios: -** If the update payload contains an operating system update, which requires a reboot, the downtime is significant and impacts cluster management and user workloads. +** If the update payload contains an operating system update, which requires a reboot, the downtime is significant and impacts cluster management and user workloads. ** If the update contains machine configuration changes that do not require a reboot, the downtime is less, and the impact on the cluster management and user workloads is lessened. In this case, the node draining step is skipped with single-node {product-title} because there is no other node in the cluster to reschedule the workloads to. - -** If the update payload does not contain an operating system update or machine configuration changes, a short API outage occurs and resolves quickly. + +** If the update payload does not contain an operating system update or machine configuration changes, a short API outage occurs and resolves quickly. [IMPORTANT] ==== -There are conditions, such as bugs in an updated package, that can cause the single node to not restart after a reboot. In this case, the update does not rollback automatically. +There are conditions, such as bugs in an updated package, that can cause the single node to not restart after a reboot. In this case, the update does not rollback automatically. ==== diff --git a/post_installation_configuration/cluster-tasks.adoc b/post_installation_configuration/cluster-tasks.adoc index 53f91bbff3f9..625ab9017834 100644 --- a/post_installation_configuration/cluster-tasks.adoc +++ b/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` diff --git a/security/container_security/security-hosts-vms.adoc b/security/container_security/security-hosts-vms.adoc index 7085d7f10a43..f44fc61ffadc 100644 --- a/security/container_security/security-hosts-vms.adoc +++ b/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] diff --git a/support/remote_health_monitoring/about-remote-health-monitoring.adoc b/support/remote_health_monitoring/about-remote-health-monitoring.adoc index 726e3edb5f11..c8432fc18b9a 100644 --- a/support/remote_health_monitoring/about-remote-health-monitoring.adoc +++ b/support/remote_health_monitoring/about-remote-health-monitoring.adoc @@ -16,7 +16,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 @@ -41,7 +41,7 @@ include::modules/telemetry-about-telemetry.adoc[leveloffset=+1] ifndef::openshift-dedicated[] .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. endif::[] include::modules/telemetry-what-information-is-collected.adoc[leveloffset=+2] @@ -95,11 +95,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 diff --git a/updating/installing-update-service.adoc b/updating/installing-update-service.adoc index a3ea303f52e6..82fc6655ff33 100644 --- a/updating/installing-update-service.adoc +++ b/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 diff --git a/updating/understanding-upgrade-channels-release.adoc b/updating/understanding-upgrade-channels-release.adoc new file mode 100644 index 000000000000..10b597c5979e --- /dev/null +++ b/updating/understanding-upgrade-channels-release.adoc @@ -0,0 +1,32 @@ +[id="understanding-upgrade-channels-releases"] += Understanding upgrade channels and releases +include::module/common-attributes.adoc[] +:context: understanding-upgrade-channels-release + +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.9 upgrade channels recommend upgrades to 4.9 and upgrades within 4.9. They also recommend upgrades within 4.8 and from 4.8 to 4.9, to allow clusters on 4.8 to eventually upgrade to 4.9. They do not recommend upgrades to 4.10 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.y` (only when running an even-numbered 4.y cluster release, like 4.10) + +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[] + +include::modules/understanding-upgrade-channels.adoc[leveloffset=+1] diff --git a/updating/update-using-custom-machine-config-pools.adoc b/updating/update-using-custom-machine-config-pools.adoc index 186f5f59ef76..ea80aae7a796 100644 --- a/updating/update-using-custom-machine-config-pools.adoc +++ b/updating/update-using-custom-machine-config-pools.adoc @@ -1,5 +1,5 @@ [id="update-using-custom-machine-config-pools"] -= Performing a canary rollout update += Performing a canary rollout update include::modules/common-attributes.adoc[] :context: update-using-custom-machine-config-pools @@ -7,7 +7,7 @@ toc::[] -There might be some scenarios where you want a more controlled rollout of an update to the worker nodes in order to ensure that mission-critical applications stay available during the whole update, even if the update process causes your applications to fail. Depending on your organizational needs, you might want to update a small subset of worker nodes, evaluate cluster and workload health over a period of time, then update the remaining nodes. This is commonly referred to as a _canary_ update. Or, you might also want to fit worker node updates, which often require a host reboot, into smaller defined maintenance windows when it is not possible to take a large maintenance window to update the entire cluster at one time. +There might be some scenarios where you want a more controlled rollout of an update to the worker nodes in order to ensure that mission-critical applications stay available during the whole update, even if the update process causes your applications to fail. Depending on your organizational needs, you might want to update a small subset of worker nodes, evaluate cluster and workload health over a period of time, then update the remaining nodes. This is commonly referred to as a _canary_ update. Or, you might also want to fit worker node updates, which often require a host reboot, into smaller defined maintenance windows when it is not possible to take a large maintenance window to update the entire cluster at one time. In these scenarios, you can create multiple custom machine config pools (MCPs) to prevent certain worker nodes from updating when you update the cluster. After the rest of the cluster is updated, you can update those worker nodes in batches at appropriate times. @@ -27,7 +27,7 @@ This scenario has not been tested and might result in an undefined cluster state [IMPORTANT] ==== -Pausing a machine config pool 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 automatially 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 a machine config pool 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 automatially 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. ==== [id="update-using-custom-machine-config-pools-about-mcp_{context}"] @@ -35,7 +35,7 @@ Pausing a machine config pool prevents the Machine Config Operator from applying In {product-title}, nodes are not considered individually. Nodes are grouped into machine config pools (MCP). There are two MCPs in a default {product-title} cluster: one for the control plane nodes and one for the worker nodes. An {product-title} update affects all MCPs concurrently. -During the update, the Machine Config Operator (MCO) drains and cordons all nodes within a MCP up to the specified `maxUnavailable` number of nodes (if specified), by default `1`. Draining and cordoning a node deschedules all pods on the node and marks the node as unschedulable. After the node is drained, the Machine Config Daemon applies a new machine configuration, which can include updating the operating system (OS). Updating the OS requires the host to reboot. +During the update, the Machine Config Operator (MCO) drains and cordons all nodes within a MCP up to the specified `maxUnavailable` number of nodes (if specified), by default `1`. Draining and cordoning a node deschedules all pods on the node and marks the node as unschedulable. After the node is drained, the Machine Config Daemon applies a new machine configuration, which can include updating the operating system (OS). Updating the OS requires the host to reboot. To prevent specific nodes from being updated, and thus, not drained, cordoned, and updated, you can create custom MCPs. Then, pause those MCPs to ensure that the nodes associated with those MCPs are not updated. The MCO does not update any paused MCPs. You can create one or more custom MCPs, which can give you more control over the sequence in which you update those nodes. After you update the nodes in the first MCP, you can verify the application compatibility, and then update the rest of the nodes gradually to the new version. @@ -46,7 +46,7 @@ To ensure the stability of the control plane, creating a custom MCP from the con You should give careful consideration to the number of MCPs you create and the number of nodes in each MCP, based on your workload deployment topology. For example, If you need to fit updates into specific maintenance windows, you need to know how many nodes that {product-title} can update within a window. This number is dependent on your unique cluster and workload characteristics. -Also, you need to consider how much extra capacity you have available in your cluster. For example, in the case where your applications fail to work as expected on the updated nodes, you can cordon and drain those nodes in the pool, which moves the application pods to other nodes. You need to consider how much extra capacity you have available in order to determine the number of custom MCPs you need and how many nodes are in each MCP. For example, if you use two custom MCPs and 50% of your nodes are in each pool, you need to determine if running 50% of your nodes would provide sufficient quality-of-service (QoS) for your applications. +Also, you need to consider how much extra capacity you have available in your cluster. For example, in the case where your applications fail to work as expected on the updated nodes, you can cordon and drain those nodes in the pool, which moves the application pods to other nodes. You need to consider how much extra capacity you have available in order to determine the number of custom MCPs you need and how many nodes are in each MCP. For example, if you use two custom MCPs and 50% of your nodes are in each pool, you need to determine if running 50% of your nodes would provide sufficient quality-of-service (QoS) for your applications. You can use this update process with all documented {product-title} update processes. However, the process does not work with {op-system-base-full} machines, which are updated using Ansible playbooks. @@ -59,14 +59,11 @@ include::modules/update-using-custom-machine-config-pools-pause.adoc[leveloffset When the MCPs enter ready state, you can peform the cluster update. See one of the following update methods, as appropriate for your cluster: -* xref:../updating/updating-cluster-between-minor.adoc#update-upgrading-web_updating-cluster-between-minor[Updating a cluster between minor versions] -* xref:../updating/updating-cluster.adoc#update-upgrading-web_updating-cluster[Updating a cluster within a minor version from the web console] -* xref:../updating/updating-cluster-cli.adoc#update-upgrading-cli_updating-cluster-cli[Updating a cluster within a minor version by using the CLI] +* xref:../updating/updating-cluster-within-minor.adoc#update-upgrading-web_updating-cluster-within-minor[Updating a cluster within a minor version using the web console] +* xref:../updating/updating-cluster-cli.adoc#update-upgrading-cli_updating-cluster-cli[Updating a cluster within a minor version using the CLI] After the update is complete, you can start to unpause the MCPs one-by-one. include::modules/update-using-custom-machine-config-pools-unpause.adoc[leveloffset=+1] include::modules/update-using-custom-machine-config-pools-mcp-remove.adoc[leveloffset=+1] - - diff --git a/updating/updating-cluster-cli.adoc b/updating/updating-cluster-cli.adoc index 675d77c19b27..7c373bc55162 100644 --- a/updating/updating-cluster-cli.adoc +++ b/updating/updating-cluster-cli.adoc @@ -1,11 +1,11 @@ [id="updating-cluster-cli"] -= Updating a cluster within a minor version by using the CLI += Updating a cluster within a minor version using the CLI include::modules/common-attributes.adoc[] :context: updating-cluster-cli toc::[] -You can update, or upgrade, an {product-title} cluster within a minor version by using the OpenShift CLI (`oc`). +You can update, or upgrade, an {product-title} cluster within a minor version using the OpenShift CLI (`oc`). == Prerequisites @@ -29,12 +29,13 @@ Using the `unsupportedConfigOverrides` section to modify the configuration of an 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] .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/update-using-custom-machine-config-pools-canary.adoc[leveloffset=+1] + +If you want to use the canary rollout update process, see xref:../updating/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools[Performing a canary rollout update]. include::modules/machine-health-checks-pausing.adoc[leveloffset=+1] diff --git a/updating/updating-cluster-rhel-compute.adoc b/updating/updating-cluster-rhel-compute.adoc index 3868f39c5c14..554e7fb29ef7 100644 --- a/updating/updating-cluster-rhel-compute.adoc +++ b/updating/updating-cluster-rhel-compute.adoc @@ -22,13 +22,10 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis 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] .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/update-upgrading-web.adoc[leveloffset=+1] [id="updating-cluster-rhel-compute-hooks"] diff --git a/updating/updating-cluster-between-minor.adoc b/updating/updating-cluster-within-minor.adoc similarity index 93% rename from updating/updating-cluster-between-minor.adoc rename to updating/updating-cluster-within-minor.adoc index 3deb9f592c5e..5e5c69b924cd 100644 --- a/updating/updating-cluster-between-minor.adoc +++ b/updating/updating-cluster-within-minor.adoc @@ -1,11 +1,11 @@ -[id="updating-cluster-between-minor"] -= Updating a cluster between minor versions +[id="updating-cluster-within-minor"] += Updating a cluster within a minor version using the web console include::modules/common-attributes.adoc[] -:context: updating-cluster-between-minor +:context: updating-cluster-within-minor toc::[] -You can update, or upgrade, an {product-title} cluster between minor versions. +You can update, or upgrade, an {product-title} cluster within a minor version using the web console. [NOTE] ==== @@ -40,13 +40,10 @@ Using the `unsupportedConfigOverrides` section to modify the configuration of an 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] .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/update-using-custom-machine-config-pools-canary.adoc[leveloffset=+1] If you want to use the canary rollout update process, see xref:../updating/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools[Performing a canary rollout update]. diff --git a/welcome/index.adoc b/welcome/index.adoc index 5db84118c212..6d2c45152989 100644 --- a/welcome/index.adoc +++ b/welcome/index.adoc @@ -268,7 +268,7 @@ endif::[] - **xref:../scalability_and_performance/scaling-cluster-monitoring-operator.adoc#scaling-cluster-monitoring-operator[Scale] and xref:../scalability_and_performance/using-node-tuning-operator.adoc#using-node-tuning-operator[tune] clusters**: Set cluster limits, tune nodes, scale cluster monitoring, and optimize networking, storage, and routes for your environment. - **Update a cluster**: -Use the Cluster Version Operator (CVO) to upgrade your {product-title} cluster. If an update is available from the OpenShift Update Service (OSUS), you apply that cluster update from either the {product-title} xref:../updating/updating-cluster.adoc#updating-cluster[web console] or the xref:../updating/updating-cluster-cli.adoc#updating-cluster-cli[OpenShift CLI] (`oc`). +Use the Cluster Version Operator (CVO) to upgrade your {product-title} cluster. If an update is available from the OpenShift Update Service (OSUS), you apply that cluster update from either the {product-title} xref:../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[web console] or the xref:../updating/updating-cluster-cli.adoc#updating-cluster-cli[OpenShift CLI] (`oc`). //// There is a separate process for diff --git a/welcome/learn_more_about_openshift.adoc b/welcome/learn_more_about_openshift.adoc index b959b4ca0c74..4f8e3e6bb7a4 100644 --- a/welcome/learn_more_about_openshift.adoc +++ b/welcome/learn_more_about_openshift.adoc @@ -68,7 +68,7 @@ Use the following sections to find content to help you learn about and use {prod | | -| xref:../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating a cluster] +| xref:../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[Updating a cluster] | | diff --git a/whats_new/new-features.adoc b/whats_new/new-features.adoc index aeb4b40c1e89..ac834a5140a1 100644 --- a/whats_new/new-features.adoc +++ b/whats_new/new-features.adoc @@ -59,7 +59,7 @@ Easy, over-the-air upgrades for asynchronous z-stream releases of OpenShift v4 is available. Cluster administrators can upgrade using the *Cluster Settings* tab in the web console. See -xref:../updating/updating-cluster.adoc#updating-cluster[Updating a cluster] +xref:../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[Updating a cluster] for more information. [id="ocp-operator-hub"]