Merge pull request #80111 from amolnar-rh/TELCODOCS-1861

TELCODOCS-1861: Lifecycle Agent Enhancements 4.17

Author: adellape

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

@@ -76,6 +76,8 @@ include::modules/cnf-image-based-upgrade.adoc[leveloffset=+1]
 
 * xref:../../edge_computing/image_based_upgrade/cnf-image-based-upgrade-base.adoc#cnf-image-based-upgrade[Performing an image-based upgrade for {sno} clusters with {lcao}]
 
+* xref:../../edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade[Performing an image-based upgrade for {sno} clusters using {ztp}]
+
 include::modules/cnf-image-based-upgrade-guidelines.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

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

@@ -6,30 +6,53 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+// Lifecycle Agent (LCA)
+
 You can use a single resource on the hub cluster, the `ImageBasedGroupUpgrade` custom resource (CR), to manage an imaged-based upgrade on a selected group of managed clusters through all stages.
 {cgu-operator-first} reconciles the `ImageBasedGroupUpgrade` CR and creates the underlying resources to complete the defined stage transitions, either in a manually controlled or a fully automated upgrade flow.
 
-// Lifecycle Agent (LCA)
-
-include::modules/ztp-image-based-upgrade-concept.adoc[leveloffset=+1]
+For more information about the image-based upgrade, see "Understanding the image-based upgrade for single-node OpenShift clusters".
 
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-scenario-3-recovering-expired-certs_dr-recovering-expired-certs[Recovering from expired control plane certificates]
+* xref:../../edge_computing/image_based_upgrade/cnf-understanding-image-based-upgrade.adoc#cnf-understanding-image-based-upgrade[Understanding the image-based upgrade for single-node OpenShift clusters]
+
+include::modules/ztp-image-based-upgrade-concept.adoc[leveloffset=+1]
 
-////
-* xref:../../edge_computing/ztp-preparing-the-hub-cluster.adoc#ztp-preparing-the-ztp-git-repository-ver-ind_ztp-preparing-the-hub-cluster[Preparing the {ztp} site configuration repository for version independence]
+include::modules/ztp-image-based-upgrade-procedure-steps.adoc[leveloffset=+1]
 
-* 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 {lcao} using {ztp}]
+[role="_additional-resources"]
+.Additional resources
 
 * xref:../../edge_computing/image_based_upgrade/preparing_for_image_based_upgrade/cnf-image-based-upgrade-shared-container-partition.adoc#ztp-image-based-upgrade-shared-container-partition_shared-container-partition[Configuring a shared container partition between ostree stateroots when using {ztp}]
 
+* 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 {lcao} using {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]
-////
+
+* xref:../../edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade-supported-combinations_ztp-gitops[Supported action combinations]
+
+include::modules/ztp-image-based-upgrade-procedure-one-step.adoc[leveloffset=+1]
+
+include::modules/ztp-image-based-upgrade-procedure-cancel.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade-supported-combinations_ztp-gitops[Supported action combinations]
+
+include::modules/ztp-image-based-upgrade-procedure-rollback.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../edge_computing/image_based_upgrade/ztp-image-based-upgrade.adoc#ztp-image-based-upgrade-supported-combinations_ztp-gitops[Supported action combinations]
+
+* xref:../../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-scenario-3-recovering-expired-certs_dr-recovering-expired-certs[Recovering from expired control plane certificates]
 
 include::modules/cnf-image-based-upgrade-troubleshooting.adoc[leveloffset=+1]

modules/ztp-image-based-upgrade-prep-label-extramanifests.adoc

@@ -17,7 +17,7 @@ Label your extra manifests so that the {lcao} can extract resources that are lab
 
 .Procedure
 
-. Label your required extra manifests with the `lca.openshift.io/target-ocp-version: <target_version>` label in your existing `PolicyGenTemplate` CR:
+. Label your required extra manifests with the `lca.openshift.io/target-ocp-version: <target_version>` label in your existing site `PolicyGenTemplate` CR:
 +
 [source,yaml]
 ----

modules/ztp-image-based-upgrade-prep-oadp.adoc

@@ -2,7 +2,7 @@
 // * edge_computing/image-based-upgrade/cnf-preparing-for-image-based-upgrade.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="zztp-image-based-upgrade-prep-oadp_{context}"]
+[id="ztp-image-based-upgrade-prep-oadp_{context}"]
 = Creating {oadp-short} resources for the image-based upgrade with {ztp}
 
 Prepare your {oadp-short} resources to restore your application after an upgrade.
