diff --git a/_topic_map.yml b/_topic_map.yml index 9aab76d9a6c0..11e0ab807d99 100644 --- a/_topic_map.yml +++ b/_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-releases # TODO: Remove below assembly for 4.10: - Name: Preparing to update to OpenShift Container Platform 4.10 File: updating-cluster-prepare @@ -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 diff --git a/contributing_to_docs/doc_guidelines.adoc b/contributing_to_docs/doc_guidelines.adoc index c0f50338ac7d..04cbe702acec 100644 --- a/contributing_to_docs/doc_guidelines.adoc +++ b/contributing_to_docs/doc_guidelines.adoc @@ -942,20 +942,6 @@ spec: + Do not use `[...]`, ``, 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. diff --git a/modules/understanding-upgrade-channels.adoc b/modules/understanding-upgrade-channels.adoc index bd36e7ded14e..1bda0a9cc251 100644 --- a/modules/understanding-upgrade-channels.adoc +++ b/modules/understanding-upgrade-channels.adoc @@ -14,26 +14,8 @@ In {product-title} 4.1, Red Hat introduced the concept of channels for recommend 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. @@ -51,8 +33,8 @@ 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. @@ -60,23 +42,23 @@ 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 + += 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. @@ -87,8 +69,8 @@ Additionally, you may only switch to the EUS channel when your cluster is runnin 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. @@ -117,22 +99,21 @@ 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 + += 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: diff --git a/updating/installing-update-service.adoc b/updating/installing-update-service.adoc index a3ea303f52e6..00880f8ef82a 100644 --- a/updating/installing-update-service.adoc +++ b/updating/installing-update-service.adoc @@ -16,7 +16,7 @@ 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] +// include::modules/update-service-overview.adoc[leveloffset=+1] [id="update-service-prereqs"] == Prerequisites diff --git a/updating/understanding-upgrade-channels-releases.adoc b/updating/understanding-upgrade-channels-releases.adoc new file mode 100644 index 000000000000..3756fc12590c --- /dev/null +++ b/updating/understanding-upgrade-channels-releases.adoc @@ -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] diff --git a/updating/updating-cluster-between-minor.adoc b/updating/updating-cluster-between-minor.adoc index 1a1111018978..328b6d55c603 100644 --- a/updating/updating-cluster-between-minor.adoc +++ b/updating/updating-cluster-between-minor.adoc @@ -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 @@ -43,12 +43,12 @@ 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] +// 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] diff --git a/updating/updating-cluster-cli.adoc b/updating/updating-cluster-cli.adoc index 72e05be3d394..175acdde3511 100644 --- a/updating/updating-cluster-cli.adoc +++ b/updating/updating-cluster-cli.adoc @@ -29,15 +29,17 @@ 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] +// 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/machine-health-checks-pausing.adoc[leveloffset=+1] include::modules/update-upgrading-cli.adoc[leveloffset=+1] include::modules/update-changing-update-server-cli.adoc[leveloffset=+1] + +include::modules/update-using-custom-machine-config-pools-canary.adoc[leveloffset=+1] diff --git a/updating/updating-cluster-rhel-compute.adoc b/updating/updating-cluster-rhel-compute.adoc index f434e2dc384a..d753227fdae6 100644 --- a/updating/updating-cluster-rhel-compute.adoc +++ b/updating/updating-cluster-rhel-compute.adoc @@ -22,12 +22,12 @@ 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] +// 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-upgrading-web.adoc[leveloffset=+1] diff --git a/updating/updating-cluster.adoc b/updating/updating-cluster.adoc index 9d78214ab3b6..7585f9fdbab2 100644 --- a/updating/updating-cluster.adoc +++ b/updating/updating-cluster.adoc @@ -5,31 +5,57 @@ include::modules/common-attributes.adoc[] toc::[] -You can update, or upgrade, an {product-title} cluster by using the web console. +You can update, or upgrade, an {product-title} cluster between minor versions. + +[NOTE] +==== +Use the web console or `oc adm upgrade channel __` to change the update channel. You can follow the steps in xref:../updating/updating-cluster-cli.adoc#updating-cluster-cli[Updating a cluster within a minor version by using the CLI] to complete the update after you change to a {product-version} channel. +==== == Prerequisites * Have access to the cluster as a user with `admin` privileges. See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. * Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. ++ +{product-title} 4.9 requires an upgrade from etcd version 3.4 to 3.5. If the etcd Operator halts the upgrade, an alert is triggered. To clear this alert, ensure that you have a current etcd backup and restart the upgrade using the `--force` flag. ++ +[source,terminal] +---- +$ oc adm upgrade --force +---- + +* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information. * Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. * If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. * If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being upgraded to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[_Upgrading an OpenShift Container Platform cluster configured for manual mode with STS_]. -* Ensure that you address all `Upgradeable=False` conditions so the cluster allows an upgrade to the next minor version. An alert displays at the top of the *Cluster Settings* page when you have one or more cluster Operators that cannot be upgraded. You can still upgrade to the next available patch update for the minor release you are currently on. +* Review the list of APIs that were removed in Kubernetes 1.22, migrate any affected components to use the new API version, and provide the administrator acknowledgment. For more information, see xref:../updating/updating-cluster-prepare.adoc#updating-cluster-prepare[Preparing to update to {product-title} 4.9]. ++ +// TODO: Currently, this ^ admin ack is only applicable for 4.9 and should be removed for 4.10+ +[IMPORTANT] +==== +Using the `unsupportedConfigOverrides` section to modify the configuration of an Operator is unsupported and might block cluster upgrades. You must remove this setting before you can upgrade your cluster. +==== [IMPORTANT] ==== 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-changing-update-server-web.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] include::modules/update-upgrading-web.adoc[leveloffset=+1] + +include::modules/update-changing-update-server-web.adoc[leveloffset=+1]