TELCODOCS-2056: Post-GA peer review comments for IBU/LCA

Author: amolnar-rh

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

@@ -46,26 +46,26 @@ kind: ImageBasedUpgrade
 metadata:
   name: upgrade
 spec:
-  stage: Idle <1>
-  seedImageRef: <2>
+  stage: Idle # <1>
+  seedImageRef: # <2>
     version: <target_version>
     image: <seed_container_image>
     pullSecretRef:
       name: <seed_pull_secret>
   autoRollbackOnFailure: {}
-#    initMonitorTimeoutSeconds: 1800 <3>
-  extraManifests: <4>
+#    initMonitorTimeoutSeconds: 1800 # <3>
+  extraManifests: # <4>
   - name: example-extra-manifests
     namespace: openshift-lifecycle-agent
-  oadpContent: <5>
+  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-short} `Backup` and `Restore` CRs.
+<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.
 
 include::modules/cnf-image-based-upgrade.adoc[leveloffset=+1]
 

modules/cnf-image-based-upgrade-backup-guide.adoc

@@ -67,7 +67,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 # <1>
   labels:
     velero.io/storage-location: default
 spec:

modules/cnf-image-based-upgrade-configure-container-storage-image-cleanup.adoc

@@ -9,7 +9,7 @@ Configure the minimum threshold for available storage space through annotations.
 
 .Prerequisites
 
-* Create an `ImageBasedUpgrade` CR.
+* You have created an `ImageBasedUpgrade` CR.
 
 .Procedure
 

modules/cnf-image-based-upgrade-generate-seed-image.adoc

@@ -143,7 +143,7 @@ If you want to generate more seed images, you must provision a new seed cluster
 
 .Verification
 
-. After the cluster recovers and it is available, you can check the status of the `SeedGenerator` CR by running the following command:
+* After the cluster recovers and it is available, you can check the status of the `SeedGenerator` CR by running the following command:
 +
 --
 [source,terminal]

modules/cnf-image-based-upgrade-installing-lifecycle-agent-using-cli.adoc

@@ -9,12 +9,12 @@ You can use the OpenShift CLI (`oc`) to install the {lcao}.
 
 .Prerequisites
 
-* Install the OpenShift CLI (`oc`).
-* Log in as a user with `cluster-admin` privileges.
+* You have installed the OpenShift CLI (`oc`).
+* You have logged in as a user with `cluster-admin` privileges.
 
 .Procedure
 
-. Create a `Namespace` object YAML file for the {lcao}, for example `lcao-namespace.yaml`:
+. Create a `Namespace` object YAML file for the {lcao}:
 +
 [source,yaml]
 ----
@@ -30,10 +30,10 @@ metadata:
 +
 [source,terminal]
 ----
-$ oc create -f lcao-namespace.yaml
+$ oc create -f <namespace_filename>.yaml
 ----
 
-. Create an `OperatorGroup` object YAML file for the {lcao}, for example `lcao-operatorgroup.yaml`:
+. Create an `OperatorGroup` object YAML file for the {lcao}:
 +
 [source,yaml]
 ----
@@ -51,10 +51,10 @@ spec:
 +
 [source,terminal]
 ----
-$ oc create -f lcao-operatorgroup.yaml
+$ oc create -f <operatorgroup_filename>.yaml
 ----
 
-. Create a `Subscription` CR, for example, `lcao-subscription.yaml`:
+. Create a `Subscription` CR for the {lcao}:
 +
 [source,yaml]
 ----
@@ -74,7 +74,7 @@ spec:
 +
 [source,terminal]
 ----
-$ oc create -f lcao-subscription.yaml
+$ oc create -f <subscription_filename>.yaml
 ----
 
 .Verification

modules/cnf-image-based-upgrade-installing-lifecycle-agent-using-web-console.adoc

@@ -9,7 +9,7 @@ You can use the {product-title} web console to install the {lcao}.
 
 .Prerequisites
 
-* Log in as a user with `cluster-admin` privileges.
+* You have logged in as a user with `cluster-admin` privileges.
 
 .Procedure
 

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

@@ -9,12 +9,12 @@ Create your {oadp-short} resources that are used to back up and restore your res
 
 .Prerequisites
 