@@ -16,6 +16,7 @@ Prepare your {oadp-short} resources to restore your application after an upgrade
 * Deploy a version of {lcao} that is compatible with the version used with the seed image.
 * Install the {oadp-short} Operator, the `DataProtectionApplication` CR, and its secret on the target cluster.
 * Create an S3-compatible storage solution and a ready-to-use bucket with proper credentials configured. For more information, see "Installing and configuring the {oadp-short} Operator with {ztp}".
+* The `openshift-adp` namespace for the OADP `ConfigMap` object must exist on all managed clusters and the hub for the OADP `ConfigMap` to be generated and copied to the clusters.
 
 .Procedure
 
@@ -29,20 +30,20 @@ Prepare your {oadp-short} resources to restore your application after an upgrade
 │   │    ├── ImageBasedUpgrade.yaml
 │   │    ├── PlatformBackupRestore.yaml
 │   │    ├── PlatformBackupRestoreLvms.yaml
+│   │    ├── PlatformBackupRestoreWithIBGU.yaml
 ├── ...
-├── ibu-upgrade-ranGen.yaml
 ├── kustomization.yaml
 ----
 
-[IMPORTANT]
-====
-The `kustomization.yaml` file must be located in the same directory structure as previously shown to reference the `ibu-upgrade-ranGen.yaml` manifest.
-====
+The `source-crs/ibu/PlatformBackupRestoreWithIBGU.yaml` file is provided in the ZTP container image.
 
-The `source-crs/ibu/PlatformBackupRestore.yaml` file is provided in the ZTP container image.
+.PlatformBackupRestoreWithIBGU.yaml
+include::snippets/ibu-PlatformBackupRestoreWithIBGU.adoc[]
 
-.PlatformBackupRestore.yaml
-include::snippets/ibu-PlatformBackupRestore.adoc[]
+[NOTE]
+====
+If you perform the image-based upgrade directly on managed clusters, use the `PlatformBackupRestore.yaml` file.
+====
 
 If you use {lvms} to create persistent volumes, you can use the `source-crs/ibu/PlatformBackupRestoreLvms.yaml` provided in the ZTP container image to back up your {lvms} resources.
 
@@ -72,65 +73,24 @@ The same version of the applications must function on both the current and the t
 ====
 --
 
-. Create the `oadp-cm` `ConfigMap` object through the `oadp-cm-policy` in a new `PolicyGenTemplate` called `ibu-upgrade-ranGen.yaml`:
-+
-[source,yaml]
-----
-apiVersion: ran.openshift.io/v1
-kind: PolicyGenTemplate
-metadata:
-  name: example-group-ibu
-  namespace: "ztp-group"
-spec:
-  bindingRules:
-    group-du-sno: ""
-  mcp: "master"
-  evaluationInterval: 
-    compliant: 10s
-    noncompliant: 10s
-  sourceFiles:
-  - fileName: ConfigMapGeneric.yaml
-    complianceType: mustonlyhave
-    policyName: "oadp-cm-policy"
-    metadata:
-      name: oadp-cm
-      namespace: openshift-adp
-----
-
 . Create a `kustomization.yaml` with the following content:
 +
 [source,yaml]
 ----
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 
-generators: <1>
-- ibu-upgrade-ranGen.yaml
-
-configMapGenerator: <2>
+configMapGenerator: # <1>
 - files:
-  - source-crs/ibu/PlatformBackupRestore.yaml
+  - source-crs/ibu/PlatformBackupRestoreWithIBGU.yaml
   #- source-crs/custom-crs/ApplicationClusterScopedBackupRestore.yaml
   #- source-crs/custom-crs/ApplicationApplicationBackupRestoreLso.yaml
   name: oadp-cm
-  namespace: ztp-group
+  namespace: openshift-adp # <2>
 generatorOptions:
-  disableNameSuffixHash: true 
-
-
-patches: <3>
-- target:
-    group: policy.open-cluster-management.io
-    version: v1
-    kind: Policy
-    name: example-group-ibu-oadp-cm-policy
-  patch: |-
-    - op: replace
-      path: /spec/policy-templates/0/objectDefinition/spec/object-templates/0/objectDefinition/data
-      value: '{{hub copyConfigMapData "ztp-group" "oadp-cm" hub}}'
+  disableNameSuffixHash: true
 ----
