diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 66cdd5c362..7275296bbc 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -479,6 +479,8 @@ Topics: File: bare-metal-postinstallation-configuration - Name: Expanding the cluster File: bare-metal-expanding-the-cluster + - Name: Using bare metal as a service + File: bare-metal-using-bare-metal-as-a-service - Name: Installing IBM Cloud Bare Metal (Classic) Dir: installing_ibm_cloud_classic Distros: openshift-origin,openshift-enterprise diff --git a/installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc b/installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc new file mode 100644 index 0000000000..a35e09d1df --- /dev/null +++ b/installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc @@ -0,0 +1,41 @@ +:_mod-docs-content-type: ASSEMBLY +[id="bare-metal-using-bare-metal-as-a-service"] += Using bare metal as a service +include::_attributes/common-attributes.adoc[] +:context: bare-metal-using-bmaas + +toc::[] + +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: + +* 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 {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. + +:FeatureName: BMaaS +include::snippets/technology-preview.adoc[] +:!FeatureName: + +include::modules/bmaas-prerequisites.adoc[leveloffset=+1] + +include::modules/bmaas-using-the-bmo-to-manage-resources-across-all-namespaces.adoc[leveloffset=+1] + +include::modules/bmaas-setting-up-a-dedicated-namespace.adoc[leveloffset=+1] + +include::modules/bmo-creating-a-bmc-secret.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#bmc-addressing_ipi-install-installation-workflow[About BMC addressing] + +include::modules/bmo-creating-a-bare-metal-host-resource.adoc[leveloffset=+1] + +include::modules/bmo-configuring-users-for-bmaas-hosts.adoc[leveloffset=+1] + +//include::modules/bmo-configuring-ignition-userdata.adoc[leveloffset=+1] + +include::modules/bmo-configuring-the-networkdata-parameter-in-the-bmo-cr.adoc[leveloffset=+1] + +include::modules/bmo-deploying-an-image-to-the-bare-metal-host.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/bmaas-prerequisites.adoc b/modules/bmaas-prerequisites.adoc new file mode 100644 index 0000000000..7bfd323a03 --- /dev/null +++ b/modules/bmaas-prerequisites.adoc @@ -0,0 +1,28 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: CONCEPT +[id="bmaas-prerequisites_{context}"] += 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 {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. + +Cluster Privileges:: +You must have `cluster-admin` privileges on the {product-title} 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: + + * `http://example.com/rhel9.qcow2` + * `http://example.com/rhel9.qcow2.sha512sum` + * `http://example.com/stream9.qcow2` + * `http://example.com/stream9.qcow2.sha512sum` + +These prerequisites ensure that BMaaS can provision and manage bare-metal hosts effectively. diff --git a/modules/bmaas-setting-up-a-dedicated-namespace.adoc b/modules/bmaas-setting-up-a-dedicated-namespace.adoc new file mode 100644 index 0000000000..fe16017215 --- /dev/null +++ b/modules/bmaas-setting-up-a-dedicated-namespace.adoc @@ -0,0 +1,176 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmaas-setting-up-a-dedicated-namespace_{context}"] += Setting up a dedicated namespace + +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. + +.Prerequisites + +* 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]. + +.Procedure + +. Configure a BMaaS `bmadmin` user in the identity provider and create a secret in OpenShift: + +.. Create the `bmadmin` user in the identity provider. For example, if using the `htpasswd` identity provider, run the following command: ++ +[source,terminal] +---- +$ htpasswd -c -B -b ./users_htpasswd +---- +:: +The user name for the identity provider. Replace `` with your preferred user name. This example uses `bmadmin`. +:: +The password for the user. Replace `` with a secure password. + +.. Create a secret in the `openshift-config` namespace to store the identity provider configuration by running the following command: ++ +[source,terminal] +---- +$ oc create secret generic -n openshift-config +---- ++ +For example, when using the `htpasswd` identity provider, run the following command: ++ +[source,terminal] +---- +$ oc create secret generic htpass-secret --from-file=htpasswd=users_htpasswd -n openshift-config +---- +:: +The arguments specific to the identity provider secret. Replace `` with the appropriate arguments for your identity provider. + +. Configure OAuth to use the identity provider: + +.. Edit the OAuth resource by running the following command: ++ +[source,terminal] +---- +$ oc edit oauth cluster +---- ++ +The editor opens and displays the Oauth resource. + +.. Add the identity provider configuration to the `spec.identityProviders` list: ++ +.Identity provider configuration examples +[options="header"] +|==== +|Type|Example +| htpasswd +a|[source,yaml] +---- +# ... +- name: my_bmaas_provider + mappingMethod: claim + type: htpasswd + htpasswd: + fileData: + name: +# ... +---- +| LDAP +a|[source,yaml] +---- +# ... +- name: my_bmaas_provider + mappingMethod: claim + type: ldap + ldap: + attributes: + id: + - dn + email: + - mail + name: + - cn + preferredUsername: + - uid +# ... +---- +| GitHub +a|[source,yaml] +---- +# ... +- 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 link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html-single/authentication_and_authorization/index[Authentication and authorization]. + +.. Save and exit the editor. + +. Create a BMaaS `bmadmin` user by running the following command: ++ +[source,terminal] +---- +$ oc create user +---- +:: +The user name. Replace `` with your username. The following examples use `bmadmin` as the username. + +. Create a dedicated `bmaas` namespace for BMaaS hosts by running the following command: ++ +[source,terminal] +---- +$ oc new-project +---- +``:: +Replace 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: ++ +[source,terminal] +---- +$ oc adm policy add-role-to-user edit -n bmaas +---- + +. Clone the `baremetal-operator` repository to obtain the role-based access control (RBAC) role definitions by running the following command: ++ +[source,terminal,subs="attributes"] +---- +$ git clone -b release-{product-version} 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: ++ +[source,terminal] +---- +$ oc apply -f baremetal-operator/config/base/rbac/.yaml +---- + +. Assign the custom RBAC roles to the BMaaS `bmadmin` user in the `bmaas` namespace by running the following command: ++ +[source,terminal] +---- +$ oc adm policy add-role-to-user bmadmin -n bmaas +---- + +. Login as the `bmadmin` user by running the following command: ++ +[source,terminal] +---- +$ oc login :6443 +---- +``:: +The URL to the Kubernetes API. + diff --git a/modules/bmaas-using-the-bmo-to-manage-resources-across-all-namespaces.adoc b/modules/bmaas-using-the-bmo-to-manage-resources-across-all-namespaces.adoc new file mode 100644 index 0000000000..fc5def61f5 --- /dev/null +++ b/modules/bmaas-using-the-bmo-to-manage-resources-across-all-namespaces.adoc @@ -0,0 +1,25 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmaas-using-the-bmo-to-manage-resources-across-all-namespaces_{context}"] += 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 {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. + +.Prerequisites + +* 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. + +.Procedure + +* Patch the provisioning configuration to enable watching all namespaces by running the following command: ++ +[source,terminal] +---- +$ oc patch provisioning/provisioning-configuration \ + --type merge -p '{"spec": {"watchAllNamespaces": true}}' +---- ++ +The BMO applies this change automatically. \ No newline at end of file diff --git a/modules/bmo-configuring-ignition-userdata.adoc b/modules/bmo-configuring-ignition-userdata.adoc new file mode 100644 index 0000000000..7f98b78262 --- /dev/null +++ b/modules/bmo-configuring-ignition-userdata.adoc @@ -0,0 +1,51 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmo-configuring-ignition-userdata_{context}"] += Configuring Ignition-based userData for Fedora CoreOS + +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. + +.Procedure + +. Create a `ignition-config.yaml` file with the following content: ++ +[source,yaml] +---- +ignition: + version: "3.4.0" +passwd: + users: + - name: + passwordHash: + sshAuthorizedKeys: + - +---- ++ +:: + The user name. For example, `bmadmin`. +:: + The hashed password for the `` user. You can generate a hashed password using tools like `mkpasswd`. +:: + The public SSH key to use when accessing this host as the `` user. + +. Create a secret from the Ignition file by running the following command: ++ +[source,terminal] +---- +$ oc create secret generic bmaas-ignition \ + --from-file=userData=ignition-config.yaml -n bmaas +---- + +. Configure the `BareMetalHost` to use the Ignition secret by running the following command: ++ +[source,terminal] +---- +$ oc patch baremetalhost -n bmaas \ + --type=json -p='[{"op": "add", "path": "/spec/userData", "value": {"name": "bmaas-ignition"}}]' +---- ++ +:: + The name of the bare-metal host. diff --git a/modules/bmo-configuring-the-networkdata-parameter-in-the-bmo-cr.adoc b/modules/bmo-configuring-the-networkdata-parameter-in-the-bmo-cr.adoc new file mode 100644 index 0000000000..2ea0fab3c2 --- /dev/null +++ b/modules/bmo-configuring-the-networkdata-parameter-in-the-bmo-cr.adoc @@ -0,0 +1,54 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmo-configuring-the-networkdata-parameter-in-the-bmo-cr_{context}"] += 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: ++ +[source,yaml] +---- +links: + - id: + type: phy + ethernet_mac_address: +networks: + - id: + link: + type: ipv4_dhcp +services: + - type: dns + address: +---- ++ +``:: +The ID of the network interface, such as `enp2s0`. +``:: +The MAC address of the network interface. +``:: +The IP address of the DNS server. + +. Create a secret from the `networkData` file by running the following command: ++ +[source,terminal] +---- +$ oc create secret generic -network-data \ + --from-file=networkData=network-data.yaml -n bmaas +---- ++ +``:: +The hostname of the bare-metal host. + +. Configure the `BareMetalHost` to use the `networkData` file by running the following command: ++ +[source,terminal] +---- +$ oc patch baremetalhost -n bmaas \ + --type merge -p '{"spec":{"networkData":{"name":"-network-data"}}}' +---- diff --git a/modules/bmo-configuring-users-for-bmaas-hosts.adoc b/modules/bmo-configuring-users-for-bmaas-hosts.adoc new file mode 100644 index 0000000000..2409059bf6 --- /dev/null +++ b/modules/bmo-configuring-users-for-bmaas-hosts.adoc @@ -0,0 +1,76 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmo-configuring-users-for-bmaas-hosts_{context}"] += 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 `-user-data.yaml` with the following content: ++ +[source,yaml] +---- +users: + - name: + sudo: [] + ssh_authorized_keys: + - + + shell: + groups: [] + lock_passwd: true|false +---- +``:: + The name of the bare-metal host. +``:: +The user name. +``:: +The sudo configuration for the user. +``:: +The SSH key type. +``:: +The public SSH key to use when accessing this host as the `` user. +``:: +The shell to use when accessing the host. +``:: +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 ++ +[source,yaml] +---- +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 `-user-data.yaml` file by running the following command: ++ +[source,terminal] +---- +$ oc create secret generic -user-data \ + --from-file=userData=-user-data.yaml -n bmaas +---- +``:: + The name of the bare-metal host. + +. Configure the `BareMetalHost` to use the `-user-data.yaml` file by running the following command: ++ +[source,terminal] +---- +$ oc patch baremetalhost -n bmaas \ + --type merge -p '{"spec":{"userData":{"name":"-user-data"}}}' +---- +``:: + The name of the bare-metal host. \ No newline at end of file diff --git a/modules/bmo-creating-a-bare-metal-host-resource.adoc b/modules/bmo-creating-a-bare-metal-host-resource.adoc new file mode 100644 index 0000000000..52d66f3c4b --- /dev/null +++ b/modules/bmo-creating-a-bare-metal-host-resource.adoc @@ -0,0 +1,61 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmo-creating-a-bare-metal-host-resource_{context}"] += 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: ++ +[source,terminal] +---- +$ vim bmaas--bmh.yaml +---- ++ +:: + Replace `` with the name of the bare-metal host. + +. Edit the CR: ++ +[source,yaml] +---- +apiVersion: metal3.io/v1alpha1 +kind: BareMetalHost +metadata: + name: bmaas- + namespace: bmaas +spec: + online: true + bootMACAddress: + bmc: + address: redfish-virtualmedia+
/redfish/v1/Systems/System.Embedded.1 + credentialsName: bmaas--bmc-secret +---- ++ +:: + Replace `` with the MAC address of the first NIC on the bare-metal host. +
:: + Replace `
` with IP address or FQDN of the host. + +. Apply the CR by running the following command: ++ +[source,terminal] +---- +$ oc apply -f bmaas--bmh.yaml +---- + +.Verification + +* Check the `BareMetalHost` state by running the following command: ++ +[source,terminal] +---- +$ oc get baremetalhost -n bmaas +---- ++ +The state progresses from *registering*, to *inspecting*, and finally to *available*. \ No newline at end of file diff --git a/modules/bmo-creating-a-bmc-secret.adoc b/modules/bmo-creating-a-bmc-secret.adoc new file mode 100644 index 0000000000..e3fcfc66ea --- /dev/null +++ b/modules/bmo-creating-a-bmc-secret.adoc @@ -0,0 +1,47 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmo-creating-a-bmc-secret_{context}"] += 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: ++ +[source,terminal] +---- +$ vim bmaas--bmc-secret.yaml +---- ++ +Replace `` with the name of the bare-metal host. + +. Edit the secret: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: bmaas--bmc-secret + namespace: bmaas +type: Opaque +data: + username: + password: +---- ++ +:: +Replace `` with the BMC user name as a Base64-encoded string. +:: +Replace `` with the BMC password as a Base64-encoded string. + +. Apply the BMC secret by running the following command: ++ +[source,terminal] +---- +$ oc apply -f bmaas--bmc-secret.yaml +---- diff --git a/modules/bmo-deploying-an-image-to-the-bare-metal-host.adoc b/modules/bmo-deploying-an-image-to-the-bare-metal-host.adoc new file mode 100644 index 0000000000..260bd60819 --- /dev/null +++ b/modules/bmo-deploying-an-image-to-the-bare-metal-host.adoc @@ -0,0 +1,26 @@ +// This module is included in the following assemblies: +// +// * installing/installing_bare_metal/bare-metal-using-bare-metal-as-a-service.adoc + +:_mod-docs-content-type: PROCEDURE +[id="bmo-deploying-an-image-to-the-bare-metal-host_{context}"] += 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: ++ +[source,terminal] +---- +$ oc patch baremetalhost \ + --type merge -p '{"spec": {"image": {"url": "", "checksum": "", "checksumType": "auto"}}}' +---- ++ +``:: +The name of your `BareMetalHost` resource. +``:: +The URL of the image to deploy. +``:: +The URL of the checksum file for the image.