[WIP] TELCODOCS-1707: Lifecycle Agent GA

_topic_maps/_topic_map.yml

@@ -3033,30 +3033,30 @@ 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: Preparing for an image-based upgrade for single-node OpenShift clusters
-#    Dir: preparing_for_image_based_upgrade
-#    Distros: openshift-origin,openshift-enterprise
-#    Topics:
-#    - Name: Configuring a shared container directory for the image-based upgrade
-#      File: cnf-image-based-upgrade-shared-container-image
-#    - Name: Installing Operators for the image-based upgrade
-#      File: cnf-image-based-upgrade-install-operators
-#    - Name: Generating a seed image for the image-based upgrade with Lifecycle Agent
-#      File: cnf-image-based-upgrade-generate-seed
-#    - Name: Creating ConfigMap objects for the image-based upgrade with Lifecycle Agent
-#      File: cnf-image-based-upgrade-prep-resources
-#    - Name: Creating ConfigMap objects for the image-based upgrade with Lifecycle Agent using GitOps ZTP
-#      File: ztp-image-based-upgrade-prep-resources
-#  - Name: Performing an image-based upgrade for single-node OpenShift clusters
-#    File: cnf-image-based-upgrade-base
-#  - Name: Performing an image-based upgrade for single-node OpenShift clusters using GitOps ZTP
-#    File: ztp-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
+    Topics:
+    - Name: Configuring a shared container directory for the image-based upgrade
+      File: cnf-image-based-upgrade-shared-container-image
+    - Name: Installing Operators for the image-based upgrade
+      File: cnf-image-based-upgrade-install-operators
+    - Name: Generating a seed image for the image-based upgrade with Lifecycle Agent
+      File: cnf-image-based-upgrade-generate-seed
+    - Name: Creating ConfigMap objects for the image-based upgrade with Lifecycle Agent
+      File: cnf-image-based-upgrade-prep-resources
+    - Name: Creating ConfigMap objects for the image-based upgrade with Lifecycle Agent using GitOps ZTP
+      File: ztp-image-based-upgrade-prep-resources
+  - Name: Performing an image-based upgrade for single-node OpenShift clusters
+    File: cnf-image-based-upgrade-base
+  - Name: Performing an image-based upgrade for single-node OpenShift clusters using GitOps ZTP
+    File: ztp-image-based-upgrade
 ---
 Name: Reference design specifications
 Dir: telco_ref_design_specs

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

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cnf-image-based-upgrade-for-sno"]
+= Performing an image-based upgrade for {sno} clusters
+include::_attributes/common-attributes.adoc[]
+:context: cnf-image-based-upgrade
+
+toc::[]
+
+You can use the {lcao} to do a manual image-based upgrade of a {sno} cluster.
+
+When you deploy the {lcao} on a cluster, an `ImageBasedUpgrade` CR is automatically created.
+You update this CR to specify the image repository of the seed image and to move through the different stages.
+
+:FeatureName: The Lifecycle Agent
+
+include::modules/cnf-image-based-upgrade-prep.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* 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 Lifecycle Agent]
+
+include::modules/cnf-image-based-upgrade-with-backup.adoc[leveloffset=+1]
+
+include::modules/cnf-image-based-upgrade-rollback.adoc[leveloffset=+1]
+
+include::modules/cnf-image-based-upgrade-troubleshooting.adoc[leveloffset=+1]

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

@@ -0,0 +1,124 @@
+:_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]

edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-generate-seed.adoc

@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cnf-image-based-upgrade-seed-image"]
+= Generating a seed image for the image-based upgrade with {lcao}
+include::_attributes/common-attributes.adoc[]
+:context: generate-seed
+
+toc::[]
+
+Use the {lcao} to generate the seed image with the `SeedGenerator` CR.
+
+:FeatureName: The Lifecycle Agent
+
+
+include::modules/cnf-image-based-upgrade-seed-image-config.adoc[leveloffset=+1]
+
+include::modules/cnf-image-based-upgrade-generate-seed-image.adoc[leveloffset=+1]
+
+[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#ztp-image-based-upgrade-shared-container-directory_shared-container-directory[Configuring a shared container directory between ostree stateroots when using GitOps ZTP]

edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-install-operators.adoc

@@ -0,0 +1,30 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cnf-image-based-upgrade-install-operators"]
+= Installing Operators for the image-based upgrade
+include::_attributes/common-attributes.adoc[]
+:context: install-operators
+
+toc::[]
+
+You need to prepare your clusters for the upgrade by installing the {lcao} and the OADP Operator.
+
+To install the OADP Operator with the non-GitOps method, see _Additional resources_.
+
+:FeatureName: The Lifecycle Agent
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../../backup_and_restore/application_backup_and_restore/installing/oadp-installing-operator.adoc[Installing the OADP Operator]
+
+* xref:../../../backup_and_restore/application_backup_and_restore/installing/installing-oadp-ocs.adoc#oadp-about-backup-snapshot-locations_installing-oadp-ocs[About backup and snapshot locations and their secrets]
+
+* xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-cr.adoc[Creating a Backup CR]
+
+* xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/restoring-applications.adoc#oadp-creating-restore-cr_restoring-applications[Creating a Restore CR]
+
+include::modules/cnf-image-based-upgrade-installing-lifecycle-agent-using-cli.adoc[leveloffset=+1]
+
+include::modules/cnf-image-based-upgrade-installing-lifecycle-agent-using-web-console.adoc[leveloffset=+1]
+
+include::modules/ztp-image-based-upgrade-installing-lifecycle-agent-using-gitops.adoc[leveloffset=+1]

edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-prep-resources.adoc

@@ -0,0 +1,24 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cnf-image-based-upgrade-prep-resources"]
+= Creating ConfigMap objects for the image-based upgrade with {lcao}
+include::_attributes/common-attributes.adoc[]
+:context: nongitops
+
+toc::[]
+
+The {lcao} needs all your OADP resources, extra manifests, and custom catalog sources wrapped in a `ConfigMap` object to process them for the image-based upgrade.
+
+:FeatureName: The Lifecycle Agent
+
+include::modules/cnf-image-based-upgrade-prep-oadp.adoc[leveloffset=+1]
+
+include::modules/cnf-image-based-upgrade-prep-extramanifests.adoc[leveloffset=+1]
+
+include::modules/cnf-image-based-upgrade-prep-catalogsource.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../../backup_and_restore/application_backup_and_restore/installing/about-installing-oadp.adoc[About installing OADP]
+
+* 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]

edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-shared-container-image.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cnf-image-based-upgrade-shared-varlibcontainers"]
+= Configuring a shared container directory for the image-based upgrade
+include::_attributes/common-attributes.adoc[]
+:context: shared-container-directory
+
+toc::[]
+
+Your {sno} clusters need to have a shared `var/lib/containers` partition for the image-based upgrade.
+You can do this at install time.
+
+:FeatureName: The Lifecycle Agent
+
+include::modules/cnf-image-based-upgrade-share-container-directory.adoc[leveloffset=+1]
+
+include::modules/ztp-image-based-upgrade-share-container-directory.adoc[leveloffset=+1]

edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/ztp-image-based-upgrade-prep-resources.adoc

@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ztp-image-based-upgrade-prep-resources"]
+= Creating ConfigMap objects for the image-based upgrade with {lcao} using {ztp}
+include::_attributes/common-attributes.adoc[]
+:context: ztp-gitops
+
+toc::[]
+
+The {lcao} needs all your OADP resources, extra manifests, and custom catalog sources wrapped in a `ConfigMap` object to process them for the image-based upgrade.
+
+:FeatureName: The Lifecycle Agent
+
+include::modules/ztp-image-based-upgrade-prep-oadp.adoc[leveloffset=+1]
+
+
+include::modules/ztp-image-based-upgrade-prep-label-extramanifests.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* 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/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade-for-sno[Performing an image-based upgrade with Lifecycle Agent and GitOps ZTP]

edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc

@@ -0,0 +1,39 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ztp-image-based-upgrade-for-sno"]
+= Performing an image-based upgrade for {sno} clusters using GitOps ZTP
+:context: ztp-image-based-upgrade
+include::_attributes/common-attributes.adoc[]
+
+toc::[]
+
+You can upgrade your managed {sno} cluster with the image-based upgrade through GitOps ZTP.
+
+When you deploy the {lcao} on a cluster, an `ImageBasedUpgrade` CR is automatically created.
+You update this CR to specify the image repository of the seed image and to move through the different stages.
+
+:FeatureName: The Lifecycle Agent
+
+// Lifecycle Agent (LCAO)
+
+include::modules/ztp-image-based-upgrade-talm-prep.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../edge_computing/ztp-preparing-the-hub-cluster.adoc#ztp-preparing-the-ztp-git-repository-ver-ind_ztp-preparing-the-hub-cluster[Preparing the GitOps ZTP site configuration repository for version independence]
+
+* xref:../../edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/ztp-image-based-upgrade-prep-resources.adoc#ztp-image-based-upgrade-prep-resources[Creating ConfigMap objects for the image-based upgrade with Lifecycle Agent using GitOps ZTP]
+
+* 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:../../backup_and_restore/application_backup_and_restore/installing/installing-oadp-ocs.adoc#oadp-about-backup-snapshot-locations_installing-oadp-ocs[About backup and snapshot locations and their secrets]
+
+* xref:../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-cr.adoc#oadp-creating-backup-cr-doc[Creating a Backup CR]
+
+* xref:../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/restoring-applications.adoc#oadp-creating-restore-cr_restoring-applications[Creating a Restore CR]
+
+include::modules/ztp-image-based-upgrade-talm-upgrade.adoc[leveloffset=+1]
+
+include::modules/ztp-image-based-upgrade-talm-rollback.adoc[leveloffset=+1]
+
+include::modules/cnf-image-based-upgrade-troubleshooting.adoc[leveloffset=+1]