openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity
Files
e877abf380497ab9fd71e34819e34dac1cd2e849
openshift-docs/modules/update-upgrading-cli.adoc

215 lines
7.5 KiB
Plaintext
Raw Blame History

// Module included in the following assemblies:
//
// * updating/updating_a_cluster/updating-cluster-cli.adoc
// * updating/updating_a_cluster/updating-cluster-rhel-compute.adoc
:_mod-docs-content-type: PROCEDURE
[id="update-upgrading-cli_{context}"]
= Updating a cluster by using the CLI
You can use the OpenShift CLI (`oc`) to review and request cluster updates.
You can find information about available {product-title} advisories and updates
link:https://access.redhat.com/downloads/content/290[in the errata section]
of the Customer Portal.
.Prerequisites
* 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
. View the available updates and note the version number of the update that
you want to apply:
+
[source,terminal]
----
$ oc adm upgrade recommend
----
+
ifndef::openshift-origin[]
.Example output
[source,terminal]
----
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]
----
...
Upstream update service: https://amd64.origin.releases.ci.openshift.org/graph
Channel: stable-scos-4
Updates to 4.20:
VERSION ISSUES
4.20.0-okd-scos.ec.14 no known issues relevant to this cluster
Updates to 4.19:
VERSION ISSUES
4.19.0-okd-scos.17 no known issues relevant to this cluster
----
endif::openshift-origin[]
+
[NOTE]
====
* 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[]
====
ifndef::openshift-origin[]
. Based on your organization requirements, set the appropriate update channel. For example, you can set your channel to `stable-4.13` or `fast-4.13`. For more information about channels, refer to _Understanding update channels and releases_ listed in the Additional resources section.
// In OKD, no need to set the channel.
//this example will need to be updated per eus release to reflect options available
+
[source,terminal]
----
$ oc adm upgrade channel <channel>
----
+
For example, to set the channel to `stable-{product-version}`:
+
[source,terminal,subs="attributes+"]
----
$ oc adm upgrade channel stable-{product-version}
----
+
[IMPORTANT]
====
For production clusters, you must subscribe to a `stable-\*`, `eus-*`, or `fast-*` channel.
====
+
[NOTE]
====
When you are ready to move to the next minor version, choose the channel that corresponds to that minor version.
The sooner the update channel is declared, the more effectively the cluster can recommend update paths to your target version.
The cluster might take some time to evaluate all the possible updates that are available and offer the best update recommendations to choose from.
Update recommendations can change over time, as they are based on what update options are available at the time.
If you cannot see an update path to your target minor version, keep updating your cluster to the latest patch release for your current version until the next minor version is available in the path.
====
endif::openshift-origin[]
. Apply an update:
** To update to the latest version:
+
[source,terminal]
----
$ oc adm upgrade --to-latest=true
----
** To update to a specific version:
+
[source,terminal]
----
$ oc adm upgrade --to=<version> <1>
----
<1> `<version>` is the update version that you obtained from the output of the
`oc adm upgrade recommend` command.
+
[IMPORTANT]
====
When using `oc adm upgrade --help`, there is a listed option for `--force`. This is _heavily discouraged_, because using the `--force` option bypasses cluster-side guards, including release verification and precondition checks. Using `--force` does not guarantee a successful update. Bypassing guards puts the cluster at risk.
====
+
. 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>
----
. Optional: Review the status of the Cluster Version Operator by running the following command:
+
[source,terminal]
----
$ 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]
.Example output
----
info: An upgrade is in progress. Working towards 4.14.0-0.okd-2024-01-06-084517: 117 of 864 done (13% complete), waiting on etcd, kube-apiserver
Upstream: https://amd64.origin.releases.ci.openshift.org/graph
Channel: stable-4
No updates available. You may still upgrade to a specific release image with --to-image or wait for new updates to be available.
----
endif::openshift-origin[]
. After the update completes, you can confirm that the cluster version has
updated to the new version:
+
[source,terminal]
----
$ oc adm upgrade
----
ifndef::openshift-origin[]
+
.Example output
[source,terminal]
----
Cluster version is <version>
Upstream is unset, so the cluster will use an appropriate default.
Channel: stable-<version> (available channels: candidate-<version>, eus-<version>, fast-<version>, stable-<version>)
No updates available. You may force an update to a specific release image, but doing so might not be supported and might result in downtime or data loss.
----
endif::openshift-origin[]
ifdef::openshift-origin[]
+
[source,terminal]
.Example output
----
Cluster version is 4.14.0-0.okd-2024-01-06-084517
Upstream: https://amd64.origin.releases.ci.openshift.org/graph
Channel: stable-4
No updates available. You may still upgrade to a specific release image with --to-image or wait for new updates to be available.
----
endif::openshift-origin[]
+
. If you are updating your cluster to the next minor version, such as version X.y to X.(y+1), it is recommended to confirm that your nodes are updated before deploying workloads that rely on a new feature:
+
[source,terminal]
----
$ oc get nodes
----
+
.Example output
[source,terminal]
----
NAME STATUS ROLES AGE VERSION
ip-10-0-168-251.ec2.internal Ready master 82m v1.33.4
ip-10-0-170-223.ec2.internal Ready master 82m v1.33.4
ip-10-0-179-95.ec2.internal Ready worker 70m v1.33.4
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 Git Blame Copy Permalink