From f7403cf4f27acacbec16d7dc09faaab5df3db568 Mon Sep 17 00:00:00 2001 From: Mark Goddard Date: Thu, 14 Oct 2021 09:54:05 +0100 Subject: [PATCH] docs: Improve info about neutron external interface Change-Id: I3a9c49c73a932b3d5ceed65c92190e5d72e27bbb Closes-Bug: #1626259 --- doc/source/_extra/.htaccess | 2 +- doc/source/conf.py | 1 + doc/source/reference/networking/index.rst | 1 - doc/source/reference/networking/neutron.rst | 67 ++++++++++++++++--- .../networking/provider-networks.rst | 21 ------ doc/test/redirect-tests.txt | 14 +++- 6 files changed, 73 insertions(+), 33 deletions(-) delete mode 100644 doc/source/reference/networking/provider-networks.rst diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess index db56ac3ade..dff3e72fb6 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 f284b6804f..8f1562ef01 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 9ac34a0198..e77090c7cd 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 b96d39503e..c7796d079a 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) +` 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 7d2a56ba8f..0000000000 --- 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 db56ac3ade..9dbc40a00f 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