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

api-ref/source/baremetal-api-v1-nodes.inc

@@ -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:**
 

api-ref/source/parameters.yaml

@@ -1079,8 +1079,10 @@ name:
   type: string
 network_data:
   description: |
-    Static network configuration for the node to eventually pass to node's
+    Static network configuration in the OpenStack network data format to use
-    operating system.
+    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

doc/source/admin/dhcp-less.rst

@@ -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

doc/source/admin/drivers/ilo.rst

@@ -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

doc/source/admin/drivers/redfish.rst

@@ -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
+DHCP-less deploy is supported by the Redfish virtual media boot. See
-service since it's a User Datagram Protocol (UDP) like other protocols used by
+:doc:`/admin/dhcp-less` for more information.
-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.
 
 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

doc/source/admin/index.rst

@@ -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: