From 214520e4e2025946ae8b235566df20678f4bebd9 Mon Sep 17 00:00:00 2001 From: Laura Hinson Date: Wed, 6 Aug 2025 10:06:22 -0400 Subject: [PATCH] Adding bare metal infra docs for HCP --- .../hcp-deploy/hcp-deploy-bm.adoc | 16 + modules/hcp-bm-add-nodes-to-inventory.adoc | 317 ++++++++++++++++++ modules/hcp-bm-create-infra-console.adoc | 19 ++ 3 files changed, 352 insertions(+) create mode 100644 modules/hcp-bm-add-nodes-to-inventory.adoc create mode 100644 modules/hcp-bm-create-infra-console.adoc diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc index 8dec59cc4c..938cb6858e 100644 --- a/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc +++ b/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc @@ -53,6 +53,22 @@ include::modules/hcp-bm-dns.adoc[leveloffset=+1] include::modules/hcp-custom-dns.adoc[leveloffset=+2] +[id="hcp-bm-create-infra_{context}"] +== Creating an InfraEnv resource + +Before you can create a hosted cluster on bare metal, you need an `InfraEnv` resource. + +include::modules/hcp-bm-add-nodes-to-inventory.adoc[leveloffset=+2] + +include::modules/hcp-bm-create-infra-console.adoc[leveloffset=+2] + +[discrete] +[role="_additional-resources"] +[id="addl-res-hcp-bm-infra-console_{context}"] +=== Additional resources + +* xref:../../web_console/web-console.adoc#web-console-overview[Accessing the web console] + include::modules/hcp-bm-hc.adoc[leveloffset=+1] [role="_additional-resources"] diff --git a/modules/hcp-bm-add-nodes-to-inventory.adoc b/modules/hcp-bm-add-nodes-to-inventory.adoc new file mode 100644 index 0000000000..e0efa107a0 --- /dev/null +++ b/modules/hcp-bm-add-nodes-to-inventory.adoc @@ -0,0 +1,317 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc + + +:_mod-docs-content-type: PROCEDURE +[id="hcp-bm-add-nodes-to-inventory_{context}"] += Creating an InfraEnv resource and adding nodes + +On {hcp}, the control-plane components run as pods on the management cluster while the data plane runs on dedicated nodes. You can use the Assisted Service to boot your hardware with a discovery ISO that adds your hardware to a hardware inventory. Later, when you create a hosted cluster, the hardware from the inventory is used to provision the data-plane nodes. The object that is used to get the discovery ISO is an `InfraEnv` resource. You need to create a `BareMetalHost` object that configures the cluster to boot the bare-metal node from the discovery ISO. + +.Procedure + +. Create a namespace to store your hardware inventory by entering the following command: ++ +[source,terminal] +---- +$ oc --kubeconfig ~//mgmt-kubeconfig create \ + namespace +---- ++ +where: ++ +:: Is the name of the directory where the `kubeconfig` file for the management cluster is saved. +:: Is the name of the namespace that you are creating; for example, `hardware-inventory`. ++ +.Example output +[source,terminal] +---- +namespace/hardware-inventory created +---- + +. Copy the pull secret of the management cluster by entering the following command: ++ +[source,terminal] +---- +$ oc --kubeconfig ~//mgmt-kubeconfig \ + -n openshift-config get secret pull-secret -o yaml \ + | grep -vE "uid|resourceVersion|creationTimestamp|namespace" \ + | sed "s/openshift-config//g" \ + | oc --kubeconfig ~//mgmt-kubeconfig \ + -n apply -f - +---- ++ +where: ++ +:: Is the name of the directory where the `kubeconfig` file for the management cluster is saved. +:: Is the name of the namespace that you are creating; for example, `hardware-inventory`. ++ +.Example output +[source,terminal] +---- +secret/pull-secret created +---- + +. Create the `InfraEnv` resource by adding the following content to a YAML file: ++ +[source,yaml] +---- +apiVersion: agent-install.openshift.io/v1beta1 +kind: InfraEnv +metadata: + name: hosted + namespace: +spec: + additionalNTPSources: + - + pullSecretRef: + name: pull-secret + sshAuthorizedKey: +# ... +---- + +. Apply the changes to the YAML file by entering the following command: ++ +[source,terminal] +---- +$ oc apply -f .yaml +---- ++ +Replace `` with the name of your file. + +. Verify that the `InfraEnv` resource was created by entering the following command: ++ +[source,terminal] +---- +$ oc --kubeconfig ~//mgmt-kubeconfig \ + -n get infraenv hosted +---- + +. Add bare-metal hosts by following one of two methods: + +** 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 by entering the following commands: ++ +[source,terminal] +---- +$ oc get infraenv -A +---- ++ +[source,terminal] +---- +$ oc get infraenv -o jsonpath='{.status.isoDownloadURL}' -n +---- + +.. Boot the ISO. The node communicates with the Assisted Service and registers as an agent in the same namespace as the `InfraEnv` resource. + +.. For each agent, set the installation disk ID and hostname, and approve it to indicate that the agent is ready for use. Enter the following commands: ++ +[source,terminal] +---- +$ oc -n get agents +---- ++ +.Example output +[source,terminal] +---- +NAME CLUSTER APPROVED ROLE STAGE +86f7ac75-4fc4-4b36-8130-40fa12602218 auto-assign +e57a637f-745b-496e-971d-1abbf03341ba auto-assign +---- ++ +[source,terminal] +---- +$ oc -n \ + patch agent 86f7ac75-4fc4-4b36-8130-40fa12602218 \ + -p '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-0.example.krnl.es"}}' \ + --type merge +---- ++ +[source,terminal] +---- +$ oc -n \ + patch agent 23d0c614-2caa-43f5-b7d3-0b3564688baa -p \ + '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-1.example.krnl.es"}}' \ + --type merge +---- ++ +[source,terminal] +---- +$ oc -n get agents +---- ++ +.Example output +[source,terminal] +---- +NAME CLUSTER APPROVED ROLE STAGE +86f7ac75-4fc4-4b36-8130-40fa12602218 true auto-assign +e57a637f-745b-496e-971d-1abbf03341ba true auto-assign +---- + +** If you use the Metal3 Operator, you can automate the bare-metal host registration by creating the following objects: + +.. Create a YAML file and add the following content to it: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: hosted-worker0-bmc-secret + namespace: +data: + password: + username: +type: Opaque +--- +apiVersion: v1 +kind: Secret +metadata: + name: hosted-worker1-bmc-secret + namespace: +data: + password: + username: +type: Opaque +--- +apiVersion: v1 +kind: Secret +metadata: + name: hosted-worker2-bmc-secret + namespace: +data: + password: + username: +type: Opaque +--- +apiVersion: metal3.io/v1alpha1 +kind: BareMetalHost +metadata: + name: hosted-worker0 + namespace: + labels: + infraenvs.agent-install.openshift.io: hosted + annotations: + inspect.metal3.io: disabled + bmac.agent-install.openshift.io/hostname: hosted-worker0 +spec: + automatedCleaningMode: disabled + bmc: + disableCertificateVerification: True + address: + credentialsName: hosted-worker0-bmc-secret + bootMACAddress: aa:aa:aa:aa:02:01 + online: true +--- +apiVersion: metal3.io/v1alpha1 +kind: BareMetalHost +metadata: + name: hosted-worker1 + namespace: + labels: + infraenvs.agent-install.openshift.io: hosted + annotations: + inspect.metal3.io: disabled + bmac.agent-install.openshift.io/hostname: hosted-worker1 +spec: + automatedCleaningMode: disabled + bmc: + disableCertificateVerification: True + address: + credentialsName: hosted-worker1-bmc-secret + bootMACAddress: aa:aa:aa:aa:02:02 + online: true +--- +apiVersion: metal3.io/v1alpha1 +kind: BareMetalHost +metadata: + name: hosted-worker2 + namespace: + labels: + infraenvs.agent-install.openshift.io: hosted + annotations: + inspect.metal3.io: disabled + bmac.agent-install.openshift.io/hostname: hosted-worker2 +spec: + automatedCleaningMode: disabled + bmc: + disableCertificateVerification: True + address: + credentialsName: hosted-worker2-bmc-secret + bootMACAddress: aa:aa:aa:aa:02:03 + online: true +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: capi-provider-role + namespace: +rules: +- apiGroups: + - agent-install.openshift.io + resources: + - agents + verbs: + - '*' +---- ++ +where: ++ +:: Is the your namespace. +:: Is the password for your secret. +:: Is the user name for your secret. +:: Is the BMC address for the `BareMetalHost` object. ++ +[NOTE] +==== +When you apply this YAML file, the following objects are created: + +* Secrets with credentials for the Baseboard Management Controller (BMCs) +* The `BareMetalHost` objects +* A role for the HyperShift Operator to be able to manage the agents + +Notice how the `InfraEnv` resource is referenced in the `BareMetalHost` objects by using the `infraenvs.agent-install.openshift.io: hosted` custom label. This ensures that the nodes are booted with the ISO generated. +==== + +.. Apply the changes to the YAML file by entering the following command: ++ +[source,terminal] +---- +$ oc apply -f .yaml +---- ++ +Replace `` with the name of your file. + +. Enter the following command, and then wait a few minutes for the `BareMetalHost` objects to move to the `Provisioning` state: ++ +[source,terminal] +---- +$ oc --kubeconfig ~//mgmt-kubeconfig -n get bmh +---- ++ +.Example output +[source,terminal] +---- +NAME STATE CONSUMER ONLINE ERROR AGE +hosted-worker0 provisioning true 106s +hosted-worker1 provisioning true 106s +hosted-worker2 provisioning true 106s +---- + +. Enter the following command to verify that nodes are booting and showing up as agents. This process can take a few minutes, and you might need to enter the command more than once. ++ +[source,terminal] +---- +$ oc --kubeconfig ~//mgmt-kubeconfig -n get agent +---- ++ +.Example output +[source,terminal] +---- +NAME CLUSTER APPROVED ROLE STAGE +aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaa0201 true auto-assign +aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaa0202 true auto-assign +aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaa0203 true auto-assign +---- \ No newline at end of file diff --git a/modules/hcp-bm-create-infra-console.adoc b/modules/hcp-bm-create-infra-console.adoc new file mode 100644 index 0000000000..9ddb873712 --- /dev/null +++ b/modules/hcp-bm-create-infra-console.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc + +:_mod-docs-content-type: PROCEDURE +[id="hcp-bm-create-infra-console_{context}"] += Creating an InfraEnv resource by using the console + +To create an `InfraEnv` resource by using the console, complete the following steps. + +.Procedure + +. Open the {product-title} web console and log in by entering your administrator credentials. For instructions to open the console, see "Accessing the web console". + +. In the console header, ensure that **All Clusters** is selected. + +. Click **Infrastructure -> Host inventory -> Create infrastructure environment**. + +. After you create the `InfraEnv` resource, add bare-metal hosts from within the **InfraEnv** view by clicking **Add hosts** and selecting from the available options. \ No newline at end of file