From d3b41a181a8f0bddb178c5cd831cfb56a81b1ccf Mon Sep 17 00:00:00 2001
From: Michal Nasiadka <mnasiadka@gmail.com>
Date: Wed, 25 Sep 2019 14:18:09 +0200
Subject: [PATCH] Update Neutron reference docs

Add Neutron reference docs, especially a note around
using OVS native firewall driver on recent (4.3+) kernels [1].

[1]: https://docs.openstack.org/neutron/latest/admin/config-ovsfwdriver.html

Change-Id: I6994e364c116234b46f5d5e9f0a4666b83f86375
Closes-Bug: #1653987
---
 doc/source/reference/networking/index.rst   |  1 +
 doc/source/reference/networking/neutron.rst | 59 +++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 doc/source/reference/networking/neutron.rst

diff --git a/doc/source/reference/networking/index.rst b/doc/source/reference/networking/index.rst
index 55c4e262ee..9bc62f399d 100644
--- a/doc/source/reference/networking/index.rst
+++ b/doc/source/reference/networking/index.rst
@@ -12,6 +12,7 @@ Networking-SFC, QoS, and so on.
 
    designate-guide
    dpdk
+   neutron
    neutron-extensions
    opendaylight
    provider-networks
diff --git a/doc/source/reference/networking/neutron.rst b/doc/source/reference/networking/neutron.rst
new file mode 100644
index 0000000000..ac78c2a1de
--- /dev/null
+++ b/doc/source/reference/networking/neutron.rst
@@ -0,0 +1,59 @@
+.. _neutron:
+
+============================
+Neutron - Networking Service
+============================
+
+Preparation and deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Neutron is enabled by default in ``/etc/kolla/globals.yml``:
+
+.. code-block:: yaml
+
+   #enable_neutron: "{{ enable_openstack_core | bool }}"
+
+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
+``/etc/kolla/globals.yml`` setting ``neutron_external_interface`` to the
+desired interface name, ``eth1`` in the example below:
+
+.. 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.
+
+To use provider networks in instances you also need to set the following in
+``/etc/kolla/globals.yml``:
+
+.. code-block:: yaml
+
+   enable_neutron_provider_networks: yes
+
+.. note::
+   ``enable_neutron_provider_networks`` ensures ``neutron_external_interface``
+   is used on hosts in the ``compute`` group.
+
+By default ``kolla-ansible`` uses ``openvswitch`` as its underlying network
+mechanism, you can change that using the ``neutron_plugin_agent`` variable in
+``/etc/kolla/globals.yml``:
+
+.. code-block:: yaml
+
+   neutron_plugin_agent: "openvswitch"
+
+When using Open vSwitch on a compatible kernel (4.3+ upstream, consult the
+documentation of your distribution for support details), you can switch
+to using the native OVS firewall driver by employing a configuration override
+(see :ref:`service-config`). You can set it in
+``/etc/kolla/config/neutron/ml2_conf.ini``:
+
+.. code-block:: ini
+
+   [security_group]
+   firewall_driver = openvswitch
+