[OSDOCS-15316]: Creating a hosted cluster on bare metal

lahinson · lahinson · commit daa7c37cf9f3 · 2025-07-17T15:38:59.000-04:00
diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc
@@ -48,11 +48,17 @@ include::modules/hcp-bm-infra-reqs.adoc[leveloffset=+2]
 include::modules/hcp-bm-dns.adoc[leveloffset=+1]
 include::modules/hcp-custom-dns.adoc[leveloffset=+2]
 
-include::modules/hcp-bm-hc.adoc[leveloffset=+1]
+[id="hcp-bm-create-hc"]
+== Creating a hosted cluster on bare metal
+
+When you create a hosted cluster with the Agent platform, the HyperShift Operator installs the Agent Cluster API provider in the hosted control plane namespace. You can create a hosted cluster on bare metal or you can import one.
+
+include::modules/hcp-bm-hc.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 * xref:../../hosted_control_planes/hcp-import.adoc[Manually importing a hosted cluster]
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#configure-hosted-disconnected-digest-image[Extracting the {product-title} release image digest]
 
 include::modules/hcp-bm-hc-console.adoc[leveloffset=+2]
 
@@ -65,6 +71,7 @@ include::modules/hcp-bm-hc-mirror.adoc[leveloffset=+2]
 * To create credentials that you can reuse when you create a hosted cluster with the console, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#creating-a-credential-for-an-on-premises-environment[Creating a credential for an on-premises environment].
 * To access a hosted cluster, see xref:../../hosted_control_planes/hcp-manage/hcp-manage-bm.adoc#hcp-bm-access_hcp-manage-bm[Accessing the hosted cluster].
 * To add hosts to the host inventory by using the Discovery Image, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#add-host-host-inventory[Adding hosts to the host inventory by using the Discovery Image].
-* To extract the {product-title} release image digest, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#configure-hosted-disconnected-digest-image[Extracting the {product-title} release image digest].
 
-include::modules/hcp-bm-verify.adoc[leveloffset=+1]
+include::modules/hcp-bm-infraenv.adoc[leveloffset=+1]
+
+include::modules/hcp-bm-verify.adoc[leveloffset=+1]
diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc
@@ -37,7 +37,17 @@ include::modules/hcp-ibm-power-infra-reqs.adoc[leveloffset=+1]
 include::modules/hcp-ibm-power-dns.adoc[leveloffset=+1]
 include::modules/hcp-custom-dns.adoc[leveloffset=+2]
 
-include::modules/hcp-bm-hc.adoc[leveloffset=+1]
+[id="hcp-bm-create-hc-ibm-power"]
+== Creating a hosted cluster on bare metal
+
+When you create a hosted cluster with the Agent platform, the HyperShift Operator installs the Agent Cluster API provider in the hosted control plane namespace. You can create a hosted cluster on bare metal or you can import one.
+
+include::modules/hcp-bm-hc.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../hosted_control_planes/hcp-import.adoc[Manually importing a hosted cluster]
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#configure-hosted-disconnected-digest-image[Extracting the {product-title} release image digest]
 
 [id="hcp-ibm-power-heterogeneous-nodepools_{context}"]
 == Creating heterogeneous node pools on agent hosted clusters
diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc
@@ -50,7 +50,17 @@ include::modules/hcp-bm-hc.adoc[leveloffset=+1]
 
 * xref:../../hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc#hcp-bm-hc-console_hcp-deploy-bm[Creating a hosted cluster on bare metal by using the console]
 
-include::modules/hcp-ibm-z-infraenv.adoc[leveloffset=+1]
+[id="hcp-bm-create-hc-ibm-z"]
+== Creating a hosted cluster on bare metal
+
+When you create a hosted cluster with the Agent platform, the HyperShift Operator installs the Agent Cluster API provider in the hosted control plane namespace. You can create a hosted cluster on bare metal or you can import one.
+
+include::modules/hcp-bm-hc.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../hosted_control_planes/hcp-import.adoc[Manually importing a hosted cluster]
+* link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#configure-hosted-disconnected-digest-image[Extracting the {product-title} release image digest]
 
 [id="hcp-ibm-z-add-agents"]
 == Adding {ibm-z-title} agents to the InfraEnv resource
diff --git a/modules/hcp-bm-hc.adoc b/modules/hcp-bm-hc.adoc
@@ -6,11 +6,13 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="hcp-bm-hc_{context}"]
-= Creating a hosted cluster on bare metal
+= Creating a hosted cluster by using the CLI
 
-When you create a hosted cluster with the Agent platform, HyperShift installs the Agent Cluster API provider in the hosted control plane namespace. You can create a hosted cluster on bare metal or import one.
+To create a hosted cluster by using the command-line interface (CLI), complete the following steps.
 
-As you create a hosted cluster, keep the following guidelines in mind:
+.Prerequisites
+
+As you create a hosted cluster, remember these requirements:
 
 - Each hosted cluster must have a cluster-wide unique name. A hosted cluster name cannot be the same as any existing managed cluster in order for {mce-short} to manage it.
 
@@ -20,6 +22,8 @@ As you create a hosted cluster, keep the following guidelines in mind:
 
 - The most common service publishing strategy is to expose services through a load balancer. That strategy is the preferred method for exposing the Kubernetes API server. If you create a hosted cluster by using the web console or by using {rh-rhacm-title}, to set a publishing strategy for a service besides the Kubernetes API server, you must manually specify the `servicePublishingStrategy` information in the `HostedCluster` custom resource.
 
