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

lahinson · 2025-07-17T16:52:04Z

Version(s): 4.17+

Issue: https://issues.redhat.com/browse/OSDOCS-15316

Link to docs preview:

Creating an infrastructure environment: https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-bm.html#hcp-bm-create-infra
Creating a hosted cluster on bare metal: https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-bm.html#hcp-bm-create-hc
Creating a hosted cluster on IBM Power: https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power#hcp-bm-create-hc-ibm-power
Creating a hosted cluster on IBM Z: https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-ibmz#hcp-bm-create-hc-ibm-z

QE review:

QE has approved this change.

Additional information:

modules/hcp-bm-infraenv.adoc

ocpdocs-previewbot · 2025-07-17T17:18:34Z

🤖 Fri Jul 25 17:02:35 - Prow CI generated the docs preview:

https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-bm.html
https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.html
https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.html
https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-non-bm.html
https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-manage/hcp-manage-bm.html
https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-manage/hcp-manage-non-bm.html
https://96275--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-manage/hcp-manage-virt.html

modules/hcp-bm-hc.adoc

hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc

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

racedo · 2025-07-21T08:34:17Z

modules/hcp-bm-hc.adoc

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


We suggest to use a load balancer but by default with the hcp create agent command the bare metal hosted clusters are created with node port: we should indicate this here. We also should explain how to change the servicePublishingStrategy in the section to create bare metal hosted clusters as otherwise we leave this for the user to research with not even references to where. @jparrill ptal

I updated the wording here, but I still need help to describe what users should do to change the servicePublishingStrategy. I've asked Juan for the details.

racedo

Add information about changing publishing strategy to recommended one for bare metal (load balancer) and explain it's not the default one

racedo · 2025-07-21T08:38:33Z

modules/hcp-bm-hc.adoc

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


We don't explain that in order to be able to add nodes to this cluster we must have previously added nodes to an InfraEnv (via web ui for example) and we don't explain how to do this. This leaves the user with a workflow that will always fail to complete as at this point the user hasn't been told how to add nodes to the inventory first.

I added a new procedure before this procedure about adding bare-metal nodes to a hardware inventory.

modules/hcp-bm-hc.adoc

modules/hcp-bm-add-nodes-to-inventory.adoc

modules/hcp-bm-hc.adoc

racedo · 2025-07-25T08:35:44Z

modules/hcp-bm-add-nodes-to-inventory.adoc

+  -n <namespace_example> get infraenv hosted
+----
+
+. Create `BareMetalHost` objects by adding the following content to a YAML file:


There are two options to get the hosts added:

BMHs, as described here, which the booting and adding to the InfraEnv are 100% automated by the bare metal operator (metal3).

Obtain the discovery ISO from the InfraEnv and boot the hosts manually, which is also supported and sometimes the only way (hosts that don't work with Redfish, hosts that don't have their BMCs configured, environments where the BMC network access is restricted, and other reasons).

We should document 2 along with this method for clarity.

@racedo Would it be accurate to distinguish between the two methods by dividing this step like this?
"If you use the Metal3 Operator, create the BMHs as follows..." and "If you do not use the Metal3 Operator, obtain the discovery ISO from the InfraEnv and boot the hosts manually, as follows..."

racedo

Add comment to explain booting hosts from discovery ISO.

racedo · 2025-07-25T08:39:01Z

modules/hcp-bm-add-nodes-to-inventory.adoc

+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-bm-add-nodes-to-inventory_{context}"]
+= Adding bare-metal nodes to a hardware inventory


The creation of the InfraEnv can also be done from the Console. There's a section below about using the console vs here doing it with the CLI. Could we explain how to do it from the console too? It's a fairly simple process worth mentioning for users to choose their preferred option.

racedo

Request to add content for adding InfraEnv via UI.

openshift-ci · 2025-07-25T17:04:46Z

@lahinson: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

lahinson · 2025-07-25T18:22:36Z

modules/hcp-bm-add-nodes-to-inventory.adoc

+:_mod-docs-content-type: PROCEDURE
+[id="hcp-bm-add-nodes-to-inventory_{context}"]
+= Creating an infrastructure environment and adding nodes
+


I based this file on information that I found in the following lab exercise: https://labs.sysdeseng.com/hypershift-baremetal-lab/4.18/adding-bm-to-hw-inventory.html

If any of the information in this file should change, please let me know.

lahinson · 2025-07-25T18:22:59Z

modules/hcp-bm-add-nodes-to-inventory.adoc

+
+** If you do not use the Metal3 Operator, obtain the discovery ISO from the `InfraEnv` resource and boot the hosts manually by completing the following steps:
+
+.. Download the live ISO.


Do we need to tell users where they should go to download the ISO?

lahinson · 2025-07-25T18:24:15Z

modules/hcp-bm-add-nodes-to-inventory.adoc

