[OSDOCS-20299]: CQA: HCP on bare metal disconnected (1 of 2)

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]
 
@@ -34,6 +48,7 @@ include::modules/hcp-dc-image-mirror.adoc[leveloffset=+1]
 .Additional resources
 * xref:../../disconnected/about-installing-oc-mirror-v2.adoc#oc-mirror-workflows-partially-disconnected-v2_about-installing-oc-mirror-v2[Mirroring an image set in a partially disconnected environment]
 * xref:../../disconnected/about-installing-oc-mirror-v2.adoc#oc-mirror-workflows-fully-disconnected-v2_about-installing-oc-mirror-v2[Mirroring an image set in a fully disconnected environment]
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.16/html/clusters/cluster_mce_overview#install-on-disconnected-networks[Install on disconnected networks]
 
 include::modules/hcp-dc-apply-objects.adoc[leveloffset=+1]
 
@@ -43,19 +58,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]
 

modules/hcp-agentserviceconfig.adoc

@@ -6,13 +6,14 @@
 [id="hcp-agentserviceconfig_{context}"]
 = Deploying AgentServiceConfig resources
 
-The `AgentServiceConfig` custom resource is an essential component of the Assisted Service add-on that is part of {mce-short}. It is responsible for bare metal cluster deployment. When the add-on is enabled, you deploy the `AgentServiceConfig` resource to configure the add-on.
+[role="_abstract"]
+The `AgentServiceConfig` custom resource is an essential component of the Assisted Service add-on that is part of {mce-short}. It is responsible for bare-metal cluster deployment. When the add-on is enabled, you deploy the `AgentServiceConfig` resource to configure the add-on.
 
 In addition to configuring the `AgentServiceConfig` resource, you need to include additional config maps to ensure that {mce-short} functions properly in a disconnected environment.
 
 .Procedure
 
-. Configure the custom registries by adding the following config map, which contains the disconnected details to customize the deployment:
+. Configure the custom registries by adding the following config map, which includes the disconnected details to customize the deployment:
 +
 [source,yaml]
 ----
@@ -36,7 +37,7 @@ data:
     mirror-by-digest-only = true
 
     [[registry.mirror]]
-      location = "registry.dns.base.domain.name:5000/openshift4" <1>
+      location = "registry.dns.base.domain.name:5000/openshift4"
 
     [[registry]]
     prefix = ""
@@ -46,12 +47,12 @@ data:
     # ...
 ----
 +
-<1> Replace `dns.base.domain.name` with the DNS base domain name.
+Replace `dns.base.domain.name` with the DNS base domain name.
 +
-The object contains two fields:
+The object has two fields:
 
-* Custom CAs: This field contains the Certificate Authorities (CAs) that are loaded into the various processes of the deployment.
-* Registries: The `Registries.conf` field contains information about images and namespaces that need to be consumed from a mirror registry rather than the original source registry.
+* Custom CAs: This field has the Certificate Authorities (CAs) that are loaded into the various processes of the deployment.
+* Registries: The `Registries.conf` field has information about images and namespaces that need to be consumed from a mirror registry rather than the original source registry.
 
 . Configure the Assisted Service by adding the `AssistedServiceConfig` object, as shown in the following example:
 +
@@ -61,12 +62,12 @@ apiVersion: agent-install.openshift.io/v1beta1
 kind: AgentServiceConfig
 metadata:
   annotations:
-    unsupported.agent-install.openshift.io/assisted-service-configmap: assisted-service-config <1>
+    unsupported.agent-install.openshift.io/assisted-service-configmap: assisted-service-config
   name: agent
   namespace: multicluster-engine
 spec:
   mirrorRegistryRef:
-    name: custom-registries <2>
+    name: custom-registries
   databaseStorage:
     storageClassName: lvms-vg1
     accessModes:
@@ -81,24 +82,25 @@ spec:
     resources:
       requests:
         storage: 20Gi
-  osImages: <3>
-  - cpuArchitecture: x86_64 <4>
+  osImages:
+  - cpuArchitecture: x86_64
     openshiftVersion: "4.14"
-    rootFSUrl: http://registry.dns.base.domain.name:8080/images/rhcos-414.92.202308281054-0-live-rootfs.x86_64.img <5>
+    rootFSUrl: http://registry.dns.base.domain.name:8080/images/rhcos-414.92.202308281054-0-live-rootfs.x86_64.img
     url: http://registry.dns.base.domain.name:8080/images/rhcos-414.92.202308281054-0-live.x86_64.iso
     version: 414.92.202308281054-0
   - cpuArchitecture: x86_64
-   openshiftVersion: "4.15"
-   rootFSUrl: http://registry.dns.base.domain.name:8080/images/rhcos-415.92.202403270524-0-live-rootfs.x86_64.img
-   url: http://registry.dns.base.domain.name:8080/images/rhcos-415.92.202403270524-0-live.x86_64.iso
-   version: 415.92.202403270524-0
+    openshiftVersion: "4.15"
+    rootFSUrl: http://registry.dns.base.domain.name:8080/images/rhcos-415.92.202403270524-0-live-rootfs.x86_64.img
+    url: http://registry.dns.base.domain.name:8080/images/rhcos-415.92.202403270524-0-live.x86_64.iso
+    version: 415.92.202403270524-0
 ----
 +
-<1> The `metadata.annotations["unsupported.agent-install.openshift.io/assisted-service-configmap"]` annotation references the config map name that the Operator consumes to customize behavior.
-<2> The `spec.mirrorRegistryRef.name` annotation points to the config map that contains disconnected registry information that the Assisted Service Operator consumes. This config map adds those resources during the deployment process.
-<3> The `spec.osImages` field contains different versions available for deployment by this Operator. This field is mandatory. This example assumes that you already downloaded the `RootFS` and `LiveISO` files.
-<4> Add a `cpuArchitecture` subsection for every {product-title} release that you want to deploy. In this example, `cpuArchitecture` subsections are included for 4.14 and 4.15.
-<5> In the `rootFSUrl` and `url` fields, replace `dns.base.domain.name` with the DNS base domain name.
+* `metadata.annotations["unsupported.agent-install.openshift.io/assisted-service-configmap"]` references the config map name that the Operator consumes to customize behavior.
+* `spec.mirrorRegistryRef.name` points to the config map that has disconnected registry information that the Assisted Service Operator consumes. This config map adds those resources during the deployment process.
+* `spec.osImages` contains different versions available for deployment by this Operator. This field is mandatory. This example assumes that you already downloaded the `RootFS` and `LiveISO` files.
+* `cpuArchitecture` is added for every {product-title} release that you want to deploy. In this example, `cpuArchitecture` subsections are included for 4.14 and 4.15.
+* `osImages.rootFSUrl` includes `dns.base.domain.name`. Replace that value with the DNS base domain name.
+* `osImages.url` includes `dns.base.domain.name`. Replace that value with the DNS base domain name.
 
 . Deploy all of the objects by concatenating them into a single file and applying them to the management cluster. To do so, enter the following command:
 +
@@ -112,12 +114,12 @@ The command triggers two pods.
 .Example output
 [source,terminal]
 ----
-assisted-image-service-0                               1/1     Running   2             11d <1>
-assisted-service-668b49548-9m7xw                       2/2     Running   5             11d <2>
+assisted-image-service-0                               1/1     Running   2             11d
+assisted-service-668b49548-9m7xw                       2/2     Running   5             11d
 ----
 +
-<1> The `assisted-image-service` pod is responsible for creating the Red Hat Enterprise Linux CoreOS (RHCOS) boot image template, which is customized for each cluster that you deploy.
-<2> The `assisted-service` refers to the Operator.
+* The `assisted-image-service` pod is responsible for creating the {op-system-first} boot image template, which is customized for each cluster that you deploy.
+* The `assisted-service` refers to the Operator.
 
 .Next steps
 

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}"]

modules/hcp-dc-apply-objects.adoc

@@ -7,7 +7,10 @@
 [id="hcp-dc-apply-objects_{context}"]
 = Applying objects in the management cluster
 
-After the mirroring process is complete, you need to apply two objects in the management cluster:
+[role="_abstract"]
+After the mirroring process is complete, you need to apply two objects in the management cluster.
+
+You apply the following objects:
 
 * `ImageContentSourcePolicy` (ICSP) or `ImageDigestMirrorSet` (IDMS)
 * Catalog sources
@@ -55,9 +58,9 @@ When you use the `management` (default) OLMCatalogPlacement mode, the image stre
 ** `hypershift.openshift.io/community-operators-catalog-image`
 ** `hypershift.openshift.io/redhat-marketplace-catalog-image`
 ** `hypershift.openshift.io/redhat-operators-catalog-image`
-
++
 In this case, the image stream is not created, and you must update the value of the annotations when the internal mirror is refreshed to pull in Operator updates.
 
 .Next steps
 
-Deploy the {mce-short} by completing the steps in _Deploying {mce-short} for a disconnected installation of {hcp}_.
+Deploy the {mce-short} by completing the steps in "Deploying {mce-short} for a disconnected installation of {hcp}".

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:
 +

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. 

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

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
 ----