// 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.

.Procedure

. View the available updates and note the version number of the update that
you want to apply:
+
[source,terminal]
----
$ oc adm upgrade
----
+
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
----
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

Recommended updates:

  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
----
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.
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 <1>
----

** 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` command.
+
[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:
+
[source,terminal]
----
$ oc adm upgrade
----
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.32.3
ip-10-0-170-223.ec2.internal   Ready    master   82m   v1.32.3
ip-10-0-179-95.ec2.internal    Ready    worker   70m   v1.32.3
ip-10-0-182-134.ec2.internal   Ready    worker   70m   v1.32.3
ip-10-0-211-16.ec2.internal    Ready    master   82m   v1.32.3
ip-10-0-250-100.ec2.internal   Ready    worker   69m   v1.32.3
----

