From 02c5ab16517beab241c533bbb33ba0e8c06a25a1 Mon Sep 17 00:00:00 2001 From: Steven Hardy Date: Fri, 25 Oct 2024 07:48:03 +0100 Subject: [PATCH] user-guide: Add Pre-Provisioning NetworkData details Add information to the instance customization guide to explain Pre-Provisioning NetworkData and how it differs to the regular networkData Signed-off-by: Steven Hardy --- docs/user-guide/src/SUMMARY.md | 1 + .../bmo/advanced_instance_customization.md | 61 +++++++++++++++++++ docs/user-guide/src/bmo/features.md | 1 + .../src/bmo/instance_customization.md | 12 ++-- 4 files changed, 71 insertions(+), 4 deletions(-) create mode 100644 docs/user-guide/src/bmo/advanced_instance_customization.md diff --git a/docs/user-guide/src/SUMMARY.md b/docs/user-guide/src/SUMMARY.md index af65c775..3671cd68 100644 --- a/docs/user-guide/src/SUMMARY.md +++ b/docs/user-guide/src/SUMMARY.md @@ -23,6 +23,7 @@ - [Reboot Annotation](bmo/reboot_annotation.md) - [Root Device Hints](bmo/root_device_hints.md) - [Advanced Features](bmo/features.md) + - [Advanced Instance Customization](bmo/advanced_instance_customization.md) - [Detached annotation](bmo/detached_annotation.md) - [External Inspection](bmo/external_inspection.md) - [Live ISO](bmo/live-iso.md) diff --git a/docs/user-guide/src/bmo/advanced_instance_customization.md b/docs/user-guide/src/bmo/advanced_instance_customization.md new file mode 100644 index 00000000..340ef58b --- /dev/null +++ b/docs/user-guide/src/bmo/advanced_instance_customization.md @@ -0,0 +1,61 @@ +# Instance Customization + +Below we cover more advanced instance customization, more complex use-cases +and/or where customization of the metal3 deployment may be required. + +For more general guidance around instance customization refer to the +[instance customization](./instance_customization.md) section. + +## Pre-Provisioning NetworkData + +*Pre-provisioning network data* describes the desired networking configuration for the +deploy ramdisk (IPA). + +Usage of this API requires an IPA ramdisk image with a tool capable of interpreting and +applying the data such as *cloud-init*, *Glean* or alternative. The default community +supported ramdisk does not currently contain such a tool, but it is possible to build +a custom image, for example using [ironic-python-agent-builder][ipa_builder] with the +[simple-init][simple_init] element enabled. + +Specifying pre-provisioning network data is useful in DHCP-less scenarios, where we +cannot rely on DHCP to provide network configuration for the IPA ramdisk during the +inspection and provisioning phases. In this situation we can use redfish virtualmedia +to boot the IPA ramdisk, and the generated virtualmedia ISO will also serve as a +configuration drive to provide the network configuration. + +The data is specified in the [OpenStack network_data.json][network_data] format +as described for *Network data* in the [instance customization](./instance_customization.md) section. + +Usually, one pre-provisioning network data secret is created per host and should be +linked to it like *Network data*. If you require the same configuration for +pre-provisioning and the deployed OS, it is only necessary to specify pre-provisioning +network data - the pre-provisioning secret is automatically applied to networkData if +no alternative secret is specified. + +For example, given a local file `host-0-network.json`, you can create a secret: + +```bash +kubectl create secret generic host-0-preprov-networkdata --from-file=networkData=host-0-network.json +``` + +Then you can attach it to the host during its enrollment: + +```yaml +apiVersion: metal3.io/v1alpha1 +kind: BareMetalHost +metadata: + name: host-0 + namespace: my-cluster +spec: + online: true + bootMACAddress: 80:c1:6e:7a:e8:10 + bmc: + address: redfish-virtualmedia://192.168.1.13 + credentialsName: host-0-bmc + preprovisioningNetworkDataName: + name: host-0-preprov-networkdata +``` + +[network_data]: https://docs.openstack.org/nova/latest/user/metadata.html#openstack-format-metadata +[ipa_builder]: https://docs.openstack.org/ironic-python-agent-builder/ +[simple_init]: https://docs.openstack.org/diskimage-builder/latest/elements/simple-init/README.html diff --git a/docs/user-guide/src/bmo/features.md b/docs/user-guide/src/bmo/features.md index cbb8ff50..9e6ad3ff 100644 --- a/docs/user-guide/src/bmo/features.md +++ b/docs/user-guide/src/bmo/features.md @@ -15,6 +15,7 @@ ## Advanced features +- [Advanced Instance Customization](./advanced_instance_customization.md) - [Detached Annotation](./detached_annotation.md) - [External Inspection](./external_inspection.md) - [Live ISO](./live-iso.md) diff --git a/docs/user-guide/src/bmo/instance_customization.md b/docs/user-guide/src/bmo/instance_customization.md index 43884716..6d9493e1 100644 --- a/docs/user-guide/src/bmo/instance_customization.md +++ b/docs/user-guide/src/bmo/instance_customization.md @@ -38,10 +38,14 @@ instead when possible. ## NetworkData -*Network data* describes the desired networking configuration in the [OpenStack -network_data.json][network_data] format supported by *cloud-init* and *Glean*. -The format is not very well documented, but you can consult the [network_data -JSON schema][network_data schema] shipped with OpenStack. +*Network data* describes the desired networking configuration for the deployed +operating system, and is typically applied on first-boot via tools such as +*cloud-init*. + +The data is specified in the [OpenStack network_data.json][network_data] format +supported by *cloud-init* and *Glean*. The format is not very well documented, +but you can consult the [network_data JSON schema][network_data schema] +shipped with OpenStack. Usually, one network data secret is created per host and should be linked to it. For example, given a local file `host-0-network.json`, you can create a