Merge pull request #77078 from rohennes/TELCODOCS-1707-understanding-peer-review

TELCODOCS-1707: Add Understanding assembly, modules, and diagrams

Author: stevsmit

_topic_maps/_topic_map.yml

@@ -3066,12 +3066,12 @@ Topics:
   File: ztp-sno-additional-worker-node
 - Name: Pre-caching images for single-node OpenShift deployments
   File: ztp-precaching-tool
-#- Name: Image-based upgrade for single-node OpenShift clusters
-#  Dir: image_based_upgrade
-#  Distros: openshift-origin,openshift-enterprise
-#  Topics:
-#  - Name: Understanding the image-based upgrade for single-node OpenShift clusters
-#    File: cnf-understanding-image-based-upgrade
+- Name: Image-based upgrade for single-node OpenShift clusters
+  Dir: image_based_upgrade
+  Distros: openshift-origin,openshift-enterprise
+  Topics:
+  - Name: Understanding the image-based upgrade for single-node OpenShift clusters
+    File: cnf-understanding-image-based-upgrade
 #  - Name: Preparing for an image-based upgrade for single-node OpenShift clusters
 #    Dir: preparing_for_image_based_upgrade
 #    Distros: openshift-origin,openshift-enterprise

edge_computing/image_based_upgrade/cnf-understanding-image-based-upgrade.adoc

@@ -0,0 +1,130 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="understanding-image-based-upgrade-for-sno"]
+= Understanding the image-based upgrade for {sno} clusters
+include::_attributes/common-attributes.adoc[]
+:context: understanding-image-based-upgrade
+
+toc::[]
+
+:FeatureName: The Lifecycle Agent
+
+From {product-title} 4.14.13, the {lcao} 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>.
+
+// Lifecycle Agent (LCAO)
+
+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 are 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 image for the upgrade of the target cluster and the backup configurations for your workloads.
+
+.Example SeedGenerator CR
+[source,yaml]
+----
+apiVersion: lca.openshift.io/v1
+kind: SeedGenerator
+metadata:
+  name: seedimage
+spec:
+  seedImage: <seed_image>
+----
+
+.Example ImageBasedUpgrade CR
+[source,yaml]
+----
+apiVersion: lca.openshift.io/v1
+kind: ImageBasedUpgrade
+metadata:
+  name: upgrade
+spec:
+  stage: Idle <1>
+  seedImageRef: <2>
+    version: <target_version>
+    image: <seed_container_image>
+    pullSecretRef:
+      name: <seed_pull_secret>
+  autoRollbackOnFailure: {}
+#    initMonitorTimeoutSeconds: 1800 <3>
+  extraManifests: <4>
+  - name: example-extra-manifests
+    namespace: openshift-lifecycle-agent
+  oadpContent: <5>
+  - 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> (Optional) Specify the time frame in seconds to roll back when the upgrade does not complete within that time frame after the first reboot. If not defined or set to `0`, the default value of `1800` seconds (30 minutes) is used.
+<4> (Optional) Specify the list of `ConfigMap` resources that contain your custom catalog sources to retain after the upgrade, and your extra manifests to apply to the target cluster that are not part of the seed image.
+<5> Specify the list of `ConfigMap` resources that contain the OADP `Backup` and `Restore` CRs.
+
+include::modules/cnf-image-based-upgrade.adoc[leveloffset=+1]
+
+////
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../edge_computing/image_based_upgrade/cnf-image-based-upgrade-base.adoc#cnf-image-based-upgrade-for-sno[Performing an image-based upgrade with Lifecycle Agent]
+
+* xref:../../edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade-for-sno[Performing an image-based upgrade with Lifecycle Agent and GitOps ZTP]
+
+* xref:../../edge_computing/image_based_upgrade/cnf-image-based-upgrade-base.adoc#ztp-image-based-upgrade-rollback_cnf-image-based-upgrade[(Optional) Moving to the Rollback stage of the image-based upgrade with Lifecycle Agent]
+
+* xref:../../edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade-with-talm-rollback_ztp-image-based-upgrade[(Optional) Moving to the Rollback stage of the image-based upgrade with Lifecycle Agent and GitOps ZTP]
+////
+
+include::modules/cnf-image-based-upgrade-guidelines.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../installing/disconnected_install/installing-mirroring-installation-images.adoc#installing-mirroring-installation-images[Mirroring images for a disconnected installation]
+
+include::modules/ztp-image-based-upgrade-cluster-validated-software.adoc[leveloffset=+2]
+
+include::modules/ztp-image-based-upgrade-hub-cluster-guide.adoc[leveloffset=+2]
+
+include::modules/ztp-image-based-upgrade-seed-image-guide.adoc[leveloffset=+2]
+
+////
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-shared-container-image.adoc#cnf-image-based-upgrade-shared-container-directory_shared-container-directory[Configuring a shared container directory between ostree stateroots]
+
+* xref:../../edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-shared-container-image.adoc#ztp-image-based-upgrade-shared-container-directory_shared-container-directory[Configuring a shared container directory between ostree stateroots when using GitOps ZTP]
+
+* xref:../../edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-generate-seed.adoc#ztp-image-based-seed-image-config_generate-seed[Seed image configuration]
+////
+
+include::modules/ztp-image-based-upgrade-backup-guide.adoc[leveloffset=+2]
+
+include::modules/ztp-image-based-upgrade-extra-manifests-guide.adoc[leveloffset=+2]
+
+////
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../edge_computing/image_based_upgrade/cnf-image-based-upgrade-base.adoc#cnf-image-based-upgrade-for-sno[Performing an image-based upgrade with Lifecycle Agent]
+
+* xref:../../edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade-for-sno[Performing an image-based upgrade with Lifecycle Agent and GitOps ZTP]
+
+* xref:../../edge_computing/ztp-preparing-the-hub-cluster.adoc#ztp-preparing-the-hub-cluster[Preparing the hub cluster for ZTP]
+
+* xref:../../edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-prep-resources.adoc#cnf-image-based-upgrade-creating-backup-oadp-resources_nongitops[Creating ConfigMap objects for the image-based upgrade with Lifecycle Agent]
+
+* xref:../../edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/ztp-image-based-upgrade-prep-resources.adoc#ztp-image-based-upgrade-creating-backup-resources-with-ztp_ztp-gitops[Creating ConfigMap objects for the image-based upgrade with GitOps ZTP]
+
+* xref:../../backup_and_restore/application_backup_and_restore/installing/about-installing-oadp.adoc#about-installing-oadp[About installing OADP]
+////