TELCODOCS-2760: DITA compatibility fixes for ztp-deploying-far-edge-sites

edge_computing/ztp-deploying-far-edge-sites.adoc

@@ -21,17 +21,6 @@ include::modules/ztp-talo-integration.adoc[leveloffset=+1]
 
 include::modules/ztp-ztp-building-blocks.adoc[leveloffset=+1]
 
-[IMPORTANT]
-====
-The target bare-metal host must meet the networking, firmware, and hardware requirements listed in xref:../edge_computing/ztp-reference-cluster-configuration-for-vdu.adoc#sno-configure-for-vdu[Recommended {sno} cluster configuration for vDU application workloads].
-====
-
-[NOTE]
-====
-To deploy clusters with virtualized control planes running on {VirtProductName} VMs instead of physical servers, you can use KubeVirt Redfish to expose VMs as Redfish endpoints.
-For more information about using virtualized control planes, see "Understanding virtualized control planes".
-====
-
 [role="_additional-resources"]
 .Additional resources
 
@@ -119,7 +108,7 @@ include::modules/ztp-site-cleanup.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.9/html/clusters/cluster_mce_overview#remove-managed-cluster[Removing a cluster from management].
+* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.9/html/clusters/cluster_mce_overview#remove-managed-cluster[Removing a cluster from management]
 
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.15/html/multicluster_engine_operator_with_red_hat_advanced_cluster_management/ibio-intro#deprovision-clusters[Deprovisioning clusters]
 

modules/ztp-clusterinstance-config-reference.adoc

@@ -6,4 +6,5 @@
 [id="ztp-clusterinstance-config-reference_{context}"]
 = ClusterInstance CR installation reference
 
+[role="_abstract"]
 For a detailed API reference for the `ClusterInstance` custom resource, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/{rh-rhacm-version}/html-single/apis/index#clusterinstance-api[ClusterInstance API] in the {rh-rhacm-first} documentation.

modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc

@@ -6,6 +6,7 @@
 [id="ztp-configuring-host-firmware-with-gitops-ztp_{context}"]
 = Managing host firmware settings with {ztp}
 
+[role="_abstract"]
 Hosts require the correct firmware configuration to ensure high performance and optimal efficiency.
 You can deploy custom host firmware configurations for managed clusters with {ztp}.
 

modules/ztp-configuring-ipsec-using-ztp-and-siteconfig-for-mno.adoc

@@ -6,6 +6,7 @@
 [id="ztp-configuring-ipsec-using-ztp-and-siteconfig-for-mno_{context}"]
 = Configuring IPsec encryption for multi-node clusters using {ztp} and ClusterInstance resources
 
+[role="_abstract"]
 You can enable IPsec encryption in managed multi-node clusters that you install using {ztp} and {rh-rhacm-first}.
 You can encrypt traffic between the managed cluster and IPsec endpoints external to the managed cluster. All network traffic between nodes on the OVN-Kubernetes cluster network is encrypted with IPsec in Transport mode.
 
@@ -71,19 +72,22 @@ spec:
                 left: '%defaultroute'
                 leftid: '%fromcert'
                 leftmodecfgclient: false
-                leftcert: left_server <1>
+                leftcert: left_server # <1>
                 leftrsasigkey: '%cert'
-                right: <external_host> <2>
+                right: <external_host> # <2>
                 rightid: '%fromcert'
                 rightrsasigkey: '%cert'
-                rightsubnet: <external_address> <3>
-                ikev2: insist <4>
+                rightsubnet: <external_address> # <3>
+                ikev2: insist # <4>
                 type: tunnel
 ----
-<1> The value of this field must match with the name of the certificate used on the remote system.
-<2> Replace `<external_host>` with the external host IP address or DNS hostname.
-<3> Replace `<external_address>` with the IP subnet of the external host on the other side of the IPsec tunnel.
-<4> Use the IKEv2 VPN encryption protocol only. Do not use IKEv1, which is deprecated.
++
+--
+. The value of this field must match with the name of the certificate used on the remote system.
+. Replace `<external_host>` with the external host IP address or DNS hostname.
+. Replace `<external_address>` with the IP subnet of the external host on the other side of the IPsec tunnel.
+. Use the IKEv2 VPN encryption protocol only. Do not use IKEv1, which is deprecated.
+--
 
 . Add the following certificates to the `optional-extra-manifest/ipsec` folder:
 
@@ -107,19 +111,22 @@ out
       └── example
            └── optional-extra-manifest
                 └── ipsec
