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

// Module included in the following assemblies:
// * scalability_and_performance/ztp-image-based-upgrade.adoc

:_mod-docs-content-type: CONCEPT
[id="ztp-image-based-upgrade-concept_{context}"]
= Image-based upgrade for {sno} cluster with the {lcao}

From {product-title} 4.14.7, the {lcao} 4.15 provides you with an alternative way to upgrade the platform version of a {sno} cluster.
The image-based upgrade is faster than the standard upgrade method and allows you to directly upgrade from {product-title} <4.y> to <4.y+2>, and <4.y.z> to <4.y.z+n>.

This upgrade method utilizes a generated OCI image from a dedicated seed cluster that is installed on the target {sno} cluster as a new `ostree` stateroot.
A seed cluster is a {sno} cluster deployed with the target {product-title} version, Day 2 Operators, and configurations that is common to all target clusters.

You can use the seed image, which is generated from the seed cluster, to upgrade the platform version on any {sno} cluster that has the same combination of hardware, Day 2 Operators, and cluster configuration as the seed cluster.

[IMPORTANT]
====
The image-based upgrade uses custom images that are specific to the hardware platform that the clusters are running on.
Each different hardware platform requires a separate seed image.
====

The {lcao} uses two custom resources (CRs) on the participating clusters to orchestrate the upgrade:

* On the seed cluster, the `SeedGenerator` CR allows for the seed image generation. This CR specifies the repository to push the seed image to.
* On the target cluster, the `ImageBasedUpgrade` CR specifies the seed container image for the upgrade of the target cluster and the backup configurations for your workloads.

.Example SeedGenerator CR
[source,yaml]
----
apiVersion: lca.openshift.io/v1alpha1
kind: SeedGenerator
metadata:
  name: seedimage
spec:
  seedImage: <seed_container_image>
----

.Example ImageBasedUpgrade CR
[source,yaml]
----
apiVersion: lca.openshift.io/v1alpha1
kind: ImageBasedUpgrade
metadata:
  name: example-upgrade
spec:
  stage: Idle <1>
  seedImageRef: <2>
    version: <target_version>
    image: <seed_container_image>
    pullSecretRef: <seed_pull_secret>
  additionalImages:
    name: ""
    namespace: ""
  autoRollbackOnFailure: {} <3>
#    disabledForPostRebootConfig: "true" <4>
#    disabledForUpgradeCompletion: "true" <5>
#    disabledInitMonitor: "true" <6>
#    initMonitorTimeoutSeconds: 1800 <7>
#  extraManifests: <8>
#  - name: sno-extra-manifests
#    namespace: openshift-lifecycle-agent
  oadpContent: <9>
  - name: oadp-cm-example
    namespace: openshift-adp
----
<1> Defines the desired stage for the `ImageBasedUpgrade` CR. The value can be `Idle`, `Prep`, `Upgrade`, or `Rollback`.
<2> Defines the target platform version, the seed image to be used, and the secret required to access the image.
<3> Configures the automatic rollback. By default, automatic rollback on failure is enabled throughout the upgrade.
<4> (Optional) If set to `true`, this option disables automatic rollback when the reconfiguration of the cluster fails upon the first reboot.
<5> (Optional) If set to `true`, this option disables automatic rollback after the {lcao} reports a failed upgrade upon completion.
<6> (Optional) If set to `true`, this option disables automatic rollback when the upgrade does not complete after reboot within the time frame specified in the `initMonitorTimeoutSeconds` field.
<7> (Optional) Specifies the time frame in seconds. If not defined or set to `0`, the default value of `1800` seconds (30 minutes) is used.
<8> (Optional) Specify the list of `ConfigMap` resources that contain the additional extra manifests that you want to apply to the target cluster. You can also add your custom catalog sources that you want to retain after the upgrade.
<9> Specify the list of `ConfigMap` resources that contain the OADP `Backup` and `Restore` CRs.

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 the following values in the `ImageBasedUpgrade` CR:

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

[id="ztp-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.

After a successful upgrade or a rollback, you commit to the change by patching the `stage` field to `Idle` in the `ImageBasedUpgrade` CR.
Changing to this stage ensures that the {lcao} cleans up resources, so the cluster is ready for upgrades again.

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

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

During 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 after upgrade

Then, based on what you specify, the {lcao} prepares for the upgrade without impacting the current running version.
This preparation includes ensuring that the target cluster is ready to proceed to the `Upgrade` stage by checking if it meets certain conditions and pulling the seed image to the target cluster with additional container images specified in the seed image.

You also prepare backup resources with the OADP 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.

[IMPORTANT]
====
The same version of the applications must function on both the current and the target release of {product-title}.
====

Additionally to the OADP Operator, the {lcao} uses the `ostree` versioning system to create a backup, which allow complete cluster reconfiguration after both upgrade and rollback.

You can stop the upgrade process at this point by moving to the `Idle` stage or you can start the upgrade by moving to the `Upgrade` stage in the `ImageBasedUpgrade` CR .
If you stop, the Operator performs cleanup operations.

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

Just before the {lcao} starts the upgrade process, the backup of your cluster resources specified in the `Prep` stage are created on a compatible Object storage solution.
After the target cluster reboots with the new platform version, the Operator applies the cluster and application configurations defined in the `Backup` and `Restore` CRs, and applies any extra manifests that are specified in the referenced `ConfigMap` resource.

The Operator 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.

Once you are satisfied with the changes, you can finalize the upgrade by moving to the `Idle` stage.
If you encounter issues after the upgrade, you can move to the `Rollback` stage for a manual rollback.

[id="ztp-image-based-upgrade-concept-rollback_{context}"]
== (Optional) Rollback stage

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

By default, automatic rollback is enabled in the `ImageBasedUpgrade` CR.
The {lcao} can initiate an automatic rollback if the upgrade fails or if the upgrade does not complete within the specified time limit.
For more information about the automatic rollback configurations, see the _(Optional) Initiating rollback of the single-node OpenShift cluster after an image-based upgrade_ section.

[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.
====