Skip to content

Commit 1c7320e

Browse files
johnwilkinsjohnwilkins
committed
HCIDOCS-623: Added documentation for Bare Metal as a Service (BMaaS)..
1 parent 6a4638f commit 1c7320e

11 files changed

+587
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -479,6 +479,8 @@ Topics:
479479
File: bare-metal-postinstallation-configuration
480480
- Name: Expanding the cluster
481481
File: bare-metal-expanding-the-cluster
482+
- Name: Using bare metal as a service
483+
File: bare-metal-using-bare-metal-as-a-service
482484
- Name: Installing IBM Cloud Bare Metal (Classic)
483485
Dir: installing_ibm_cloud_classic
484486
Distros: openshift-origin,openshift-enterprise

‎installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="bare-metal-using-bare-metal-as-a-service"]
3+
= Using bare metal as a service
4+
include::_attributes/common-attributes.adoc[]
5+
:context: bare-metal-using-bmaas
6+
7+
toc::[]
8+
9+
The Bare Metal as a Service (BMaaS) feature for {product-title} enables you to provision and manage bare-metal hosts by using the Metal^3^ API and the Bare Metal Operator (BMO). These hosts, external to the {product-title} cluster, can run workloads that might not be suitable for containerization or virtualization. For example, workloads such as applications that require direct hardware access, conduct high-performance computing tasks or are legacy applications. BMaaS has the following capabilities:
10+
11+
* Provisioning of bare-metal hosts, including initial configuration.
12+
* Lifecycle management such as power management, firmware updates, and decommissioning by using the BMO.
13+
14+
As standalone systems, these hosts operate independently of the {product-title} cluster and support diverse workloads by integrating bare-metal resources with containerized and virtualized applications. BMaaS can run other operating systems, but only {op-system-base-full} and CentOS Stream 9 were tested.
15+
16+
:FeatureName: BMaaS
17+
include::snippets/technology-preview.adoc[]
18+
:!FeatureName:
19+
20+
include::modules/bmaas-prerequisites.adoc[leveloffset=+1]
21+
22+
include::modules/bmaas-using-the-bmo-to-manage-resources-across-all-namespaces.adoc[leveloffset=+1]
23+
24+
include::modules/bmaas-setting-up-a-dedicated-namespace.adoc[leveloffset=+1]
25+
26+
include::modules/bmo-creating-a-bmc-secret.adoc[leveloffset=+1]
27+
28+
[role="_additional-resources"]
29+
.Additional resources
30+
31+
* xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#bmc-addressing_ipi-install-installation-workflow[About BMC addressing]
32+
33+
include::modules/bmo-creating-a-bare-metal-host-resource.adoc[leveloffset=+1]
34+
35+
include::modules/bmo-configuring-users-for-bmaas-hosts.adoc[leveloffset=+1]
36+
37+
//include::modules/bmo-configuring-ignition-userdata.adoc[leveloffset=+1]
38+
39+
include::modules/bmo-configuring-the-networkdata-parameter-in-the-bmo-cr.adoc[leveloffset=+1]
40+
41+
include::modules/bmo-deploying-an-image-to-the-bare-metal-host.adoc[leveloffset=+1]

