Rewrite DHCP-less documentation

The current documentation is basically unreadable and contains a few
factual errors. Rewrite it for simplicity and move to a separate file
since at least 2 hardware types claim its support.

The patch does not concern the current status of the feature, an
easily revertable follow-up will be posted for that.

Change-Id: I3404378333316b0736ce07610a1dbbd7847bac00
This commit is contained in:
Dmitry Tantsur 2020-12-15 14:34:54 +01:00
parent 2d70e6e26e
commit 255fac17a0
6 changed files with 91 additions and 47 deletions

View File

@ -208,6 +208,7 @@ microversion 1.48.
- lessee: lessee
- description: n_description
- allocation_uuid: allocation_uuid
- network_data: network_data
**Example JSON representation of a Node:**
@ -562,6 +563,7 @@ Response
- description: n_description
- conductor: conductor
- allocation_uuid: allocation_uuid
- network_data: network_data
**Example JSON representation of a Node:**
@ -658,6 +660,7 @@ Response
- description: n_description
- conductor: conductor
- allocation_uuid: allocation_uuid
- network_data: network_data
**Example JSON representation of a Node:**

View File

@ -1079,8 +1079,10 @@ name:
type: string
network_data:
description: |
Static network configuration for the node to eventually pass to node's
operating system.
Static network configuration in the OpenStack network data format to use
during deployment and cleaning. Requires a specially crafted ramdisk, see
`DHCP-less documentation
<https://docs.openstack.org/ironic/latest/admin/dhcp-less.html>`_.
in: body
required: false
type: JSON

View File

@ -0,0 +1,78 @@
Layer 3 or DHCP-less ramdisk booting
====================================
Booting nodes via PXE, while universally supported, suffers from one
disadvantage: it requires a direct L2 connectivity between the node and the
control plane for DHCP. Using virtual media it is possible to avoid not only
the unreliable TFTP protocol, but DHCP altogether.
When network data is provided for a node as explained below, the generated
virtual media ISO will also serve as a configdrive_, and the network data will
be stored in the standard OpenStack location.
The simple-init_ element needs to be used when creating the deployment ramdisk.
The Glean_ tool will look for a media labeled as ``config-2``. If found, the
network information from it will be read, and the node's networking stack will
be configured accordingly.
.. note::
If desired, some interfaces can still be configured to use DHCP.
Hardware type support
---------------------
This feature is known to work with the following hardware types:
* :doc:`Redfish </admin/drivers/redfish>` with ``redfish-virtual-media`` boot
* :doc:`iLO </admin/drivers/ilo>` with ``ilo-virtual-media`` boot
Configuring network data
------------------------
When the Bare Metal service is running within OpenStack, no additional
configuration is required - the network configuration will be fetched from the
Network service.
Alternatively, the user can build and pass network configuration in form of
a network_data_ JSON to a node via the ``network_data`` field. Node-based
configuration takes precedence over the configuration generated by the
Network service and also works in standalone mode.
.. code-block:: bash
baremetal node set --network-data ~/network_data.json <node>
An example network data:
.. code-block:: json
{
"links": [
{
"id": "port-92750f6c-60a9-4897-9cd1-090c5f361e18",
"type": "phy",
"ethernet_mac_address": "52:54:00:d3:6a:71"
}
],
"networks": [
{
"id": "network0",
"type": "ipv4",
"link": "port-92750f6c-60a9-4897-9cd1-090c5f361e18",
"ip_address": "192.168.122.42",
"netmask": "255.255.255.0",
"network_id": "network0",
"routes": []
}
],
"services": []
}
.. note::
Some fields are redundant with the port information. We're looking into
simplifying the format, but currently all these fields are mandatory.
.. _configdrive: https://docs.openstack.org/nova/queens/user/config-drive.html
.. _Glean: https://docs.openstack.org/infra/glean/
.. _simple-init: https://docs.openstack.org/diskimage-builder/latest/elements/simple-init/README.html
.. _network_data: https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html

View File

@ -2164,7 +2164,7 @@ Layer 3 or DHCP-less ramdisk booting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
DHCP-less deploy is supported by ``ilo`` and ``ilo5`` hardware types.
However it would work only with ilo-virtual-media boot interface. See
:ref:`dhcpless_booting` for more information.
:doc:`/admin/dhcp-less` for more information.
.. _`ssacli documentation`: https://support.hpe.com/hpsc/doc/public/display?docId=c03909334
.. _`proliant-tools`: https://docs.openstack.org/diskimage-builder/latest/elements/proliant-tools/README.html

View File

@ -137,6 +137,8 @@ into the introspection ramdisk.
node does not have local storage or the Redfish implementation does not
support the required schema. In this case the property will be set to 0.
.. _redfish-virtual-media:
Virtual media boot
==================
@ -269,49 +271,11 @@ This initial interface does not support bootloader configuration
parameter injection, as such the ``[instance_info]/kernel_append_params``
setting is ignored. Configuration drives are not supported yet.
.. _`dhcpless_booting`:
Layer 3 or DHCP-less ramdisk booting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The DHCP used by PXE requires direct L2 connectivity between the node and the
service since it's a User Datagram Protocol (UDP) like other protocols used by
the PXE suite, there is no guarantee that packets will be delivered.
One of the solutions is the reliance on virtual media boot capability coupled
with another feature of hardware type - its ability to provide
network configuration that is placed in the config-drive_ of the node, the
configuration follows the same schema that OpenStack Nova uses for the
``network_data.json``. The config drive filesystem information is on the IPA
ramdisk ISO image from which the node is booted.
The Glean_ tool is available in the simple-init_ element that needs to be used
when creating the ramdisk image. The ironic ramdisk will probe all removable
media devices on the node in search of media labeled as `config-2`. If found,
this tool will consume static network configuration and set up node's
networking stack accordingly without calling out for DHCP.
When ironic is running within OpenStack, no additional configuration is required
on the ironic side - config drive with ramdisk network configuration will be
collected from Networking service and written on the IPA ramdisk ISO.
Alternatively, the user can build and pass node network configuration, in
form of a network_data_ JSON blob, to ironic node being managed via the
``--network-data`` CLI option. Node-based configuration takes precedence over
the configuration generated by the Network service.
.. code-block:: bash
baremetal node set \
--network-data ~/network_data.json <node>
Node-based configuration can be useful in standalone ironic deployment
scenario.
.. note::
Make sure to use add the simple-init_ element when building the IPA ramdisk.
DHCP-less deploy is supported by the Redfish virtual media boot. See
:doc:`/admin/dhcp-less` for more information.
Firmware update using manual cleaning
=====================================
@ -447,7 +411,3 @@ In the following example, the JSON is specified directly on the command line::
.. _Sushy: https://opendev.org/openstack/sushy
.. _TLS: https://en.wikipedia.org/wiki/Transport_Layer_Security
.. _ESP: https://wiki.ubuntu.com/EFIBootLoaders#Booting_from_EFI
.. _network_data: https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html
.. _config-drive: https://docs.openstack.org/nova/queens/user/config-drive.html
.. _Glean: https://docs.openstack.org/infra/glean/
.. _simple-init: https://docs.openstack.org/diskimage-builder/latest/elements/simple-init/README.html

View File

@ -52,6 +52,7 @@ Advanced Topics
Service State Reporting <gmr>
Agent Token <agent-token>
Deploying without BMC Credentials <agent-power>
Layer 3 or DHCP-less Ramdisk Booting <dhcp-less>
.. toctree::
:hidden: