1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00

OSDOCS-15792 Adding oc adm upgrade recommend to updating with cli

This commit is contained in:
cbippley
2025-09-05 12:02:53 -04:00
parent 1443e730fc
commit ee7250d6f6
9 changed files with 112 additions and 227 deletions

View File

@@ -1,27 +0,0 @@
// Module included in the following assemblies:
//
// * updating/updating_a_cluster/updating-cluster-cli.adoc
:_mod-docs-content-type: PROCEDURE
[id="update-conditional-upgrade-path_{context}"]
= Updating along a conditional update path
You can update along a recommended conditional update path using the web console or the OpenShift CLI (`oc`).
When a conditional update is not recommended for your cluster, you can update along a conditional update path using the OpenShift CLI (`oc`) 4.10 or later.
.Procedure
. To view the description of the update when it is not recommended because a risk might apply, run the following command:
+
[source,terminal]
----
$ oc adm upgrade --include-not-recommended
----
. If the cluster administrator evaluates the potential known risks and decides it is acceptable for the current cluster, then the administrator can waive the safety guards and proceed the update by running the following command:
+
[source,terminal]
----
$ oc adm upgrade --allow-not-recommended --to <version> <.>
----
<.> `<version>` is the update version that you obtained from the output of the previous command, which is supported but also has known issues or risks.

View File

@@ -0,0 +1,67 @@
// Module included in the following assemblies:
//
// * updating/updating_a_cluster/updating-cluster-cli.adoc
:_mod-docs-content-type: CONCEPT
[id="update-upgrading-oc-adm-upgrade-status_{context}"]
= Cluster update status using oc adm upgrade status
When updating your cluster, the `oc adm upgrade` command returns limited information about the status of your update. The cluster administrator can use the `oc adm upgrade status` command to decouple status information from the `oc adm upgrade` command and return specific information regarding a cluster update, including the status of the control plane and worker node updates. Worker is also known as compute.
The `oc adm upgrade status` command is read-only and does not alter any state in your cluster.
The `oc adm upgrade status` command can be used for clusters from version 4.12 up to the latest supported release.
The `oc adm upgrade status` command will output three sections, control plane update, worker nodes update, and health insights.
* *Control Plane Update*: Displays details about the updating cluster control plane, contains a high-level assessment, completion status, duration estimate, or cluster operator health. The section also shows a table with control plane node update information.
+
The control plane update section can also show an additional table that lists cluster operators being updated if the `--details=operators` or `--details-all` flags are used. Please note that due the asynchronous distributed nature of {product-title}, an operator may appear in this section more than once during the update, or not at all. The section is only shown when a Cluster Operator is observed to be updating. It is normal during an update to observe no updating Cluster Operator at certain periods; not every performed action can be assigned to an observable updating Cluster Operator.
+
* *Worker Notes Update*: Displays the worker node update information. The worker nodes section starts with a table that displays a summary of information about each worker pool configured in the cluster. Each non-empty worker pool output will show a dedicated table listing update information about nodes that belong to that pool. If a cluster does not have any worker nodes the output will not contain the worker node section. You can make the node tables show all lines by using `--details=nodes` or `--details=all`.
+
* *Health Insights*: displays insights about states and events present in the cluster that may be relevant for the ongoing update. You can use `--details=health` to expand the items in this section into a more verbose form with more content such as documentation links, longer form descriptions, or cluster resources involved in the insight.
[NOTE]
====
The `oc adm upgrade status` command is currently not supported on {hcp} clusters.
====
The following is an example of the output you will see for an update progressing successfully:
[source,terminal]
----
= Control Plane =
Assessment: Progressing
Target Version: 4.17.1 (from 4.17.0)
Updating: machine-config
Completion: 97% (32 operators updated, 1 updating, 0 waiting)
Duration: 54m (Est. Time Remaining: <10m)
Operator Status: 32 Healthy, 1 Unavailable
Control Plane Nodes
NAME ASSESSMENT PHASE VERSION EST MESSAGE
ip-10-0-53-40.us-east-2.compute.internal Progressing Draining 4.17.0 +10m
ip-10-0-30-217.us-east-2.compute.internal Outdated Pending 4.17.0 ?
ip-10-0-92-180.us-east-2.compute.internal Outdated Pending 4.17.0 ?
= Worker Upgrade =
WORKER POOL ASSESSMENT COMPLETION STATUS
worker Progressing 0% (0/2) 1 Available, 1 Progressing, 1 Draining
infra Progressing 50% (1/2) 1 Available, 1 Progressing, 1 Draining
Worker Pool Nodes: Worker
NAME ASSESSMENT PHASE VERSION EST MESSAGE
ip-10-0-4-159.us-east-2.compute.internal Progressing Draining 4.17.0 +10m
ip-10-0-99-40.us-east-2.compute.internal Outdated Pending 4.17.0 ?
Worker Pool Nodes: infra
NAME ASSESSMENT PHASE VERSION EST MESSAGE
ip-10-0-4-159-infra.us-east-2.compute.internal Progressing Draining 4.17.0 +10m
ip-10-0-20-162.us-east-2.compute.internal Completed Updated 4.17.1 -
= Update Health =
SINCE LEVEL IMPACT MESSAGE
54m4s Info None Update is proceeding well
----

