Browse Source

Add port groups configuration documentation

Closes-Bug: #1640592
Related-Bug: #1618754
Change-Id: Ib4b670e031402acc151e650e48924129d90595e9
Vladyslav Drok 3 years ago
4 changed files with 118 additions and 0 deletions
  1. +108
  2. +1
  3. +8
  4. +1

+ 108
- 0
doc/source/deploy/portgroups.rst View File

@@ -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 <>`_
and `code <>`_.
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 \

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

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

+ 1
- 0
doc/source/index.rst View File

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

+ 8
- 0
install-guide/source/configure-port-groups.rst View File

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

+ 1
- 0
install-guide/source/index.rst View File

@@ -17,6 +17,7 @@ It contains the following sections: