TELCODOCS-2809: Fix DITA compatibility in PolicyGenerator docs

edge_computing/policygenerator_for_ztp/ztp-advanced-policygenerator-config.adoc

@@ -1,6 +1,7 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="ztp-advanced-policygenerator-config"]
 = Advanced managed cluster configuration with PolicyGenerator resources
+
 include::_attributes/common-attributes.adoc[]
 :context: ztp-advanced-policygenerator-config
 :policy-gen-cr: PolicyGenerator
@@ -11,6 +12,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can use `{policy-gen-cr}` CRs to deploy custom functionality in your managed clusters.
 Using {rh-rhacm} and `{policy-gen-cr}` CRs is the recommended approach for managing policies and deploying them to managed clusters.
 This replaces the use of `PolicyGenTemplate` CRs for this purpose.

modules/ztp-add-local-reg-for-sno-duprofile.adoc

@@ -7,6 +7,7 @@
 [id="ztp-add-local-reg-for-sno-duprofile_{context}"]
 = Configuring the Image Registry Operator for local caching of images
 
+[role="_abstract"]
 {product-title} manages image caching using a local registry. In edge computing use cases, clusters are often subject to bandwidth restrictions when communicating with centralized image registries, which might result in long image download times.
 
 Long download times are unavoidable during initial deployment. Over time, there is a risk that CRI-O will erase the `/var/lib/containers/storage` directory in the case of an unexpected shutdown.

modules/ztp-adding-new-content-to-gitops-ztp.adoc

@@ -8,6 +8,7 @@
 [id="ztp-adding-new-content-to-gitops-ztp_{context}"]
 = Adding custom content to the {ztp} pipeline
 
+[role="_abstract"]
 Perform the following procedure to add new content to the {ztp} pipeline.
 
 .Procedure
@@ -65,16 +66,18 @@ $ oc apply -f cgu-test.yaml
 
 * Check that the updates have succeeded by running the following command:
 +
+--
 [source, terminal]
 ----
 $ oc get cgu -A
 ----
-+
-.Example output
-+
+
+The following example shows the output:
+
 [source, terminal]
 ----
 NAMESPACE     NAME               AGE   STATE        DETAILS
 ztp-clusters  custom-source-cr   6s    InProgress   Remediating non-compliant policies
 ztp-install   cluster1           19h   Completed    All clusters are compliant with all the managed policies
 ----
+--

modules/ztp-configuring-disk-partitioning.adoc

@@ -7,6 +7,7 @@
 [id="ztp-configuring-disk-partitioning_{context}"]
 = Configuring disk partitioning with ClusterInstance
 
+[role="_abstract"]
 Configure disk partitioning for a managed cluster using a `ClusterInstance` CR and {ztp-first}. The  disk partition details in the `ClusterInstance` CR must match the underlying disk.
 
 [IMPORTANT]
@@ -28,12 +29,12 @@ variant: fcos
 version: 1.3.0
 storage:
   disks:
-  - device: /dev/disk/by-path/pci-0000:01:00.0-scsi-0:2:0:0 <1>
+  - device: <device>
     wipe_table: false
     partitions:
     - label: var-lib-containers
-      start_mib: <start_of_partition> <2>
-      size_mib: <partition_size> <3>
+      start_mib: <start_of_partition>
+      size_mib: <partition_size>
   filesystems:
     - path: /var/lib/containers
       device: /dev/disk/by-partlabel/var-lib-containers
@@ -44,9 +45,14 @@ storage:
         - defaults
         - prjquota
 ----
-<1> Specify the root disk.
-<2> Specify the start of the partition in MiB. If the value is too small, the installation fails.
-<3> Specify the size of the partition. If the value is too small, the deployments fails.
++
+--
+where:
+
+`<device>`:: Specifies the root disk.
+`<start_of_partition>`:: Specifies the start of the partition in MiB. If the value is too small, the installation fails.
+`<partition_size>`:: Specifies the size of the partition. If the value is too small, the deployment fails.
+--
 
 . Convert the `storage.bu` to an Ignition file by running the following command:
 +