+  -p '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-0.example.krnl.es"}}' \
+  --type merge
+----
+


Should any of the values on line 125 be changed to example values?

lahinson · 2025-07-25T18:24:31Z

modules/hcp-bm-add-nodes-to-inventory.adoc

+86f7ac75-4fc4-4b36-8130-40fa12602218                        auto-assign
+e57a637f-745b-496e-971d-1abbf03341ba                        auto-assign
+----
+


Should any of the values on line 117 be changed to example values?

lahinson · 2025-07-25T18:25:24Z

modules/hcp-bm-create-infra-console.adoc

+
+. Click **Infrastructure -> Host inventory -> Create infrastructure environment**.
+
+. After you create the infrastructure environment, add bare-metal hosts from within the InfraEnv view by clicking **Add hosts -> With BMC**.


I would appreciate it if someone could verify that the user-interface elements that we're mentioning here actually match the UI.

openshift-ci bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Jul 17, 2025

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch from a51c7f8 to 0c0d363 Compare July 17, 2025 17:00

lahinson commented Jul 17, 2025

View reviewed changes

modules/hcp-bm-infraenv.adoc Outdated Show resolved Hide resolved

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch from 0c0d363 to 17bbb24 Compare July 17, 2025 17:03

lahinson added branch/enterprise-4.17 branch/enterprise-4.18 branch/enterprise-4.19 branch/enterprise-4.20 labels Jul 17, 2025

lahinson added this to the Continuous Release milestone Jul 17, 2025

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch 2 times, most recently from 09a5173 to 4b08e25 Compare July 17, 2025 17:23

ocpdocs-vale-bot reviewed Jul 17, 2025

View reviewed changes

modules/hcp-bm-hc.adoc Show resolved Hide resolved

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch 3 times, most recently from 73ffe57 to daa7c37 Compare July 17, 2025 19:39

openshift-ci bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Jul 17, 2025

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch from daa7c37 to e5561df Compare July 17, 2025 19:57

ocpdocs-vale-bot reviewed Jul 17, 2025

View reviewed changes

hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc Show resolved Hide resolved

ocpdocs-vale-bot reviewed Jul 17, 2025

View reviewed changes

hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc Show resolved Hide resolved

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch 6 times, most recently from aba8843 to 30573c3 Compare July 18, 2025 15:49

racedo reviewed Jul 21, 2025

View reviewed changes

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch from cc2d20e to 549af30 Compare July 22, 2025 16:01

ocpdocs-vale-bot reviewed Jul 22, 2025

View reviewed changes

modules/hcp-bm-hc.adoc Outdated Show resolved Hide resolved

ocpdocs-vale-bot reviewed Jul 22, 2025

View reviewed changes

modules/hcp-bm-hc.adoc Outdated Show resolved Hide resolved

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch from 549af30 to e15611b Compare July 22, 2025 18:17

ocpdocs-vale-bot reviewed Jul 22, 2025

View reviewed changes

modules/hcp-bm-add-nodes-to-inventory.adoc Outdated Show resolved Hide resolved

ocpdocs-vale-bot reviewed Jul 22, 2025

View reviewed changes

modules/hcp-bm-add-nodes-to-inventory.adoc Outdated Show resolved Hide resolved

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch 4 times, most recently from 531204b to 1104fb6 Compare July 22, 2025 21:01

ocpdocs-vale-bot reviewed Jul 22, 2025

View reviewed changes

modules/hcp-bm-hc.adoc Show resolved Hide resolved

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch 4 times, most recently from 007db9a to d7dd5ba Compare July 23, 2025 17:05

racedo reviewed Jul 25, 2025

View reviewed changes

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch 3 times, most recently from 7ca992f to cb1ef15 Compare July 25, 2025 16:32

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

9ca2c35

lahinson force-pushed the osdocs-15316-hcp-bm-improvements branch from cb1ef15 to 9ca2c35 Compare July 25, 2025 16:49

lahinson commented Jul 25, 2025

View reviewed changes

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


		** If you do not use the Metal3 Operator, obtain the discovery ISO from the `InfraEnv` resource and boot the hosts manually by completing the following steps:

		.. Download the live ISO.


		. Click Infrastructure -> Host inventory -> Create infrastructure environment.

		. After you create the infrastructure environment, add bare-metal hosts from within the InfraEnv view by clicking Add hosts -> With BMC.

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

Are you sure you want to change the base?

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

Conversation

lahinson commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ocpdocs-previewbot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lahinson Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

racedo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

racedo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

racedo left a comment

Choose a reason for hiding this comment

Uh oh!

openshift-ci bot commented Jul 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lahinson commented Jul 17, 2025 •

edited

Loading

ocpdocs-previewbot commented Jul 17, 2025 •

edited

Loading

lahinson Jul 23, 2025 •

edited

Loading