Skip to content

Commit 1d6aabf

Browse files
MahnoorAsgharMahnoorAsghar
committed
Auto-generate API documentation from CRDs
Signed-off-by: Mahnoor Asghar <[email protected]>
1 parent e334842 commit 1d6aabf

File tree

6 files changed

+4795
-95
lines changed

6 files changed

+4795
-95
lines changed

‎Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,7 @@ manifests: manifests-generate manifests-kustomize ## Generate manifests e.g. CRD
224224
manifests-generate: $(CONTROLLER_GEN)
225225
cd apis; $(abspath $<) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:webhook:dir=../config/base/webhook/ output:crd:artifacts:config=../config/base/crds/bases
226226
$< rbac:roleName=manager-role paths="./..." output:rbac:artifacts:config=config/base/rbac
227+
./hack/gen-api-doc.sh
227228

228229
.PHONY: manifests-kustomize
229230
manifests-kustomize: $(KUSTOMIZE)

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ components, see the [Metal³ docs](https://github.com/metal3-io/metal3-docs).
2727

2828
## Resources
2929

30+
- [API overview](docs/api.md)
3031
- [API documentation](docs/api.md)
3132
- [Setup Development Environment](docs/dev-setup.md)
3233
- [Configuration](docs/configuration.md)

‎docs/api-overview.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# API and Resource Definitions
2+
3+
## BareMetalHost
4+
5+
**Metal³** introduces the concept of **BareMetalHost** resource, which
6+
defines a physical host and its properties. See [BareMetalHost
7+
CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/BareMetalHost/v1alpha1)
8+
or check the source code at `apis/metal3.io/v1alpha1/baremetalhost_types.go`
9+
for a detailed API description. See the [user
10+
guide](https://book.metal3.io/bmo/introduction) for information on how to
11+
manage hosts.
12+
13+
## Triggering Provisioning
14+
15+
Several conditions must be met in order to initiate provisioning.
16+
17+
1. The host `spec.image.url` field must contain a URL for a valid
18+
image file that is visible from within the cluster and from the
19+
host receiving the image.
20+
2. The host must have `online` set to `true` so that the operator will
21+
keep the host powered on.
22+
3. The host must have all of the BMC details.
23+
24+
To initiate deprovisioning, clear the image URL from the host spec.
25+
26+
## Unmanaged Hosts
27+
28+
Hosts created without BMC details will be left in the `unmanaged`
29+
state until the details are provided. Unmanaged hosts cannot be
30+
provisioned and their power state is undefined.
31+
32+
## Pausing reconciliation
33+
34+
It is possible to pause the reconciliation of a BareMetalHost object by adding
35+
an annotation `baremetalhost.metal3.io/paused`. **Metal³** provider sets the
36+
value of this annotation as `metal3.io/capm3` when the cluster to which the
37+
**BareMetalHost** belongs, is paused and removes it when the cluster is
38+
not paused. If you want to pause the reconciliation of **BareMetalHost** you can
39+
put any value on this annotation **other than `metal3.io/capm3`**. Please make
40+
sure that you remove the annotation **only if the value of the annotation is
41+
not `metal3.io/capm3`, but another value that you have provided**. Removing the
42+
annotation will enable the reconciliation again.
43+
44+
## HostFirmwareSettings
45+
46+
A **HostFirmwareSettings** resource is used to manage BIOS settings for a host,
47+
there is a one-to-one mapping with **BareMetalHosts**. A
48+
**HostFirmwareSettings** resource is created when BIOS settings are read from
49+
Ironic as the host moves to the Ready state. These settings are the complete
50+
actual BIOS configuration names returned from the BMC, typically 100-200
51+
settings per host, as compared to the three vendor-independent fields stored in
52+
the **BareMetalHosts** `firmware` field.
53+
54+
See [HostFirmwareSettings
55+
CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/HostFirmwareSettings/v1alpha1)
56+
or check the source code at `apis/metal3.io/v1alpha1/hostfirmwaresettings_types.go`
57+
for a detailed API description. See the [firmware settings
58+
guide](https://book.metal3.io/bmo/firmware_settings) for information on how to
59+
change firmware settings.
60+
61+
## FirmwareSchema
62+
63+
A **FirmwareSchema** resource contains the limits each setting, specific to
64+
each host. This data comes directly from the BMC via Ironic. It can be used
65+
to prevent misconfiguration of the **HostFirmwareSettings** *spec* field so
66+
that invalid values are not sent to the host. The **FirmwareSchema** has a
67+
unique identifier derived from its settings and limits. Multiple hosts may therefore
68+
have the same **FirmwareSchema** identifier so its likely that more than one
69+
**HostFirmwareSettings** reference the same **FirmwareSchema** when
70+
hardware of the same vendor and model are used.
71+
72+
See [FirmwareSchema
73+
CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/FirmwareSchema/v1alpha1)
74+
or check the source code at `apis/metal3.io/v1alpha1/firmwareschema_types.go`
75+
for a detailed API description.
76+
77+
## HardwareData
78+
79+
A **HardwareData** resource contains hardware specifications data of a
80+
specific host and it is tightly coupled to its owner resource
81+
BareMetalHost. The data in the HardwareData comes from Ironic after a
82+
successful inspection phase. As such, operator will create HardwareData
83+
resource for a specific BareMetalHost during transitioning phase from
84+
inspecting into available state of the BareMetalHost. HardwareData gets
85+
deleted automatically by the operator whenever its BareMetalHost is
86+
deleted. Deprovisioning of the BareMetalHost should not trigger the
87+
deletion of HardwareData, but during next provisioning it can be
88+
re-created (with the same name and namespace) with the latest inspection
89+
data retrieved from Ironic. HardwareData holds the same name and
90+
namespace as its corresponding BareMetalHost resource. Currently,
91+
HardwareData doesn't have *Status* subresource but only the *Spec*.
92+
93+
See [HardwareData
94+
CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/HardwareData/v1alpha1)
95+
or check the source code at `apis/metal3.io/v1alpha1/hardwaredata_types.go`
96+
for a detailed API description.
97+
98+
## PreprovisioningImage
99+
100+
A **PreprovisioningImage** resource is automatically created by
101+
baremetal-operator for each BareMetalHost to ensure creation of a
102+
*preprovisioning image* for it. In this context, a preprovisioning image
103+
is an ISO or initramfs file that contains the [Ironic
104+
agent](https://docs.openstack.org/ironic-python-agent/). The relevant
105+
parts of BareMetalHost are copied to the PreprovisioningImage *Spec*,
106+
the resulting image is expected to appear in the *Status*.
107+
108+
The baremetal-operator project contains a simple controller for
109+
PreprovisioningImages that uses images provided in the environment
110+
variables `DEPLOY_ISO_URL` and `DEPLOY_RAMDISK_URL`. More sophisticated
111+
controllers may be written downstream (for example, the OpenShift
112+
[image-customization-controller](https://github.com/openshift/image-customization-controller)).
113+
114+
See [PreprovisioningImage
115+
CR](https://doc.crds.dev/github.com/metal3-io/baremetal-operator/metal3.io/PreprovisioningImage/v1alpha1)
116+
or check the source code at `apis/metal3.io/v1alpha1/preprovisioningimage_types.go`
117+
for a detailed API description.

0 commit comments

Comments
 (0)