openshift · lahinson · Jun 22, 2026 · lahinson · Jun 22, 2026
diff --git a/hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc b/hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc
@@ -1,15 +1,30 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="hcp-deploy-dc-bm"]
-include::_attributes/common-attributes.adoc[]
 = Deploying {hcp} on bare metal in a disconnected environment
+include::_attributes/common-attributes.adoc[]
 :context: hcp-deploy-dc-bm
 
 toc::[]
 
-When you provision {hcp} on bare metal, you use the Agent platform. The Agent platform and {mce} work together to enable disconnected deployments. The Agent platform uses the central infrastructure management service to add worker nodes to a hosted cluster. For an introduction to the central infrastructure management service, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/html/clusters/cluster_mce_overview#enable-cim[Enabling the central infrastructure management service].
+[role="_abstract"]
+In the context of {hcp}, a disconnected environment is an {product-title} deployment that is not connected to the internet and that uses {hcp} as a base. You can deploy {hcp} in a disconnected environment on bare metal.
+
+When you provision {hcp} on bare metal, you use the Agent platform. The Agent platform and {mce} work together to enable disconnected deployments. The Agent platform uses the central infrastructure management service to add worker nodes to a hosted cluster. For an introduction to the central infrastructure management service, see "Enabling the central infrastructure management service".
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/html/clusters/cluster_mce_overview#enable-cim[Enabling the central infrastructure management service]
 
 include::modules/hcp-dc-bm-arch.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc#hcp-dc-tls-mgmt_hcp-deploy-dc-bm[Adding the registry CA to the management cluster]
+
+* xref:../../hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc#hcp-dc-tls-hosted_hcp-deploy-dc-bm[Adding the registry CA to the compute nodes for the hosted cluster]
+
 include::modules/hcp-dc-bm-reqs.adoc[leveloffset=+1]
 
 include::modules/hcp-dc-extract.adoc[leveloffset=+1]
@@ -23,8 +38,7 @@ include::modules/hcp-dc-mgmt-cluster.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/html/clusters/cluster_mce_overview#mce-install-intro[Installing and upgrading multicluster engine operator]
-* xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.html#hcp-enable-manual-addon_hcp-enable-disable[Manually enabling the hypershift-addon managed cluster add-on for local-cluster]
-* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/html/clusters/cluster_mce_overview#mce-intro[About cluster lifecycle with multicluster engine operator]
+* xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.adoc#hcp-enable-manual-addon_hcp-enable-disable[Manually enabling the hypershift-addon managed cluster add-on for local-cluster]
 
 include::modules/hcp-dc-web-server.adoc[leveloffset=+1]
 
@@ -43,19 +57,11 @@ include::modules/hcp-dc-apply-objects.adoc[leveloffset=+1]
 
 include::modules/hcp-agentserviceconfig.adoc[leveloffset=+1]
 
-[id="hcp-dc-tls-bm"]
-== Configuring TLS certificates for a disconnected installation of {hcp}
-
-To ensure proper function in a disconnected deployment, you need to configure the registry CA certificates in the management cluster and the worker nodes for the hosted cluster.
-
-include::modules/hcp-dc-tls-mgmt.adoc[leveloffset=+2]
-
-include::modules/hcp-dc-tls-hosted.adoc[leveloffset=+2]
+include::modules/hcp-dc-tls-mgmt.adoc[leveloffset=+1]
 
-[id="hcp-dc-bm-hosted"]
-== Creating a hosted cluster on bare metal
+include::modules/hcp-dc-tls-hosted.adoc[leveloffset=+1]
 
-A hosted cluster is an {product-title} cluster with its control plane and API endpoint hosted on a management cluster. The hosted cluster includes the control plane and its corresponding data plane.
+include::modules/hcp-dc-bm-hosted.adoc[leveloffset=+1]
 
 include::modules/hcp-hc-objects.adoc[leveloffset=+2]
 

diff --git a/modules/hcp-bm-dns.adoc b/modules/hcp-bm-dns.adoc
@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
 // * hosted_control_planes/hcp-deploy-bm.adoc
+// * hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="hcp-bm-dns_{context}"]

diff --git a/modules/hcp-dc-bm-arch.adoc b/modules/hcp-dc-bm-arch.adoc
@@ -2,10 +2,13 @@
 //
 // * hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: REFERENCE
 [id="hcp-dc-bm-arch_{context}"]
 = Disconnected environment architecture for bare metal
 
+[role="_abstract"]
+Get familiar with the architecture for a deployment of {hcp} on bare metal in a disconnected environment.
+
 The following diagram illustrates an example architecture of a disconnected environment:
 
 image:../images/489_RHACM_HyperShift_on_bare_metal_1223.png[Disconnected architecture diagram]
@@ -16,7 +19,7 @@ image:../images/489_RHACM_HyperShift_on_bare_metal_1223.png[Disconnected archite
 * Key: `<registry_dns_domain_name>..<port>`, for example, `registry.hypershiftdomain.lab..5000:`. Ensure that you place `..` after the registry DNS domain name when you specify a port.
 * Value: The certificate content
 +
-For more information about creating a config map, see _Configuring TLS certificates for a disconnected installation of {hcp}_.
+For more information about creating a config map, see "Adding the registry CA to the management cluster" and "Adding the registry CA to the compute nodes for the hosted cluster".
 . Modify the `images.config.openshift.io` custom resource (CR) specification and adds a new field named `additionalTrustedCA` with a value of `name: registry-config`.
 . Create a config map that contains two data fields. One field contains the `registries.conf` file in `RAW` format, and the other field contains the Registry CA and is named `ca-bundle.crt`. The config map belongs to the `multicluster-engine` namespace, and the config map name is referenced in other objects. For an example of a config map, see the following sample configuration:
 +

diff --git a/modules/hcp-dc-bm-hosted.adoc b/modules/hcp-dc-bm-hosted.adoc
@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="hcp-dc-bm-hosted_{context}"]
+= Hosted clusters on bare metal in a disconnected environment
+
+[role="_abstract"]
+In a disconnected environment, creating a hosted cluster involves deploying hosted cluster objects, creating node pools, creating an `InfraEnv` resource, creating bare-metal hosts, and scaling the node pools as needed.
+
+A hosted cluster is an {product-title} cluster with its control plane and API endpoint hosted on a management cluster. The hosted cluster includes the corresponding data plane. 
diff --git a/modules/hcp-dc-bm-reqs.adoc b/modules/hcp-dc-bm-reqs.adoc
@@ -6,15 +6,16 @@
 [id="hcp-dc-bm-reqs_{context}"]
 = Requirements to deploy {hcp} on bare metal in a disconnected environment
 
-To configure {hcp} in a disconnected environment, you must meet the following prerequisites:
+[role="_abstract"]
+To configure {hcp} in a disconnected environment, you must meet several prerequisites.
 
-- CPU: The number of CPUs provided determines how many hosted clusters can run concurrently. In general, use 16 CPUs for each node for 3 nodes. For minimal development, you can use 12 CPUs for each node for 3 nodes.
-- Memory: The amount of RAM affects how many hosted clusters can be hosted. Use 48 GB of RAM for each node. For minimal development, 18 GB of RAM might be sufficient.
-- Storage: Use SSD storage for {mce-short}.
+* CPU: The number of CPUs provided determines how many hosted clusters can run concurrently. In general, use 16 CPUs for each node for 3 nodes. For minimal development, you can use 12 CPUs for each node for 3 nodes.
+* Memory: The amount of RAM affects how many hosted clusters can be hosted. Use 48 GB of RAM for each node. For minimal development, 18 GB of RAM might be sufficient.
+* Storage: Use SSD storage for {mce-short}.
 * Management cluster: 250 GB.
 * Registry: The storage needed depends on the number of releases, operators, and images that are hosted. An acceptable number might be 500 GB, preferably separated from the disk that hosts the hosted cluster.
 * Web server: The storage needed depends on the number of ISOs and images that are hosted. An acceptable number might be 500 GB.
-- Production: For a production environment, separate the management cluster, the registry, and the web server on different disks. This example illustrates a possible configuration for production:
+* Production: For a production environment, separate the management cluster, the registry, and the web server on different disks. This example illustrates a possible configuration for production:
 * Registry: 2 TB
 * Management cluster: 500 GB
 * Web server: 2 TB
diff --git a/modules/hcp-dc-extract.adoc b/modules/hcp-dc-extract.adoc
@@ -2,11 +2,12 @@
 //
 // * hosted_control_planes/hcp-disconnected/hcp-deploy-dc-bm.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: PROCEDURE
 [id="hcp-dc-extract_{context}"]
 = Extracting the release image digest
 