-* Generate a seed image from a compatible seed cluster.
-* Create {oadp-short} backup and restore resources.
-* Create a separate partition on the target cluster for the container images that is shared between stateroots. For more information about, see "Configuring a shared container partition for the image-based 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 "About installing {oadp-short}".
+* You have generated a seed image from a compatible seed cluster.
+* You have created {oadp-short} backup and restore resources.
+* You have created a separate partition on the target cluster for the container images that is shared between stateroots. For more information, see "Configuring a shared container partition for the image-based upgrade".
+* You have deployed a version of {lcao} that is compatible with the version used with the seed image.
+* You have installed the {oadp-short} Operator, the `DataProtectionApplication` CR, and its secret on the target cluster.
+* You have created an S3-compatible storage solution and a ready-to-use bucket with proper credentials configured. For more information, see "About installing {oadp-short}".
 
 .Procedure
 

modules/cnf-image-based-upgrade-prep.adoc

@@ -27,26 +27,26 @@ metadata:
 spec:
   stage: Idle
   seedImageRef:
-    version: 4.15.2 <1>
-    image: <seed_container_image> <2>
-    pullSecretRef: <seed_pull_secret> <3>
+    version: 4.15.2 # <1>
+    image: <seed_container_image> # <2>
+    pullSecretRef: <seed_pull_secret> # <3>
   autoRollbackOnFailure: {}
-#    initMonitorTimeoutSeconds: 1800 <4>
-  extraManifests: <5>
+#    initMonitorTimeoutSeconds: 1800 # <4>
+  extraManifests: # <5>
   - name: example-extra-manifests-cm
     namespace: openshift-lifecycle-agent
   - name: example-catalogsources-cm
     namespace: openshift-lifecycle-agent
-  oadpContent: <6>
+  oadpContent: # <6>
   - name: oadp-cm-example
     namespace: openshift-adp
 ----
-<1> Specify the target platform version. The value must match the version of the seed image.
-<2> Specify the repository where the target cluster can pull the seed image from.
-<3> Specify the reference to a secret with credentials to pull container images if the images are in a private registry.
-<4> (Optional) Specify the time frame in seconds to roll back if 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.
-<5> (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.
-<6> Add the `oadpContent` section with the {oadp-short} `ConfigMap` information.
+<1> Target platform version. The value must match the version of the seed image.
+<2> Repository where the target cluster can pull the seed image from.
+<3> Reference to a secret with credentials to pull container images if the images are in a private registry.
+<4> Optional: Time frame in seconds to roll back if 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.
+<5> 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.
+<6> List of `ConfigMap` resources that contain the {oadp-short} `Backup` and `Restore` CRs.
 
 . To start the `Prep` stage, change the value of the `stage` field to `Prep` in the `ImageBasedUpgrade` CR by running the following command:
 +
@@ -68,11 +68,11 @@ These warnings, for example missing CRDs, namespaces, or dry run failures, updat
 .Example validation warning
 [source,yaml]
 ----
-[...]
+# ...
 metadata:
 annotations:
   extra-manifest.lca.openshift.io/validation-warning: '...'
-[...]
+# ...
 ----
 
 However, validation errors, such as adding `MachineConfig` or Operator manifests to extra manifests, cause the `Prep` stage to fail and block the `Upgrade` stage.

modules/cnf-image-based-upgrade-rollback.adoc

@@ -20,17 +20,17 @@ spec:
     version: 4.15.2
     image: <seed_container_image>
   autoRollbackOnFailure: {}
-#    initMonitorTimeoutSeconds: 1800 <1>
-[...]
+#    initMonitorTimeoutSeconds: 1800 # <1>
+# ...
 ----
-<1> (Optional) Specify the time frame in seconds to roll back if 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.
+<1> Optional: The time frame in seconds to roll back if 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.
 
 You can manually roll back the changes if you encounter unresolvable issues after an upgrade.
 
 .Prerequisites
 
-* Log in to the hub cluster as a user with `cluster-admin` privileges.
-* Ensure that the control plane certificates on the original stateroot are valid. If the certificates expired, see "Recovering from expired control plane certificates".
+* You have logged into the hub cluster as a user with `cluster-admin` privileges.
+* You ensured that the control plane certificates on the original stateroot are valid. If the certificates expired, see "Recovering from expired control plane certificates".
 
 .Procedure
 

modules/cnf-image-based-upgrade-seed-image-config.adoc

@@ -68,7 +68,7 @@ endif::[]
 |====
 . Dual-stack networking is not supported in this release.
 . If the seed cluster is installed in a disconnected environment, the target clusters must also be installed in a disconnected environment.
-. The proxy configuration does not have to be the same.
+. The proxy configuration on the seed and target clusters does not have to match.
 
 [id="ztp-image-based-upgrade-seed-image-config-ran_{context}"]
 == Seed image configuration using the RAN DU profile