‎modules/bmaas-prerequisites.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
// This module is included in the following assemblies:
2+
//
3+
// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="bmaas-prerequisites_{context}"]
7+
= Prerequisites for using BMaaS
8+
9+
To use the Bare Metal as a Service (BMaaS) Technology Preview, complete the following prerequisites:
10+
11+
BareMetalHost Configuration::
12+
All bare-metal hosts must use a Baseboard Management Controller (BMC) configured with the Redfish protocol and virtual media (`redfish-virtualmedia`) driver. Each bare-metal host requires a boot interface with a MAC address configured to receive an IP address lease.
13+
14+
Network Requirements::
15+
A DHCP server, separate from the {product-title} and Metal^3^ infrastructure, must be operational on the same Layer 2 network as the bare-metal hosts. The DHCP server must be configured to match the MAC addresses of the boot interfaces on the bare-metal hosts, enabling IP address assignment for communication with Metal^3^ components.
16+
17+
Cluster Privileges::
18+
You must have `cluster-admin` privileges on the {product-title} cluster to perform BMaaS configuration tasks.
19+
20+
Web server with images::
21+
BMaaS does not provide images for deployment on hardware. You must configure a web server with the images and checksums you want to use. The `image` field of the `BareMetalHost` spec references these images during deployment. Ensure that the bare-metal hosts can reach the web server URL. The following is an example of an image and checksum you might include:
22+
23+
* `http://example.com/rhel9.qcow2`
24+
* `http://example.com/rhel9.qcow2.sha512sum`
25+
* `http://example.com/stream9.qcow2`
26+
* `http://example.com/stream9.qcow2.sha512sum`
27+
28+
These prerequisites ensure that BMaaS can provision and manage bare-metal hosts effectively.

‎modules/bmaas-setting-up-a-dedicated-namespace.adoc

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
// This module is included in the following assemblies:
2+
//
3+
// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="bmaas-setting-up-a-dedicated-namespace_{context}"]
7+
= Setting up a dedicated namespace
8+
9+
To prevent accidental interference between Bare Metal as a Service (BMaaS) workloads and the {product-title} infrastructure, set up a dedicated namespace. Repeat this procedure for every BMaaS project.
10+
11+
.Prerequisites
12+
13+
* You have link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html-single/authentication_and_authorization/index#configuring-identity-providers[configured an identify provider].
14+
15+
.Procedure
16+
17+
. Configure a BMaaS `bmadmin` user in the identity provider and create a secret in OpenShift:
18+
19+
.. Create the `bmadmin` user in the identity provider. For example, if using the `htpasswd` identity provider, run the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ htpasswd -c -B -b ./users_htpasswd <username> <password>
24+
----
25+
<username>::
26+
The user name for the identity provider. Replace `<username>` with your preferred user name. This example uses `bmadmin`.
27+
<password>::
28+
The password for the user. Replace `<password>` with a secure password.
29+
30+
.. Create a secret in the `openshift-config` namespace to store the identity provider configuration by running the following command:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc create secret generic <identity_provider_arguments> -n openshift-config
35+
----
36+
+
37+
For example, when using the `htpasswd` identity provider, run the following command:
38+
+
39+
[source,terminal]
40+
----
41+
$ oc create secret generic htpass-secret --from-file=htpasswd=users_htpasswd -n openshift-config
42+
----
43+
<identity_provider_arguments>::
44+
The arguments specific to the identity provider secret. Replace `<identity_provider_arguments>` with the appropriate arguments for your identity provider.
45+
46+
. Configure OAuth to use the identity provider:
47+
48+
.. Edit the OAuth resource by running the following command:
49+
+
50+
[source,terminal]
51+
----
52+
$ oc edit oauth cluster
53+
----
54+
+
55+
The editor opens and displays the Oauth resource.
56+
57+
.. Add the identity provider configuration to the `spec.identityProviders` list:
58+
+
59+
.Identity provider configuration examples
60+
[options="header"]
61+
|====
62+
|Type|Example
63+
| htpasswd
64+
a|[source,yaml]
65+
----
66+
# ...
67+
- name: my_bmaas_provider
68+
mappingMethod: claim
69+
type: htpasswd
70+
htpasswd:
71+
fileData:
72+
name: <secret>
73+
# ...
74+
----
75+
| LDAP
76+
a|[source,yaml]
77+
----
78+
# ...
79+
- name: my_bmaas_provider
80+
mappingMethod: claim
81+
type: ldap
82+
ldap:
83+
attributes:
84+
id:
85+
- dn
86+
email:
87+
- mail
88+
name:
89+
- cn
90+
preferredUsername:
91+
- uid
92+
# ...
93+
----
94+
| GitHub
95+
a|[source,yaml]
96+
----
97+
# ...
98+
- name: my_bmaas_provider
99+
mappingMethod: claim
100+
type: GitHub
101+
github:
102+
ca:
103+
name: ca-config-map
104+
clientID: {...}
105+
clientSecret:
106+
name: github-secret
107+
hostname: ...
108+
organizations:
109+
- myorganization1
110+
- myorganization2
111+
teams:
112+
- myorganization1/team-a
113+
- myorganization2/team-b
114+
# ...
115+
----
116+
|====
117+
+
118+
For more information about identify providers, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html-single/authentication_and_authorization/index[Authentication and authorization].
119+
120+
.. Save and exit the editor.
121+
122+
. Create a BMaaS `bmadmin` user by running the following command:
123+
+
124+
[source,terminal]
125+
----
126+
$ oc create user <username>
127+
----
128+
<username>::
129+
The user name. Replace `<username>` with your username. The following examples use `bmadmin` as the username.
130+
131+
. Create a dedicated `bmaas` namespace for BMaaS hosts by running the following command:
132+
+
133+
[source,terminal]
134+
----
135+
$ oc new-project <namespace>
136+
----
137+
`<namespace>`::
138+
Replace <namespace> with the namespace name that you want to use. This example uses bmaas.
139+
140+
. Assign the `edit` role to the BMaaS `bmadmin` user in the `bmaas` namespace by running the following command:
141+
+
142+
[source,terminal]
143+
----
144+
$ oc adm policy add-role-to-user edit <username> -n bmaas
145+
----
146+
147+
. Clone the `baremetal-operator` repository to obtain the role-based access control (RBAC) role definitions by running the following command:
148+
+
149+
[source,terminal,subs="attributes"]
150+
----
151+
$ git clone -b release-{product-version} https://github.com/openshift/baremetal-operator.git
152+
----
153+
154+
. For each role you want to add, apply the appropriate RBAC role YAML file from the repository by running the following command:
155+
+
156+
[source,terminal]
157+
----
158+
$ oc apply -f baremetal-operator/config/base/rbac/<role_filename>.yaml
159+
----
160+
161+
. Assign the custom RBAC roles to the BMaaS `bmadmin` user in the `bmaas` namespace by running the following command:
162+
+
163+
[source,terminal]
164+
----
165+
$ oc adm policy add-role-to-user <role_name> bmadmin -n bmaas
166+
----
167+
168+
. Login as the `bmadmin` user by running the following command:
169+
+
170+
[source,terminal]
171+
----
172+
$ oc login <api_server_url>:6443
173+
----
174+
`<api_server_url>`::
175+
The URL to the Kubernetes API.
176+