View File

@@ -17,8 +17,8 @@ of the Customer Portal.
* Install the OpenShift CLI (`oc`) that matches the version for your updated version.
* Log in to the cluster as user with `cluster-admin` privileges.
* Pause all `MachineHealthCheck` resources.
// Example output Failing=true taken from https://github.com/openshift/oc/blob/main/pkg/cli/admin/upgrade/recommend/examples/4.16.27-degraded-monitoring.output
.Procedure
@@ -27,47 +27,50 @@ you want to apply:
+
[source,terminal]
----
$ oc adm upgrade
$ oc adm upgrade recommend
----
+
ifndef::openshift-origin[]
.Example output
[source,terminal]
----
Cluster version is 4.13.10
Upstream is unset, so the cluster will use an appropriate default.
Channel: stable-4.13 (available channels: candidate-4.13, candidate-4.14, fast-4.13, stable-4.13)
Recommended updates:
VERSION IMAGE
4.13.14 quay.io/openshift-release-dev/ocp-release@sha256:406fcc160c097f61080412afcfa7fd65284ac8741ac7ad5b480e304aba73674b
4.13.13 quay.io/openshift-release-dev/ocp-release@sha256:d62495768e335c79a215ba56771ff5ae97e3cbb2bf49ed8fb3f6cefabcdc0f17
4.13.12 quay.io/openshift-release-dev/ocp-release@sha256:73946971c03b43a0dc6f7b0946b26a177c2f3c9d37105441315b4e3359373a55
4.13.11 quay.io/openshift-release-dev/ocp-release@sha256:e1c2377fdae1d063aaddc753b99acf25972b6997ab9a0b7e80cfef627b9ef3dd
Failing=True:
Reason: ClusterOperatorNotAvailable
Message: Cluster operator monitoring is not available
...
Upstream update service: https://api.integration.openshift.com/api/upgrades_info/graph
Channel: candidate-4.16 (available channels: candidate-4.16, candidate-4.17, candidate-4.18, eus-4.16, fast-4.16, fast-4.17, stable-4.16, stable-4.17)
Updates to 4.16:
VERSION ISSUES
4.16.32 no known issues relevant to this cluster
4.16.30 no known issues relevant to this cluster
And 2 older 4.16 updates you can see with '--show-outdated-releases' or '--version VERSION'.
----
endif::openshift-origin[]
ifdef::openshift-origin[]
.Example output
[source,terminal]
----
Cluster version is 4.13.0-0.okd-2023-10-28-065448
...
Upstream: https://amd64.origin.releases.ci.openshift.org/graph
Channel: stable-4
Upstream update service: https://amd64.origin.releases.ci.openshift.org/graph
Channel: stable-scos-4
Recommended updates:
Updates to 4.20:
VERSION ISSUES
4.20.0-okd-scos.ec.14 no known issues relevant to this cluster
VERSION IMAGE
4.14.0-0.okd-2024-01-06-084517 registry.ci.openshift.org/origin/release@sha256:c4a6b6850701202f629c0e451de784b02f0de079650a1b9ccbf610448ebc9227
4.14.0-0.okd-2023-11-14-101924 registry.ci.openshift.org/origin/release@sha256:72d40c51e7c4d1b9c31e9b0d276d045f1b2b93def5ecee49186df856d40bcb5c
4.14.0-0.okd-2023-11-12-042703 registry.ci.openshift.org/origin/release@sha256:2242d1df4e4cbcc0cd27191ab9ad5f55ac4f0c60c3cda2a186181a2435e3bd00
4.14.0-0.okd-2023-10-28-073550 registry.ci.openshift.org/origin/release@sha256:7a6200e347a1b857e47f2ab0735eb1303af7d796a847d79ef9706f217cd12f5c
Updates to 4.19:
VERSION ISSUES
4.19.0-okd-scos.17 no known issues relevant to this cluster
----
endif::openshift-origin[]
+
[NOTE]
====
* If there are no recommended updates, updates that have known issues might still be available.
See _Updating along a conditional update path_ for more information.
* You can use the `--version` flag to determine whether a specific version is recommended for your update. If there are no recommended updates, updates that have known issues might still be available.
ifndef::openshift-origin[]
* For details and information on how to perform a `Control Plane Only` update, please refer to the _Preparing to perform a Control Plane Only update_ page, listed in the Additional resources section.
endif::openshift-origin[]
@@ -120,19 +123,32 @@ $ oc adm upgrade --to-latest=true <1>
$ oc adm upgrade --to=<version> <1>
----
<1> `<version>` is the update version that you obtained from the output of the
`oc adm upgrade` command.
`oc adm upgrade recommend` command.
+
.. If the cluster administrator evaluates the potential known risks and decides it is acceptable for the current cluster, then the administrator can waive the safety guards and proceed with the update by running the following command:
+
[source,terminal]
----
$ oc adm upgrade --allow-not-recommended --to <version>
----
+
[IMPORTANT]
====
When using `oc adm upgrade --help`, there is a listed option for `--force`. This is *heavily discouraged*, as using the `--force` option bypasses cluster-side guards, including release verification and precondition checks. Using `--force` does not guarantee a successful update. Bypassing guards put the cluster at risk.
====
. Review the status of the Cluster Version Operator:
. Optional: Review the status of the Cluster Version Operator by running the following command:
+
[source,terminal]
----
$ oc adm upgrade
$ oc adm upgrade status
----
+
[NOTE]
====
To monitor the update in real time, run `oc adm upgrade status` in a `watch` utility.
====
ifdef::openshift-origin[]
+
[source,terminal]
@@ -197,4 +213,3 @@ ip-10-0-182-134.ec2.internal Ready worker 70m v1.33.4
ip-10-0-211-16.ec2.internal Ready master 82m v1.33.4
ip-10-0-250-100.ec2.internal Ready worker 69m v1.33.4
----