+- Ensure that you meet the requirements described in "Preparing to deploy {hcp} on bare metal", which includes requirements related to infrastructure, firewalls, ports, and services.
+
 .Procedure
 
 . Create the hosted control plane namespace by entering the following command:
@@ -29,9 +33,9 @@ As you create a hosted cluster, keep the following guidelines in mind:
 $ oc create ns <hosted_cluster_namespace>-<hosted_cluster_name>
 ----
 +
-Replace `<hosted_cluster_namespace>` with your hosted cluster namespace name, for example, `clusters`. Replace `<hosted_cluster_name>` with your hosted cluster name.
+Replace `<hosted_cluster_namespace>` with your hosted cluster namespace name, for example, `my-hosted-ns`. Replace `<hosted_cluster_name>` with your hosted cluster name, for example, `my-hosted-cluster`. Typically, the namespace is created by the HyperShift Operator, but during the hosted cluster creation process on bare metal, a Cluster API provider role is generated that needs the namespace to already exist.
 
-. Verify that you have a default storage class configured for your cluster. Otherwise, you might see pending PVCs. Run the following command:
+. Verify that you have a default storage class configured for your cluster by running the following command. Otherwise, you might see pending PVCs.
 +
 [source,terminal]
 ----
@@ -45,20 +49,20 @@ $ hcp create cluster agent \
     --ssh-key  <path_to_ssh_public_key> \// <7>
     --namespace <hosted_cluster_namespace> \// <8>
     --control-plane-availability-policy HighlyAvailable \// <9>
-    --release-image=quay.io/openshift-release-dev/ocp-release:<ocp_release_image> \// <10>
+    --release-image=quay.io/openshift-release-dev/ocp-release:<ocp_release_image>-multi \// <10>
     --node-pool-replicas <node_pool_replica_count> <11>
 ----
 +
-<1> Specify the name of your hosted cluster, for instance, `example`.
+<1> Specify the name of your hosted cluster, for instance, `my-hosted-cluster`.
 <2> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
-<3> Specify your hosted control plane namespace, for example, `clusters-example`. Ensure that agents are available in this namespace by using the `oc get agent -n <hosted_control_plane_namespace>` command.
+<3> Specify your hosted control plane namespace, for example, `my-hcp-ns`. Ensure that agents are available in this namespace by using the `oc get agent -n <hosted_control_plane_namespace>` command.
 <4> Specify your base domain, for example, `krnl.es`.
 <5> The `--api-server-address` flag defines the IP address that is used for the Kubernetes API communication in the hosted cluster. If you do not set the `--api-server-address` flag, you must log in to connect to the management cluster.
 <6> Specify the etcd storage class name, for example, `lvm-storageclass`.
 <7> Specify the path to your SSH public key. The default file path is `~/.ssh/id_rsa.pub`.
-<8> Specify your hosted cluster namespace.
+<8> Specify your hosted cluster namespace, for example, `my-hosted-ns`.
 <9> Specify the availability policy for the hosted control plane components. Supported options are `SingleReplica` and `HighlyAvailable`. The default value is `HighlyAvailable`.
-<10> Specify the supported {product-title} version that you want to use, for example, `4.19.0-multi`. If you are using a disconnected environment, replace `<ocp_release_image>` with the digest image. To extract the {product-title} release image digest, see _Extracting the {product-title} release image digest_.
+<10> Specify the supported {product-title} version that you want to use, for example, `4.19.0-multi`. If you are using a disconnected environment, replace `<ocp_release_image>` with the digest image. To extract the {product-title} release image digest, see "Extracting the {product-title} release image digest".
 <11> Specify the node pool replica count, for example, `3`. You must specify the replica count as `0` or greater to create the same number of replicas. Otherwise, no node pools are created.
 
 +
diff --git a/modules/hcp-bm-infraenv.adoc b/modules/hcp-bm-infraenv.adoc
@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-bm-infraenv_{context}"]
+= Creating an InfraEnv resource for a hosted cluster on bare metal
+
+An `InfraEnv` is an environment where hosts that are booted with PXE images can join as agents. In this case, the agents are created in the same namespace as your hosted control plane.
+
+.Procedure
+
+. Create a YAML file to contain the configuration. See the following example:
++
+[source,yaml]
+----
+apiVersion: agent-install.openshift.io/v1beta1
+kind: InfraEnv
+metadata:
+  name: <hosted_cluster_name>
+  namespace: <hosted_control_plane_namespace>
+spec:
+  cpuArchitecture: s390x
+  pullSecretRef:
+    name: pull-secret
+  sshAuthorizedKey: <ssh_public_key>
+----
+
+. Save the file as `infraenv-config.yaml`.
+
+. Apply the configuration by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f infraenv-config.yaml
+----
+
+. To fetch the URL to download the PXE images, such as, `initrd.img`, `kernel.img`, or `rootfs.img`, which allows {ibm-z-title} machines to join as agents, enter the following command:
++
+[source,terminal]
+----
+$ oc -n <hosted_control_plane_namespace> get InfraEnv <hosted_cluster_name> -o json
+----