@@ -56,7 +62,8 @@ storage:
 $ butane storage.bu
 ----
 
-.Example output
+The following example shows the output:
+
 [source,terminal]
 ----
 {"ignition":{"version":"3.2.0"},"storage":{"disks":[{"device":"/dev/disk/by-path/pci-0000:01:00.0-scsi-0:2:0:0","partitions":[{"label":"var-lib-containers","sizeMiB":0,"startMiB":250000}],"wipeTable":false}],"filesystems":[{"device":"/dev/disk/by-partlabel/var-lib-containers","format":"xfs","mountOptions":["defaults","prjquota"],"path":"/var/lib/containers","wipeFilesystem":true}]},"systemd":{"units":[{"contents":"# # Generated by Butane\n[Unit]\nRequires=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\nAfter=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\n\n[Mount]\nWhere=/var/lib/containers\nWhat=/dev/disk/by-partlabel/var-lib-containers\nType=xfs\nOptions=defaults,prjquota\n\n[Install]\nRequiredBy=local-fs.target","enabled":true,"name":"var-lib-containers.mount"}]}}
@@ -65,9 +72,8 @@ $ butane storage.bu
 
 . Use a tool such as link:https://jsonformatter.org/json-pretty-print[JSON Pretty Print] to convert the output into JSON format.
 
-. Copy the output into the `spec.nodes[].ignitionConfigOverride` field in the `ClusterInstance` CR.
+. Copy the output into the `spec.nodes[].ignitionConfigOverride` field in the `ClusterInstance` CR, as shown in the following example:
 +
-.Example
 [source,yaml]
 ----
 apiVersion: siteconfig.open-cluster-management.io/v1alpha1
@@ -139,7 +145,8 @@ If the `spec.nodes[].ignitionConfigOverride` field does not exist, create it.
 $ oc get bmh -n my-sno-ns my-sno -ojson | jq '.metadata.annotations["bmac.agent-install.openshift.io/ignition-config-overrides"]
 ----
 
-.Example output
+The following example shows the output:
+
 [source,terminal]
 ----
 "{\"ignition\":{\"version\":\"3.2.0\"},\"storage\":{\"disks\":[{\"device\":\"/dev/disk/by-id/wwn-0x6b07b250ebb9d0002a33509f24af1f62\",\"partitions\":[{\"label\":\"var-lib-containers\",\"sizeMiB\":0,\"startMiB\":250000}],\"wipeTable\":false}],\"filesystems\":[{\"device\":\"/dev/disk/by-partlabel/var-lib-containers\",\"format\":\"xfs\",\"mountOptions\":[\"defaults\",\"prjquota\"],\"path\":\"/var/lib/containers\",\"wipeFilesystem\":true}]},\"systemd\":{\"units\":[{\"contents\":\"# Generated by Butane\\n[Unit]\\nRequires=systemd-fsck@dev-disk-by\\\\x2dpartlabel-var\\\\x2dlib\\\\x2dcontainers.service\\nAfter=systemd-fsck@dev-disk-by\\\\x2dpartlabel-var\\\\x2dlib\\\\x2dcontainers.service\\n\\n[Mount]\\nWhere=/var/lib/containers\\nWhat=/dev/disk/by-partlabel/var-lib-containers\\nType=xfs\\nOptions=defaults,prjquota\\n\\n[Install]\\nRequiredBy=local-fs.target\",\"enabled\":true,\"name\":\"var-lib-containers.mount\"}]}}"
@@ -164,12 +171,14 @@ $ oc debug node/my-sno-node
 
 .. List information about all available block devices by running the following command:
 +
+--
 [source,terminal]
 ----
 # lsblk
 ----
-+
-.Example output
+
+The following example shows the output:
+
 [source,terminal]
 ----
 NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
