From aaebeca8991a00c3435d639082ccabcdbfe06941 Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Tue, 17 Feb 2026 16:34:01 +0000 Subject: [PATCH] TELCODOCS-2760: DITA compatibility fixes for ztp-deploying-far-edge-sites Fix 45 AsciiDocDITA Vale issues across 20 files: - Add [role="_abstract"] short descriptions to 19 modules - Convert 17 callout lists to DITA-compatible numbered lists - Fix 5 RelatedLinks issues (non-link content in Additional resources) - Replace 2 unsupported TaskTitle block titles with inline text - Fix 1 TaskStep issue (non-list content in Procedure section) - Move 1 assembly IMPORTANT admonition into referenced module Co-Authored-By: Claude Opus 4.6 --- .../ztp-deploying-far-edge-sites.adoc | 18 ++---- .../ztp-clusterinstance-config-reference.adoc | 1 + ...iguring-host-firmware-with-gitops-ztp.adoc | 1 + ...psec-using-ztp-and-siteconfig-for-mno.adoc | 62 ++++++++++++------- ...guring-ipsec-using-ztp-and-siteconfig.adoc | 62 ++++++++++++------- ...ng-kernel-arguments-for-discovery-iso.adoc | 34 ++++++---- modules/ztp-creating-the-site-secrets.adoc | 19 +++--- modules/ztp-deploying-a-site.adoc | 14 +++-- ...irmware-configuration-with-gitops-ztp.adoc | 25 +++++--- .../ztp-monitoring-installation-progress.adoc | 5 +- ...iew-managed-site-installation-process.adoc | 27 ++++++++ modules/ztp-removing-obsolete-content.adoc | 1 + ...p-retrieving-the-host-firmware-schema.adoc | 4 +- ...retrieving-the-host-firmware-settings.adoc | 29 ++++----- modules/ztp-site-cleanup.adoc | 1 + modules/ztp-talo-integration.adoc | 1 + modules/ztp-tearing-down-the-pipeline.adoc | 1 + ...eshooting-ztp-gitops-installation-crs.adoc | 1 + ...bleshooting-ztp-gitops-supermicro-tls.adoc | 1 + modules/ztp-verifying-ipsec.adoc | 10 ++- modules/ztp-ztp-building-blocks.adoc | 23 ++----- 21 files changed, 208 insertions(+), 132 deletions(-) create mode 100644 modules/ztp-overview-managed-site-installation-process.adoc diff --git a/edge_computing/ztp-deploying-far-edge-sites.adoc b/edge_computing/ztp-deploying-far-edge-sites.adoc index 3402fb4ebc86..b88098edf238 100644 --- a/edge_computing/ztp-deploying-far-edge-sites.adoc +++ b/edge_computing/ztp-deploying-far-edge-sites.adoc @@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] You can provision {product-title} clusters at scale with {rh-rhacm-first} using the assisted service and the GitOps plugin policy generator with core-reduction technology enabled. The {ztp-first} pipeline performs the cluster installations. {ztp} can be used in a disconnected environment. include::snippets/pgt-deprecation-notice.adoc[] @@ -21,21 +22,12 @@ 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 -* xref:../vcp/vcp-overview.adoc#vcp-overview[Understanding virtualized control planes] for setup instructions +* xref:../vcp/vcp-overview.adoc#vcp-overview[Understanding virtualized control planes] + +include::modules/ztp-overview-managed-site-installation-process.adoc[leveloffset=+1] include::modules/ztp-creating-the-site-secrets.adoc[leveloffset=+1] @@ -119,7 +111,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] diff --git a/modules/ztp-clusterinstance-config-reference.adoc b/modules/ztp-clusterinstance-config-reference.adoc index 8b2872554701..7629554625e4 100644 --- a/modules/ztp-clusterinstance-config-reference.adoc +++ b/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. diff --git a/modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc b/modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc index 480c23b525e3..d2b265fae270 100644 --- a/modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc +++ b/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}. diff --git a/modules/ztp-configuring-ipsec-using-ztp-and-siteconfig-for-mno.adoc b/modules/ztp-configuring-ipsec-using-ztp-and-siteconfig-for-mno.adoc index 5a9b6ca09cdb..cd91ebe37582 100644 --- a/modules/ztp-configuring-ipsec-using-ztp-and-siteconfig-for-mno.adoc +++ b/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 leftrsasigkey: '%cert' - right: <2> + right: rightid: '%fromcert' rightrsasigkey: '%cert' - rightsubnet: <3> - ikev2: insist <4> + rightsubnet: + ikev2: insist type: tunnel ---- -<1> The value of this field must match with the name of the certificate used on the remote system. -<2> Replace `` with the external host IP address or DNS hostname. -<3> Replace `` 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. ++ +-- +* `leftcert` must match the name of the certificate used on the remote system. +* `right` is the external host IP address or DNS hostname. +* `rightsubnet` is the IP subnet of the external host on the other side of the IPsec tunnel. +* `ikev2: insist` uses the IKEv2 VPN encryption protocol only. Do not use IKEv1, which is deprecated. +-- . Add the following certificates to the `optional-extra-manifest/ipsec` folder: @@ -99,7 +103,8 @@ The certificate files are required for the Network Security Services (NSS) datab + If the PKCS#12 certificate is protected with a password, set the `-W` argument. + -.Example output +The following example shows the generated output directory structure: ++ [source,terminal] ---- out @@ -107,19 +112,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 + ├── 99-ipsec-master-import-certs.yaml + ├── 99-ipsec-worker-import-certs.bu + ├── 99-ipsec-worker-import-certs.yaml ├── import-certs.sh - ├── ca.pem <2> - ├── left_server.p12 <2> + ├── ca.pem + ├── left_server.p12 ├── 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 +154,19 @@ resources: - hub-1/clusterinstance-site1-mno-du.yaml configMapGenerator: - name: ipsec-manifests-cm - namespace: site1-mno-du <1> + namespace: site1-mno-du 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 ---- -<1> The namespace must match the `ClusterInstance` namespace. -<2> Disables the hash suffix so the `ConfigMap` name is predictable. ++ +-- +* `namespace` must match the `ClusterInstance` namespace. +* `disableNameSuffixHash: true` disables the hash suffix so the `ConfigMap` name is predictable. +-- . In your `ClusterInstance` CR, reference the `ConfigMap` in the `extraManifestsRefs` field: + @@ -170,10 +181,13 @@ spec: clusterName: "site1-mno-du" networkType: "OVNKubernetes" extraManifestsRefs: - - name: ipsec-manifests-cm <1> + - name: ipsec-manifests-cm # ... ---- -<1> Reference to the `ConfigMap` containing the IPsec certificate import manifests. ++ +-- +* `extraManifestsRefs.name` references the `ConfigMap` containing the IPsec certificate import manifests. +-- + [NOTE] ==== @@ -190,4 +204,4 @@ During cluster provisioning, the SiteConfig Operator applies the CRs contained i .Verification -For information about verifying the IPsec encryption, see "Verifying the IPsec encryption". \ No newline at end of file +For information about verifying the IPsec encryption, see "Verifying the IPsec encryption". diff --git a/modules/ztp-configuring-ipsec-using-ztp-and-siteconfig.adoc b/modules/ztp-configuring-ipsec-using-ztp-and-siteconfig.adoc index f8cfb342c20e..eba0fd43bfad 100644 --- a/modules/ztp-configuring-ipsec-using-ztp-and-siteconfig.adoc +++ b/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 leftrsasigkey: '%cert' - right: <2> + right: rightid: '%fromcert' rightrsasigkey: '%cert' - rightsubnet: <3> - ikev2: insist <4> + rightsubnet: + ikev2: insist type: tunnel ---- -<1> The value of this field must match with the name of the certificate used on the remote system. -<2> Replace `` with the external host IP address or DNS hostname. -<3> Replace `` 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. ++ +-- +* `leftcert` must match the name of the certificate used on the remote system. +* `right` is the external host IP address or DNS hostname. +* `rightsubnet` is the IP subnet of the external host on the other side of the IPsec tunnel. +* `ikev2: insist` uses the IKEv2 VPN encryption protocol only. Do not use IKEv1, which is deprecated. +-- . Add the following certificates to the `optional-extra-manifest/ipsec` folder: @@ -74,7 +78,8 @@ The certificate files are required for the Network Security Services (NSS) datab + If the PKCS#12 certificate is protected with a password, set the `-W` argument. + -.Example output +The following example shows the generated output directory structure: ++ [source,terminal] ---- out @@ -82,19 +87,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 + ├── 99-ipsec-master-endpoint-config.yaml + ├── 99-ipsec-worker-endpoint-config.bu + ├── 99-ipsec-worker-endpoint-config.yaml ├── build.sh - ├── ca.pem <2> - ├── left_server.p12 <2> + ├── ca.pem + ├── left_server.p12 ├── 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 +130,19 @@ resources: - hub-1/clusterinstance-site1-sno-du.yaml configMapGenerator: - name: ipsec-manifests-cm - namespace: site1-sno-du <1> + namespace: site1-sno-du 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 ---- -<1> The namespace must match the `ClusterInstance` namespace. -<2> Disables the hash suffix so the `ConfigMap` name is predictable. ++ +-- +* `namespace` must match the `ClusterInstance` namespace. +* `disableNameSuffixHash: true` disables the hash suffix so the `ConfigMap` name is predictable. +-- . In your `ClusterInstance` CR, reference the `ConfigMap` in the `extraManifestsRefs` field: + @@ -146,10 +157,13 @@ spec: clusterName: "site1-sno-du" networkType: "OVNKubernetes" extraManifestsRefs: - - name: ipsec-manifests-cm <1> + - name: ipsec-manifests-cm # ... ---- -<1> Reference to the `ConfigMap` containing the IPsec manifests. ++ +-- +* `extraManifestsRefs.name` references the `ConfigMap` containing the IPsec manifests. +-- + [NOTE] ==== @@ -164,4 +178,4 @@ During cluster provisioning, the SiteConfig Operator applies the CRs contained i .Verification -For information about verifying the IPsec encryption, see "Verifying the IPsec encryption". \ No newline at end of file +For information about verifying the IPsec encryption, see "Verifying the IPsec encryption". diff --git a/modules/ztp-configuring-kernel-arguments-for-discovery-iso.adoc b/modules/ztp-configuring-kernel-arguments-for-discovery-iso.adoc index 67ee1a60ea91..2aa4fcf35fb8 100644 --- a/modules/ztp-configuring-kernel-arguments-for-discovery-iso.adoc +++ b/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 + value: audit=0 - 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. ++ +-- +* `kernelArguments.operation` specifies the append operation to add a kernel argument. +* `kernelArguments.value` specifies 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 configMapGenerator: - - name: custom-infraenv-cm <2> - namespace: example-cluster <3> + - name: custom-infraenv-cm + namespace: example-cluster 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. ++ +-- +* `clusterinstance-example.yaml` specifies the name of the `ClusterInstance` CR. +* `configMapGenerator.name` specifies the name of the `ConfigMap` that contains the custom `InfraEnv` CR. +* `configMapGenerator.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 namespace: example-cluster # ... ---- -<1> Reference to the `ConfigMap` CR that contains the custom `InfraEnv` CR template. ++ +-- +* `spec.templateRefs` specifies 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. + diff --git a/modules/ztp-creating-the-site-secrets.adoc b/modules/ztp-creating-the-site-secrets.adoc index 8a622fcb09fa..fd30f1739389 100644 --- a/modules/ztp-creating-the-site-secrets.adoc +++ b/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 +data: password: username: type: Opaque @@ -37,14 +38,16 @@ apiVersion: v1 kind: Secret metadata: name: pull-secret - namespace: example-sno <3> + namespace: example-sno data: - .dockerconfigjson: <4> + .dockerconfigjson: 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 ++ +-- +* `namespace` must match the namespace configured in the related `ClusterInstance` CR. +* `data` contains base64-encoded values for `password` and `username`. +* `.dockerconfigjson` is the 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. diff --git a/modules/ztp-deploying-a-site.adoc b/modules/ztp-deploying-a-site.adoc index 02f970d68da5..6a672b886207 100644 --- a/modules/ztp-deploying-a-site.adoc +++ b/modules/ztp-deploying-a-site.adoc @@ -6,6 +6,7 @@ [id="ztp-deploying-a-site_{context}"] = Deploying a managed cluster with ClusterInstance and {ztp} +[role="_abstract"] Use the following procedure to create a `ClusterInstance` custom resource (CR) and related files and initiate the {ztp-first} cluster deployment. [NOTE] @@ -115,8 +116,9 @@ The ArgoCD pipeline detects the changes and begins the managed cluster deploymen ---- $ oc describe node example-node.example.com ---- - -.Example output ++ +The following example output shows the custom roles and labels: ++ [source,terminal] ---- Name: example-node.example.com @@ -128,9 +130,13 @@ Labels: beta.kubernetes.io/arch=amd64 kubernetes.io/hostname=cnfdf03.telco5gran.eng.rdu2.redhat.com kubernetes.io/os=linux node-role.kubernetes.io/control-plane= - node-role.kubernetes.io/example-label= <1> + node-role.kubernetes.io/example-label= node-role.kubernetes.io/master= node-role.kubernetes.io/worker= node.openshift.io/os_id=rhcos ---- -<1> The custom label is applied to the node. \ No newline at end of file ++ +-- +* `node-role.kubernetes.io/example-label=` shows the custom label applied to the node. +-- + diff --git a/modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc b/modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc index f769e8239718..958341537fd8 100644 --- a/modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc +++ b/modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc @@ -6,6 +6,7 @@ [id="ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp_{context}"] = Deploying user-defined firmware to cluster hosts with {ztp} +[role="_abstract"] You can deploy user-defined firmware settings to cluster hosts by creating custom node templates that include `HostFirmwareSettings` CRs, and referencing them in the `ClusterInstance` CR. You can configure hardware profiles to apply to hosts in the following scenarios: @@ -73,14 +74,16 @@ resources: - clusterinstance-site1-sno-du.yaml configMapGenerator: - name: host-firmware-settings-cm - namespace: site1-sno-du <1> + namespace: site1-sno-du files: - - host-firmware-settings.yaml <2> + - host-firmware-settings.yaml generatorOptions: disableNameSuffixHash: true ---- -<1> The namespace must match the `ClusterInstance` namespace. -<2> The name of the `HostFirmwareSettings` CR. ++ +* `namespace` must match the `ClusterInstance` namespace. +* `host-firmware-settings.yaml` is the name of the `HostFirmwareSettings` CR. + . To apply a hardware profile to all hosts in the cluster, reference the `ConfigMap` in the `spec.templateRefs` field of your `ClusterInstance` CR. For example: @@ -96,13 +99,15 @@ spec: clusterName: "site1-sno-du" # ... templateRefs: - - name: host-firmware-settings-cm <1> + - name: host-firmware-settings-cm namespace: site1-sno-du nodes: - hostName: "node1.example.com" # ... ---- -<1> Applies the firmware profile to all hosts in the cluster. ++ +* `templateRefs` applies the firmware profile to all hosts in the cluster. + . Optional: To apply a hardware profile to a specific host in the cluster, reference the `ConfigMap` in the `spec.nodes[].templateRefs` field. For example: @@ -121,12 +126,13 @@ spec: - hostName: "node1.example.com" # ... templateRefs: - - name: host-firmware-node1-cm <1> + - name: host-firmware-node1-cm namespace: site1-sno-du - hostName: "node2.example.com" # ... ---- -<1> Applies the firmware profile only to the `node1.example.com` host. ++ +* `nodes[].templateRefs` applies the firmware profile only to the `node1.example.com` host. + [NOTE] ==== @@ -155,7 +161,8 @@ $ oc get hfs -n -o jsonpath=' + ** where `` is the namespace of the managed cluster and `` is the name of the managed cluster. + -.Example output +The following example output shows valid firmware settings: ++ [source,terminal] ---- True diff --git a/modules/ztp-monitoring-installation-progress.adoc b/modules/ztp-monitoring-installation-progress.adoc index e7474d1981cc..acc53785e53c 100644 --- a/modules/ztp-monitoring-installation-progress.adoc +++ b/modules/ztp-monitoring-installation-progress.adoc @@ -6,6 +6,7 @@ [id="ztp-monitoring-deployment-progress_{context}"] = Monitoring managed cluster installation progress +[role="_abstract"] The Argo CD pipeline syncs the `ClusterInstance` CR from the Git repository to the hub cluster. The SiteConfig Operator then processes the `ClusterInstance` CR and generates the required cluster configuration CRs. You can monitor the progress of the cluster installation from the {rh-rhacm} dashboard or from the command line. .Prerequisites @@ -16,9 +17,7 @@ The Argo CD pipeline syncs the `ClusterInstance` CR from the Git repository to t .Procedure -When the synchronization is complete, the installation generally proceeds as follows: - -. The Assisted Service Operator installs {product-title} on the cluster. You can monitor the progress of cluster installation from the {rh-rhacm} dashboard or from the command line by running the following commands: +. Monitor the progress of cluster installation by running the following commands: .. Export the cluster name: + diff --git a/modules/ztp-overview-managed-site-installation-process.adoc b/modules/ztp-overview-managed-site-installation-process.adoc new file mode 100644 index 000000000000..ec53e104f12b --- /dev/null +++ b/modules/ztp-overview-managed-site-installation-process.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * edge_computing/ztp-deploying-far-edge-sites.adoc + +:_mod-docs-content-type: CONCEPT +[id="ztp-overview-managed-site-installation-process_{context}"] += Overview of the managed site installation process + +[role="_abstract"] +After you apply the managed site custom resources (CRs) on the hub cluster, the following actions happen automatically: + +. A Discovery image ISO file is generated and booted on the target host. + +. When the ISO file successfully boots on the target host it reports the host hardware information to {rh-rhacm}. + +. After all hosts are discovered, {product-title} is installed. + +. When {product-title} finishes installing, the hub installs the `klusterlet` service on the target cluster. + +. The requested add-on services are installed on the target cluster. + +The Discovery image ISO process is complete when the `Agent` CR for the managed cluster is created on the hub cluster. + +[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]. +==== diff --git a/modules/ztp-removing-obsolete-content.adoc b/modules/ztp-removing-obsolete-content.adoc index 654eb3e34c87..25267e408b7b 100644 --- a/modules/ztp-removing-obsolete-content.adoc +++ b/modules/ztp-removing-obsolete-content.adoc @@ -6,6 +6,7 @@ [id="ztp-removing-obsolete-content_{context}"] = Removing obsolete content from the {ztp} pipeline +[role="_abstract"] If a change to the `PolicyGenerator` or `PolicyGentemplate` configuration results in obsolete policies, for example, if you rename policies, use the following procedure to remove the obsolete policies. .Prerequisites diff --git a/modules/ztp-retrieving-the-host-firmware-schema.adoc b/modules/ztp-retrieving-the-host-firmware-schema.adoc index c4ae6c971241..5a448b3dac28 100644 --- a/modules/ztp-retrieving-the-host-firmware-schema.adoc +++ b/modules/ztp-retrieving-the-host-firmware-schema.adoc @@ -6,6 +6,7 @@ [id="ztp-retrieving-the-host-firmware-schema_{context}"] = Retrieving the host firmware schema for a managed cluster +[role="_abstract"] You can discover the host firmware schema for managed clusters. The host firmware schema for bare-metal hosts is populated with information that the Ironic API returns. The API returns information about host firmware interfaces, including firmware setting types, allowable values, ranges, and flags. @@ -28,7 +29,8 @@ Run the following command: $ oc get firmwareschema -n -o yaml ---- + -.Example output +The following example output shows the host firmware schema: ++ [source,terminal] ---- apiVersion: v1 diff --git a/modules/ztp-retrieving-the-host-firmware-settings.adoc b/modules/ztp-retrieving-the-host-firmware-settings.adoc index c4c112fa7162..1818566bf3c2 100644 --- a/modules/ztp-retrieving-the-host-firmware-settings.adoc +++ b/modules/ztp-retrieving-the-host-firmware-settings.adoc @@ -6,6 +6,7 @@ [id="ztp-retrieving-the-host-firmware-settings_{context}"] = Retrieving the host firmware settings for a managed cluster +[role="_abstract"] You can retrieve the host firmware settings for managed clusters. This is useful when you have deployed changes to the host firmware and you want to monitor the changes and ensure that they are applied successfully. @@ -22,13 +23,13 @@ This is useful when you have deployed changes to the host firmware and you want . Retrieve the host firmware settings for the managed cluster. Run the following command: + --- [source,terminal] ---- $ oc get hostfirmwaresettings -n -o yaml ---- - -.Example output ++ +The following example output shows the host firmware settings: ++ [source,terminal] ---- apiVersion: v1 @@ -57,28 +58,27 @@ items: message: "" observedGeneration: 1 reason: Success - status: "True" <1> + # Indicates that a change in the host firmware settings has been detected. + status: "True" type: ChangeDetected - lastTransitionTime: "2024-09-11T10:29:43Z" message: Invalid BIOS setting observedGeneration: 1 reason: ConfigurationError - status: "False" <2> + # Indicates that the host has an invalid firmware setting. + status: "False" type: Valid lastUpdated: "2024-09-11T10:29:43Z" schema: name: schema-40562318 namespace: compute-1 - settings: <3> + # Contains the complete list of configured host firmware settings returned under the `status.settings` field. + settings: AccessControlService: Enabled AcpiHpet: Enabled AcpiRootBridgePxm: Enabled # ... ---- -<1> Indicates that a change in the host firmware settings has been detected -<2> Indicates that the host has an invalid firmware setting -<3> The complete list of configured host firmware settings is returned under the `status.settings` field --- . Optional: Check the status of the `HostFirmwareSettings` (`hfs`) custom resource in the cluster: + @@ -87,21 +87,22 @@ items: $ oc get hfs -n -o jsonpath='{.status.conditions[?(@.type=="ChangeDetected")].status}' ---- + -.Example output +The following example output shows a detected change: ++ [source,terminal] ---- True ---- -. Optional: Check for invalid firmware settings in the cluster host. -Run the following command: +. Optional: Check for invalid firmware settings in the cluster host by running the following command: + [source,terminal] ---- $ oc get hfs -n -o jsonpath='{.status.conditions[?(@.type=="Valid")].status}' ---- + -.Example output +The following example output shows an invalid firmware setting: ++ [source,terminal] ---- False diff --git a/modules/ztp-site-cleanup.adoc b/modules/ztp-site-cleanup.adoc index 339484666454..0cc499579b79 100644 --- a/modules/ztp-site-cleanup.adoc +++ b/modules/ztp-site-cleanup.adoc @@ -6,6 +6,7 @@ [id="ztp-site-cleanup_{context}"] = Removing a managed cluster site from the {ztp} pipeline +[role="_abstract"] You can remove a managed site and the associated installation and configuration policy CRs from the {ztp-first} pipeline. .Prerequisites diff --git a/modules/ztp-talo-integration.adoc b/modules/ztp-talo-integration.adoc index 2c39461e233c..074b4d8418d7 100644 --- a/modules/ztp-talo-integration.adoc +++ b/modules/ztp-talo-integration.adoc @@ -6,6 +6,7 @@ [id="ztp-talo-integration_{context}"] = {ztp} and {cgu-operator-full} +[role="_abstract"] {ztp-first} generates installation and configuration CRs from manifests stored in Git. These artifacts are applied to a centralized hub cluster where {rh-rhacm-first}, the assisted service, and the {cgu-operator-first} use the CRs to install and configure the managed cluster. The configuration phase of the {ztp} pipeline uses the {cgu-operator} to orchestrate the application of the configuration CRs to the cluster. There are several key integration points between {ztp} and the {cgu-operator}. Inform policies:: diff --git a/modules/ztp-tearing-down-the-pipeline.adoc b/modules/ztp-tearing-down-the-pipeline.adoc index bf053c4f9670..c1975c464aa5 100644 --- a/modules/ztp-tearing-down-the-pipeline.adoc +++ b/modules/ztp-tearing-down-the-pipeline.adoc @@ -6,6 +6,7 @@ [id="ztp-tearing-down-the-pipeline_{context}"] = Tearing down the {ztp} pipeline +[role="_abstract"] You can remove the ArgoCD pipeline and all generated {ztp-first} artifacts. .Prerequisites diff --git a/modules/ztp-troubleshooting-ztp-gitops-installation-crs.adoc b/modules/ztp-troubleshooting-ztp-gitops-installation-crs.adoc index 5fdf3600c47e..be22eac60dc2 100644 --- a/modules/ztp-troubleshooting-ztp-gitops-installation-crs.adoc +++ b/modules/ztp-troubleshooting-ztp-gitops-installation-crs.adoc @@ -6,6 +6,7 @@ [id="ztp-troubleshooting-ztp-gitops-installation-crs_{context}"] = Troubleshooting {ztp} by validating the installation CRs +[role="_abstract"] The ArgoCD pipeline uses the `ClusterInstance` and `PolicyGenerator` or `PolicyGentemplate` custom resources (CRs) to generate the cluster configuration CRs and {rh-rhacm-first} policies. Use the following steps to troubleshoot issues that might occur during this process. .Prerequisites diff --git a/modules/ztp-troubleshooting-ztp-gitops-supermicro-tls.adoc b/modules/ztp-troubleshooting-ztp-gitops-supermicro-tls.adoc index b06e5e3d8cab..1f3f08d9db61 100644 --- a/modules/ztp-troubleshooting-ztp-gitops-supermicro-tls.adoc +++ b/modules/ztp-troubleshooting-ztp-gitops-supermicro-tls.adoc @@ -6,6 +6,7 @@ [id="ztp-troubleshooting-ztp-gitops-supermicro-tls_{context}"] = Troubleshooting {ztp} virtual media booting on SuperMicro servers +[role="_abstract"] SuperMicro X11 servers do not support virtual media installations when the image is served using the `https` protocol. As a result, {sno} deployments for this environment fail to boot on the target node. To avoid this issue, log in to the hub cluster and disable Transport Layer Security (TLS) in the `Provisioning` resource. This ensures the image is not served with TLS even though the image address uses the `https` scheme. .Prerequisites diff --git a/modules/ztp-verifying-ipsec.adoc b/modules/ztp-verifying-ipsec.adoc index fc656cbc6684..162c8991c9c8 100644 --- a/modules/ztp-verifying-ipsec.adoc +++ b/modules/ztp-verifying-ipsec.adoc @@ -6,6 +6,7 @@ [id="ztp-verifying-ipsec_{context}"] = Verifying the IPsec encryption +[role="_abstract"] You can verify that the IPsec encryption is successfully applied in a managed {product-title} cluster. .Prerequisites @@ -32,7 +33,8 @@ $ oc debug node/ sh-5.1# ip xfrm policy ---- + -.Example output +The following example output shows the IPsec policy applied to the cluster node: ++ [source,terminal] ---- src 172.16.123.0/24 dst 10.1.232.10/32 @@ -56,7 +58,8 @@ src 10.1.232.10/32 dst 172.16.123.0/24 sh-5.1# ip xfrm state ---- + -.Example output +The following example output shows the IPsec tunnel is up and connected: ++ [source,terminal] ---- src 10.1.232.10 dst 10.1.28.190 @@ -87,7 +90,8 @@ For example, ping an IP address in the `rightsubnet` range that you set in the ` sh-5.1# ping 172.16.110.8 ---- + -.Example output +The following example output shows a successful ping response: ++ [source,terminal] ---- PING 172.16.110.8 (172.16.110.8) 56(84) bytes of data. diff --git a/modules/ztp-ztp-building-blocks.adoc b/modules/ztp-ztp-building-blocks.adoc index b5afa92a2c37..c8f0369e0b6a 100644 --- a/modules/ztp-ztp-building-blocks.adoc +++ b/modules/ztp-ztp-building-blocks.adoc @@ -6,6 +6,7 @@ [id="ztp-ztp-building-blocks_{context}"] = Overview of deploying managed clusters with {ztp} +[role="_abstract"] {rh-rhacm-first} uses {ztp-first} to deploy single-node {product-title} clusters, three-node clusters, and standard clusters. You manage site configuration data as {product-title} custom resources (CRs) in a Git repository. {ztp} uses a declarative GitOps approach for a develop once, deploy anywhere model to deploy the managed clusters. The deployment of the clusters includes: @@ -20,20 +21,8 @@ The deployment of the clusters includes: * Deploying profile Operators and performing any needed software-related configuration, such as performance profile, PTP, and SR-IOV - -[id="ztp-overview-managed-site-installation-process_{context}"] -== Overview of the managed site installation process - -After you apply the managed site custom resources (CRs) on the hub cluster, the following actions happen automatically: - -. A Discovery image ISO file is generated and booted on the target host. - -. When the ISO file successfully boots on the target host it reports the host hardware information to {rh-rhacm}. - -. After all hosts are discovered, {product-title} is installed. - -. When {product-title} finishes installing, the hub installs the `klusterlet` service on the target cluster. - -. The requested add-on services are installed on the target cluster. - -The Discovery image ISO process is complete when the `Agent` CR for the managed cluster is created on the hub cluster. +[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". +====