Recommended Bare Metal Node enrollment method missing info, also can lose data

[QuantumTux]

In the CHI-in-a-Box documentation for enrolling Bare Metal Nodes, one method suggested is to create a JSON file with the relevant information and import it. This works to an extent, but there are several issues.

First, and probably most-important, the documentation fails to mention that additional configuration of various port attributes for the NICs in the Bare Metal Nodes is required for the imported Node to actually be useful. Specifically, the attribute --pxe-enabled needs to be set on the appropriate NIC(s), --pxe-disabled probably ought to be set on any NICs that are not actually wired to anywhere, and --local-link-connection attributes such as port_id, switch_id and switch_info need values set.

Second, the documentation also fails to mention that when altering attributes of an enrolled Node using CLI commands like openstack baremetal port set blahblahblah, the work effort is destroyed if someone subsequently issues a command such as openstack hardware sync <node_uuid>. At minimum, that should be clearly noted, and also a process documented to address this problem for sites who may have already made this mistake.

Next, the upstream documentation for openstack baremetal port set --local-link-connection switch_id fails to mention format requirements for the value. Based on my testing, the command expects the value to be a string matching a valid MAC address, complete with colon characters separating each octet. Thus,

openstack baremetal port set --local-link-connection switch_id="de:ad:be:ef:de:ad" <node_uuid>

is valid, while this next example would generate an error:

openstack baremetal port set --local-link-connection switch_id="deadbeefdead" <node_uuid>

The CHI-in-a-Box documentation/examples should probably make the requirement clear.

Finally, the switch_info attribute is not actually required, at least not by the openstack baremetal port set --local-link-connection blahblahblah command. This seems odd, as the recommended value of the attribute is the name of the switch as it is listed in defaults.yml for the CHI-in-a-Box installation. Again, the CHI-in-a-Box documentation should probably recommend setting a useful value for the attribute.