fixed broken link reference to CRs

crs_reference.md

@@ -8,7 +8,7 @@ they reference to each other. To see the example CRs check
 ## Environment Variables
 
 The user is required to set the following environment variables before applying
-the [CRs](https://github.com/metal3-io/metal3-dev-env/tree/master/crs)
+the [CRs](https://github.com/metal3-io/metal3-dev-env/tree/b5a53ecf9576c6deab81f692733782d4c5e8091a/crs)
 
 ```console
 CLUSTER_NAME

docs/user-guide/src/SUMMARY.md

@@ -13,6 +13,7 @@
    - [Basic Features](bmo/features.md)
       - [Automated Cleaning](bmo/automated_cleaning.md)
       - [Automatic Secure Boot](bmo/automatic_secure_boot.md)
+      - [Firmware Settings](bmo/firmware_settings.md)
       - [Inspect Annotation](bmo/inspect_annotation.md)
       - [Reboot Annotation](bmo/reboot_annotation.md)
    - [Advanced Features](bmo/features.md)

docs/user-guide/src/bmo/features.md

@@ -4,6 +4,7 @@
 
 - [Automated Cleaning](./automated_cleaning.md)
 - [Automatic Secure Boot](./automatic_secure_boot.md)
+- [Firmware Settings](./firmware_settings.md)
 - [Inspect annotation](./inspect_annotation.md)
 - [Reboot annotation](./reboot_annotation.md)
 

docs/user-guide/src/bmo/firmware_settings.md

@@ -0,0 +1,196 @@
+# Firmware Settings
+
+Metal3 supports modifying firmware settings of the hosts before provisioning
+them. This feature can be used, for example, to enable or disable CPU
+virtualization extensions, huge pages or SRIOV support. The corresponding
+functionality in Ironic is called [BIOS
+settings](https://docs.openstack.org/ironic/latest/admin/bios.html).
+
+Reading and modifying firmware settings is only supported for drivers based on
+Redfish, iRMC or iLO (see [supported hardware](./supported_hardware.md)). The
+commonly used IPMI driver does not support this feature.
+
+## HostFirmwareSettings Resources
+
+A `HostFirmwareSettings` resource is automatically created for each host that
+supports firmware settings with the same name and in the same namespace as
+host.  BareMetal Operator puts the current settings in the `status.settings`
+field:
+
+```yaml
+apiVersion: metal3.io/v1alpha1
+kind: HostFirmwareSettings
+metadata:
+  creationTimestamp: "2024-05-28T16:31:06Z"
+  generation: 1
+  name: worker-0
+  namespace: my-cluster
+  ownerReferences:
+  - apiVersion: metal3.io/v1alpha1
+    blockOwnerDeletion: true
+    controller: true
+    kind: BareMetalHost
+    name: worker-0
+    uid: 663a1453-d4d8-43a3-b459-64ea94d1435f
+  resourceVersion: "20653"
+  uid: 46fc9ccb-0717-4ced-93aa-babbe1a8cd5b
+spec:
+  settings: {}
+status:
+  conditions:
+  - lastTransitionTime: "2024-05-28T16:31:06Z"
+    message: ""
+    observedGeneration: 1
+    reason: Success
+    status: "True"
+    type: Valid
+  - lastTransitionTime: "2024-05-28T16:31:06Z"
+    message: ""
+    observedGeneration: 1
+    reason: Success
+    status: "False"
+    type: ChangeDetected
+  lastUpdated: "2024-05-28T16:31:06Z"
+  schema:
+    name: schema-f229959d
+    namespace: my-cluster
+  settings:
+    BootMode: Uefi
+    EmbeddedSata: Raid
+    L2Cache: 10x256 KB
+    NicBoot1: NetworkBoot
+    NumCores: "10"
+    ProcTurboMode: Enabled
+    QuietBoot: "true"
+    SecureBootStatus: Enabled
+    SerialNumber: QPX12345
+```
+
+In this example (taken from a virtual testing environment):
+
+- The `spec.settings` mapping is empty - no change is requested by the user.
+
+- The `status.settings` mapping is populated with the current values detected
+  by Ironic.
+
+- The `Valid` condition is `True`, which means that `spec.settings` are valid
+  according to the host's `FirmwareSchema`. The condition will be set to
+  `False` if any value in `spec.settings` fails validation.
+
+- The `ChangeDetected` condition is `False`, which means that the desired
+  settings and the real settings do not diverge. This condition will be set
+  to `True` after you modify `spec.settings` until the change is reflected
+  in `status.settings`.
+
+- The `schema` field contains a link to the firmware schema (see below).
+
+**Warning:** Ironic does not constantly update the current settings to avoid an
+unnecessary load on the host's BMC. The current settings are updated on
+enrollment, provisioning and deprovisioning only.
+
+## FirmwareSchema resources
+
+One or more `FirmwareSchema` resources are created for hosts that support
+firmware settings. Each schema object represents a list of possible settings
+and limits on their values.
+
+```yaml
+apiVersion: metal3.io/v1alpha1
+kind: FirmwareSchema
+metadata:
+  creationTimestamp: "2024-05-28T16:31:06Z"
+  generation: 1
+  name: schema-f229959d
+  namespace: my-cluster
+  ownerReferences:
+  - apiVersion: metal3.io/v1alpha1
+    kind: HostFirmwareSettings
+    name: worker-1
+    uid: bd97a81c-c736-4a6d-aee5-32dccb26e366
+  - apiVersion: metal3.io/v1alpha1
+    kind: HostFirmwareSettings
+    name: worker-0
+    uid: d8fb3c8a-395e-4c0a-9171-5928a68305b3
+spec:
+  hardwareModel: KVM (8.6.0)
+  hardwareVendor: Red Hat
+  schema:
+    BootMode:
+      allowable_values:
+      - Bios
+      - Uefi
+      attribute_type: Enumeration
+      read_only: false
+    NumCores:
+      attribute_type: Integer
+      lower_bound: 10
+      read_only: true
+      unique: false
+      upper_bound: 20
+    QuietBoot:
+      attribute_type: Boolean
+      read_only: false
+      unique: false
+```
+
+The following fields are included for each setting:
+
+- `attribute_type` -- The type of the setting (`Enumeration`, `Integer`,
+  `String`, `Boolean`, or `Password`).
+- `read_only` -- The setting is read-only and cannot be modified.
+- `unique` -- The setting's value is unique in this host (e.g. serial numbers).
+
+For type `Enumeration`:
+
+- `allowable_values` -- A list of allowable values.
+
+For type `Integer`:
+
+- `lower_bound` -- The lowest allowed integer value.
+- `upper_bound` -- The highest allowed integer value.
+
+For type `String`:
+
+- `min_length` -- The minimum length that the string value can have.
+- `max_length` -- The maximum length that the string value can have.
+
+**Note:** the `FirmwareSchema` has a unique identifier derived from its
+settings and limits. Multiple hosts may therefore have the same
+`FirmwareSchema` identifier so its likely that more than one
+`HostFirmwareSettings` reference the same `FirmwareSchema` when hardware of the
+same vendor and model are used.
+
+## How to change firmware settings
+
+To change one or more settings for a host, update the corresponding
+`HostFirmwareSettings` resource, changing or adding the required settings to
+`spec.settings`. For example:
+
+```yaml
+apiVersion: metal3.io/v1alpha1
+kind: HostFirmwareSettings
+metadata:
+  name: worker-0
+  namespace: my-cluster
+  # ...
+spec:
+  settings:
+     QuietBoot: true
+status:
+  # ...
+```
+
+**Hint:** you don't need to copy over the settings you don't want to change.
+
+If the host is in the `available` state, it will be moved to the `preparing`
+state and the new settings will be applied. After some time, the host will move
+back to `available`, and the resulting changes will be reflected in the
+`status` of the `HostFirmwareSettings` object. Applying firmware settings
+requires 1-2 reboots of the machine and thus may take 5-20 minutes.
+
+**Warning:** if the host is not in the `available` state, the settings will be
+pending until it gets to this state (e.g. as a result of deprovisioning).
+
+Alternatively, you can create a `HostFirmwareSettings` object together with
+the `BareMetalHost` object. In this case, the settings will be applied after
+inspection is finished.

docs/user-guide/src/version_support.md

@@ -57,6 +57,22 @@ Following table summarizes BMO release/test process:
 | v0.2          | EOL       |
 | v0.1          | EOL       |
 
+## Ironic-image
+
+Since `v23.1.0`, Ironic follows the semantic versioning scheme for its own
+release cycle, the same way as CAPM3 and IPAM. Currently, we have release-25.0,
+release-24.1, release-24.0 and release-23.1 release branches for `v25.0.x`,
+`v24.1.x` `v24.0.x` and `v23.1.x` release cycle respectively and as such two or
+three braches are maintained as supported releases.
+Following table summarizes Ironic-image release/test process:
+
+| Minor release | Status    |
+| ------------- | --------- |
+| v25.0         | Supported |
+| v24.1         | Supported |
+| v24.0         | Supported |
+| v23.1         | Tested    |
+
 ## Image tags
 
 The Metal³ team provides container images for all the main projects and also
@@ -86,16 +102,16 @@ The table describes which branches/image-tags are tested in each periodic CI tes
 | -------------------------------------------------------------- | ------------ | ----------- | -------------- | -------------- | ----------- | ---------- |
 | metal3-periodic-ubuntu/centos-e2e-integration-test-main        | main         | main        | main           | latest         | latest      | latest     |
 | metal3_periodic_main_integration_test_ubuntu/centos            | main         | main        | main           | latest         | latest      | latest     |
-| metal3-periodic-ubuntu/centos-e2e-integration-test-release-1-7 | release-1.7  | release-1.7 | release-0.6    | v0.6.0         | latest      | latest     |
-| metal3-periodic-ubuntu/centos-e2e-integration-test-release-1-6 | release-1.6  | release-1.6 | release-0.5    | v0.5.0         | latest      | latest     |
-| metal3-periodic-ubuntu/centos-e2e-integration-test-release-1-5 | release-1.5  | release-1.5 | release-0.5    | v0.5.0         | latest      | latest     |
+| metal3-periodic-ubuntu/centos-e2e-integration-test-release-1-7 | release-1.7  | release-1.7 | release-0.6    | v0.6.1         | latest      | v24.1.1    |
+| metal3-periodic-ubuntu/centos-e2e-integration-test-release-1-6 | release-1.6  | release-1.6 | release-0.5    | v0.5.0         | latest      | v24.0.0    |
+| metal3-periodic-ubuntu/centos-e2e-integration-test-release-1-5 | release-1.5  | release-1.5 | release-0.5    | v0.5.0         | latest      | v23.1.0    |
 
 | FEATURE AND E2E TESTS                                          | CAPM3 branch | IPAM branch | BMO branch/tag | Keepalived tag | MariaDB tag | Ironic tag |
 | -------------------------------------------------------------- | ------------ | ----------- | -------------- | -------------- | ----------- | ---------- |
 | metal3-periodic-ubuntu/centos-e2e-feature-test-main            | main         | main        | main           | latest         | latest      | latest     |
-| metal3-periodic-ubuntu/centos-e2e-feature-test-release-1-7     | release-1.7  | release-1.7 | release-0.6    | v0.6.0         | latest      | latest     |
-| metal3-periodic-ubuntu/centos-e2e-feature-test-release-1-6     | release-1.6  | release-1.6 | release-0.5    | v0.5.0         | latest      | latest     |
-| metal3-periodic-ubuntu/centos-e2e-feature-test-release-1-5     | release-1.5  | release-1.5 | release-0.4    | v0.4.0         | latest      | latest     |
+| metal3-periodic-ubuntu/centos-e2e-feature-test-release-1-7     | release-1.7  | release-1.7 | release-0.6    | v0.6.1         | latest      | v24.1.1    |
+| metal3-periodic-ubuntu/centos-e2e-feature-test-release-1-6     | release-1.6  | release-1.6 | release-0.5    | v0.5.0         | latest      | v24.0.0    |
+| metal3-periodic-ubuntu/centos-e2e-feature-test-release-1-5     | release-1.5  | release-1.5 | release-0.4    | v0.4.0         | latest      | v23.1.0    |
 
 | EPHEMERAL TESTS                                                | CAPM3 branch | IPAM branch | BMO branch/tag | Keepalived tag | MariaDB tag | Ironic tag |
 | -------------------------------------------------------------- | ------------ | ----------- | -------------- | -------------- | ----------- | ---------- |