-You can extract the {product-title} release image digest by using the tagged image.
+[role="_abstract"]
+To deploy {hcp} on bare metal in a disconnected environment, you need the {product-title} release image. You can extract the release image digest by using the tagged image.
 
 .Procedure
 
@@ -20,7 +21,7 @@ $ oc adm release info <tagged_openshift_release_image> | grep "Pull From"
 Replace `<tagged_openshift_release_image>` with the tagged image for the supported {product-title} version, for example, `quay.io/openshift-release-dev/ocp-release:4.14.0-x8_64`.
 +
 .Example output
-+
+[source,terminal]
 ----
 Pull From: quay.io/openshift-release-dev/ocp-release@sha256:69d1292f64a2b67227c5592c1a7d499c7d00376e498634ff8e1946bc9ccdddfe
 ----
diff --git a/modules/hcp-dc-mgmt-cluster.adoc b/modules/hcp-dc-mgmt-cluster.adoc
@@ -6,7 +6,8 @@
 [id="hcp-dc-mgmt-cluster_{context}"]
 = Setting up a management cluster for {hcp} in a disconnected environment
 
-To set up an {product-title} management cluster, you need to ensure that the {mce} is installed. The {mce-short} plays a crucial role in deploying clusters across providers.
+[role="_abstract"]
+An important part of a {hcp} deployment is the {product-title} management cluster. To set up an management cluster for a disconnected environment, you install {mce} on it. The {mce-short} plays a crucial role in deploying clusters across providers.
 
 .Prerequisites
 
@@ -24,7 +25,7 @@ To set up an {product-title} management cluster, you need to ensure that the {mc
 
 .Procedure
 
-. Install {mce-short} 2.4 or later on an {product-title} cluster. You can install {mce-short} as an Operator from the {product-title} software catalog. The HyperShift Operator is included with {mce-short}. For more information about installing {mce-short}, see "Installing and upgrading multicluster engine operator" in the Red{nbsp}Hat Advanced Cluster Management documentation.
+. Install {mce-short} 2.7 or later on an {product-title} cluster. You can install {mce-short} as an Operator from the {product-title} software catalog. The HyperShift Operator is included with {mce-short}. For more information about installing {mce-short}, see "Installing and upgrading multicluster engine operator" in the Red{nbsp}Hat Advanced Cluster Management documentation.
 
 . Ensure that the HyperShift Operator is installed. The HyperShift Operator is automatically included with {mce-short}, but if you need to manually install it, follow the steps in "Manually enabling the hypershift-addon managed cluster add-on for local-cluster".
 

diff --git a/modules/hcp-dc-registry.adoc b/modules/hcp-dc-registry.adoc
@@ -6,11 +6,12 @@
 [id="hcp-dc-registry_{context}"]
 = Deploying a registry for {hcp} in a disconnected environment
 
+[role="_abstract"]
 For development environments, deploy a small, self-hosted registry by using a Podman container. For production environments, deploy an enterprise-hosted registry, such as {quay}, Nexus, or Artifactory.
 
-.Procedure
+To deploy a small registry by using Podman, complete the following steps.
 
-To deploy a small registry by using Podman, complete the following steps:
+.Procedure
 
 . As a privileged user, access the `${HOME}` directory and create the following script:
 +
@@ -22,7 +23,7 @@ set -euo pipefail
 
 PRIMARY_NIC=$(ls -1 /sys/class/net | grep -v podman | head -1)
 export PATH=/root/bin:$PATH
-export PULL_SECRET="/root/baremetal/hub/openshift_pull.json" <1>
+export PULL_SECRET="/root/baremetal/hub/openshift_pull.json"
 
 if [[ ! -f $PULL_SECRET ]];then
   echo "Pull Secret not found, exiting..."
@@ -73,7 +74,7 @@ podman create --name registry --net host --security-opt label=disable --replace
 systemctl enable --now registry
 ----
 +
-<1> Replace the location of the `PULL_SECRET` with the appropriate location for your setup.
+Replace the location of the `PULL_SECRET` with the appropriate location for your setup.
 
 . Name the script file `registry.sh` and save it. When you run the script, it pulls in the following information: 
 +
@@ -96,23 +97,29 @@ $ ${HOME}/registry.sh
 +
 The script starts the server. The script uses a `systemd` service for management purposes. 
 
-. If you need to manage the script, you can use the following commands:
+. If you need to manage the script, you can use the following commands.
++
+.. To view the status, enter the following command:
 +
 [source,terminal]
 ----
 $ systemctl status
 ----
 +
+.. To start the script, enter the following command:
++
 [source,terminal]
 ----
 $ systemctl start
 ----
 +
+.. To stop the script, enter the following command:
++
 [source,terminal]
 ----
 $ systemctl stop
 ----
-
++
 The root folder for the registry is in the `/opt/registry` directory and contains the following subdirectories:
 
 * `certs` contains the TLS certificates.

diff --git a/modules/hcp-dc-tls-hosted.adoc b/modules/hcp-dc-tls-hosted.adoc
@@ -5,9 +5,10 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="hcp-dc-tls-hosted_{context}"]
-= Adding the registry CA to the worker nodes for the hosted cluster
+= Adding the registry CA to the compute nodes for the hosted cluster
 
