diff --git a/doc/source/deploy/portgroups.rst b/doc/source/deploy/portgroups.rst new file mode 100644 index 0000000000..afb0ed2652 --- /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 `_ + 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 \ + $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 d93b8e60ac..87572fbb41 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 Adopting Nodes in an ACTIVE state Configuring for Multi-tenant Networking + Configuring for port groups Configuring node web or serial console Emitting software metrics Auditing API Traffic diff --git a/install-guide/source/configure-port-groups.rst b/install-guide/source/configure-port-groups.rst new file mode 100644 index 0000000000..1bb0924cc1 --- /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 2348f456b9..1447a6f60f 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