@@ -185,15 +194,18 @@ sda      8:0    0 446.6G  0 disk
 │                                /sysroot
 └─sda5   8:5    0 202.5G  0 part /var/lib/containers
 ----
+--
 
 .. Display information about the file system disk space usage by running the following command:
 +
+--
 [source,terminal]
 ----
 # df -h
 ----
-+
-.Example output
+
+The following example shows the output:
+
 [source,terminal]
 ----
 Filesystem      Size  Used Avail Use% Mounted on
@@ -206,3 +218,4 @@ tmpfs           126G  4.0K  126G   1% /tmp
 /dev/sda3       350M  110M  218M  34% /boot
 tmpfs            26G     0   26G   0% /run/user/1000
 ----
+--

modules/ztp-configuring-pgt-compliance-eval-timeouts.adoc

@@ -7,6 +7,7 @@
 [id="ztp-configuring-pgt-compliance-eval-timeouts_{context}"]
 = Configuring policy compliance evaluation timeouts for {policy-gen-cr} CRs
 
+[role="_abstract"]
 Use {rh-rhacm-first} installed on a hub cluster to monitor and report on whether your managed clusters are compliant with applied policies. {rh-rhacm} uses policy templates to apply predefined policy controllers and policies. Policy controllers are Kubernetes custom resource definition (CRD) instances.
 
 You can override the default policy evaluation intervals with `{policy-gen-cr}` custom resources (CRs). You configure duration settings that define how long a `ConfigurationPolicy` CR can be in a state of policy compliance or non-compliance before {rh-rhacm} re-evaluates the applied cluster policies.
@@ -82,28 +83,34 @@ Check that the managed spoke cluster policies are monitored at the expected inte
 
 . Get the pods that are running in the `open-cluster-management-agent-addon` namespace. Run the following command:
 +
+--
 [source,terminal]
 ----
 $ oc get pods -n open-cluster-management-agent-addon
 ----
-+
-.Example output
+
+The following example shows the output:
+
 [source,terminal]
 ----
 NAME                                         READY   STATUS    RESTARTS        AGE
 config-policy-controller-858b894c68-v4xdb    1/1     Running   22 (5d8h ago)   10d
 ----
+--
 
 . Check the applied policies are being evaluated at the expected interval in the logs for the `config-policy-controller` pod:
 +
+--
 [source,terminal]
 ----
 $ oc logs -n open-cluster-management-agent-addon config-policy-controller-858b894c68-v4xdb
 ----
-+
-.Example output
+
+The following example shows the output:
+
 [source,terminal]
 ----
 2022-05-10T15:10:25.280Z       info   configuration-policy-controller controllers/configurationpolicy_controller.go:166      Skipping the policy evaluation due to the policy not reaching the evaluation interval  {"policy": "compute-1-config-policy-config"}
 2022-05-10T15:10:25.280Z       info   configuration-policy-controller controllers/configurationpolicy_controller.go:166      Skipping the policy evaluation due to the policy not reaching the evaluation interval  {"policy": "compute-1-common-compute-1-catalog-policy-config"}
 ----
+--

modules/ztp-configuring-pgt-image-registry.adoc

@@ -7,6 +7,7 @@
 [id="ztp-configuring-pgt-image-registry_{context}"]
 = Configuring the image registry using {policy-gen-cr} CRs
 
+[role="_abstract"]
 Use `{policy-gen-cr}` (PGT) CRs to apply the CRs required to configure the image registry and patch the `imageregistry` configuration.
 
 .Prerequisites
@@ -32,7 +33,7 @@ sourceFiles:
     metadata:
       name: image-registry-sc
       annotations:
-        ran.openshift.io/ztp-deploy-wave: "100" <1>
+        ran.openshift.io/ztp-deploy-wave: "100"
   # persistent volume claim
   - fileName: StoragePVC.yaml
     policyName: "pvc-for-image-registry"
@@ -50,7 +51,7 @@ sourceFiles:
       storageClassName: image-registry-sc
       volumeMode: Filesystem
   # persistent volume
-  - fileName: ImageRegistryPV.yaml <2>
+  - fileName: ImageRegistryPV.yaml
     policyName: "pv-for-image-registry"
     metadata:
       annotations:
@@ -66,14 +67,18 @@ sourceFiles:
         pvc:
           claim: "image-registry-pvc"
 ----
-<1> Set the appropriate value for `ztp-deploy-wave` depending on whether you are configuring image registries at the site, common, or group level. `ztp-deploy-wave: "100"` is suitable for development or testing because it allows you to group the referenced source files together.
-<2> In `ImageRegistryPV.yaml`, ensure that the `spec.local.path` field is set to `/var/imageregistry` to match the value set for the `mount_point` field in the `ClusterInstance` CR.
-
 +
+--
+where:
+
+`ran.openshift.io/ztp-deploy-wave: "100"`:: Sets the appropriate value for `ztp-deploy-wave` depending on whether you are configuring image registries at the site, common, or group level. `ztp-deploy-wave: "100"` is suitable for development or testing because it allows you to group the referenced source files together.
+`ImageRegistryPV.yaml`:: In `ImageRegistryPV.yaml`, ensure that the `spec.local.path` field is set to `/var/imageregistry` to match the value set for the `mount_point` field in the `ClusterInstance` CR.
+
 [IMPORTANT]
 ====
 Do not set `complianceType: mustonlyhave` for the `- fileName: ImageRegistryConfig.yaml` configuration. This can cause the registry pod deployment to fail.
 ====
+--
 
 . Commit the `{policy-gen-cr}` change in Git, and then push to the Git repository being monitored by the {ztp} ArgoCD application.
 
@@ -108,12 +113,14 @@ $ oc get secret -n $cluster $cluster-admin-kubeconfig -o jsonpath='{.data.kubeco
 
 * Check that the `Config` CRD in the `imageregistry.operator.openshift.io` group instance is not reporting errors. Run the following command while logged in to the managed cluster:
 +
+--
 [source,terminal]
 ----
 $ oc get image.config.openshift.io cluster -o yaml
 ----
-+
-.Example output
+
+The following example shows the output:
+
 [source,yaml]
 ----
 apiVersion: config.openshift.io/v1
@@ -133,6 +140,7 @@ spec:
   additionalTrustedCA:
     name: acm-ice
 ----
+--
 
 * Check that the `PersistentVolumeClaim` on the managed cluster is populated with data. Run the following command while logged in to the managed cluster:
 +
@@ -143,17 +151,20 @@ $ oc get pv image-registry-sc
 
 * Check that the `registry*` pod is running and is located under the `openshift-image-registry` namespace.
 +
+--
 [source,terminal]
 ----
 $ oc get pods -n openshift-image-registry | grep registry*
 ----
-+
-.Example output
+
+The following example shows the output:
+
 [source,terminal]
 ----
 cluster-image-registry-operator-68f5c9c589-42cfg   1/1     Running     0          8d
 image-registry-5f8987879-6nx6h                     1/1     Running     0          8d
 ----
+--
 
 * Check that the disk partition on the managed cluster is correct:
 
@@ -175,8 +186,9 @@ sda      8:0    0 446.6G  0 disk
   |-sda2   8:2    0   127M  0 part
   |-sda3   8:3    0   384M  0 part /boot
   |-sda4   8:4    0 336.3G  0 part /sysroot
-  `-sda5   8:5    0 100.1G  0 part /var/imageregistry <1>
+  `-sda5   8:5    0 100.1G  0 part /var/imageregistry
 sdb      8:16   0 446.6G  0 disk
 sr0     11:0    1   104M  0 rom
 ----
-<1> `/var/imageregistry` indicates that the disk is correctly partitioned.
++
+The `/var/imageregistry` mount point indicates that the disk is correctly partitioned.

modules/ztp-configuring-ptp-fast-events.adoc