‎modules/bmaas-using-the-bmo-to-manage-resources-across-all-namespaces.adoc

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// This module is included in the following assemblies:
2+
//
3+
// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="bmaas-using-the-bmo-to-manage-resources-across-all-namespaces_{context}"]
7+
= Using the Bare Metal Operator to manage resources across all namespaces
8+
9+
For the Bare Metal Operator (BMO) to manage `BareMetalHost` resources across all namespaces in your {product-title} cluster, you must configure the Operator to watch all namespaces. This configuration is important to avoid mixing non-{product-title} workloads with other components in the same namespace.
10+
11+
.Prerequisites
12+
13+
* If you are using user-provisioned installation and the Provisioning CR does not exist, you must create it manually. For instructions, see https://docs.openshift.com/container-platform/{product-version}/installing/installing_bare_metal/scaling-a-user-provisioned-cluster-with-the-bare-metal-operator.html#configuring-a-provisioning-resource-to-scale-user-provisioned-clusters_scaling-a-user-provisioned-cluster-with-the-bare-metal-operator[Configuring a provisioning resource to scale user-provisioned clusters]. For installer-provisioned installations, the installation program creates the Provisioning custom resource (CR) automatically.
14+
15+
.Procedure
16+
17+
* Patch the provisioning configuration to enable watching all namespaces by running the following command:
18+
+
19+
[source,terminal]
20+
----
21+
$ oc patch provisioning/provisioning-configuration \
22+
--type merge -p '{"spec": {"watchAllNamespaces": true}}'
23+
----
24+
+
25+
The BMO applies this change automatically.

