Add documentation for changing node's hardware type

Change-Id: Iec93aaf85751895efed5dac4ccb4383ee919305c
Story: #2002868

1 files changed, 74 insertions, 0 deletions

diff --git a/doc/source/admin/drivers.rst b/doc/source/admin/drivers.rst
index bef955a3b..bb6568582 100644
--- a/doc/source/admin/drivers.rst
+++ b/doc/source/admin/drivers.rst
@@ -28,6 +28,80 @@ Hardware Types
   drivers/ucs
   drivers/xclarity
 
+Changing Hardware Types and Interfaces
+--------------------------------------
+
+Hardware types and interfaces are enabled in the configuration as described in
+:doc:`/install/enabling-drivers`. Usually, a hardware type is configured on
+enrolling as described in :doc:`/install/enrollment`::
+
+    openstack baremetal node create --driver <hardware type>
+
+Any hardware interfaces can be specified on enrollment as well::
+
+    openstack baremetal node create --driver <hardware type> \
+        --deploy-interface direct --<other>-interface <other implementation>
+
+For the remaining interfaces the default value is assigned as described in
+:ref:`hardware_interfaces_defaults`. Both the hardware type and the hardware
+interfaces can be changed later.
+
+Changing hardware interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A hardware interfaces can be changed by the following command::
+
+    openstack baremetal node set <NODE> \
+        --deploy-interface direct \
+        --<other>-interface <other implementation>
+
+The modified interfaces must be enabled and compatible with the current node's
+hardware type.
+
+Changing hardware type
+~~~~~~~~~~~~~~~~~~~~~~
+
+Changing the node's hardware type can pose a problem. When the ``driver``
+field is updated, the final result must be consistent, that is, the resulting
+hardware interfaces must be compatible with the new hardware type. This will
+not work::
+
+    openstack baremetal node create --name test --driver fake-hardware
+    openstack baremetal node set test --driver ipmi
+
+This is because the ``fake-hardware`` hardware type defaults to ``fake``
+implementations for some or all interfaces, but the ``ipmi`` hardware type is
+not compatible with them. There are three ways to deal with this situation:
+
+#. Provide new values for all incompatible interfaces, for example::
+
+    openstack baremetal node set test --driver ipmi \
+        --boot-interface pxe \
+        --deploy-interface iscsi \
+        --management-interface ipmitool \
+        --power-interface ipmitool
+
+#. Request resetting some of the interfaces to their new defaults by using the
+   ``--reset-<IFACE>-interface`` family of arguments, for example::
+
+    openstack baremetal node set test --driver ipmi \
+        --reset-boot-interface \
+        --reset-deploy-interface \
+        --reset-management-interface \
+        --reset-power-interface
+
+   .. note:: This feature is available starting with the Rocky release.
+
+#. Request resetting all interfaces to their new defaults::
+
+    openstack baremetal node set test --driver ipmi --reset-interfaces
+
+   You can still specify explicit values for some interfaces::
+
+    openstack baremetal node set test --driver ipmi --reset-interfaces \
+        --deploy-interface direct
+
+   .. note:: This feature is available starting with the Rocky release.
 
 Unsupported drivers
 -------------------