Merge pull request #107635 from lcavalle/TELCODOCS-2671-cnf-understanding-image-based-upgrade

slovern · web-flow · commit a9ed23339b29 · 2026-04-02T09:25:39.000+01:00
TELCODOCS#2671: Vale check for cnf-understanding-image-based-upgrade
diff --git a/edge_computing/image_based_upgrade/cnf-understanding-image-based-upgrade.adoc b/edge_computing/image_based_upgrade/cnf-understanding-image-based-upgrade.adoc
@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 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>.
 
@@ -46,26 +47,33 @@ kind: ImageBasedUpgrade
 metadata:
   name: upgrade
 spec:
-  stage: Idle # <1>
-  seedImageRef: # <2>
+  stage: Idle
+  seedImageRef:
     version: <target_version>
     image: <seed_container_image>
     pullSecretRef:
       name: <seed_pull_secret>
   autoRollbackOnFailure: {}
-#    initMonitorTimeoutSeconds: 1800 # <3>
-  extraManifests: # <4>
+  extraManifests:
   - name: example-extra-manifests
     namespace: openshift-lifecycle-agent
-  oadpContent: # <5>
+  # List of ConfigMap resources that contain the OADP Backup and Restore CRs.
+  oadpContent:
   - name: oadp-cm-example
     namespace: openshift-adp
 ----
-<1> Stage of the `ImageBasedUpgrade` CR. The value can be `Idle`, `Prep`, `Upgrade`, or `Rollback`.
-<2> Target platform version, seed image to be used, and the secret required to access the image.
-<3> Optional: 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: 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> List of `ConfigMap` resources that contain the {oadp-short} `Backup` and `Restore` CRs.
+
+where
+
+`spec.stage`:: Defines the stage of the `ImageBasedUpgrade` CR. The value can be `Idle`, `Prep`, `Upgrade`, or `Rollback`.
+
+`spec.seedImageRef`:: Defines the seed image to be used, the target platform version, and the secret required to access the image.
+
+`initMonitorTimeoutSeconds`:: Optionally defines 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.
+
+`spec.extraManifests`:: Optionally defines 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.
+
+`spec.oadpContent`:: Defines the list of `ConfigMap` resources that contain the {oadp-short} `Backup` and `Restore` CRs.
 
 include::modules/cnf-image-based-upgrade.adoc[leveloffset=+1]
 
diff --git a/modules/cnf-image-based-upgrade-backup-guide.adoc b/modules/cnf-image-based-upgrade-backup-guide.adoc
@@ -1,9 +1,13 @@
 // Module included in the following assemblies:
 // * edge_computing/image-based-upgrade/cnf-understanding-image-based-upgrade.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="ztp-image-based-upgrade-backup-guide_{context}"]
 = {oadp-short} backup and restore guidelines
 
+[role="_abstract"]
+Use the {oadp-short} Operator to back up and restore applications during the image-based upgrade by creating `Backup` and `Restore` CRs wrapped in `ConfigMap` objects.
+
 With the {oadp-short} Operator, you can back up and restore your applications on your target clusters by using `Backup` and `Restore` CRs wrapped in `ConfigMap` objects.
 The application must work on the current and the target {product-title} versions so that they can be restored after the upgrade.
 The backups must include resources that were initially created.
@@ -67,7 +71,7 @@ metadata:
   name: acm-klusterlet
   namespace: openshift-adp
   annotations:
-    lca.openshift.io/apply-label: rbac.authorization.k8s.io/v1/clusterroles/klusterlet,apps/v1/deployments/open-cluster-management-agent/klusterlet # <1>
+    lca.openshift.io/apply-label: rbac.authorization.k8s.io/v1/clusterroles/klusterlet,apps/v1/deployments/open-cluster-management-agent/klusterlet
   labels:
     velero.io/storage-location: default
 spec:
@@ -78,4 +82,5 @@ spec:
   includedNamespaceScopedResources:
    - deployments
 ----
-<1> The value must be a list of comma-separated objects in `group/version/resource/name` format for cluster-scoped resources or `group/version/resource/namespace/name` format for namespace-scoped resources, and it must be attached to the related `Backup` CR.
+
+* The `metadata.annotations.lca.openshift.io/apply-label` value must be a list of comma-separated objects in `group/version/resource/name` format for cluster-scoped resources or `group/version/resource/namespace/name` format for namespace-scoped resources, and it must be attached to the related `Backup` CR.
diff --git a/modules/cnf-image-based-upgrade-cluster-validated-software.adoc b/modules/cnf-image-based-upgrade-cluster-validated-software.adoc
@@ -1,9 +1,13 @@
 // Module included in the following assemblies:
 // * edge_computing/image-based-upgrade/cnf-understanding-image-based-upgrade.adoc
 
+:_mod-docs-content-type: REFERENCE
 [id="cnf-image-based-upgrade-cluster-validated-software_{context}"]
 = Minimum software version of components
 
+[role="_abstract"]
+The image-based upgrade requires specific minimum software versions for various components depending on your deployment method.
+
 Depending on your deployment method, the image-based upgrade requires the following minimum software versions.
 
 .Minimum software version of components
diff --git a/modules/cnf-image-based-upgrade-extra-manifests-guide.adoc b/modules/cnf-image-based-upgrade-extra-manifests-guide.adoc
@@ -1,9 +1,13 @@
 // 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-extra-manifests-guide_{context}"]
 = Extra manifest guidelines
 
+[role="_abstract"]
+Extra manifests enable the {lcao} to restore cluster-specific configurations after the upgrade pivot but before restoring application artifacts.
+
 The {lcao} uses extra manifests to restore your target clusters after rebooting with the new stateroot deployment and before restoring application artifacts.
 
 Different deployment methods require a different way to apply the extra manifests:
diff --git a/modules/cnf-image-based-upgrade-guidelines.adoc b/modules/cnf-image-based-upgrade-guidelines.adoc
@@ -5,6 +5,9 @@
 [id="cnf-image-based-upgrade-guidelines_{context}"]
 = Guidelines for the image-based upgrade
 
+[role="_abstract"]
+Your deployments must meet specific requirements for a successful image-based upgrade, which can be performed using either {ztp} or non-GitOps deployment methods.
+
 For a successful image-based upgrade, your deployments must meet certain requirements.
 
 There are different deployment methods in which you can perform the image-based upgrade:
diff --git a/modules/cnf-image-based-upgrade-seed-image-guide.adoc b/modules/cnf-image-based-upgrade-seed-image-guide.adoc
@@ -1,9 +1,13 @@
 // 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-seed-image-guide_{context}"]
 = Seed image guidelines
 
+[role="_abstract"]
+The seed image targets {sno} clusters with matching hardware and configuration, requiring the seed cluster to match specific aspects of the target clusters.
+
 The seed image targets a set of {sno} clusters with the same hardware and similar configuration.
 This means that the seed cluster must match the configuration of the target clusters for the following items:
 
diff --git a/modules/cnf-image-based-upgrade.adoc b/modules/cnf-image-based-upgrade.adoc
@@ -5,6 +5,9 @@
 [id="cnf-image-based-upgrade_{context}"]
 = Stages of the image-based upgrade
 
+[role="_abstract"]
+The image-based upgrade consists of four stages that you control by setting the `spec.stage` field in the `ImageBasedUpgrade` CR: Idle, Prep, Upgrade, and Rollback.
+
 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`
diff --git a/modules/ztp-image-based-upgrade-hub-cluster-guide.adoc b/modules/ztp-image-based-upgrade-hub-cluster-guide.adoc
@@ -1,9 +1,13 @@
 // Module included in the following assemblies:
 // * edge_computing/image-based-upgrade/cnf-understanding-image-based-upgrade.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="ztp-image-based-upgrade-hub-cluster-guide_{context}"]
 = Hub cluster guidelines
 
+[role="_abstract"]
+When using {rh-rhacm}, the hub cluster must meet specific conditions including disabling optional add-ons and upgrading to at least the target version.
+
 If you are using {rh-rhacm-first}, your hub cluster needs to meet the following conditions:
 
 * To avoid including any {rh-rhacm} resources in your seed image, you need to disable all optional {rh-rhacm} add-ons before generating the seed image.