View File

@@ -1,85 +0,0 @@
// Module included in the following assemblies:
//
// * updating/updating_a_cluster/updating-cluster-cli.adoc
:_mod-docs-content-type: PROCEDURE
[id="update-upgrading-oc-adm-upgrade-recommend_{context}"]
= Finding recommended update paths with oc adm upgrade recommend (Technology Preview)
When updating your cluster, the `oc adm upgrade` command returns a list of the next available versions. You can use the `oc adm upgrade recommend` command to narrow down your suggestions and recommend a new target release before you launch your update.
The `oc adm upgrade recommend` command is read-only and cannot alter the state of your cluster.
:FeatureName: The `oc adm upgrade recommend` command
include::snippets/technology-preview.adoc[]
[NOTE]
====
Your cluster does not need to be a Technology Preview-enabled cluster in order for you to use the `oc adm upgrade recommend` command.
====
.Procedure
. Set the `OC_ENABLE_CMD_UPGRADE_RECOMMEND` environment variable to `true` by running the following command:
+
[source,terminal]
----
$ export OC_ENABLE_CMD_UPGRADE_RECOMMEND=true
----
. Run one of the following commands:
** To list the recommended versions for your update, run the `oc adm upgrade recommend` command:
+
[source,terminal]
----
$ oc adm upgrade recommend
----
+
.Example output
[source,terminal]
----
Upstream is unset, so the cluster will use an appropriate default.
Channel: stable-4.13 (available channels: candidate-4.12, candidate-4.13, eus-4.12, eus-4.14, fast-4.12, fast-4.13, stable-4.12, stable-4.13)
Updates to 4.13:
Version: 4.13.50
Image: quay.io/openshift-release-dev/ocp-release@sha256:6afb11e1cac46fd26476ca134072937115256b9c6360f7a1cd1812992c065f02
Reason: AdminAckRequired
Message: Kubernetes 1.26 and therefore OpenShift 4.13 remove several APIs which require admin consideration. Please see the knowledge article https://access.redhat.com/articles/6958394 for details and instructions.
Version: 4.13.49
Image: quay.io/openshift-release-dev/ocp-release@sha256:ab6f574665395d809511db9dc57764358278538eaae248c6d199208b3c30ab7d
Reason: AdminAckRequired
Message: Kubernetes 1.26 and therefore OpenShift 4.13 remove several APIs which require admin consideration. Please see the knowledge article https://access.redhat.com/articles/6958394 for details and instructions.
Updates to 4.12:
VERSION ISSUES
4.12.64 no known issues
4.12.63 no known issues
And 43 older 4.12 updates you can see with '--show-outdated-releases' or '--version VERSION'.
----
** To determine whether a specific version is recommended for your update, run the `oc adm upgrade recommend --version` command:
+
[source,terminal]
----
$ oc adm upgrade recommend --version 4.12.51
----
+
.Example output
[source,terminal]
----
Upstream is unset, so the cluster will use an appropriate default.
Channel: stable-4.13 (available channels: candidate-4.12, candidate-4.13, eus-4.12, eus-4.14, fast-4.12, fast-4.13, stable-4.12, stable-4.13)
Update to 4.12.51 Recommended=False:
Image: quay.io/openshift-release-dev/ocp-release@sha256:158ced797e49f6caf7862acccef58484be63b642fdd2f66e6416295fa7958ab0
Release URL: https://access.redhat.com/errata/RHSA-2024:1052
Reason: MultipleReasons
Message: An unintended reversion to the default kubelet nodeStatusReportFrequency can cause significant load on the control plane. https://issues.redhat.com/browse/MCO-1094
After rebooting into kernel-4.18.0-372.88.1.el8_6 or later, kernel nodes experience high load average and io_wait times. The nodes might fail to start or stop pods and probes may fail. Workload and host processes may become unresponsive and workload may be disrupted. https://issues.redhat.com/browse/COS-2705
----

