Refactor multitenant networking release notes

This puts everything into one release note, and rewrites it a bit
to make it more cohesive and about the general "multitenant networking"
feature, rather than bit-by-bit.

Change-Id: I91b3c74a4f9edfd4e3454b7c80d3886b15494eb7

releasenotes/notes/add-network-interface-api-a3a56b8d0c796d88.yaml

@@ -1,9 +0,0 @@
----
-features:
-    - |
-      Exposes the ``network_interface`` field of the Node resource to the REST
-      API, raising the API maximum version to 1.20. This field is the network
-      interface to use for a node. Its possible values are from the
-      configuration option ``[DEFAULT]enabled_network_interfaces``. Note that
-      the value of this option must be the same on all the ironic-conductor and
-      ironic-api service nodes.

releasenotes/notes/add-network-interfaces-0a13c4aba252573e.yaml

@@ -1,39 +0,0 @@
----
-features:
-  - |
-    Added network interface. Introduced two network interface implementations:
-    ``flat``, which replicates the flat network behavior present previously and
-    ``noop`` when neutron is not used, which is basically a noop interface.
-    The network interface is used to switch network for node during
-    provisioning/cleaning. Added ``enabled_network_interfaces`` option in
-    DEFAULT config section. This option defines a list of enabled network
-    interfaces on the conductor.
-deprecations:
-  - |
-    ``create_cleaning_ports`` and ``delete_cleaning_ports`` methods in DHCP
-    providers are deprecated and will be removed completely in the Ocata
-    release. The logic they are implementing should be moved to a custom
-    network interface's ``add_cleaning_network`` and
-    ``remove_cleaning_network`` methods respectively. After that, the methods
-    themselves should be removed from DHCP provider so that network interface
-    is used instead. ``flat`` network interface does not require
-    ``[neutron]cleaning_network_uuid`` for now so as not to break standalone
-    deployments, but it will be required in the Ocata release.
-upgrade:
-  - |
-    ``[DEFAULT]default_network_interface`` configuration option is introduced,
-    with empty default value. If set, the specified interface will be used as
-    the network interface for nodes that don't have ``network_interface`` field
-    set. If it is not set, the network interface is determined by looking at
-    the ``[dhcp]dhcp_provider`` value. If it is ``neutron`` - ``flat`` network
-    interface is the default, ``noop`` otherwise.
-    The network interface will be set for all nodes without network_interface
-    already set via a database migration. This will be set following the logic
-    above. When running database migrations for an existing deployment, it's
-    important to check the above configuration options to ensure the existing
-    nodes will have the expected network_interface. If
-    ``[DEFAULT]default_network_interface`` is not set, everything should go as
-    expected. If it is set, ensure that it is set to the value that you wish
-    existing nodes to use.
-  - Note that if ``[DEFAULT]default_network_interface`` is set, it must be set
-    in the configuration file for both the API and conductor hosts.

releasenotes/notes/add-neutron-network-interface-aa9e7e65011ab8cd.yaml

@@ -1,14 +0,0 @@
----
-features:
-  - Added ``neutron`` network interface. This interface allows to provision
-    and/or clean node in separate networks. A new config option
-    ``[neutron]provisioning_network_uuid`` has been added. This option
-    specifies provision network UUID.
-upgrade:
-  - |
-    If ``neutron`` network interface is specified in
-    ``[DEFAULT]enabled_network_interfaces``,
-    ``[neutron]provisioning_network_uuid`` and
-    ``[neutron]cleaning_network_uuid`` configuration options are required. If
-    any of them is not specified, the ironic-conductor service will fail to
-    start.

releasenotes/notes/multitenant-networking-0a13c4aba252573e.yaml

@@ -0,0 +1,77 @@
+---
+features:
+  - |
+    Adds multitenant networking support.
+
+    Ironic now has the concept of "network interfaces" for a node, which
+    represent a networking driver.
+
+    There are three network interfaces available:
+
+    * ``flat``: this replicates the old flat network behavior and is the default
+      when using neutron for DHCP.
+    * ``noop``: this replicates the old flat behavior when not using neutron for
+      DHCP, and is the default when the configuration option
+      ``[DHCP]/dhcp_provider`` is set to "none".
+    * ``neutron``: this allows for separating the provisioning and cleaning
+      networks from the tenant networks, and provides isolation from tenant
+      network to tenant network, and tenant network to control plane.
+      The following configuration options must be set if the neutron interface
+      is enabled, or ironic-conductor will fail to start:
+
+      * ``[neutron]/provisioning_network_uuid``
+      * ``[neutron]/cleaning_network_uuid``
+
+    A ``[DEFAULT]/enabled_network_interfaces`` option (which must be set for
+    both ironic-api and ironic-conductor services) controls which network
+    interfaces are available for use.
+
+    A network interface is set for a node by setting the ``network_interface``
+    field for the node via the REST API. This field is available in API version
+    1.20 and above. Changing the network interface may only be done in the
+    ``enroll``, ``inspecting``, and ``manageable`` states.
+
+    The configuration option ``[DEFAULT]/default_network_interface`` may be
+    used to specify which network interface is defined when a node is created.
+
+    **WARNING: don't set the option ``[DEFAULT]/default_network_interface``
+    before upgrading to this release without reading the upgrade notes about
+    it, due to data migrations depending on the value.**
+deprecations:
+  - |
+    ``create_cleaning_ports`` and ``delete_cleaning_ports`` methods in DHCP
+    providers are deprecated and will be removed completely in the Ocata
+    release. The logic they are implementing should be moved to a custom
+    network interface's ``add_cleaning_network`` and
+    ``remove_cleaning_network`` methods respectively. After that, the methods
+    themselves should be removed from DHCP provider so that the custom
+    network interface is used instead. ``flat`` network interface does not
+    require ``[neutron]/cleaning_network_uuid`` for now so as not to break
+    standalone deployments upon upgrade, but it will be required in the Ocata
+    release if the ``flat`` network interface is enabled.
+upgrade:
+  - |
+    ``[DEFAULT]/default_network_interface`` configuration option is introduced,
+    with empty default value. If set, the specified interface will be used as
+    the network interface for nodes that don't have ``network_interface`` field
+    set. If it is not set, the network interface is determined by looking at
+    the ``[dhcp]/dhcp_provider`` value. If it is ``neutron`` - ``flat`` network
+    interface is the default, ``noop`` otherwise.
+
+    The network interface will be set for all nodes without network_interface
+    already set via a database migration. This will be set following the logic
+    above. When running database migrations for an existing deployment, it's
+    important to check the above configuration options to ensure the existing
+    nodes will have the expected network_interface. If
+    ``[DEFAULT]/default_network_interface`` is not set, everything should go as
+    expected. If it is set, ensure that it is set to the value that you wish
+    existing nodes to use.
+  - Note that if the configuration option
+    ``[DEFAULT]/default_network_interface`` is set, it must be set
+    in the configuration file for both the API and conductor hosts.
+  - If ``neutron`` network interface is specified for the configuration option
+    ``[DEFAULT]/enabled_network_interfaces``, then
+    ``[neutron]/provisioning_network_uuid`` and
+    ``[neutron]/cleaning_network_uuid`` configuration options are required. If
+    either of them is not specified, the ironic-conductor service will fail to
+    start.