Add port groups configuration documentation

Closes-Bug: #1640592
Related-Bug: #1618754
Change-Id: Ib4b670e031402acc151e650e48924129d90595e9

4 files changed, 118 insertions, 0 deletions

diff --git a/doc/source/deploy/portgroups.rst b/doc/source/deploy/portgroups.rst
new file mode 100644
index 000000000..afb0ed265
--- /dev/null
+++ b/doc/source/deploy/portgroups.rst
@@ -0,0 +1,108 @@
+===================
+Port groups support
+===================
+
+The Bare Metal service supports static configuration of port groups (bonds) in
+the instances via configdrive. See `kernel documentation on bonding`_ to see
+why it may be useful and how it is setup in linux. The sections below describe
+how to make use of them in the Bare Metal service.
+
+Switch-side configuration
+-------------------------
+
+If port groups are desired in the ironic deployment, they need to be configured
+on the switches. It needs to be done manually, and the mode and properties
+configured on the switch have to correspond to the mode and properties that
+will be configured on the ironic side, as bonding mode and properties may be
+named differently on your switch, or have possible values different from the
+ones described in `kernel documentation on bonding`_. Please refer to your
+switch configuration documentation for more details. In the future, we may
+pass the port group mode and properties to ML2 drivers so that they can do the
+configuration automatically, but it is not supported as of now.
+
+Provisioning and cleaning cannot make use of port groups if they need to boot
+the deployment ramdisk via (i)PXE. If your switches or desired port group
+configuration do not support port group fallback, which will allow port group
+members to be used by themselves, you need to set port group's
+``standalone_ports_supported`` value to be ``False`` in ironic, as it is
+``True`` by default.
+
+Port groups configuration in the Bare Metal service
+---------------------------------------------------
+
+Port group configuration is supported in ironic API microversions 1.26, the
+CLI commands below specify it for completeness.
+
+#. When creating a port group, the node to which it belongs must be specified,
+   along with, optionally, its name, address, mode, properties, and if it
+   supports fallback to standalone ports::
+
+    openstack --os-baremetal-api-version 1.26 baremetal port group create \
+    --node $NODE_UUID --name test --address fa:ab:25:48:fd:ba --mode 802.3ad \
+    --property miimon=100 --property xmit_hash_policy="layer2+3" \
+    --support-standalone-ports True
+
+   A port group can also be updated with ``openstack baremetal port group set``
+   command, see its help for more details.
+
+   If an address is not specified, the port group address on the deployed
+   instance will be the same as the address of the neutron port that is
+   attached to the port group. If the neutron port is not attached, the port
+   group will not be configured.
+
+   .. note::
+
+      In standalone mode, port groups have to be configured manually. It can
+      be done either statically inside the image, or by generating the
+      configdrive and adding it to the node's ``instance_info``. For more
+      information on how to configure bonding via configdrive, refer to
+      `cloud-init documentation <https://cloudinit.readthedocs.io/en/latest/topics/datasources/configdrive.html#version-2>`_
+      and `code <https://git.launchpad.net/cloud-init/tree/cloudinit>`_.
+      cloud-init version 0.7.7 or later is required for bonding configuration
+      to work.
+
+      If the port group's address is not explicitly set in standalone mode, it
+      will be set automatically by the process described in
+      `kernel documentation on bonding`_.
+
+   During interface attachment, port groups have higher priority than ports,
+   so they will be used first. (It is not yet possible to specify which one is
+   desired, a port group or a port, in an interface attachment request). Port
+   groups that don't have any ports will be ignored.
+
+   The mode and properties values are described in the
+   `kernel documentation on bonding`_. The default port group mode is
+   ``active-backup``, and this default can be changed by setting the
+   ``[DEFAULT]default_portgroup_mode`` configuration option in the ironic API
+   service configuration file.
+
+#. Associate ports with the created port group.
+
+   It can be done on port creation::
+
+     openstack --os-baremetal-api-version 1.26 baremetal port create \
+     --node $NODE_UUID --address fa:ab:25:48:fd:ba --port-group test
+
+   Or by updating an existing port::
+
+     openstack --os-baremetal-api-version 1.26 baremetal port set \
+     $PORT_UUID --port-group $PORT_GROUP_UUID
+
+   When updating a port, the node associated with the port has to be in
+   ``enroll``, ``manageable``, or ``inspecting`` states. A port group can have
+   the same or different address as individual ports.
+
+#. Boot an instance (or node directly, in case of using standalone ironic)
+   providing an image that has cloud-init version 0.7.7 or later and supports
+   bonding.
+
+When the deployment is done, you can check that the port group is set up
+properly by running the following command in the instance::
+
+  cat /proc/net/bonding/bondX
+
+where ``X`` is a number autogenerated by cloud-init for each configured port
+group, in no particular order. It starts with 0 and increments by 1 for every
+configured port group.
+
+.. _`kernel documentation on bonding`: https://www.kernel.org/doc/Documentation/networking/bonding.txt
diff --git a/doc/source/index.rst b/doc/source/index.rst
index d93b8e60a..87572fbb4 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -161,6 +161,7 @@ of ironic that may or may not be suitable to every situation.
   Security considerations for your Bare Metal installation <deploy/security>
   Adopting Nodes in an ACTIVE state <deploy/adoption>
   Configuring for Multi-tenant Networking <deploy/multitenancy>
+  Configuring for port groups <deploy/portgroups>
   Configuring node web or serial console <deploy/console>
   Emitting software metrics <deploy/metrics>
   Auditing API Traffic <deploy/api-audit-support>
diff --git a/install-guide/source/configure-port-groups.rst b/install-guide/source/configure-port-groups.rst
new file mode 100644
index 000000000..1bb0924cc
--- /dev/null
+++ b/install-guide/source/configure-port-groups.rst
@@ -0,0 +1,8 @@
+.. _configure-port-groups:
+
+Configure port groups
+=====================
+
+See `Port groups configuration in Bare Metal service`_.
+
+.. _`Port groups configuration in Bare Metal service`: http://docs.openstack.org/developer/ironic/deploy/portgroups.html
diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst
index 2348f456b..1447a6f60 100644
--- a/install-guide/source/index.rst
+++ b/install-guide/source/index.rst
@@ -17,6 +17,7 @@ It contains the following sections:
    configure-integration.rst
    configure-cleaning.rst
    configure-tenant-networks.rst
+   configure-port-groups.rst
    enrollment.rst
    enabling-https.rst
    standalone.rst