Using bare metal as a service - Installing on bare metal | Installing

Prerequisites for using BMaaS
Using the Bare Metal Operator to manage resources across all namespaces
Setting up a dedicated namespace
Creating a BMC secret
Creating a bare-metal host resource
Configuring users for BMaaS hosts
Configuring the networkData parameter in the BareMetalHost resource
Deploying an image to the bare-metal host

The Bare Metal as a Service (BMaaS) feature for OKD enables you to provision and manage bare-metal hosts by using the Metal³ API and the Bare Metal Operator (BMO). These hosts, external to the OKD 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:

Provisioning of bare-metal hosts, including initial configuration.
Lifecycle management such as power management, firmware updates, and decommissioning by using the BMO.

As standalone systems, these hosts operate independently of the OKD cluster and support diverse workloads by integrating bare-metal resources with containerized and virtualized applications. BMaaS can run other operating systems, but only Fedora and CentOS Stream 9 were tested.

BMaaS is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Prerequisites for using BMaaS

To use the Bare Metal as a Service (BMaaS) Technology Preview, complete the following prerequisites:

BareMetalHost Configuration

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.

Network Requirements

A DHCP server, separate from the OKD and Metal³ 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³ components.

Cluster Privileges

You must have cluster-admin privileges on the OKD cluster to perform BMaaS configuration tasks.

Web server with images

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:

These prerequisites ensure that BMaaS can provision and manage bare-metal hosts effectively.

Using the Bare Metal Operator to manage resources across all namespaces

For the Bare Metal Operator (BMO) to manage BareMetalHost resources across all namespaces in your OKD cluster, you must configure the Operator to watch all namespaces. This configuration is important to avoid mixing non-OKD workloads with other components in the same namespace.

Prerequisites

If you are using user-provisioned installation and the Provisioning CR does not exist, you must create it manually. For instructions, see Configuring a provisioning resource to scale user-provisioned clusters. For installer-provisioned installations, the installation program creates the Provisioning custom resource (CR) automatically.

Procedure

Patch the provisioning configuration to enable watching all namespaces by running the following command:
```
$ oc patch provisioning/provisioning-configuration \
  --type merge -p '{"spec": {"watchAllNamespaces": true}}'
```
The BMO applies this change automatically.

Setting up a dedicated namespace

To prevent accidental interference between Bare Metal as a Service (BMaaS) workloads and the OKD infrastructure, set up a dedicated namespace. Repeat this procedure for every BMaaS project.

Prerequisites

You have configured an identify provider.

Procedure

Configure a BMaaS bmadmin user in the identity provider and create a secret in OpenShift:
1. Create the bmadmin user in the identity provider. For example, if using the htpasswd identity provider, run the following command:
  $ htpasswd -c -B -b ./users_htpasswd <username> <password>
  <username>
  
  The user name for the identity provider. Replace <username> with your preferred user name. This example uses bmadmin.
  
  <password>
  
  The password for the user. Replace <password> with a secure password.
2. Create a secret in the openshift-config namespace to store the identity provider configuration by running the following command:
  $ oc create secret generic <identity_provider_arguments> -n openshift-config
  For example, when using the htpasswd identity provider, run the following command:
  $ oc create secret generic htpass-secret --from-file=htpasswd=users_htpasswd -n openshift-config
  <identity_provider_arguments>
  
  The arguments specific to the identity provider secret. Replace <identity_provider_arguments> with the appropriate arguments for your identity provider.

Configure OAuth to use the identity provider:

Edit the OAuth resource by running the following command:
```
$ oc edit oauth cluster
```
The editor opens and displays the Oauth resource.

Add the identity provider configuration to the spec.identityProviders list:

Type Example

Table 1. Identity provider configuration examples
Type	Example
htpasswd	`# ... - name: my_bmaas_provider mappingMethod: claim type: htpasswd htpasswd: fileData: name: <secret> # ...`
LDAP	`# ... - name: my_bmaas_provider mappingMethod: claim type: ldap ldap: attributes: id: - dn email: - mail name: - cn preferredUsername: - uid # ...`
GitHub	`# ... - name: my_bmaas_provider mappingMethod: claim type: GitHub github: ca: name: ca-config-map clientID: {...} clientSecret: name: github-secret hostname: ... organizations: - myorganization1 - myorganization2 teams: - myorganization1/team-a - myorganization2/team-b # ...`

htpasswd

# ...
- name: my_bmaas_provider
  mappingMethod: claim
  type: htpasswd
  htpasswd:
    fileData:
      name: <secret>
# ...

LDAP

# ...
- name: my_bmaas_provider
  mappingMethod: claim
  type: ldap
  ldap:
    attributes:
      id:
      - dn
      email:
      - mail
      name:
      - cn
      preferredUsername:
      - uid
# ...

GitHub

# ...
- name: my_bmaas_provider
  mappingMethod: claim
  type: GitHub
    github:
      ca:
        name: ca-config-map
      clientID: {...}
      clientSecret:
        name: github-secret
      hostname: ...
      organizations:
      - myorganization1
      - myorganization2
      teams:
      - myorganization1/team-a
      - myorganization2/team-b
# ...

For more information about identify providers, see Authentication and authorization.

Save and exit the editor.

Create a BMaaS bmadmin user by running the following command:
```
$ oc create user <username>
```
<username>

The user name. Replace <username> with your username. The following examples use bmadmin as the username.
Create a dedicated bmaas namespace for BMaaS hosts by running the following command:
```
$ oc new-project <namespace>
```
<namespace>

Replace <namespace> with the namespace name that you want to use. This example uses bmaas.
Assign the edit role to the BMaaS bmadmin user in the bmaas namespace by running the following command:
```
$ oc adm policy add-role-to-user edit <username> -n bmaas
```
Clone the baremetal-operator repository to obtain the role-based access control (RBAC) role definitions by running the following command:
```
$ git clone -b release-4.19 https://github.com/openshift/baremetal-operator.git
```
For each role you want to add, apply the appropriate RBAC role YAML file from the repository by running the following command:
```
$ oc apply -f baremetal-operator/config/base/rbac/<role_filename>.yaml
```
Assign the custom RBAC roles to the BMaaS bmadmin user in the bmaas namespace by running the following command:
```
$ oc adm policy add-role-to-user <role_name> bmadmin -n bmaas
```
Login as the bmadmin user by running the following command:
```
$ oc login <api_server_url>:6443
```
<api_server_url>

The URL to the Kubernetes API.

Creating a BMC secret

To deploy a bare-metal host, you must create a secret to access the baseboard management controller (BMC).

Procedure

Create a BMC secret file by running the following command:
```
$ vim bmaas-<name>-bmc-secret.yaml
```
Replace <name> with the name of the bare-metal host.
Edit the secret:
```
apiVersion: v1
kind: Secret
metadata:
  name: bmaas-<name>-bmc-secret
  namespace: bmaas
type: Opaque
data:
  username: <base64_of_uid>
  password: <base64_of_pwd>
```
<base64_of_uid>

Replace <base64_of_uid> with the BMC user name as a Base64-encoded string.

<base64_of_pwd>

Replace <base64_of_pwd> with the BMC password as a Base64-encoded string.
Apply the BMC secret by running the following command:
```
$ oc apply -f bmaas-<name>-bmc-secret.yaml
```

Additional resources

About BMC addressing

Creating a bare-metal host resource

To deploy a bare-metal host, you must create a BareMetalHost resource.

Procedure

Create a BareMetalHost custom resource (CR) file by running the following command:
```
$ vim bmaas-<name>-bmh.yaml
```
<name>

Replace <name> with the name of the bare-metal host.

Edit the CR:

apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
  name: bmaas-<name>
  namespace:  bmaas
spec:
  online: true
  bootMACAddress: <mac_addr>
  bmc:
    address: redfish-virtualmedia+<address>/redfish/v1/Systems/System.Embedded.1
    credentialsName: bmaas-<num>-bmc-secret

<mac_addr>: Replace <mac_addr> with the MAC address of the first NIC on the bare-metal host.
<address>: Replace <address> with IP address or FQDN of the host.

Apply the CR by running the following command:
```
$ oc apply -f bmaas-<name>-bmh.yaml
```

Verification

Check the BareMetalHost state by running the following command:
```
$ oc get baremetalhost -n bmaas
```
The state progresses from registering, to inspecting, and finally to available.

Configuring users for BMaaS hosts

Configure bare-metal host users and add them to a Kubernetes secret. Then, create and apply the secret to customize the host.

Procedure

Create a file named <hostname>-user-data.yaml with the following content:
```
users:
  - name: <name>
    sudo: [<sudo_config>]
    ssh_authorized_keys:
      - <key_type>
      <key>
    shell: <shell_path>
    groups: [<groups>]
    lock_passwd: true|false
```
<hostname>

The name of the bare-metal host.

<name>

The user name.

<sudo_config>

The sudo configuration for the user.

<key_type>

The SSH key type.

<key>

The public SSH key to use when accessing this host as the <name> user.

<shell_path>

The shell to use when accessing the host.

<groups>

The groups the user belongs to.

lock_passwd
Whether the user password is locked. If true, the user cannot log in by using the password, but can still use SSH.
Example user

users: - name: sysadmin sudo: ["ALL=(ALL) NOPASSWD:ALL"] ssh_authorized_keys: - ssh-rsa AAAAB3NzaC1yc2E... sysadmin@workstation.example.com shell: /bin/bash groups: [adm, sudo] lock_passwd: true
Create a secret from the <hostname>-user-data.yaml file by running the following command:
```
$ oc create secret generic <hostname>-user-data \
  --from-file=userData=<hostname>-user-data.yaml -n bmaas
```
<hostname>

The name of the bare-metal host.
Configure the BareMetalHost to use the <hostname>-user-data.yaml file by running the following command:
```
$ oc patch baremetalhost <hostname> -n bmaas \
     --type merge -p '{"spec":{"userData":{"name":"<hostname>-user-data"}}}'
```
<hostname>

The name of the bare-metal host.

Configuring the networkData parameter in the BareMetalHost resource

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.

Procedure

Create a file named network-data.yaml with the following content:

links:
  - id: <interface_id>
    type: phy
    ethernet_mac_address: <mac_address>
networks:
  - id: <interface_id>
    link: <interface_id>
    type: ipv4_dhcp
services:
  - type: dns
    address: <dns_server>

<interface_id>: The ID of the network interface, such as enp2s0.
<mac_address>: The MAC address of the network interface.
<dns_server>: The IP address of the DNS server.

Create a secret from the networkData file by running the following command:
```
$ oc create secret generic <hostname>-network-data \
  --from-file=networkData=network-data.yaml -n bmaas
```
<hostname>

The hostname of the bare-metal host.

Configure the BareMetalHost to use the networkData file by running the following command:

$ oc patch baremetalhost <hostname> -n bmaas \
  --type merge -p '{"spec":{"networkData":{"name":"<hostname>-network-data"}}}'

Deploying an image to the bare-metal host

To deploy the image to the host, update the image field in the spec section of the BareMetalHost resource. Once you update the image field, provisioning begins immediately.

Procedure

Update the image field in the BareMetalHost CR by running the following command:
```
$ oc patch baremetalhost <hostname> \
  --type merge -p '{"spec": {"image": {"url": "<image_url>", "checksum": "<checksum_url>", "checksumType": "auto"}}}'
```
<hostname>

The name of your BareMetalHost resource.

<image_url>

The URL of the image to deploy.

<checksum_url>

The URL of the checksum file for the image.