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 93f56ce..0000000 Binary files a/docs/public/favicon.ico and /dev/null differ