Merge "Add L3 boot section to the docs"

2 files changed, 50 insertions, 0 deletions

diff --git a/doc/source/admin/drivers/redfish.rst b/doc/source/admin/drivers/redfish.rst
index 01352302a..c2740452a 100644
--- a/doc/source/admin/drivers/redfish.rst
+++ b/doc/source/admin/drivers/redfish.rst
@@ -208,7 +208,52 @@ This initial interface does not support bootloader configuration
 parameter injection, as such the ``[instance_info]/kernel_append_params``
 setting is ignored.
 
+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 ``redfish`` 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
+
+  openstack 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.
+
 .. _Redfish: http://redfish.dmtf.org/
 .. _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
diff --git a/doc/source/install/deploy-ramdisk.rst b/doc/source/install/deploy-ramdisk.rst
index 5d4b2411a..3979f705f 100644
--- a/doc/source/install/deploy-ramdisk.rst
+++ b/doc/source/install/deploy-ramdisk.rst
@@ -19,6 +19,10 @@ Two kinds of images are published on every commit from every branch of
   .. warning:: CentOS 7 master images are no longer updated and must not be
                used.
 
+  .. warning:: The published images will not work for dhcp-less deployments
+               since the simple-init_ element is not present. Check the DIB_
+               documentation to see how to build the image.
+
 * TinyIPA_ images are suitable for CI and testing environments and can be
   downloaded from
   https://tarballs.openstack.org/ironic-python-agent/tinyipa/files/.
@@ -32,3 +36,4 @@ ironic-python-agent ramdisks.
 .. _DIB: https://docs.openstack.org/ironic-python-agent-builder/latest/admin/dib.html
 .. _TinyIPA: https://docs.openstack.org/ironic-python-agent-builder/latest/admin/tinyipa.html
 .. _ironic-python-agent-builder: https://docs.openstack.org/ironic-python-agent-builder/latest/
+.. _simple-init: https://docs.openstack.org/diskimage-builder/latest/elements/simple-init/README.html