-                     ├── 99-ipsec-master-import-certs.bu <1> 
-                     ├── 99-ipsec-master-import-certs.yaml <1>
-                     ├── 99-ipsec-worker-import-certs.bu <1>
-                     ├── 99-ipsec-worker-import-certs.yaml <1>
+                     ├── 99-ipsec-master-import-certs.bu # <1>
+                     ├── 99-ipsec-master-import-certs.yaml # <1>
+                     ├── 99-ipsec-worker-import-certs.bu # <1>
+                     ├── 99-ipsec-worker-import-certs.yaml # <1>
                      ├── import-certs.sh
-                     ├── ca.pem <2>
-                     ├── left_server.p12 <2>
+                     ├── ca.pem # <2>
+                     ├── left_server.p12 # <2>
                      ├── enable-ipsec.yaml
                      ├── ipsec-config-policy.yaml
                      └── README.md
 ----
-<1> The `ipsec/import-certs.sh` script generates the Butane and endpoint configuration CRs.
-<2> Add the `ca.pem` and `left_server.p12` certificate files that are relevant to your network.
++
+--
+. The `ipsec/import-certs.sh` script generates the Butane and endpoint configuration CRs.
+. Add the `ca.pem` and `left_server.p12` certificate files that are relevant to your network.
+--
 
 . Create an `ipsec-manifests/` folder in the repository where you manage your custom site configuration data and add the `enable-ipsec.yaml` and `99-ipsec-*` YAML files to the directory.
 +
@@ -146,16 +153,19 @@ resources:
   - hub-1/clusterinstance-site1-mno-du.yaml
 configMapGenerator:
   - name: ipsec-manifests-cm
-    namespace: site1-mno-du <1>
+    namespace: site1-mno-du # <1>
     files:
       - ipsec-manifests/enable-ipsec.yaml
       - ipsec-manifests/99-ipsec-master-import-certs.yaml
       - ipsec-manifests/99-ipsec-worker-import-certs.yaml
 generatorOptions:
-  disableNameSuffixHash: true <2>
+  disableNameSuffixHash: true # <2>
 ----
-<1> The namespace must match the `ClusterInstance` namespace.
-<2> Disables the hash suffix so the `ConfigMap` name is predictable.
++
+--
+. The namespace must match the `ClusterInstance` namespace.
+. Disables the hash suffix so the `ConfigMap` name is predictable.
+--
 
 . In your `ClusterInstance` CR, reference the `ConfigMap` in the `extraManifestsRefs` field:
 +
@@ -170,10 +180,13 @@ spec:
   clusterName: "site1-mno-du"
   networkType: "OVNKubernetes"
   extraManifestsRefs:
-    - name: ipsec-manifests-cm <1>
+    - name: ipsec-manifests-cm # <1>
 # ...
 ----
-<1> Reference to the `ConfigMap` containing the IPsec certificate import manifests.
++
+--
+. Reference to the `ConfigMap` containing the IPsec certificate import manifests.
+--
 +
 [NOTE]
 ====

modules/ztp-configuring-ipsec-using-ztp-and-siteconfig.adoc

@@ -6,6 +6,7 @@
 [id="ztp-configuring-ipsec-using-ztp-and-siteconfig_{context}"]
 = Configuring IPsec encryption for {sno} clusters using {ztp} and ClusterInstance resources
 
+[role="_abstract"]
 You can enable IPsec encryption in managed {sno} clusters that you install using {ztp} and {rh-rhacm-first}.
 You can encrypt traffic between the managed cluster and IPsec endpoints external to the managed cluster. All network traffic between nodes on the OVN-Kubernetes cluster network is encrypted with IPsec in Transport mode.
 
@@ -46,19 +47,22 @@ interfaces:
     left: '%defaultroute'
     leftid: '%fromcert'
     leftmodecfgclient: false
-    leftcert: left_server <1>
+    leftcert: left_server # <1>
     leftrsasigkey: '%cert'
-    right: <external_host> <2>
+    right: <external_host> # <2>
     rightid: '%fromcert'
     rightrsasigkey: '%cert'
-    rightsubnet: <external_address> <3>
-    ikev2: insist <4>
+    rightsubnet: <external_address> # <3>
+    ikev2: insist # <4>
     type: tunnel
 ----
-<1> The value of this field must match with the name of the certificate used on the remote system.
-<2> Replace `<external_host>` with the external host IP address or DNS hostname.
-<3> Replace `<external_address>` with the IP subnet of the external host on the other side of the IPsec tunnel.
-<4> Use the IKEv2 VPN encryption protocol only. Do not use IKEv1, which is deprecated.
++
+--
+. The value of this field must match with the name of the certificate used on the remote system.
+. Replace `<external_host>` with the external host IP address or DNS hostname.
+. Replace `<external_address>` with the IP subnet of the external host on the other side of the IPsec tunnel.
+. Use the IKEv2 VPN encryption protocol only. Do not use IKEv1, which is deprecated.
+--
 
 . Add the following certificates to the `optional-extra-manifest/ipsec` folder:
 
@@ -82,19 +86,22 @@ out
       └── example
            └── optional-extra-manifest
                 └── ipsec
-                     ├── 99-ipsec-master-endpoint-config.bu <1>
-                     ├── 99-ipsec-master-endpoint-config.yaml <1>
-                     ├── 99-ipsec-worker-endpoint-config.bu <1>
-                     ├── 99-ipsec-worker-endpoint-config.yaml <1>
+                     ├── 99-ipsec-master-endpoint-config.bu # <1>
+                     ├── 99-ipsec-master-endpoint-config.yaml # <1>
+                     ├── 99-ipsec-worker-endpoint-config.bu # <1>
+                     ├── 99-ipsec-worker-endpoint-config.yaml # <1>
                      ├── build.sh
-                     ├── ca.pem <2>
-                     ├── left_server.p12 <2>
+                     ├── ca.pem # <2>
+                     ├── left_server.p12 # <2>
                      ├── enable-ipsec.yaml
                      ├── ipsec-endpoint-config.yml
                      └── README.md
 ----
-<1> The `ipsec/build.sh` script generates the Butane and endpoint configuration CRs.
-<2> You provide `ca.pem` and `left_server.p12` certificate files that are relevant to your network.
++
+--
+. The `ipsec/build.sh` script generates the Butane and endpoint configuration CRs.
+. You provide `ca.pem` and `left_server.p12` certificate files that are relevant to your network.
+--
 
 . Create an `ipsec-manifests/` folder in the repository where you manage your custom site configuration data.
 Add the `enable-ipsec.yaml` and `99-ipsec-*` YAML files to the directory.
@@ -122,16 +129,19 @@ resources:
   - hub-1/clusterinstance-site1-sno-du.yaml
 configMapGenerator:
   - name: ipsec-manifests-cm
-    namespace: site1-sno-du <1>
+    namespace: site1-sno-du # <1>
     files:
       - ipsec-manifests/enable-ipsec.yaml
       - ipsec-manifests/99-ipsec-master-endpoint-config.yaml
       - ipsec-manifests/99-ipsec-worker-endpoint-config.yaml
 generatorOptions:
-  disableNameSuffixHash: true <2>
+  disableNameSuffixHash: true # <2>
 ----
-<1> The namespace must match the `ClusterInstance` namespace.
-<2> Disables the hash suffix so the `ConfigMap` name is predictable.
++
+--
+. The namespace must match the `ClusterInstance` namespace.
+. Disables the hash suffix so the `ConfigMap` name is predictable.
+--
 
 . In your `ClusterInstance` CR, reference the `ConfigMap` in the `extraManifestsRefs` field:
 +
@@ -146,10 +156,13 @@ spec:
   clusterName: "site1-sno-du"
   networkType: "OVNKubernetes"
   extraManifestsRefs:
-    - name: ipsec-manifests-cm <1>
+    - name: ipsec-manifests-cm # <1>
 # ...
 ----
-<1> Reference to the `ConfigMap` containing the IPsec manifests.
++
+--
+. Reference to the `ConfigMap` containing the IPsec manifests.
+--
 +
 [NOTE]
 ====

modules/ztp-configuring-kernel-arguments-for-discovery-iso.adoc

@@ -5,6 +5,7 @@
 [id="setting-managed-bare-metal-host-kernel-arguments_{context}"]
 = Configuring Discovery ISO kernel arguments for installations using {ztp}
 
+[role="_abstract"]
 The {ztp-first} workflow uses the Discovery ISO as part of the {product-title} installation process on managed bare-metal hosts. You can edit the `InfraEnv` resource to specify kernel arguments for the Discovery ISO. This is useful for cluster installations with specific environmental requirements. 
 
 For example, configure the `rd.net.timeout.carrier` kernel argument for the Discovery ISO to facilitate static networking for the cluster or to receive a DHCP address before downloading the root file system during installation.
@@ -44,8 +45,8 @@ spec:
     name: "{{ .Cluster.ClusterName }}"
     namespace: "{{ .Cluster.ClusterName }}"
   kernelArguments:
-    - operation: append <1>
-      value: audit=0 <2>
+    - operation: append # <1>
+      value: audit=0 # <2>
     - operation: append
       value: trace=1
   sshAuthorizedKey: "{{ .Site.SshPublicKey }}"
@@ -58,8 +59,11 @@ spec:
       nmstate-label: "{{ .Cluster.ClusterName }}"
   additionalNTPSources: "{{ .Cluster.AdditionalNTPSources }}"
 ----
-<1> Specify the append operation to add a kernel argument.
-<2> Specify the kernel argument you want to configure. This example configures the audit kernel argument and the trace kernel argument.
++
+--
+. Specify the append operation to add a kernel argument.
+. Specify the kernel argument you want to configure. This example configures the audit kernel argument and the trace kernel argument.
+--
 
 . Commit the `InfraEnv-example.yaml` file to your Git repository and push your changes. The following example shows a sample Git repository structure:
 +
@@ -79,18 +83,21 @@ spec:
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
-  - clusterinstance-example.yaml <1>
+  - clusterinstance-example.yaml # <1>
 configMapGenerator:
-  - name: custom-infraenv-cm <2>
-    namespace: example-cluster <3>
+  - name: custom-infraenv-cm # <2>
+    namespace: example-cluster # <3>
     files:
       - InfraEnv-example.yaml
 generatorOptions:
   disableNameSuffixHash: true
 ----
-<1> The name of the `ClusterInstance` CR.
-<2> The name of the `ConfigMap` that contains the custom `InfraEnv` CR.
-<3> The namespace must match the `ClusterInstance` namespace.
++
+--
+. The name of the `ClusterInstance` CR.
+. The name of the `ConfigMap` that contains the custom `InfraEnv` CR.
+. The namespace must match the `ClusterInstance` namespace.
+--
 
 . In your `ClusterInstance` CR, reference the `ConfigMap` in the `spec.templateRefs` field:
 +
@@ -104,11 +111,14 @@ metadata:
 spec:
   clusterName: "example-cluster"
   templateRefs:
-    - name: custom-infraenv-cm <1>
+    - name: custom-infraenv-cm # <1>
       namespace: example-cluster
 # ...
 ----
-<1> Reference to the `ConfigMap` CR that contains the custom `InfraEnv` CR template.
++
+--
+. Reference to the `ConfigMap` CR that contains the custom `InfraEnv` CR template.
+--
 
 . Commit the `ClusterInstance` CR and `kustomization.yaml` to your Git repository and push your changes.
 +

modules/ztp-creating-the-site-secrets.adoc

@@ -7,6 +7,7 @@
 [id="ztp-creating-the-site-secrets_{context}"]
 = Creating the managed bare-metal host secrets
 
+[role="_abstract"]
 Add the required `Secret` custom resources (CRs) for the managed bare-metal host to the hub cluster. You need a secret for the {ztp-first} pipeline to access the Baseboard Management Controller (BMC) and a secret for the assisted installer service to pull cluster installation images from the registry.
 
 [NOTE]
@@ -27,8 +28,8 @@ apiVersion: v1
 kind: Secret
 metadata:
   name: example-sno-bmc-secret
-  namespace: example-sno <1>
-data: <2>
+  namespace: example-sno # <1>
+data: # <2>
   password: <base64_password>
   username: <base64_username>
 type: Opaque
@@ -37,14 +38,17 @@ apiVersion: v1
 kind: Secret
 metadata:
   name: pull-secret
-  namespace: example-sno  <3>
+  namespace: example-sno # <3>
 data:
-  .dockerconfigjson: <pull_secret> <4>
+  .dockerconfigjson: <pull_secret> # <4>
 type: kubernetes.io/dockerconfigjson
 ----
-<1> Must match the namespace configured in the related `ClusterInstance` CR
-<2> Base64-encoded values for `password` and `username`
-<3> Must match the namespace configured in the related `ClusterInstance` CR
-<4> Base64-encoded pull secret
++
+--
+. Must match the namespace configured in the related `ClusterInstance` CR
+. Base64-encoded values for `password` and `username`
+. Must match the namespace configured in the related `ClusterInstance` CR
+. Base64-encoded pull secret
+--
 
 . Add the relative path to `example-sno-secret.yaml` to the `kustomization.yaml` file that you use to install the cluster.