docs: Improve info about neutron external interface

Change-Id: I3a9c49c73a932b3d5ceed65c92190e5d72e27bbb
Closes-Bug: #1626259

6 files changed, 73 insertions, 33 deletions

diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess
index db56ac3ad..dff3e72fb 100644
--- a/doc/source/_extra/.htaccess
+++ b/doc/source/_extra/.htaccess
@@ -1 +1 @@
-# No redirects in place yet.
+redirectmatch 301 ^/([^/]+/[^/]+)/reference/networking/provider-networks.html$   /$1/reference/networking/neutron.html#provider-networks
diff --git a/doc/source/conf.py b/doc/source/conf.py
index f284b6804..8f1562ef0 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -95,6 +95,7 @@ openstack_projects = [
     'glance',
     'ironic',
     'keystone',
+    'kayobe',
     'kolla',
     'kolla-ansible',
     'magnum',
diff --git a/doc/source/reference/networking/index.rst b/doc/source/reference/networking/index.rst
index 9ac34a019..e77090c7c 100644
--- a/doc/source/reference/networking/index.rst
+++ b/doc/source/reference/networking/index.rst
@@ -15,5 +15,4 @@ Networking-SFC, QoS, and so on.
    neutron
    neutron-extensions
    octavia
-   provider-networks
    sriov
diff --git a/doc/source/reference/networking/neutron.rst b/doc/source/reference/networking/neutron.rst
index b96d39503..c7796d079 100644
--- a/doc/source/reference/networking/neutron.rst
+++ b/doc/source/reference/networking/neutron.rst
@@ -13,19 +13,65 @@ Neutron is enabled by default in ``/etc/kolla/globals.yml``:
 
    #enable_neutron: "{{ enable_openstack_core | bool }}"
 
+Network interfaces
+~~~~~~~~~~~~~~~~~~
+
 Neutron external interface is used for communication with the external world,
-for example provider networks and floating IPs.
-For setting up the neutron external interface please modify
+for example provider networks, routers and floating IPs.
+For setting up the neutron external interface modify
 ``/etc/kolla/globals.yml`` setting ``neutron_external_interface`` to the
-desired interface name, ``eth1`` in the example below:
+desired interface name. This interface is used by hosts in the ``network``
+group. It is also used by hosts in the ``compute`` group if
+``enable_neutron_provider_networks`` is set or DVR is enabled.
+
+The interface is plugged into a bridge (Open vSwitch or Linux Bridge, depending
+on the driver) defined by ``neutron_bridge_name``, which defaults to ``br-ex``.
+The default Neutron physical network is ``physnet1``.
+
+Example: single interface
+-------------------------
+
+In the case where we have only a single Neutron external interface,
+configuration is simple:
 
 .. code-block:: yaml
 
    neutron_external_interface: "eth1"
 
-.. note::
-   This is used by hosts in the ``network`` group, and hosts in the ``compute``
-   group if ``enable_neutron_provider_networks`` is set or DVR is enabled.
+Example: multiple interfaces
+----------------------------
+
+In some cases it may be necessary to have multiple external network interfaces.
+This may be achieved via comma-separated lists:
+
+.. code-block:: yaml
+
+   neutron_external_interface: "eth1,eth2"
+   neutron_bridge_name: "br-ex1,br-ex2"
+
+These two lists are "zipped" together, such that ``eth1`` is plugged into the
+``br-ex1`` bridge, and ``eth2`` is plugged into the ``br-ex2`` bridge.  Kolla
+Ansible maps these interfaces to Neutron physical networks ``physnet1`` and
+``physnet2`` respectively.
+
+Example: shared interface
+-------------------------
+
+Sometimes an interface used for Neutron external networking may also be used
+for other traffic. Plugging an interface directly into a bridge would prevent
+us from having a usable IP address on the interface. One solution to this issue
+is to use an intermediate Linux bridge and virtual Ethernet pair, then assign
+IP addresses on the Linux bridge. This setup is supported by
+:kayobe-doc:`Kayobe </>`. It is out of scope here, as it is non-trivial to set
+up in a persistent manner.
+
+Provider networks
+~~~~~~~~~~~~~~~~~
+
+Provider networks allow to connect compute instances directly to physical
+networks avoiding tunnels. This is necessary for example for some performance
+critical applications. Only administrators of OpenStack can create such
+networks.
 
 To use provider networks in instances you also need to set the following in
 ``/etc/kolla/globals.yml``:
@@ -34,9 +80,12 @@ To use provider networks in instances you also need to set the following in
 
    enable_neutron_provider_networks: yes
 
-.. note::
-   ``enable_neutron_provider_networks`` ensures ``neutron_external_interface``
-   is used on hosts in the ``compute`` group.
+For provider networks, compute hosts must have an external bridge
+created and configured by Ansible (this is also necessary when
+:neutron-doc:`Neutron Distributed Virtual Routing (DVR)
+<admin/deploy-ovs-ha-dvr.html>` mode is enabled). In this case, ensure
+``neutron_external_interface`` is configured correctly for hosts in the
+``compute`` group.
 
 OpenvSwitch (ml2/ovs)
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/reference/networking/provider-networks.rst b/doc/source/reference/networking/provider-networks.rst
deleted file mode 100644
index 7d2a56ba8..000000000
--- a/doc/source/reference/networking/provider-networks.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-.. _provider-networks:
-
-=================
-Provider Networks
-=================
-
-Provider networks allow to connect compute instances directly to physical
-networks avoiding tunnels. This is necessary for example for some performance
-critical applications. Only administrators of OpenStack can create such
-networks. For provider networks compute hosts must have external bridge
-created and configured by Ansible tasks like it is already done for tenant
-DVR mode networking. Normal tenant non-DVR networking does not need external
-bridge on compute hosts and therefore operators don't need additional
-dedicated network interface.
-
-To enable provider networks, modify the ``/etc/kolla/globals.yml`` file
-as the following example shows:
-
-.. code-block:: yaml
-
-   enable_neutron_provider_networks: "yes"
diff --git a/doc/test/redirect-tests.txt b/doc/test/redirect-tests.txt
index db56ac3ad..9dbc40a00 100644
--- a/doc/test/redirect-tests.txt
+++ b/doc/test/redirect-tests.txt
@@ -1 +1,13 @@
-# No redirects in place yet.
+# This file contains tests for redirects to handle existing URLs for
+# specs that have been moved. See
+# https://docs.openstack.org/whereto/latest/ for details.
+
+# No redirect.
+/ 200
+/kolla-ansible 200
+/kolla-ansible/latest 200
+/kolla-ansible/latest/reference/ 200
+/kolla-ansible/latest/reference/index.html 200
+
+# Moved /kolla-ansible/latest/reference/networking/provider-networks.html to /kolla-ansible/latest/reference/networking/neutron.html#provider-networks
+/kolla-ansible/latest/reference/networking/provider-networks.html 301 /kolla-ansible/latest/reference/networking/neutron.html#provider-networks