View File

@@ -1,75 +0,0 @@
// Module included in the following assemblies:
//
// * updating/updating_a_cluster/updating-cluster-cli.adoc
:_mod-docs-content-type: PROCEDURE
[id="update-upgrading-oc-adm-upgrade-status_{context}"]
= Gathering cluster update status using oc adm upgrade status (Technology Preview)
When updating your cluster, the `oc adm upgrade` command returns returns limited information about the status of your update. You can use the `oc adm upgrade status` command to decouple status information from the `oc adm upgrade` command and return specific information regarding a cluster update, including the status of the control plane and worker node updates.
The `oc adm upgrade status` command is read-only and does not alter any state in your cluster.
:FeatureName: The `oc adm upgrade status` command
include::snippets/technology-preview.adoc[]
The `oc adm upgrade status` command can be used for clusters from version 4.12 up to the latest supported release.
[NOTE]
====
Your cluster does not need to be a Technology Preview-enabled cluster in order for you to use the `oc adm upgrade status` command.
====
.Procedure
. Set the `OC_ENABLE_CMD_UPGRADE_STATUS` environment variable to `true` by running the following command:
+
[source,terminal]
----
$ export OC_ENABLE_CMD_UPGRADE_STATUS=true
----
. Run the `oc adm upgrade status` command:
+
[source,terminal]
----
$ oc adm upgrade status
----
+
.Example output for an update progressing successfully
[source,terminal]
----
= Control Plane =
Assessment: Progressing
Target Version: 4.17.1 (from 4.17.0)
Updating: machine-config
Completion: 97% (32 operators updated, 1 updating, 0 waiting)
Duration: 54m (Est. Time Remaining: <10m)
Operator Status: 32 Healthy, 1 Unavailable
Control Plane Nodes
NAME ASSESSMENT PHASE VERSION EST MESSAGE
ip-10-0-53-40.us-east-2.compute.internal Progressing Draining 4.17.0 +10m
ip-10-0-30-217.us-east-2.compute.internal Outdated Pending 4.17.0 ?
ip-10-0-92-180.us-east-2.compute.internal Outdated Pending 4.17.0 ?
= Worker Upgrade =
WORKER POOL ASSESSMENT COMPLETION STATUS
worker Progressing 0% (0/2) 1 Available, 1 Progressing, 1 Draining
infra Progressing 50% (1/2) 1 Available, 1 Progressing, 1 Draining
Worker Pool Nodes: Worker
NAME ASSESSMENT PHASE VERSION EST MESSAGE
ip-10-0-4-159.us-east-2.compute.internal Progressing Draining 4.17.0 +10m
ip-10-0-99-40.us-east-2.compute.internal Outdated Pending 4.17.0 ?
Worker Pool Nodes: infra
NAME ASSESSMENT PHASE VERSION EST MESSAGE
ip-10-0-4-159-infra.us-east-2.compute.internal Progressing Draining 4.17.0 +10m
ip-10-0-20-162.us-east-2.compute.internal Completed Updated 4.17.1 -
= Update Health =
SINCE LEVEL IMPACT MESSAGE
54m4s Info None Update is proceeding well
----

