TELCODOCS-2797: DITA rework and rewrite for ztp-advanced-policygenerator-config

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

@@ -62,10 +62,7 @@ include::modules/ztp-using-pgt-to-maximize-power-saving-mode.adoc[leveloffset=+2
 
 include::modules/ztp-provisioning-lvm-storage.adoc[leveloffset=+1]
 
-[id="ztp-advanced-policy-config-ptp_{context}"]
-== Configuring PTP events with {policy-gen-cr} CRs
-
-You can use the {ztp} pipeline to configure PTP events that use HTTP transport.
+include::modules/ztp-about-configuring-ptp-events-with-pgt.adoc[leveloffset=+1]
 
 include::modules/ztp-configuring-ptp-fast-events.adoc[leveloffset=+2]
 
@@ -99,4 +96,4 @@ include::modules/ztp-configuring-pgt-image-registry.adoc[leveloffset=+2]
 :!policy-prefix:
 :!rangen-yaml-path:
 :!argocd-folder:
-:!path-prefix:
+:!path-prefix:

modules/ztp-about-configuring-ptp-events-with-pgt.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/policygenerator_for_ztp/ztp-advanced-policygenerator-config.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ztp-advanced-policy-config-ptp_{context}"]
+= Configuring PTP events with {policy-gen-cr} CRs
+
+[role="_abstract"]
+You can use the {ztp} pipeline to configure PTP events that use HTTP transport.

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
@@ -16,21 +17,25 @@ Perform the following procedure to add new content to the {ztp} pipeline.
 
 . Add your user-provided CRs to the `source-crs` subdirectory, as shown in the following example:
 +
+--
 ifeval::["{policy-gen-cr}" == "PolicyGenTemplate"]
 include::snippets/pgt-ztp-adding-new-content-to-gitops-ztp-folder-structure.adoc[]
 endif::[]
 ifeval::["{policy-gen-cr}" == "PolicyGenerator"]
 include::snippets/pg-ztp-adding-new-content-to-gitops-ztp-folder-structure.adoc[]
 endif::[]
+--
 
 . Update the required `{policy-gen-cr}` CRs to include references to the content you added in the `source-crs/custom-crs` and `source-crs/elasticsearch` directories. For example:
 +
+--
 ifeval::["{policy-gen-cr}" == "PolicyGenTemplate"]
 include::snippets/pgt-ztp-adding-new-content-to-gitops-ztp.adoc[]
 endif::[]
 ifeval::["{policy-gen-cr}" == "PolicyGenerator"]
 include::snippets/pg-ztp-adding-new-content-to-gitops-ztp.adoc[]
 endif::[]
+--
 
 . Commit the `{policy-gen-cr}` change in Git, and then push to the Git repository that is monitored by the GitOps ZTP Argo CD policies application.
 
@@ -70,7 +75,7 @@ $ oc apply -f cgu-test.yaml
 $ oc get cgu -A
 ----
 +
-.Example output
+Example output:
 +
 [source, terminal]
 ----

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: /dev/disk/by-path/pci-0000:01:00.0-scsi-0:2:0:0
     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,12 @@ 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:
+
+`storage.device`:: Specifies the root disk.
+`storage.disks.partitions.start_mib`:: Specifies the start of the partition in MiB. If the value is too small, the installation fails.
+`storage.disks.partitions.size_mib`:: Specifies the size of the partition. If the value is too small, the deployments fails.
 
 . Convert the `storage.bu` to an Ignition file by running the following command:
 +
@@ -56,7 +60,6 @@ storage:
 $ butane storage.bu
 ----
 
-.Example 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"}]}}
@@ -67,7 +70,7 @@ $ butane storage.bu
 
 . Copy the output into the `spec.nodes[].ignitionConfigOverride` field in the `ClusterInstance` CR.
 +
-.Example
+Example:
 [source,yaml]
 ----
 apiVersion: siteconfig.open-cluster-management.io/v1alpha1
@@ -139,7 +142,6 @@ 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
 [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\"}]}}"
@@ -169,7 +171,7 @@ $ oc debug node/my-sno-node
 # lsblk
 ----
 +
-.Example output
+Example output:
 [source,terminal]
 ----
 NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
@@ -193,7 +195,7 @@ sda      8:0    0 446.6G  0 disk
 # df -h
 ----
 +
-.Example output
+Example output:
 [source,terminal]
 ----
 Filesystem      Size  Used Avail Use% Mounted on

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.
@@ -87,7 +88,7 @@ Check that the managed spoke cluster policies are monitored at the expected inte
 $ oc get pods -n open-cluster-management-agent-addon
 ----
 +
-.Example output
+Example output:
 [source,terminal]
 ----
 NAME                                         READY   STATUS    RESTARTS        AGE
@@ -101,7 +102,7 @@ config-policy-controller-858b894c68-v4xdb    1/1     Running   22 (5d8h ago)   1
 $ oc logs -n open-cluster-management-agent-addon config-policy-controller-858b894c68-v4xdb
 ----
 +
-.Example output
+Example 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"}

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,8 +67,11 @@ 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:
+
+`sourceFiles.metadata.annotations.ztp-deploy-wave`:: Specifies 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.
+`sourceFiles.fileName`:: 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]
@@ -113,7 +117,7 @@ $ oc get secret -n $cluster $cluster-admin-kubeconfig -o jsonpath='{.data.kubeco
 $ oc get image.config.openshift.io cluster -o yaml
 ----
 +
-.Example output
+Example output:
 [source,yaml]
 ----
 apiVersion: config.openshift.io/v1
@@ -148,7 +152,7 @@ $ oc get pv image-registry-sc
 $ oc get pods -n openshift-image-registry | grep registry*
 ----
 +
-.Example output
+Example output:
 [source,terminal]
 ----
 cluster-image-registry-operator-68f5c9c589-42cfg   1/1     Running     0          8d
@@ -175,8 +179,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.
+
+`/var/imageregistry` 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
@@ -40,12 +41,14 @@ In {product-title} 4.13 or later, you do not need to set the `transportHost` fie
 
 .. Configure the `linuxptp` and `phc2sys` for the PTP clock type and interface. For example, add the following YAML into `{rangen-yaml-path}`:
 +
+--
 ifeval::["{policy-gen-cr}" == "PolicyGenTemplate"]
 include::snippets/pgt-ztp-configuring-ptp-fast-events-linuxptp.adoc[]
 endif::[]
 ifeval::["{policy-gen-cr}" == "PolicyGenerator"]
 include::snippets/pg-ztp-configuring-ptp-fast-events-linuxptp.adoc[]
 endif::[]
+--
 
 . Merge any other required changes and files with your custom site repository.
 

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.
@@ -60,6 +61,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`.

modules/ztp-using-pgt-to-configure-power-states.adoc

@@ -7,7 +7,9 @@
 [id="ztp-using-pgt-to-configure-power-saving-states_{context}"]
 = Configuring power states using {policy-gen-cr} CRs
 
+[role="_abstract"]
 For low latency and high-performance edge deployments, it is necessary to disable or limit C-states and P-states.
+
 With this configuration, the CPU runs at a constant frequency, which is typically the maximum turbo frequency. This ensures that the CPU is always running at its maximum speed, which results in high performance and low latency.
 This leads to the best latency for workloads.
 However, this also leads to the highest power consumption, which might not be necessary for all workloads.
@@ -24,9 +26,7 @@ The default configuration is for a low latency, performance mode.
 
 Configure the power states 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 following common prerequisites apply to configuring all three power states.
-
-.Prerequisites
+The following common prerequisites apply to configuring all three power states:
 
 * You have created a Git repository where you manage your custom site configuration data. The repository must be accessible from the hub cluster and be defined as a source repository for Argo CD.
 

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

@@ -7,7 +7,9 @@
 [id="ztp-using-pgt-to-maximize-power-savings-mode_{context}"]
 = Maximizing power savings
 
+[role="_abstract"]
 Limiting the maximum CPU frequency is recommended to achieve maximum power savings.
+
 Enabling C-states on the non-critical workload CPUs without restricting the maximum CPU frequency negates much of the power savings by boosting the frequency of the critical CPUs.
 
 Maximize power savings by updating the `sysfs` plugin fields, setting an appropriate value for `max_perf_pct` in the `TunedPerformancePatch` CR for the reference configuration. This example based on the `{policy-prefix}group-du-sno-ranGen.yaml` describes the procedure to follow to restrict the maximum CPU frequency.

modules/ztp-using-pgt-to-update-source-crs.adoc

@@ -7,6 +7,7 @@
 [id="ztp-using-pgt-to-update-source-crs_{context}"]
 = Using {policy-gen-cr} CRs to override source CRs content
 
+[role="_abstract"]
 `{policy-gen-cr}` custom resources (CRs) allow you to overlay additional configuration details on top of the base source CRs provided with the GitOps plugin in the `ztp-site-generate` container. You can think of `{policy-gen-cr}` CRs as a logical merge or patch to the base CR. Use `{policy-gen-cr}` CRs to update a single field of the base CR, or overlay the entire contents of the base CR. You can update values and insert fields that are not in the base CR.
 
 The following example procedure describes how to update 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` file. Use the procedure as a basis for modifying other parts of the `{policy-gen-cr}` based on your requirements.
@@ -87,7 +88,7 @@ endif::[]
 
 . Commit the `{policy-gen-cr}` change in Git, and then push to the Git repository being monitored by the {ztp} argo CD application.
 +
-.Example output
+Example output:
 The {ztp} application generates an {rh-rhacm} policy that contains the generated `PerformanceProfile` CR. The contents of that CR are derived by merging the `metadata` and `spec` contents from the `PerformanceProfile` entry in the `{policy-gen-cr}` onto the source CR. The resulting CR has the following content:
 +
 [source,yaml]
@@ -121,6 +122,7 @@ spec:
     realTimeKernel:
         enabled: true
 ----
++
 
 [NOTE]
 ====