-In order for the data plane workers in the hosted cluster to be able to retrieve images from the private registry, you need to add the registry CA to the worker nodes.
+[role="_abstract"]
+In order for the data plane compute nodes in the hosted cluster to be able to retrieve images from the private registry, you need to add the registry CA to the compute nodes.
 
 .Procedure
 
@@ -17,10 +18,10 @@ In order for the data plane workers in the hosted cluster to be able to retrieve
 ----
 spec:
   additionalTrustBundle:
-    name: user-ca-bundle <1>
+    name: user-ca-bundle
 ----
 +
-<1> The `user-ca-bundle` entry is a config map that you create in the next step.
+The `user-ca-bundle` entry is a config map that you create in the next step.
 
 . In the same namespace where the `HostedCluster` object is created, create the `user-ca-bundle` config map. The config map resembles the following example:
 +
@@ -44,7 +45,7 @@ data:
 kind: ConfigMap
 metadata:
   name: user-ca-bundle
-  namespace: <hosted_cluster_namespace> <1>
+  namespace: <hosted_cluster_namespace>
 ----
 +
-<1> Specify the namespace where the `HostedCluster` object is created.
+Specify the namespace where the `HostedCluster` object is created.
diff --git a/modules/hcp-dc-tls-mgmt.adoc b/modules/hcp-dc-tls-mgmt.adoc
@@ -7,6 +7,9 @@
 [id="hcp-dc-tls-mgmt_{context}"]
 = Adding the registry CA to the management cluster
 
+[role="_abstract"]
+To ensure proper function in a disconnected deployment, you need to configure the registry CA certificates in the management cluster.
+
 To add the registry CA to the management cluster, complete the following steps.
 
 .Procedure
@@ -18,10 +21,10 @@ To add the registry CA to the management cluster, complete the following steps.
 apiVersion: v1
 kind: ConfigMap
 metadata:
-  name: <config_map_name> <1>
-  namespace: <config_map_namespace> <2>
-data: <3>
-  <registry_name>..<port>: | <4>
+  name: <config_map_name>
+  namespace: <config_map_namespace>
+data:
+  <registry_name>..<port>: |
     -----BEGIN CERTIFICATE-----
     -----END CERTIFICATE-----
   <registry_name>..<port>: |
@@ -32,10 +35,9 @@ data: <3>
     -----END CERTIFICATE-----
 ----
 +
-<1> Specify the name of the config map.
-<2> Specify the namespace for the config map.
-<3> In the `data` field, specify the registry names and the registry certificate content. Replace `<port>` with the port where the registry server is running; for example, `5000`.
-<4> Ensure that the data in the config map is defined by using `|` only instead of other methods, such as `| -`. If you use other methods, issues can occur when the pod reads the certificates.
+* `metadata.name` specifies the name of the config map.
+* `metadata.namespace` specifies the namespace for the config map.
+* `data` specifies the registry names and the registry certificate content. Replace `<port>` with the port where the registry server is running; for example, `5000`. Ensure that the data in the config map is defined by using `|` only instead of other methods, such as `| -`. If you use other methods, issues can occur when the pod reads the certificates.
 
 . Patch the cluster-wide object, `image.config.openshift.io` to include the following specification:
 +