‎modules/bmo-configuring-ignition-userdata.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// This module is included in the following assemblies:
2+
//
3+
// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="bmo-configuring-ignition-userdata_{context}"]
7+
= Configuring Ignition-based userData for Fedora CoreOS
8+
9+
The Fedora CoreOS (FCOS) image requires the `userData` field to use an Ignition configuration instead of a `cloud-init` script. Ignition is the utility FCOS uses for initial system configuration. See link:https://docs.fedoraproject.org/en-US/fedora-coreos/producing-ign/[Producing an Ignition config] for details.
10+
11+
.Procedure
12+
13+
. Create a `ignition-config.yaml` file with the following content:
14+
+
15+
[source,yaml]
16+
----
17+
ignition:
18+
version: "3.4.0"
19+
passwd:
20+
users:
21+
- name: <name>
22+
passwordHash: <password_hash>
23+
sshAuthorizedKeys:
24+
- <ssh_key>
25+
----
26+
+
27+
<name>::
28+
The user name. For example, `bmadmin`.
29+
<password_hash>::
30+
The hashed password for the `<name>` user. You can generate a hashed password using tools like `mkpasswd`.
31+
<ssh_key>::
32+
The public SSH key to use when accessing this host as the `<name>` user.
33+
34+
. Create a secret from the Ignition file by running the following command:
35+
+
36+
[source,terminal]
37+
----
38+
$ oc create secret generic bmaas-ignition \
39+
--from-file=userData=ignition-config.yaml -n bmaas
40+
----
41+
42+
. Configure the `BareMetalHost` to use the Ignition secret by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc patch baremetalhost <hostname> -n bmaas \
47+
--type=json -p='[{"op": "add", "path": "/spec/userData", "value": {"name": "bmaas-ignition"}}]'
48+
----
49+
+
50+
<hostname>::
51+
The name of the bare-metal host.

‎modules/bmo-configuring-the-networkdata-parameter-in-the-bmo-cr.adoc

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// This module is included in the following assemblies:
2+
//
3+
// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="bmo-configuring-the-networkdata-parameter-in-the-bmo-cr_{context}"]
7+
= Configuring the networkData parameter in the BareMetalHost resource
8+
9+
The `networkData` field in the `BareMetalHost` custom resource (CR) allows you to control the network configuration of the bare-metal host at creation time. For most operating systems, this is achieved using a configuration file encapsulated in a Kubernetes secret. Then, the `cloud-init` service uses it to customize services.
10+
11+
.Procedure
12+
13+
. Create a file named `network-data.yaml` with the following content:
14+
+
15+
[source,yaml]
16+
----
17+
links:
18+
- id: <interface_id>
19+
type: phy
20+
ethernet_mac_address: <mac_address>
21+
networks:
22+
- id: <interface_id>
23+
link: <interface_id>
24+
type: ipv4_dhcp
25+
services:
26+
- type: dns
27+
address: <dns_server>
28+
----
29+
+
30+
`<interface_id>`::
31+
The ID of the network interface, such as `enp2s0`.
32+
`<mac_address>`::
33+
The MAC address of the network interface.
34+
`<dns_server>`::
35+
The IP address of the DNS server.
36+
37+
. Create a secret from the `networkData` file by running the following command:
38+
+
39+
[source,terminal]
40+
----
41+
$ oc create secret generic <hostname>-network-data \
42+
--from-file=networkData=network-data.yaml -n bmaas
43+
----
44+
+
45+
`<hostname>`::
46+
The hostname of the bare-metal host.
47+
48+
. Configure the `BareMetalHost` to use the `networkData` file by running the following command:
49+
+
50+
[source,terminal]
51+
----
52+
$ oc patch baremetalhost <hostname> -n bmaas \
53+
--type merge -p '{"spec":{"networkData":{"name":"<hostname>-network-data"}}}'
54+
----

0 commit comments

Comments
 (0)