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

Author: lahinson

hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc

@@ -19,7 +19,7 @@ The {mce-short} supports only the default `local-cluster`, which is a hub cluste
 
 A _hosted cluster_ is an {product-title} cluster with its API endpoint and control plane that are hosted on the management cluster. The hosted cluster includes the control plane and its corresponding data plane. You can use the {mce-short} console or the hosted control plane command-line interface, `hcp`, to create a hosted cluster.
 
-The hosted cluster is automatically imported as a managed cluster. If you want to disable this automatic import feature, see _Disabling the automatic import of hosted clusters into {mce-short}_.
+The hosted cluster is automatically imported as a managed cluster. If you want to disable this automatic import feature, see "Disabling the automatic import of hosted clusters into {mce-short}".
 
 include::modules/hcp-bm-prepare.adoc[leveloffset=+1]
 include::modules/hcp-bm-prereqs.adoc[leveloffset=+2]
@@ -48,23 +48,47 @@ 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]
 
-.Next steps
-* To access the web console, see xref:../../web_console/web-console.adoc#web-console-overview[Accessing the web console].
+[role="_additional-resources"]
+.Additional resources
+* xref:../../web_console/web-console.adoc#web-console-overview[Accessing the web console]
 
 include::modules/hcp-bm-hc-mirror.adoc[leveloffset=+2]
 
-.Next steps
-* 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].
+[role="_additional-resources"]
+.Additional resources
+* 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]
+* 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]
+
+include::modules/hcp-bm-infraenv.adoc[leveloffset=+1]
 
 include::modules/hcp-bm-verify.adoc[leveloffset=+1]
+
+include::modules/hcp-bm-access.adoc[leveloffset=+1]
+include::modules/hcp-bm-scale-np.adoc[leveloffset=+1]
+include::modules/hcp-bm-add-np.adoc[leveloffset=+2]
+include::modules/hcp-bm-autoscale.adoc[leveloffset=+2]
+include::modules/hcp-bm-autoscale-disable.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../hosted_control_planes/hcp-troubleshooting.adoc#scale-down-data-plane_hcp-troubleshooting[Scaling down the data plane to zero]
+
+include::modules/hcp-bm-ingress.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../networking/networking_operators/metallb-operator/about-metallb.adoc#about-metallb_about-metallb[About MetalLB and the MetalLB Operator]

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

hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc

@@ -43,15 +43,19 @@ include::modules/hcp-ibm-z-infra-reqs.adoc[leveloffset=+1]
 include::modules/hcp-ibm-z-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-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]
 * 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-ibm-z-add-agents"]
 == Adding {ibm-z-title} agents to the InfraEnv resource
 

hosted_control_planes/hcp-deploy/hcp-deploy-non-bm.adoc

@@ -74,7 +74,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 access a hosted cluster, see xref:../../hosted_control_planes/hcp-manage/hcp-deploy-bm.adoc#hcp-bm-access_hcp-deploy-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].
 

hosted_control_planes/hcp-manage/hcp-manage-bm.adoc

@@ -8,28 +8,9 @@ toc::[]
 
 After you deploy {hcp} on bare metal, you can manage a hosted cluster by completing the following tasks.
 
-include::modules/hcp-bm-access.adoc[leveloffset=+1]
-include::modules/hcp-bm-scale-np.adoc[leveloffset=+1]
-include::modules/hcp-bm-add-np.adoc[leveloffset=+2]
-include::modules/hcp-bm-autoscale.adoc[leveloffset=+2]
-include::modules/hcp-bm-autoscale-disable.adoc[leveloffset=+2]
-
-[role="_additional-resources"]
-.Additional resources
-
-* xref:../../hosted_control_planes/hcp-troubleshooting.adoc#scale-down-data-plane_hcp-troubleshooting[Scaling down the data plane to zero]
-
-include::modules/hcp-bm-ingress.adoc[leveloffset=+1]
-
-[role="_additional-resources"]
-.Additional resources
-
-* xref:../../networking/networking_operators/metallb-operator/about-metallb.adoc#about-metallb_about-metallb[About MetalLB and the MetalLB Operator]
-
 include::modules/hcp-bm-machine-health.adoc[leveloffset=+1]
 include::modules/hcp-bm-machine-health-disable.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
-
 * xref:../../machine_management/deploying-machine-health-checks.adoc#deploying-machine-health-checks[Deploying machine health checks]

modules/hcp-bm-hc.adoc

@@ -6,11 +6,11 @@
 
 :_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
 
 - 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 +20,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 +31,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 +47,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.
 
 +

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