
// Module included in the following assemblies:
//
// * assemblies/upgrades.adoc

:_mod-docs-content-type: CONCEPT
[id="upgrade_{context}"]
= Understanding {product-title} cluster upgrades

When upgrades are made available for your {product-title} cluster, you can upgrade to the newest version through {cluster-manager-first} or {cluster-manager} CLI. You can set your upgrade policies on existing clusters or during cluster creation, and upgrades can be scheduled to occur automatically or manually.

[IMPORTANT]
====
Before upgrading a Workload Identity Federation (WIF)-enabled {product-title} on {GCP} cluster, you must update the wif-config. For more information, see "Cluster upgrades with Workload Identity Federation (WIF)".
====

Red Hat Site Reliability Engineers (SRE) will provide a curated list of available versions for your {product-title} clusters. For each cluster you will be able to review the full list of available releases, as well as the corresponding release notes. {cluster-manager} will enable installation of clusters at the latest supported versions, and upgrades can be canceled at any time.

You can also set a grace period for how long `PodDisruptionBudget` protected workloads are respected during upgrades. After this grace period, any workloads protected by  `PodDisruptionBudget` that have not been successfully drained from a node, will be forcibly deleted.

[NOTE]
====
All Kubernetes objects and PVs in each {product-title} cluster are backed up as part of the {product-title} service. Application and application data backups are not a part of the {product-title} service. Ensure you have a backup policy in place for your applications and application data prior to scheduling upgrades.
====

[NOTE]
====
When following a scheduled upgrade policy, there might be a delay of an hour or more before the upgrade process begins, even if it is an immediate upgrade. Additionally, the duration of the upgrade might vary based on your workload configuration.
====

[id="upgrade-automatic_{context}"]
== Recurring upgrades

Upgrades can be scheduled to occur automatically on a day and time specified by the cluster owner or administrator. Upgrades occur on a weekly basis, unless an upgrade is unavailable for that week.

If you select recurring updates for your cluster, you must provide an administrator’s acknowledgment. {cluster-manager} does not start scheduled y-stream updates for minor versions without receiving an administrator’s acknowledgment.

[NOTE]
====
Recurring upgrade policies are optional and if they are not set, the upgrade policies default to individual.
====

[id="upgrade-manual_upgrades_{context}"]
== Individual upgrades

If you opt for individual upgrades, you are responsible for updating your cluster. If you select an update version that requires approval, you must provide an administrator’s acknowledgment.

If your cluster version becomes outdated, it will transition to a limited support status. For more information on OpenShift life cycle policies, see xref:../osd_architecture/osd_policy/osd-life-cycle.adoc#osd-life-cycle[{product-title} update life cycle].

[id="upgrade-notifications_{context}"]
== Upgrade notifications

From {cluster-manager} console you can view your cluster's history from the *Overview* tab. The Upgrade states can be viewed in the service log under the *Cluster history* heading.

Every change of state also triggers an email notification to the cluster owner and subscribed users. You will receive email notifications for the following events:

* An upgrade has been scheduled.
* An upgrade has started.
* An upgrade has completed.
* An upgrade has been canceled.

[NOTE]
====
For recurring upgrades, you will also receive email notifications before the upgrade occurs based on the following cadence:

* 2 week notice
* 1 week notice
* 1 day notice
====

[id="wif-upgrades_{context}"]
== Cluster upgrades with Workload Identity Federation (WIF)
Before upgrading an {product-title} on {GCP} cluster with WIF authentication type to a newer y-stream version, you must update the WIF configuration to that version as well. Failure to do so before attempting to upgrade the cluster version will result in an error.
For more information on how to update a WIF configuration, see the  _Additional resources_ section.

[NOTE]
====
The update path to a brand new release of {product-title} is not available in the stable channel until 45 to 90 days after the initial GA of a newer y-stream version.
====