Update TBN docs for group_and_attach_ports

Adds documentation for Trait Based Networking's new group_and_attach_ports
action.

Along with a few minor additions and cleanup.

Change-Id: Ib34769ad582bc06e91459cbf6d3b2c5cccb0ea6d
Signed-off-by: Clif Houck <me@clifhouck.com>

doc/source/admin/trait-based-networking.rst

@@ -9,22 +9,51 @@ Trait Based Networking, or TBN for short, is an Ironic feature that allows an
 Openstack installation utilizing Ironic, Neutron, and Nova to dynamically
 configure port scheduling for Ironic nodes.
 
-Configure
----------
+Enable and Configure
+--------------------
 
 To configure and enable TBN for your Ironic installation please see
 :doc:`/install/configure-trait-based-networking`
-variable_name: /[a-z]+\.[a-z\_]+/
 
-Available Actions
------------------
+Terminology
+-----------
 
-Attach port - Attach one or more ports belonging to a node to a network
-              (aka vif)
-Attach portgroup - Attach one or more portgroups belonging to a node to a
-                   network (aka vif)
+First some terms:
 
-Future actions are coming.
+- Node: An Ironic node.
+- Trait: A set of actions referred to by a name.
+- Action or Trait Action: A defined operation to apply to a node if
+  the action's Filter Expression matches network objects associated
+  with a node.
+- Filter Expression: A boolean expression which filters for specific network
+  objects like a port, portgroup or network.
+- Port: A network interface.
+- Portgroup: A set of ports, grouped together.
+- Dynamic Portgroup: An ephemeral portgroup that is created by a trait's action
+  and is subsequently destroyed once detached.
+- Network (aka VIF): A neutron network.
+
+
+Trait Actions
+-------------
+
+The core of TBN functionality lies in actions that each trait defines. Each
+action allows the operator to define how exactly TBN will setup networking for
+the node.
+
+The following actions are available:
+
+- Attach port: Attach one or more ports belonging to a node to a network
+  (aka vif).
+- Attach portgroup: Attach one or more portgroups belonging to a node to a
+  network (aka vif).
+- Group and attach ports: Create a dynamic portgroup and attach it to a
+  network.
+
+In the future more actions may be added.
+
+See :doc:`/references/trait-based-networking/tbn-config-file` for more
+information on configuring and applying trait actions.
 
 Filter Expression Primer
 ------------------------
@@ -64,7 +93,7 @@ Like so:
 
      port.vendor == "purple" && port.category != "privatenet"
 
-Again in plain English this could be read as: 'filter for ports with vendor
+Again, in plain English this could be read as: 'filter for ports with vendor
 that is exactly equal to the string "purple" and whose category field is not
 "privatenet"'.
 

doc/source/references/trait-based-networking/tbn-config-file.rst

@@ -19,7 +19,7 @@ Below is a valid YAML example trait:
     CUSTOM_TRAIT_NAME:
       order: 1
       actions:
-        - action: bond_ports
+        - action: group_and_attach_ports
           filter: port.vendor == 'vendor_string'
           min_count: 2
         - action: attach_port
@@ -59,6 +59,11 @@ The following actions are currently available:
   filter expression.
 * ``attach_portgroup`` - Attach (portgroup, network) pairs that pass this
   action's filter expression.
+* ``group_and_attach_ports`` - Select a set of ports. Create a dynamic
+  portgroup comprised of the set of ports. Then attach the newly created
+  dynamic portgroup to a suitable network. This action must set a
+  ``min_count`` of at least 2. Also note that all ports selected for the
+  portgroup must have the same ``physical_network``.
 
 Future actions are planned. This document will be updated as they become
 available.

etc/ironic/trait_based_networks.yaml.sample

@@ -1,7 +1,7 @@
 CUSTOM_TRAIT_NAME:
   order: 1
   actions:
-    - action: bond_ports
+    - action: group_and_attach_ports
       filter: port.vendor == 'vendor_string'
       min_count: 2
 CUSTOM_DIRECT_ATTACH_A_PURPLE_TO_STORAGE:

tools/trait_based_networking/tbn_trait_config.yaml.sample

@@ -1,5 +1,5 @@
 CUSTOM_TRAIT_NAME:
-  - action: bond_ports
+  - action: group_and_attach_ports
     filter: port.vendor == 'clover'
     min_count: 2
 CUSTOM_DIRECT_ATTACH_A_PURPLE_TO_STORAGE: