Migrate BareMetalHost and HardwareData API docs from BMO to user-guide #475
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,133 @@ | ||
| # Status and Inspect Annotations | ||
|
|
||
| ## Status annotation | ||
|
|
||
| The status annotation is useful when you need to avoid inspection of a BareMetalHost. | ||
| This can happen if the status is already known, for example, when moving the BareMetalHost from one cluster to another. | ||
| By setting this annotation, the BareMetal Operator will take the status of the BareMetalHost directly from the annotation. | ||
|
|
||
| The annotation key is `baremetalhost.metal3.io/status` and the value is a JSON representation of the BareMetalHosts `status` field. | ||
| One simple way of extracting the status and turning it into an annotation is using kubectl like this: | ||
|
|
||
| ```bash | ||
| # Save the status in json format to a file | ||
| kubectl get bmh <name-of-bmh> -o jsonpath="{.status}" > status.json | ||
| # Save the BMH and apply the status annotation to the saved BMH. | ||
| kubectl -n metal3 annotate bmh <name-of-bmh> \ | ||
| baremetalhost.metal3.io/status="$(cat status.json)" \ | ||
| --dry-run=client -o yaml > bmh.yaml | ||
| ``` | ||
|
|
||
| Note that the above example does not apply the annotation to the BareMetalHost directly since this is most likely not useful to apply it on one that already has a status. | ||
| Instead it saves the BareMetalHost *with the annotation applied* to a file `bmh.yaml`. | ||
| This file can then be applied in another cluster. | ||
| The status would be discarded at this point since the user is usually not allowed to set it, but the annotation is still there and would be used by the BareMetal Operator to set status again. | ||
| Once this is done, the operator will remove the status annotation. | ||
| In this situation you may also want to check the [detached annotation](./detached_annotation.md) for how to remove the BareMetalHost from the old cluster without going through deprovisioning. | ||
|
|
||
| Here is an example of a BareMetalHost, first without the annotation, but with status and spec, and then the other way around. | ||
| This shows how the status field is turned into the annotation value. | ||
|
|
||
| ```yaml | ||
| apiVersion: metal3.io/v1alpha1 | ||
| kind: BareMetalHost | ||
| metadata: | ||
| name: node-0 | ||
| namespace: metal3 | ||
| spec: | ||
| automatedCleaningMode: metadata | ||
| bmc: | ||
| address: redfish+http://192.168.111.1:8000/redfish/v1/Systems/febc9f61-4b7e-411a-ada9-8c722edcee3e | ||
| credentialsName: node-0-bmc-secret | ||
| bootMACAddress: 00:80:1f:e6:f1:8f | ||
| bootMode: legacy | ||
| online: true | ||
| status: | ||
| errorCount: 0 | ||
| errorMessage: "" | ||
| goodCredentials: | ||
| credentials: | ||
| name: node-0-bmc-secret | ||
| namespace: metal3 | ||
| credentialsVersion: "1775" | ||
| hardwareProfile: "" | ||
| lastUpdated: "2022-05-31T06:33:05Z" | ||
| operationHistory: | ||
| deprovision: | ||
| end: null | ||
| start: null | ||
| inspect: | ||
| end: null | ||
| start: "2022-05-31T06:33:05Z" | ||
| provision: | ||
| end: null | ||
| start: null | ||
| register: | ||
| end: "2022-05-31T06:33:05Z" | ||
| start: "2022-05-31T06:32:54Z" | ||
| operationalStatus: OK | ||
| poweredOn: false | ||
| provisioning: | ||
| ID: 8d566f5b-a28f-451b-a70f-419507c480cd | ||
| bootMode: legacy | ||
| image: | ||
| url: "" | ||
| state: inspecting | ||
| triedCredentials: | ||
| credentials: | ||
| name: node-0-bmc-secret | ||
| namespace: metal3 | ||
| credentialsVersion: "1775" | ||
| ``` | ||
|
|
||
| ```yaml | ||
| apiVersion: metal3.io/v1alpha1 | ||
| kind: BareMetalHost | ||
| metadata: | ||
| name: node-0 | ||
| namespace: metal3 | ||
| annotations: | ||
| baremetalhost.metal3.io/status: | | ||
| {"errorCount":0,"errorMessage":"","goodCredentials":{"credentials":{"name":"node-0-bmc-secret","namespace":"metal3"},"credentialsVersion":"1775"},"hardwareProfile":"","lastUpdated":"2022-05-31T06:33:05Z","operationHistory":{"deprovision":{"end":null,"start":null},"inspect":{"end":null,"start":"2022-05-31T06:33:05Z"},"provision":{"end":null,"start":null},"register":{"end":"2022-05-31T06:33:05Z","start":"2022-05-31T06:32:54Z"}},"operationalStatus":"OK","poweredOn":false,"provisioning":{"ID":"8d566f5b-a28f-451b-a70f-419507c480cd","bootMode":"legacy","image":{"url":""},"state":"inspecting"},"triedCredentials":{"credentials":{"name":"node-0-bmc-secret","namespace":"metal3"},"credentialsVersion":"1775"}} | ||
| spec: | ||
| ... | ||
| ``` | ||
|
|
||
| ## Inspect Annotation | ||
|
|
||
| ## Re-running inspection | ||
|
|
||
| The inspect annotation can be used to request the BareMetal Operator to (re-)inspect an `available` BareMetalHost, for example, when the hardware changes. If an inspection request is made while the host is any otherstate than `available`, the request will be ignored. | ||
|
|
||
| To request a new inspection, simply annotate the host with `inspect.metal3.io`. Once inspection is requested, you should see the BMH in `inspecting` stateuntil inspection is completed, and by the end of inspection the`inspect.metal3.io` annotation will be removed automatically. | ||
|
|
||
| Here is an example: | ||
|
|
||
| ```yaml | ||
| apiVersion: metal3.io/v1alpha1 | ||
| kind: BareMetalHost | ||
| metadata: | ||
| name: example | ||
| annotations: | ||
| # The inspect annotation with no value | ||
| inspect.metal3.io: "" | ||
| spec: | ||
| ... | ||
| ``` | ||
|
|
||
| ## Disabling inspection | ||
|
|
||
| If you do not need the HardwareData collected by inspection, you can disable it by setting the `inspect.metal3.io` annotation to `disabled`, for example: | ||
|
|
||
| ```yaml | ||
| apiVersion: metal3.io/v1alpha1 | ||
| kind: BareMetalHost | ||
| metadata: | ||
| name: example | ||
| annotations: | ||
| inspect.metal3.io: disabled | ||
| spec: | ||
| ... | ||
| ``` | ||
|
|
||
| For advanced use cases, such as providing externally gathered inspection data, see [external inspection](./external_inspection.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| # API and Resource Definitions | ||
|
|
||
| ## BareMetalHost | ||
|
|
||
| **Metal³** introduces the concept of **BareMetalHost** resource, which | ||
| defines a physical host and its properties. See [BareMetalHost | ||
| CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/BareMetalHost/v1alpha1) | ||
| or check the source code at `apis/metal3.io/v1alpha1/baremetalhost_types.go` | ||
| for a detailed API description. See the [user | ||
| guide](https://book.metal3.io/bmo/introduction) for information on how to | ||
| manage hosts. | ||
|
|
||
| ## Triggering Provisioning | ||
|
|
||
| Several conditions must be met in order to initiate provisioning. | ||
|
|
||
| 1. The host `spec.image.url` field must contain a URL for a valid | ||
| image file that is visible from within the cluster and from the | ||
| host receiving the image. | ||
| 2. The host must have `online` set to `true` so that the operator will | ||
| keep the host powered on. | ||
| 3. The host must have all of the BMC details. | ||
|
|
||
| To initiate deprovisioning, clear the image URL from the host spec. | ||
|
|
||
| ## Unmanaged Hosts | ||
|
There was a problem hiding this comment. This is covered in the state machine docs (expand if needed) |
||
|
|
||
| Hosts created without BMC details will be left in the `unmanaged` | ||
| state until the details are provided. Unmanaged hosts cannot be | ||
| provisioned and their power state is undefined. | ||
|
|
||
| ## Pausing reconciliation | ||
|
There was a problem hiding this comment. This deserves a separate page in the advanced features section |
||
|
|
||
| It is possible to pause the reconciliation of a BareMetalHost object by adding | ||
| an annotation `baremetalhost.metal3.io/paused`. **Metal³** provider sets the | ||
| value of this annotation as `metal3.io/capm3` when the cluster to which the | ||
| **BareMetalHost** belongs, is paused and removes it when the cluster is | ||
| not paused. If you want to pause the reconciliation of **BareMetalHost** you can | ||
| put any value on this annotation **other than `metal3.io/capm3`**. Please make | ||
| sure that you remove the annotation **only if the value of the annotation is | ||
| not `metal3.io/capm3`, but another value that you have provided**. Removing the | ||
| annotation will enable the reconciliation again. | ||
|
|
||
| ## HostFirmwareSettings | ||
|
|
||
| A **HostFirmwareSettings** resource is used to manage BIOS settings for a host, | ||
| there is a one-to-one mapping with **BareMetalHosts**. A | ||
| **HostFirmwareSettings** resource is created when BIOS settings are read from | ||
| Ironic as the host moves to the Ready state. These settings are the complete | ||
| actual BIOS configuration names returned from the BMC, typically 100-200 | ||
| settings per host, as compared to the three vendor-independent fields stored in | ||
| the **BareMetalHosts** `firmware` field. | ||
|
|
||
| See [HostFirmwareSettings | ||
| CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/HostFirmwareSettings/v1alpha1) | ||
| or check the source code at `apis/metal3.io/v1alpha1/hostfirmwaresettings_types.go` | ||
| for a detailed API description. See the [firmware settings | ||
| guide](https://book.metal3.io/bmo/firmware_settings) for information on how to | ||
| change firmware settings. | ||
|
|
||
| ## FirmwareSchema | ||
|
|
||
| A **FirmwareSchema** resource contains the limits each setting, specific to | ||
| each host. This data comes directly from the BMC via Ironic. It can be used | ||
| to prevent misconfiguration of the **HostFirmwareSettings** *spec* field so | ||
| that invalid values are not sent to the host. 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. | ||
|
|
||
| See [FirmwareSchema | ||
| CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/FirmwareSchema/v1alpha1) | ||
| or check the source code at `apis/metal3.io/v1alpha1/firmwareschema_types.go` | ||
| for a detailed API description. | ||
|
|
||
| ## HardwareData | ||
|
|
||
| A **HardwareData** resource contains hardware specifications data of a | ||
| specific host and it is tightly coupled to its owner resource | ||
| BareMetalHost. The data in the HardwareData comes from Ironic after a | ||
| successful inspection phase. As such, operator will create HardwareData | ||
| resource for a specific BareMetalHost during transitioning phase from | ||
| inspecting into available state of the BareMetalHost. HardwareData gets | ||
| deleted automatically by the operator whenever its BareMetalHost is | ||
| deleted. Deprovisioning of the BareMetalHost should not trigger the | ||
| deletion of HardwareData, but during next provisioning it can be | ||
| re-created (with the same name and namespace) with the latest inspection | ||
| data retrieved from Ironic. HardwareData holds the same name and | ||
| namespace as its corresponding BareMetalHost resource. Currently, | ||
| HardwareData doesn't have *Status* subresource but only the *Spec*. | ||
|
|
||
| See [HardwareData | ||
| CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/HardwareData/v1alpha1) | ||
| or check the source code at `apis/metal3.io/v1alpha1/hardwaredata_types.go` | ||
| for a detailed API description. | ||
|
|
||
| ## PreprovisioningImage | ||
|
There was a problem hiding this comment. This also deserves its own advanced page |
||
|
|
||
| A **PreprovisioningImage** resource is automatically created by | ||
| baremetal-operator for each BareMetalHost to ensure creation of a | ||
| *preprovisioning image* for it. In this context, a preprovisioning image | ||
| is an ISO or initramfs file that contains the [Ironic | ||
| agent](https://docs.openstack.org/ironic-python-agent/). The relevant | ||
| parts of BareMetalHost are copied to the PreprovisioningImage *Spec*, | ||
| the resulting image is expected to appear in the *Status*. | ||
|
|
||
| The baremetal-operator project contains a simple controller for | ||
| PreprovisioningImages that uses images provided in the environment | ||
| variables `DEPLOY_ISO_URL` and `DEPLOY_RAMDISK_URL`. More sophisticated | ||
| controllers may be written downstream (for example, the OpenShift | ||
| [image-customization-controller](https://github.com/openshift/image-customization-controller)). | ||
|
|
||
| See [PreprovisioningImage | ||
| CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/PreprovisioningImage/v1alpha1) | ||
| or check the source code at `apis/metal3.io/v1alpha1/preprovisioningimage_types.go` | ||
| for a detailed API description. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is already covered in more details in the provisioning docs