@@ -7,6 +7,7 @@
 [id="ztp-configuring-ptp-fast-events_{context}"]
 = Configuring PTP events that use HTTP transport
 
+[role="_abstract"]
 You can configure PTP events that use HTTP transport on managed clusters that you deploy with the {ztp-first} pipeline.
 
 .Prerequisites

modules/ztp-creating-a-validator-inform-policy.adoc

@@ -7,6 +7,7 @@
 [id="ztp-creating-a-validator-inform-policy_{context}"]
 = Signalling {ztp} cluster deployment completion with validator inform policies
 
+[role="_abstract"]
 Create a validator inform policy that signals when the {ztp-first} installation and configuration of the deployed cluster is complete. This policy can be used for deployments of {sno} clusters, three-node clusters, and standard clusters.
 
 .Procedure

modules/ztp-deploying-additional-changes-to-clusters.adoc

@@ -7,6 +7,7 @@
 [id="ztp-deploying-additional-changes-to-clusters_{context}"]
 = Deploying additional changes to clusters
 
+[role="_abstract"]
 If you require cluster configuration changes outside of the base {ztp-first} pipeline configuration, there are three options:
 
 Apply the additional configuration after the {ztp} pipeline is complete:: When the {ztp} pipeline deployment is complete, the deployed cluster is ready for application workloads. At this point, you can install additional Operators and apply configurations specific to your requirements. Ensure that additional configurations do not negatively affect the performance of the platform or allocated CPU budget.

modules/ztp-provisioning-lvm-storage.adoc

@@ -7,6 +7,7 @@
 [id="ztp-provisioning-lvm-storage_{context}"]
 = Configuring {lvms} using {policy-gen-cr} CRs
 
+[role="_abstract"]
 You can configure {lvms-first} for managed clusters that you deploy with {ztp-first}.
 
 [NOTE]

modules/ztp-using-pgt-to-configure-high-performance-mode.adoc

@@ -7,6 +7,7 @@
 [id="ztp-using-pgt-to-configure-high-performance-mode_{context}"]
 = Configuring high-performance mode using {policy-gen-cr} CRs
 
+[role="_abstract"]
 Follow this example to set high performance mode by updating the `workloadHints` fields in the generated `PerformanceProfile` CR for the reference configuration, based on the `{policy-gen-cr}` CR in the `{policy-prefix}group-du-sno-ranGen.yaml`.
 
 High performance mode provides ultra low latency at the highest power consumption.

modules/ztp-using-pgt-to-configure-performance-mode.adoc

@@ -7,6 +7,7 @@
 [id="ztp-using-pgt-to-configure-performance-mode_{context}"]
 = Configuring performance mode using {policy-gen-cr} CRs
 
+[role="_abstract"]
 Follow this example to set performance mode by updating the `workloadHints` fields in the generated `PerformanceProfile` CR for the reference configuration, based on the `{policy-gen-cr}` CR in the `{policy-prefix}group-du-sno-ranGen.yaml`.
 
 Performance mode provides low latency at a relatively high power consumption.

modules/ztp-using-pgt-to-configure-power-saving-mode.adoc

@@ -7,6 +7,7 @@
 [id="ztp-using-pgt-to-configure-power-saving-mode_{context}"]
 = Configuring power saving mode using {policy-gen-cr} CRs
 
+[role="_abstract"]
 Follow this example to set power saving mode by updating the `workloadHints` fields in the generated `PerformanceProfile` CR for the reference configuration, based on the `{policy-gen-cr}` CR in the `{policy-prefix}group-du-sno-ranGen.yaml`.
 
 The power saving mode balances reduced power consumption with increased latency.
@@ -59,7 +60,5 @@ Replace `<node-name>` with the name of the node you want to verify the power sta
 ----
 # cat /proc/cmdline
 ----
-
-.Expected output
-
-* For power saving mode the `intel_pstate=passive`.
++
+For power saving mode, verify that the output includes `intel_pstate=passive`.