View File

@@ -17,8 +17,6 @@ include::modules/gathering-log-data.adoc[leveloffset=+1]
include::modules/changing-cvo-log-level.adoc[leveloffset=+1]
include::modules/update-upgrading-oc-adm-upgrade-status.adoc[leveloffset=+1]
include::modules/gathering-clusterversion-history.adoc[leveloffset=+1]
include::modules/gathering-clusterversion-history-console.adoc[leveloffset=+2]

View File

@@ -56,5 +56,5 @@ include::modules/understanding-update-channels.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../updating/updating_a_cluster/updating-cluster-cli.adoc#update-conditional-upgrade-path_updating-cluster-cli[Updating along a conditional upgrade path]
* xref:../../updating/understanding_updates/understanding-update-channels-release.adoc#fast-stable-channel-strategies_understanding-update-channels-releases[Choosing the correct channel for your cluster]

View File

@@ -36,7 +36,6 @@ include::modules/migrating-to-multi-arch-cli.adoc[leveloffset=+1]
* xref:../../updating/understanding_updates/understanding-update-channels-release.adoc#understanding-update-channels-releases[Understanding update channels and releases]
* xref:../../installing/overview/installing-preparing.adoc#installing-preparing-selecting-cluster-type[Selecting a cluster installation type]
* xref:../../machine_management/deploying-machine-health-checks.adoc#machine-health-checks-about_deploying-machine-health-checks[About machine health checks]
* xref:../../updating/updating_a_cluster/updating-cluster-cli.adoc#update-upgrading-oc-adm-upgrade-status_updating-cluster-cli[Gathering cluster update status using oc adm upgrade status (Technology Preview)]
// Migrating the x86 control plane to the arm64 architecture on AWS
include::modules/migrating-from-x86-to-arm-cp.adoc[leveloffset=+1]

View File

@@ -57,11 +57,8 @@ include::modules/updating-sno.adoc[leveloffset=+1]
// Updating a cluster by using the CLI
include::modules/update-upgrading-cli.adoc[leveloffset=+1]
//Finding recommended update paths with oc adm upgrade recommend (Technology Preview)
include::modules/update-upgrading-oc-adm-upgrade-recommend.adoc[leveloffset=+1]
//Gathering cluster update status using oc adm upgrade status (Technology Preview)
include::modules/update-upgrading-oc-adm-upgrade-status.adoc[leveloffset=+1]
// Cluster update status using oc adm upgrade status
include::modules/update-oc-adm-upgrade-status.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
@@ -69,14 +66,10 @@ include::modules/update-upgrading-oc-adm-upgrade-status.adoc[leveloffset=+1]
ifndef::openshift-origin[]
* xref:../../updating/updating_a_cluster/control-plane-only-update.adoc#control-plane-only-update[Performing a Control Plane Only update]
endif::openshift-origin[]
* xref:../../updating/updating_a_cluster/updating-cluster-cli.adoc#update-conditional-upgrade-path_updating-cluster-cli[Updating along a conditional update path]
ifndef::openshift-origin[]
* xref:../../updating/understanding_updates/understanding-update-channels-release.adoc#understanding-update-channels-releases[Understanding update channels and releases]
endif::openshift-origin[]
// Updating along a conditional update path
include::modules/update-conditional-updates.adoc[leveloffset=+1]
// OKD removed the section that this link points to.
ifndef::openshift-origin[]