openshift-docs/modules/cnf-image-based-upgrade.adoc

// Module included in the following assemblies:
// * edge_computing/image-based-upgrade/cnf-understanding-image-based-upgrade.adoc

:_mod-docs-content-type: CONCEPT
[id="cnf-image-based-upgrade_{context}"]
= Stages of the image-based upgrade

After generating the seed image on the seed cluster, you can move through the stages on the target cluster by setting the `spec.stage` field to one of the following values in the `ImageBasedUpgrade` CR:

* `Idle`
* `Prep`
* `Upgrade`
* `Rollback` (Optional)

.Stages of the image-based upgrade
image::696_OpenShift_Lifecycle_Agent_0624_0.png[Stages of the image-based upgrade]

[id="cnf-image-based-upgrade-concept-idle_{context}"]
== Idle stage

The {lcao} creates an `ImageBasedUpgrade` CR set to `stage: Idle` when the Operator is first deployed.
This is the default stage.
There is no ongoing upgrade and the cluster is ready to move to the `Prep` stage.

.Transition from Idle stage
image::696_OpenShift_Lifecycle_Agent_0624_1.png[Transition from Idle stage]

You also move to the `Idle` stage to do one of the following steps:

* Finalize a successful upgrade
* Finalize a rollback
* Cancel an ongoing upgrade until the pre-pivot phase in the `Upgrade` stage

Moving to the `Idle` stage ensures that the {lcao} cleans up resources, so that the cluster is ready for upgrades again.

.Transitions to Idle stage
image::696_OpenShift_Lifecycle_Agent_0624_2.png[Transitions to Idle stage]

[IMPORTANT]
====
If using {rh-rhacm} when you cancel an upgrade, you must remove the `import.open-cluster-management.io/disable-auto-import` annotation from the target managed cluster to re-enable the automatic import of the cluster.
====

[id="cnf-image-based-upgrade-concept-prep_{context}"]
== Prep stage

[NOTE]
====
You can complete this stage before a scheduled maintenance window.
====

For the `Prep` stage, you specify the following upgrade details in the `ImageBasedUpgrade` CR:

* seed image to use
* resources to back up
* extra manifests to apply and custom catalog sources to retain after the upgrade, if any

Then, based on what you specify, the {lcao} prepares for the upgrade without impacting the current running version.
During this stage, the {lcao} ensures that the target cluster is ready to proceed to the `Upgrade` stage by checking if it meets certain conditions.
The Operator pulls the seed image to the target cluster with additional container images specified in the seed image.
The {lcao} checks if there is enough space on the container storage disk and if necessary, the Operator deletes unpinned images until the disk usage is below the specified threshold.
For more information about how to configure or disable the cleaning up of the container storage disk, see "Configuring the automatic image cleanup of the container storage disk".

You also prepare backup resources with the {oadp-short} Operator's `Backup` and `Restore` CRs.
These CRs are used in the `Upgrade` stage to reconfigure the cluster, register the cluster with {rh-rhacm}, and restore application artifacts.

In addition to the {oadp-short} Operator, the {lcao} uses the `ostree` versioning system to create a backup, which allows complete cluster reconfiguration after both upgrade and rollback.

After the `Prep` stage finishes, you can cancel the upgrade process by moving to the `Idle` stage or you can start the upgrade by moving to the `Upgrade` stage in the `ImageBasedUpgrade` CR.
If you cancel the upgrade, the Operator performs cleanup operations.

.Transition from Prep stage
image::696_OpenShift_Lifecycle_Agent_0624_3.png[Transition from Prep stage]

[id="cnf-image-based-upgrade-concept-upgrade_{context}"]
== Upgrade stage

The `Upgrade` stage consists of two phases:

pre-pivot:: Just before pivoting to the new stateroot, the {lcao} collects the required cluster specific artifacts and stores them in the new stateroot. The backup of your cluster resources specified in the `Prep` stage are created on a compatible Object storage solution. The {lcao} exports CRs specified in the `extraManifests` field in the `ImageBasedUpgrade` CR or the CRs described in the ZTP policies that are bound to the target cluster. After pre-pivot phase has completed, the {lcao} sets the new stateroot deployment as the default boot entry and reboots the node.
post-pivot:: After booting from the new stateroot, the {lcao} also regenerates the seed image's cluster cryptography.
This ensures that each {sno} cluster upgraded with the same seed image has unique and valid cryptographic objects.
The Operator then reconfigures the cluster by applying cluster-specific artifacts that were collected in the pre-pivot phase.
The Operator applies all saved CRs, and restores the backups.

After the upgrade has completed and you are satisfied with the changes, you can finalize the upgrade by moving to the `Idle` stage.

[IMPORTANT]
====
When you finalize the upgrade, you cannot roll back to the original release.
====

.Transitions from Upgrade stage
image::696_OpenShift_Lifecycle_Agent_0624_4.png[Transitions from Upgrade stage]

If you want to cancel the upgrade, you can do so until the pre-pivot phase of the `Upgrade` stage.
If you encounter issues after the upgrade, you can move to the `Rollback` stage for a manual rollback.

[id="cnf-image-based-upgrade-concept-rollback_{context}"]
== Rollback stage

The `Rollback` stage can be initiated manually or automatically upon failure.
During the `Rollback` stage, the {lcao} sets the original `ostree` stateroot deployment as default.
Then, the node reboots with the previous release of {product-title} and application configurations.

[WARNING]
====
If you move to the `Idle` stage after a rollback, the {lcao} cleans up resources that can be used to troubleshoot a failed upgrade.
====

The {lcao} initiates an automatic rollback if the upgrade does not complete within a specified time limit.
For more information about the automatic rollback, see the "Moving to the Rollback stage with {lcao}" or "Moving to the Rollback stage with {lcao} and {ztp}" sections.

.Transition from Rollback stage
image::696_OpenShift_Lifecycle_Agent_0624_4.png[Transition from Rollback stage]