-<1> Generates the `oadp-cm-policy`.
-<2> Creates the `oadp-cm` `ConfigMap` object on the hub cluster with `Backup` and `Restore` CRs.
-<3> Overrides the data field of `ConfigMap` added in `oadp-cm-policy`. A hub template is used to propagate the `oadp-cm` `ConfigMap` to all target clusters.
+<1> Creates the `oadp-cm` `ConfigMap` object on the hub cluster with `Backup` and `Restore` CRs.
+<2> The namespace must exist on all managed clusters and the hub for the OADP `ConfigMap` to be generated and copied to the clusters.
 
 . Push the changes to your Git repository.

modules/ztp-image-based-upgrade-procedure-cancel.adoc

@@ -0,0 +1,84 @@
+// Module included in the following assemblies:
+// * edge_computing/image-based-upgrade/ztp-image-based-upgrade.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ztp-image-based-upgrade-procedure-cancel_{context}"]
+= Canceling an image-based upgrade on managed clusters at scale
+
+You can cancel the upgrade on a set of managed clusters that completed the `Prep` stage.
+
+include::snippets/ibu-supported-action-combinations.adoc[]
+
+.Prerequisites
+
+* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
+
+.Procedure
+
+. Create a separate YAML file on the hub cluster that contains the `ImageBasedGroupUpgrade` CR:
++
+[source,yaml]
+----
+apiVersion: lcm.openshift.io/v1alpha1
+kind: ImageBasedGroupUpgrade
+metadata:
+  name: <filename>
+  namespace: default
+spec:
+  clusterLabelSelectors:
+  - matchExpressions:
+    - key: name
+      operator: In
+      values:
+      - spoke4
+  ibuSpec:
+    seedImageRef:
+      image: quay.io/seed/image:4.16.0-rc.1
+      version: 4.16.0-rc.1
+      pullSecretRef:
+        name: "<seed_pull_secret>"
+  extraManifests:
+    - name: example-extra-manifests
+      namespace: openshift-lifecycle-agent
+  oadpContent:
+    - name: oadp-cm
+      namespace: openshift-adp
+  plan:
+  - actions: ["Abort"]
+    rolloutStrategy:
+      maxConcurrency: 5
+      timeout: 10
+----
++
+All managed clusters that completed the `Prep` stage are moved back to the `Idle` stage. 
+
+. Apply the created file by running the following command on the hub cluster:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
+
+.Verification
+
+* Monitor the status updates by running the following command:
++
+[source,terminal]
+----
+$ oc get ibgu -o yaml
+----
+
++
+.Example output
+[source,yaml]
+----
+# ...
+status:
+  clusters:
+  - completedActions:
+    - action: Prep
+    currentActions:
+    - action: Abort
+    name: spoke4
+# ...
+----

modules/ztp-image-based-upgrade-procedure-one-step.adoc

@@ -0,0 +1,63 @@
+// Module included in the following assemblies:
+// * edge_computing/image-based-upgrade/ztp-image-based-upgrade.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ztp-image-based-upgrade-procedure-one-step_{context}"]
+= Performing an image-based upgrade on managed clusters at scale in one step
+
+For use cases when service interruption is not a concern, you can upgrade a set of your managed clusters by using the `ImageBasedGroupUpgrade` CR with several actions combined in one step with one rollout strategy.
+With one rollout strategy, the upgrade time can be reduced but you can only troubleshoot failed clusters after the upgrade plan is complete.
+
+.Prerequisites
+
+* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
+* You have created policies and `ConfigMap` objects for resources used in the image-based upgrade.
+* You have installed the {lcao} and OADP Operators on all managed clusters through the hub cluster.
+
+.Procedure
+
+. Create a YAML file on the hub cluster that contains the `ImageBasedGroupUpgrade` CR:
++
+--
+include::snippets/ibu-ImageBasedGroupUpgrade.adoc[]
+--
+
+. Apply the created file by running the following command on the hub cluster:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
+
+.Verification
+
+* Monitor the status updates by running the following command:
++
+--
+[source,terminal]
+----
+$ oc get ibgu -o yaml
+----
+
+.Example output
+[source,yaml]
+----
+# ...
+status:
+  clusters:
+  - completedActions:
+    - action: Prep
+    failedActions:
+    - action: Upgrade
+    name: spoke1
+  - completedActions:
+    - action: Prep
+    - action: Upgrade
+    - action: FinalizeUpgrade
+    name: spoke4
+  - failedActions:
+    - action: Prep
+    name: spoke6
+# ...
+----
+--