From 3831743c666f6dae94b669ae8b9f9abeb992a488 Mon Sep 17 00:00:00 2001 From: Andreas Fritzler Date: Thu, 26 Jun 2025 10:03:53 +0200 Subject: [PATCH] Add docs for BM discovery and first boot --- README.md | 2 +- docs/.vitepress/config.mts | 2 +- docs/baremetal/architecture/discovery.md | 169 ++++++++++++++++++++++- docs/baremetal/index.md | 4 + docs/public/favicon.ico | Bin 1150 -> 0 bytes 5 files changed, 171 insertions(+), 6 deletions(-) delete mode 100644 docs/public/favicon.ico diff --git a/README.md b/README.md index deb835e..c12f024 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# IronCore Project Central Documentation +# IronCore Project Landing Page and Central Documentation [![REUSE status](https://api.reuse.software/badge/github.com/ironcore-dev/ironcore-dev.github.io)](https://api.reuse.software/info/github.com/ironcore-dev/ironcore-dev.github.io) [![GitHub License](https://img.shields.io/static/v1?label=License&message=Apache-2.0&color=blue)](LICENSE) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index c7ab337..1d81f81 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -5,7 +5,7 @@ export default withMermaid({ title: "IronCore Project", description: "Welcome to IronCore Documentation", base: '/', - head: [['link', { rel: 'icon', href: '/favicon.ico' }]], + head: [['link', { rel: 'icon', href: 'https://raw.githubusercontent.com/ironcore-dev/ironcore/refs/heads/main/docs/assets/logo_borderless.svg' }]], themeConfig: { // https://vitepress.dev/reference/default-theme-config nav: [ diff --git a/docs/baremetal/architecture/discovery.md b/docs/baremetal/architecture/discovery.md index 51566b9..9b4c2e8 100644 --- a/docs/baremetal/architecture/discovery.md +++ b/docs/baremetal/architecture/discovery.md @@ -1,6 +1,167 @@ -# Discovery Boot +# Server Discovery and First Boot -TODO: +This document describes the discovery and first boot process for bare metal servers in IronCore's baremetal automation. +The goal here is to provide a clear understanding of how bare metal servers are discovered and prepared for provisioning. -* Describe the discovery boot process -* Describe the role of the discovery image/metalprobe \ No newline at end of file +## Server Discovery + +The `metal-operator` supports two types of server discovery: +1. **DHCP-based discovery**: This method uses [FeDHCP](https://github.com/ironcore-dev/fedhcp) to discover servers based +on their DHCP requests. +2. **BMC-based discovery**: This method uses the Baseboard Management Controller (BMC) to discover servers managed by a BMC. + +### DHCP-based Discovery + +The DHCP-based discovery process works as follows: + +```mermaid +graph TD + A[BMC Instance] -->|DHCP Request| B[FeDHCP] + B -->|creates| C[Endpoint] + C <-->|watches| D[EndpointReconciler] + D --> |lookup| E[MACAddress DB] + D -->|creates| F[BMC] + D -->|creates| G[BMCSecret] + F <-->|watches| H[BMCReconciler] + H -->|creates| J[Server] +``` + +1. The BMC instance sends a DHCP request to the FeDHCP server. +2. FeDHCP creates an `Endpoint` resource based on the DHCP request. + +Here is an example of an `Endpoint` resource: + +```yaml +apiVersion: metal.ironcore.dev/v1alpha1 +kind: Endpoint +metadata: + name: device-12345 +spec: + macAddress: "00:1A:2B:3C:4D:5E" + ip: 192.168.100.10 +``` + +3. The `EndpointReconciler` watches for changes to the `Endpoint` and looks up the MAC address in the [MACAddress database](https://ironcore-dev.github.io/metal-operator/concepts/endpoints.html#configuration) +to find a matching MAC address prefix end derive from that the initial credentials, protocol, and other information needed to create a BMC resource. +4. If a MAC address prefix is found in the database, the `EndpointReconciler` creates a `BMC` and `BMCSecret` resource. + +Here is an example of a `BMC` resource: + +```yaml +apiVersion: metal.ironcore.dev/v1alpha1 +kind: BMC +metadata: + name: my-bmc +spec: + endpointRef: + name: my-bmc-endpoint + bmcSecretRef: + name: my-bmc-secret + protocol: + name: Redfish + port: 8000 + scheme: http + consoleProtocol: + name: SSH + port: 22 +``` + +5. The `BMCReconciler` watches for changes to the `BMC` resource and creates a `Server` resource based on the BMC information. + +Here is an example of a `Server` resource: + +```yaml +apiVersion: metal.ironcore.dev/v1alpha1 +kind: Server +metadata: + name: my-server +spec: + uuid: "123e4567-e89b-12d3-a456-426614174000" + power: "Off" + bmcRef: + name: my-bmc +``` + +### BMC-based Discovery + +The BMC-based discovery process works similar to the DHCP-based discovery, but here a `BMC` resource is created directly by +a user or an external system. + +An example of a `BMC` resource using inline access credentials is as follows: + +```yaml +apiVersion: metal.ironcore.dev/v1alpha1 +kind: BMC +metadata: + name: my-bmc-inline +spec: + access: + macAddress: "00:1A:2B:3C:4D:5E" + ip: "192.168.100.10" + bmcSecretRef: + name: my-bmc-secret + protocol: + name: Redfish + port: 8000 + consoleProtocol: + name: SSH + port: 22 +``` + +The rest of the process is the same as in the DHCP-based discovery. + +## Discovery Boot + +The first boot process (discovery boot) is triggered when a `Server` resource is created and is in the `Initial` state. +That will cause the `ServerReconciler` to initialize the first boot process which looks like this: + +```mermaid +graph TD + A[Server] <-->|watches| B[ServerReconciler] + B --> |creates/watches| C[ServerBootConfiguration] + B --> |power on/off| J[Server Instance] + C <--> |watches| D[boot-operator] + D --> |creates/serves| E[iPXEBoot/HTTPBoot] + D --> |creates/serves| F[Ignition] +``` + +1. The `ServerReconciler` creates for every `Server` resource which is in the `Initial` state a [`ServerBootConfiguration`](https://ironcore-dev.github.io/metal-operator/concepts/serverbootconfigurations.html). +An example of a `ServerBootConfiguration` resource is as follows: + +```yaml +apiVersion: metal.ironcore.dev/v1alpha1 +kind: ServerBootConfiguration +metadata: + name: my-server-boot-config + namespace: defauilt +spec: + serverRef: + name: my-server + image: my-osimage:latest + ignitionSecretRef: + name: my-ignition-secret +``` + +The key fields here are: +- `image`: The OS image to be used for booting the server. This image is configured in the `metal-operator` and expects a valid +IronCore [OCI OS image](/iaas/architecture/os-images). +- `ignitionSecretRef`: A reference to a Kubernetes secret that contains the Ignition configuration for the server. This Ignition +is generated by the `metal-operator` and contains in essence a [`metalprobe`](https://github.com/ironcore-dev/metal-operator/pkgs/container/metalprobe) +image. `metalprobe` is an agent which is part of the `metal-operator` project that will be run on the server to extract +additional information about the server. This image can also be configured in the `metal-operator`. + +2. The `boot-operator` watches for changes to the `ServerBootConfiguration` resource and ensures the following: + - It creates an iPXE or HTTP boot configuration based on the `ServerBootConfiguration`. + - It serves the boot configuration via HTTP and is presented to the server via DHCP. + - It serves the necessary Ignition files for the server to boot and configure itself. +As soon as everything is ready to be served, the `boot-operator` will set the status of the `ServerBootConfiguration` to `Ready`. + +3. `Server` with a `spec.Power` set to `On` and a `ServerBootConfiguration` in `Ready` state will trigger the server to boot. + - The server will boot using the iPXE or HTTP boot configuration served by the `boot-operator`. + - The server will then apply the Ignition configuration and start the `metalprobe` image to gather additional information about the server. + - The `metalprobe` will report to a [registry endpoint](https://github.com/ironcore-dev/metal-operator/tree/main/internal/registry) the +extracted information about the server, which will be used by the `ServerReconciler` to update the `Server` status information and set the `Server` +state to `Available` if all expected information is available. + +Once the discovery and first boot process is completed, the `Server` resource will be in the `Available` state and +ready for further operations like provisioning custom software on it. diff --git a/docs/baremetal/index.md b/docs/baremetal/index.md index 7c1bb3b..1ca017f 100644 --- a/docs/baremetal/index.md +++ b/docs/baremetal/index.md @@ -16,6 +16,10 @@ The core components of the baremetal automation in IronCore include: - [**Boot Operator**](https://github.com/ironcore-dev/boot-operator): iPXE and HTTP boot server that provides boot images and Ignition configurations. - [**FeDHCP**](https://github.com/ironcore-dev/fedhcp): A DHCP server that provides inband and out of band network configuration to bare metal servers. +## Concepts and Usage Guides + +Usage guides and concepts for the `metal-operator` API types can be found in the [metal-operator documentation](https://ironcore-dev.github.io/metal-operator/concepts/). + ## Prerequisites The current implementation of the baremetal automation in IronCore requires the following prerequisites: diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico deleted file mode 100644 index 93f56ce7b9e0631e10c8994ae630b78b42f695cf..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1150 zcmb7EX-HI26h6-x6^f!i6(m9S!=436RDZ%~cgV`66X5@u0z@@{BQ4r~e3t=j3DJoiWR5WF&XyjEJOA#FXZm?LGA$+Y3n_ZvYJr1i(pSA)Fcq9;t198e?)?U%4p&> zRFtFz;f`esO09cwHDWGucM$UT=#aI=4d=Egs7h4eGAgJ!s=%J4g(F#qYF@XAd0dMZ z_%o5c#|zf&lW-=~4VfW2oC+eC4J60=(K^(c^>8HXVINyZ@DY2--LJy5l5pIha1fG~ z6HKcJCjtp4HxSYS75O}WE1^7+_j5#WaFhEH^%oENA~itdDjaTbTuDT6N&r&V5iCLO zFs~&PnGAU1xP|sIGhF5=yasC__{(}#=1RPcI*fiF!o#~ch+o27{0TRV0T5SreFla; zKF6EdGpLMV9;~h8&zcK-QJ=m^kKutYcwSe6{D?*Di8mgXWdpxP@buy;=KDQmR)j9^a;e16AhzxewDeXs3!TbC*EJMV=teg_8Mw`yKW{k7gG*hx6X z9MYNpx3B$NV}&h@P!T0OT8N(`{rJ>j!{~4yI`4%~;4e5hnNJbtTY}v&*xQ4V-dE^u zF2IM@BDhkgqb}VGUFC6T$@7=JNC7h z#d=jlaWBOZMD4hLjNN!vmAxo@btZAIa$gFc%Ol48W}QWi=p9FrPHHE5NUSCFZ$7^i zb(UGluM7w0D|3Ie#i1<@n)Ap+S1mkm;lGNYHv~!g(1#JB-U` w$zhy~#|106HUMomLeOy9n|1d6_nb06!Er)}ysUYsKQ)_cL-F_f;D7Ib19)O%TL1t6