openstack/neutron
Code Issues Proposed changes

Add RST linting to neutron

Browse Source 
Start running the doc8 RST linter in the pep8 job. This
will catch obvious errors like line too long, etc. Tried
to fix most of the errors (there were a lot!), but added
some ignore directives so we can address some files later.

Did have to move a couple of files around as a double
include was causing some issues, but content is unchanged.

Change-Id: I336a9ee7729045da095be22ea0f58ee596967174
This commit is contained in:
Brian Haley 2024-08-23 12:03:12 -04:00
parent bd7abaabef
commit 7d139a013b
86 changed files with 1015 additions and 822 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
TESTING.rst
View File

@ -97,10 +97,10 @@ At the end of each test run:
* The in-memory database is cleared of content, but its schema is maintained. * The in-memory database is cleared of content, but its schema is maintained.
* The global Oslo configuration object is reset. * The global Oslo configuration object is reset.
The unit testing framework can be used to effectively test database interaction, The unit testing framework can be used to effectively test database
for example, distributed routers allocate a MAC address for every host running interaction, for example, distributed routers allocate a MAC address for
an OVS agent. One of DVR's DB mixins implements a method that lists all host every host running an OVS agent. One of DVR's DB mixins implements a method
MAC addresses. Its test looks like this: that lists all host MAC addresses. Its test looks like this:
.. code-block:: python .. code-block:: python
@ -159,9 +159,9 @@ One of its methods is called 'device_exists' which accepts a device name
and a namespace and returns True if the device exists in the given namespace. and a namespace and returns True if the device exists in the given namespace.
It's easy building a test that targets the method directly, and such a test It's easy building a test that targets the method directly, and such a test
would be considered a 'unit' test. However, what framework should such a test would be considered a 'unit' test. However, what framework should such a test
use? A test using the unit tests framework could not mutate state on the system, use? A test using the unit tests framework could not mutate state on the
and so could not actually create a device and assert that it now exists. Such system, and so could not actually create a device and assert that it now
a test would look roughly like this: exists. Such a test would look roughly like this:
* It would mock 'execute', a method that executes shell commands against the * It would mock 'execute', a method that executes shell commands against the
system to return an IP device named 'foo'. system to return an IP device named 'foo'.
@ -261,9 +261,10 @@ should be validated, and all interaction with the daemon should be via
a REST client. a REST client.
The neutron-tempest-plugin/neutron_tempest_plugin directory was copied from the The neutron-tempest-plugin/neutron_tempest_plugin directory was copied from the
Tempest project around the Kilo timeframe. At the time, there was an overlap of tests Tempest project around the Kilo timeframe. At the time, there was an overlap of
between the Tempest and Neutron repositories. This overlap was then eliminated by carving tests between the Tempest and Neutron repositories. This overlap was then
out a subset of resources that belong to Tempest, with the rest in Neutron. eliminated by carving out a subset of resources that belong to Tempest, with
the rest in Neutron.
API tests that belong to Tempest deal with a subset of Neutron's resources: API tests that belong to Tempest deal with a subset of Neutron's resources:
@ -296,9 +297,10 @@ define a list of required extensions for particular test class.
Scenario Tests Scenario Tests
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
Scenario tests (neutron-tempest-plugin/neutron_tempest_plugin/scenario), like API tests, Scenario tests (neutron-tempest-plugin/neutron_tempest_plugin/scenario), like
use the Tempest test infrastructure and have the same requirements. Guidelines for API tests, use the Tempest test infrastructure and have the same requirements.
writing a good scenario test may be found at the Tempest developer guide: Guidelines for writing a good scenario test may be found at the Tempest
developer guide:
https://docs.openstack.org/tempest/latest/field_guide/scenario.html https://docs.openstack.org/tempest/latest/field_guide/scenario.html
Scenario tests, like API tests, are split between the Tempest and Neutron Scenario tests, like API tests, are split between the Tempest and Neutron
@ -322,15 +324,18 @@ Specific test requirements for advanced images are:
Rally Tests Rally Tests
~~~~~~~~~~~ ~~~~~~~~~~~
Rally tests (rally-jobs/plugins) use the `rally <http://rally.readthedocs.io/>`_ Rally tests (rally-jobs/plugins) use the
infrastructure to exercise a neutron deployment. Guidelines for writing a `rally <http://rally.readthedocs.io/>`_ infrastructure to exercise a neutron
good rally test can be found in the `rally plugin documentation <http://rally.readthedocs.io/en/latest/plugins/>`_. deployment. Guidelines for writing a good rally test can be found in the
`rally plugin documentation <http://rally.readthedocs.io/en/latest/plugins/>`_.
There are also some examples in tree; the process for adding rally plugins to There are also some examples in tree; the process for adding rally plugins to
neutron requires three steps: 1) write a plugin and place it under rally-jobs/plugins/. neutron requires three steps:
This is your rally scenario; 2) (optional) add a setup file under rally-jobs/extra/. 1) write a plugin and place it under rally-jobs/plugins/. This is your rally
This is any devstack configuration required to make sure your environment can scenario;
successfully process your scenario requests; 3) edit neutron-neutron.yaml. This 2) (optional) add a setup file under rally-jobs/extra/. This is any devstack
is your scenario 'contract' or SLA. configuration required to make sure your environment can successfully process
your scenario requests;
3) edit neutron-neutron.yaml. This is your scenario 'contract' or SLA.
Grenade Tests Grenade Tests
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -346,8 +351,8 @@ similar to deploying OpenStack using Devstack. All is described in the
`Project's wiki <https://wiki.openstack.org/wiki/Grenade>`_ and `documentation `Project's wiki <https://wiki.openstack.org/wiki/Grenade>`_ and `documentation
<https://opendev.org/openstack/grenade/src/branch/master/README.rst>`_. <https://opendev.org/openstack/grenade/src/branch/master/README.rst>`_.
More info about how to troubleshoot Grenade failures in the CI jobs can be found More info about how to troubleshoot Grenade failures in the CI jobs can be
in the :ref:`Troubleshooting Grenade jobs <troubleshooting-grenade-jobs>` found in the :ref:`Troubleshooting Grenade jobs <troubleshooting-grenade-jobs>`
document. document.
Development Process Development Process
@ -438,8 +443,11 @@ To run only pep8::
tox -e pep8 tox -e pep8
Since pep8 includes running pylint on all files, it can take quite some time to run. Since pep8 includes running pylint on all files, it can take quite some time
To restrict the pylint check to only the files altered by the latest patch changes:: to run.
To restrict the pylint check to only the files altered by the latest patch
changes::
tox -e pep8 HEAD~1 tox -e pep8 HEAD~1

12
doc/source/admin/archives/auth.rst
View File

@ -90,7 +90,7 @@ This extract is from the default ``policy.yaml`` file:
administrator or the owner of the resource specified in the request administrator or the owner of the resource specified in the request
(project identifier is equal). (project identifier is equal).
.. code-block:: none .. code-block:: yaml
"admin_or_owner": "role:admin or tenant_id:%(tenant_id)s" "admin_or_owner": "role:admin or tenant_id:%(tenant_id)s"
"admin_or_network_owner": "role:admin or tenant_id:%(network_tenant_id)s" "admin_or_network_owner": "role:admin or tenant_id:%(network_tenant_id)s"
@ -101,7 +101,7 @@ This extract is from the default ``policy.yaml`` file:
- The default policy that is always evaluated if an API operation does - The default policy that is always evaluated if an API operation does
not match any of the policies in ``policy.yaml``. not match any of the policies in ``policy.yaml``.
.. code-block:: none .. code-block:: yaml
"default": "rule:admin_or_owner" "default": "rule:admin_or_owner"
"create_subnet": "rule:admin_or_network_owner" "create_subnet": "rule:admin_or_network_owner"
@ -113,7 +113,7 @@ This extract is from the default ``policy.yaml`` file:
- This policy evaluates successfully if either *admin_or_owner*, or - This policy evaluates successfully if either *admin_or_owner*, or
*shared* evaluates successfully. *shared* evaluates successfully.
.. code-block:: none .. code-block:: yaml
"get_network": "rule:admin_or_owner or rule:shared" "get_network": "rule:admin_or_owner or rule:shared"
"create_network:shared": "rule:admin_only" "create_network:shared": "rule:admin_only"
@ -121,7 +121,7 @@ This extract is from the default ``policy.yaml`` file:
- This policy restricts the ability to manipulate the *shared* - This policy restricts the ability to manipulate the *shared*
attribute for a network to administrators only. attribute for a network to administrators only.
.. code-block:: none .. code-block:: yaml
"update_network": "rule:admin_or_owner" "update_network": "rule:admin_or_owner"
"delete_network": "rule:admin_or_owner" "delete_network": "rule:admin_or_owner"
@ -133,7 +133,7 @@ This extract is from the default ``policy.yaml`` file:
attribute for a port only to administrators and the owner of the attribute for a port only to administrators and the owner of the
network where the port is attached. network where the port is attached.
.. code-block:: none .. code-block:: yaml
"get_port": "rule:admin_or_owner" "get_port": "rule:admin_or_owner"
"update_port": "rule:admin_or_owner" "update_port": "rule:admin_or_owner"
@ -144,7 +144,7 @@ This example shows you how to modify a policy file to permit project to
define networks, see their resources, and permit administrative users to define networks, see their resources, and permit administrative users to
perform all other operations: perform all other operations:
.. code-block:: none .. code-block:: yaml
"admin_or_owner": "role:admin or tenant_id:%(tenant_id)s" "admin_or_owner": "role:admin or tenant_id:%(tenant_id)s"
"admin_only": "role:admin" "admin_only": "role:admin"

3
doc/source/admin/archives/introduction.rst
View File

@ -107,7 +107,8 @@ Set these options to configure SSL:
Firewall-as-a-Service (FWaaS) overview Firewall-as-a-Service (FWaaS) overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For information on Firewall-as-a-Service (FWaaS), please consult the :doc:`Networking Guide <../fwaas>`. For information on Firewall-as-a-Service (FWaaS), please consult the
:doc:`Networking Guide <../fwaas>`.
Allowed-address-pairs Allowed-address-pairs
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~

3
doc/source/admin/config-active-active-l3gw.rst
View File

@ -130,7 +130,8 @@ can be set per router at router creation time by passing the
``--enable-default-route-bfd`` argument or by updating an existing router using ``--enable-default-route-bfd`` argument or by updating an existing router using
the ``openstack router set`` command. the ``openstack router set`` command.
The default behavior for new routers can be controlled using the `enable_default_route_bfd`_ configuration option. The default behavior for new routers can be controlled using the
`enable_default_route_bfd`_ configuration option.
It is recommended to enable this when `adding multiple default routes to a It is recommended to enable this when `adding multiple default routes to a
router`_ as failure to do so will lead to degraded performance in the event of router`_ as failure to do so will lead to degraded performance in the event of

22
doc/source/admin/config-dns-int-ext-serv.rst
View File

@ -47,10 +47,11 @@ Once this is done, the user has to take the following steps and restart
Networking service to create and update reverse lookup (PTR) zones. Networking service to create and update reverse lookup (PTR) zones.
* ``project_name``: the name of the project to be used by the * ``project_name``: the name of the project to be used by the
Networking service to create and update reverse lookup (PTR) zones. Networking service to create and update reverse lookup (PTR) zones.
* ``project_domain_name``: the name of the domain for the project to be used by the * ``project_domain_name``: the name of the domain for the project to be
Networking service to create and update reverse lookup (PTR) zones. used by the Networking service to create and update reverse lookup (PTR)
* ``user_domain_name``: the name of the domain for the user to be used by the zones.
Networking service to create and update reverse lookup (PTR) zones. * ``user_domain_name``: the name of the domain for the user to be used by
the Networking service to create and update reverse lookup (PTR) zones.
* ``region_name``: the name of the region to be used by the * ``region_name``: the name of the region to be used by the
Networking service to create and update reverse lookup (PTR) zones. Networking service to create and update reverse lookup (PTR) zones.
* ``allow_reverse_dns_lookup``: a boolean value specifying whether to enable * ``allow_reverse_dns_lookup``: a boolean value specifying whether to enable
@ -60,10 +61,11 @@ Once this is done, the user has to take the following steps and restart
* ``ipv6_ptr_zone_prefix_size``: the size in bits of the prefix for the IPv6 * ``ipv6_ptr_zone_prefix_size``: the size in bits of the prefix for the IPv6
reverse lookup (PTR) zones. reverse lookup (PTR) zones.
* ``ptr_zone_email``: the email address to use when creating new reverse * ``ptr_zone_email``: the email address to use when creating new reverse
lookup (PTR) zones. The default is ``admin@<dns_domain>`` where ``<dns_domain>`` lookup (PTR) zones. The default is ``admin@<dns_domain>`` where
is the domain for the first record being created in that zone. ``<dns_domain>`` is the domain for the first record being created in that
* ``insecure``: whether to disable SSL certificate validation. By default, certificates zone.
are validated. * ``insecure``: whether to disable SSL certificate validation. By default,
certificates are validated.
* ``cafile``: Path to a valid Certificate Authority (CA) certificate. * ``cafile``: Path to a valid Certificate Authority (CA) certificate.
Optional, the system CAs are used as default. Optional, the system CAs are used as default.
@ -908,8 +910,8 @@ Only for :ref:`config-dns-use-case-3`, if the port binding extension is
enabled in the Networking service, the Compute service will execute one enabled in the Networking service, the Compute service will execute one
additional port update operation when allocating the port for the instance additional port update operation when allocating the port for the instance
during the boot process. This may have a noticeable adverse effect in the during the boot process. This may have a noticeable adverse effect in the
performance of the boot process that should be evaluated before adoption of this performance of the boot process that should be evaluated before adoption of
use case. this use case.
.. _config-dns-int-ext-serv-net: .. _config-dns-int-ext-serv-net:

2
doc/source/admin/config-experimental-framework.rst
View File

@ -31,7 +31,7 @@ experimetal:
This is an example of how to enable the use of an experimental feature: This is an example of how to enable the use of an experimental feature:
.. code-block:: none .. code-block:: ini
[experimental] [experimental]
linuxbridge = true linuxbridge = true

10
doc/source/admin/config-ipv6.rst
View File

@ -350,8 +350,8 @@ follows:
Setting DHCPv6-stateless for ``ipv6_ra_mode`` configures the neutron Setting DHCPv6-stateless for ``ipv6_ra_mode`` configures the neutron
router with an radvd agent to send Router Advertisements. The list below router with an radvd agent to send Router Advertisements. The list below
captures the values set for the address configuration flags in the Router captures the values set for the address configuration flags in the Router
Advertisement messages in this scenario. Similarly, setting DHCPv6-stateless for Advertisement messages in this scenario. Similarly, setting DHCPv6-stateless
``ipv6_address_mode`` configures neutron DHCP implementation to provide for ``ipv6_address_mode`` configures neutron DHCP implementation to provide
the additional network information. the additional network information.
* Autonomous Address Configuration Flag = 1 * Autonomous Address Configuration Flag = 1
@ -361,8 +361,8 @@ the additional network information.
Setting DHCPv6-stateful for ``ipv6_ra_mode`` configures the neutron Setting DHCPv6-stateful for ``ipv6_ra_mode`` configures the neutron
router with an radvd agent to send Router Advertisements. The list below router with an radvd agent to send Router Advertisements. The list below
captures the values set for the address configuration flags in the Router captures the values set for the address configuration flags in the Router
Advertisements messages in this scenario. Similarly, setting DHCPv6-stateful for Advertisements messages in this scenario. Similarly, setting DHCPv6-stateful
``ipv6_address_mode`` configures neutron DHCP implementation to provide for ``ipv6_address_mode`` configures neutron DHCP implementation to provide
addresses and additional network information through DHCPv6. addresses and additional network information through DHCPv6.
* Autonomous Address Configuration Flag = 0 * Autonomous Address Configuration Flag = 0
@ -609,7 +609,7 @@ Configuring the Dibbler server
After installing Dibbler, edit the ``/etc/dibbler/server.conf`` file: After installing Dibbler, edit the ``/etc/dibbler/server.conf`` file:
.. code-block:: none .. code-block::
script "/var/lib/dibbler/pd-server.sh" script "/var/lib/dibbler/pd-server.sh"

31
doc/source/admin/config-logging.rst
View File

@ -40,7 +40,7 @@ Service Configuration
To enable the logging service, add ``log`` to the ``service_plugins`` setting To enable the logging service, add ``log`` to the ``service_plugins`` setting
in ``/etc/neutron/neutron.conf``: in ``/etc/neutron/neutron.conf``:
.. code-block:: none .. code-block:: ini
service_plugins = router,metering,log service_plugins = router,metering,log
@ -181,13 +181,14 @@ To enable the logging service, follow the below steps.
#. On Neutron controller node, add ``log`` to ``service_plugins`` setting in #. On Neutron controller node, add ``log`` to ``service_plugins`` setting in
``/etc/neutron/neutron.conf`` file. For example: ``/etc/neutron/neutron.conf`` file. For example:
.. code-block:: none .. code-block:: ini
service_plugins = router,metering,log service_plugins = router,metering,log
#. To enable logging service for ``security_group`` in Layer 2, add ``log`` to #. To enable logging service for ``security_group`` in Layer 2, add ``log`` to
option ``extensions`` in section ``[agent]`` in ``/etc/neutron/plugins/ml2/ml2_conf.ini`` option ``extensions`` in section ``[agent]`` in
for controller node and in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini`` ``/etc/neutron/plugins/ml2/ml2_conf.ini`` for controller node and in
``/etc/neutron/plugins/ml2/openvswitch_agent.ini``
for compute/network nodes. For example: for compute/network nodes. For example:
.. code-block:: ini .. code-block:: ini
@ -210,8 +211,8 @@ To enable the logging service, follow the below steps.
extensions = fwaas_v2,fwaas_v2_log extensions = fwaas_v2,fwaas_v2_log
#. On compute/network nodes, add configuration for logging service to #. On compute/network nodes, add configuration for logging service to
``[network_log]`` in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini`` and in ``[network_log]`` in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``
``/etc/neutron/l3_agent.ini`` as shown below: and in ``/etc/neutron/l3_agent.ini`` as shown below:
.. code-block:: ini .. code-block:: ini
@ -245,14 +246,14 @@ cloud, neutron's policy file ``policy.yaml`` can be modified to allow this.
Modify ``/etc/neutron/policy.yaml`` entries as follows: Modify ``/etc/neutron/policy.yaml`` entries as follows:
.. code-block:: none .. code-block:: yaml
"get_loggable_resources": "rule:regular_user", "get_loggable_resources": "rule:regular_user"
"create_log": "rule:regular_user", "create_log": "rule:regular_user"
"get_log": "rule:regular_user", "get_log": "rule:regular_user"
"get_logs": "rule:regular_user", "get_logs": "rule:regular_user"
"update_log": "rule:regular_user", "update_log": "rule:regular_user"
"delete_log": "rule:regular_user", "delete_log": "rule:regular_user"
Service workflow for Operator Service workflow for Operator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -406,8 +407,8 @@ The general characteristics of each event will be shown as the following:
* A timestamp of the flow. * A timestamp of the flow.
* A status of the flow ``ACCEPT``/``DROP``. * A status of the flow ``ACCEPT``/``DROP``.
* An indication of the originator of the flow, e.g which project or log resource * An indication of the originator of the flow, e.g which project or log
generated the events. resource generated the events.
* An identifier of the associated instance interface (neutron port id). * An identifier of the associated instance interface (neutron port id).
* A layer 2, 3 and 4 information (mac, address, port, protocol, etc). * A layer 2, 3 and 4 information (mac, address, port, protocol, etc).

4
doc/source/admin/config-ml2.rst
View File

@ -316,7 +316,9 @@ The ML2 plug-in also supports extension drivers that allows other pluggable
drivers to extend the core resources implemented in the ML2 plug-in drivers to extend the core resources implemented in the ML2 plug-in
(``networks``, ``ports``, etc.). Examples of extension drivers include support (``networks``, ``ports``, etc.). Examples of extension drivers include support
for QoS, port security, etc. For more details see the ``extension_drivers`` for QoS, port security, etc. For more details see the ``extension_drivers``
configuration option in the `Configuration Reference <../configuration/ml2-conf.html#ml2.extension_drivers>`__. configuration option in the
`Configuration Reference
<../configuration/ml2-conf.html#ml2.extension_drivers>`__.
Agents Agents

9
doc/source/admin/config-ndp-proxy.rst
View File

@ -83,10 +83,10 @@ To configure NDP proxy, take the following steps:
a single, integrated subnetpool. In order to make NDP proxy work correctly, a single, integrated subnetpool. In order to make NDP proxy work correctly,
the admin operator needs to set direct routes for these subnetpools. the admin operator needs to set direct routes for these subnetpools.
Such as, we have a IPv6 subnetpool, it's CIDR is 2001:db8::/96. The direct route Such as, we have a IPv6 subnetpool, it's CIDR is 2001:db8::/96. The direct
like below should be set: route like below should be set:
.. code-block:: none .. code-block:: console
2001:db8::/96 dev <ext-gw> 2001:db8::/96 dev <ext-gw>
@ -275,7 +275,8 @@ network (such as: public network) are the following:
:ref:`prefix-delegation` etc.) to publish the internal IPv6 address, the :ref:`prefix-delegation` etc.) to publish the internal IPv6 address, the
command will break dataplane traffic. command will break dataplane traffic.
#. Create an internal network and IPv6 subnet and add the subnet to the above router: #. Create an internal network and IPv6 subnet and add the subnet to the above
router:
.. code-block:: console .. code-block:: console

6
doc/source/admin/config-ovs-offload.rst
View File

@ -75,7 +75,8 @@ Prerequisites
Using Open vSwitch hardware offloading Using Open vSwitch hardware offloading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to enable Open vSwitch hardware offloading, the following steps are required: In order to enable Open vSwitch hardware offloading, the following steps are
required:
#. Enable SR-IOV #. Enable SR-IOV
#. Configure NIC to switchdev mode (relevant Nodes) #. Configure NIC to switchdev mode (relevant Nodes)
@ -425,7 +426,8 @@ Validate Open vSwitch hardware offloading
.. end .. end
#. Check traffic on the representor port. Verify that only the first ICMP packet appears. #. Check traffic on the representor port. Verify that only the first ICMP
packet appears.
.. code-block:: console .. code-block:: console

17
doc/source/admin/config-ovsfwdriver.rst
View File

@ -82,18 +82,19 @@ Both OVS and iptables firewall drivers should always behave in the same way if
the same rules are configured for the security group. But in some cases that is the same rules are configured for the security group. But in some cases that is
not true and there may be slight differences between those drivers. not true and there may be slight differences between those drivers.
+----------------------------------------+-----------------------+-----------------------+ +-------------------------------------+----------------+----------------------+
| Case | OVS | iptables | | Case | OVS | iptables |
+========================================+=======================+=======================+ +=====================================+================+======================+
| Traffic marked as INVALID by conntrack | Blocked | Allowed because it | | Traffic marked as INVALID by | Blocked | Allowed because it |
| but matching some of the SG rules | | first matches SG rule,| | conntrack but matching some of the | | first matches SG |
| (please check [1]_ and [2]_ | | never reaches rule to | | SG rules (please check [1]_ and | | rule, never reaches |
| for details) | | drop invalid packets | | [2]_ for details) | | rule to drop invalid |
+----------------------------------------+-----------------------+-----------------------+ | | | packets |
+-------------------------------------+----------------+----------------------+
| Multicast traffic sent in the group | Allowed always | Blocked, | | Multicast traffic sent in the group | Allowed always | Blocked, |
| 224.0.0.X | | Can be enabled by SG | | 224.0.0.X | | Can be enabled by SG |
| (please check [3]_ for details) | | rule. | | (please check [3]_ for details) | | rule. |
+----------------------------------------+-----------------------+-----------------------+ +-------------------------------------+----------------+----------------------+
Open Flow rules processing considerations Open Flow rules processing considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3
doc/source/admin/config-qos-min-bw.rst
View File

@ -172,7 +172,8 @@ In release Stein the following agent-based ML2 mechanism drivers are
supported: supported:
* Open vSwitch (``openvswitch``) vnic_types: ``normal``, ``direct`` * Open vSwitch (``openvswitch``) vnic_types: ``normal``, ``direct``
* SR-IOV (``sriovnicswitch``) vnic_types: ``direct``, ``macvtap``, ``direct-physical`` * SR-IOV (``sriovnicswitch``) vnic_types: ``direct``, ``macvtap``,
``direct-physical``
* OVN (``ovn``) vnic_types: ``normal`` * OVN (``ovn``) vnic_types: ``normal``
.. note:: .. note::

2
doc/source/admin/config-qos-min-pps.rst
View File

@ -230,7 +230,9 @@ with:
* :oslo.config:option:`ovs.resource_provider_packet_processing_without_direction` * :oslo.config:option:`ovs.resource_provider_packet_processing_without_direction`
Format for this option is ``<hypervisor>:<packet_rate>``. This option should Format for this option is ``<hypervisor>:<packet_rate>``. This option should
be used for non-hardware-offloaded OVS deployments. be used for non-hardware-offloaded OVS deployments.
* :oslo.config:option:`ovs.resource_provider_packet_processing_with_direction` * :oslo.config:option:`ovs.resource_provider_packet_processing_with_direction`
Format for this option is Format for this option is
``<hypervisor>:<egress_packet_rate>:<ingress_packet_rate>``. You may set only ``<hypervisor>:<egress_packet_rate>:<ingress_packet_rate>``. You may set only
one direction and omit the other. This option should be used for one direction and omit the other. This option should be used for

17
doc/source/admin/config-qos.rst
View File

@ -40,7 +40,8 @@ QoS supported rule types are now available as ``VALID_RULE_TYPES`` in `QoS rule
* minimum_bandwidth: Minimum bandwidth constraints on certain types of traffic. * minimum_bandwidth: Minimum bandwidth constraints on certain types of traffic.
* minimum_packet_rate: Minimum packet rate constraints on certain types of traffic. * minimum_packet_rate: Minimum packet rate constraints on certain types of
traffic.
Any QoS driver can claim support for some QoS rule types Any QoS driver can claim support for some QoS rule types
@ -182,7 +183,7 @@ On the controller nodes:
#. Add the QoS service to the ``service_plugins`` setting in #. Add the QoS service to the ``service_plugins`` setting in
``/etc/neutron/neutron.conf``. For example: ``/etc/neutron/neutron.conf``. For example:
.. code-block:: none .. code-block:: ini
service_plugins = router,metering,qos service_plugins = router,metering,qos
@ -194,7 +195,7 @@ On the controller nodes:
set the ``service_plugins`` option in ``/etc/neutron/neutron.conf`` to set the ``service_plugins`` option in ``/etc/neutron/neutron.conf`` to
include both ``router`` and ``qos``. For example: include both ``router`` and ``qos``. For example:
.. code-block:: none .. code-block:: ini
service_plugins = router,qos service_plugins = router,qos
@ -321,7 +322,7 @@ your cloud, neutron's file ``policy.yaml`` can be modified to allow this.
Modify ``/etc/neutron/policy.yaml`` policy entries as follows: Modify ``/etc/neutron/policy.yaml`` policy entries as follows:
.. code-block:: none .. code-block:: yaml
"get_policy": "rule:regular_user" "get_policy": "rule:regular_user"
"create_policy": "rule:regular_user" "create_policy": "rule:regular_user"
@ -331,7 +332,7 @@ Modify ``/etc/neutron/policy.yaml`` policy entries as follows:
To enable bandwidth limit rule: To enable bandwidth limit rule:
.. code-block:: none .. code-block:: yaml
"get_policy_bandwidth_limit_rule": "rule:regular_user" "get_policy_bandwidth_limit_rule": "rule:regular_user"
"create_policy_bandwidth_limit_rule": "rule:regular_user" "create_policy_bandwidth_limit_rule": "rule:regular_user"
@ -340,7 +341,7 @@ To enable bandwidth limit rule:
To enable DSCP marking rule: To enable DSCP marking rule:
.. code-block:: none .. code-block:: yaml
"get_policy_dscp_marking_rule": "rule:regular_user" "get_policy_dscp_marking_rule": "rule:regular_user"
"create_policy_dscp_marking_rule": "rule:regular_user" "create_policy_dscp_marking_rule": "rule:regular_user"
@ -349,7 +350,7 @@ To enable DSCP marking rule:
To enable minimum bandwidth rule: To enable minimum bandwidth rule:
.. code-block:: none .. code-block:: yaml
"get_policy_minimum_bandwidth_rule": "rule:regular_user" "get_policy_minimum_bandwidth_rule": "rule:regular_user"
"create_policy_minimum_bandwidth_rule": "rule:regular_user" "create_policy_minimum_bandwidth_rule": "rule:regular_user"
@ -358,7 +359,7 @@ To enable minimum bandwidth rule:
To enable minimum packet rate rule: To enable minimum packet rate rule:
.. code-block:: none .. code-block:: yaml
"get_policy_minimum_packet_rate_rule": "rule:regular_user" "get_policy_minimum_packet_rate_rule": "rule:regular_user"
"create_policy_minimum_packet_rate_rule": "rule:regular_user" "create_policy_minimum_packet_rate_rule": "rule:regular_user"

3
doc/source/admin/config-rbac.rst
View File

@ -826,7 +826,8 @@ database following the next steps:
* Insert the indexes for the "target_tenant" and "action" columns: * Insert the indexes for the "target_tenant" and "action" columns:
$ for table in $tables do; mysql -e \ $ for table in $tables do; mysql -e \
"alter table $table add key (action); alter table $table add key (target_tenant);"; done "alter table $table add key (action); \
alter table $table add key (target_tenant);"; done
In order to prevent errors during a system upgrade, [3]_ was In order to prevent errors during a system upgrade, [3]_ was

10
doc/source/admin/config-services-agent.rst
View File

@ -111,11 +111,11 @@ To address this problem, operators should use the ``AGENT`` config group option
``kill_scripts_path`` to configure a path to where ``kill scripts`` for such ``kill_scripts_path`` to configure a path to where ``kill scripts`` for such
processes live. By default, it is set to ``/etc/neutron/kill_scripts/``. processes live. By default, it is set to ``/etc/neutron/kill_scripts/``.
If option ``kill_scripts_path`` is changed in the config to the different If option ``kill_scripts_path`` is changed in the config to the different
location, ``exec_dirs`` in ``/etc/rootwrap.conf`` should be changed accordingly. location, ``exec_dirs`` in ``/etc/rootwrap.conf`` should be changed
If ``kill_scripts_path`` is set, every time neutron has to kill a process, accordingly. If ``kill_scripts_path`` is set, every time neutron has to kill a
for example ``dnsmasq``, it will look in this directory for a file with the name process, for example ``dnsmasq``, it will look in this directory for a file
``<process_name>-kill``. So for ``dnsmasq`` process it will look for a with the name ``<process_name>-kill``. So for ``dnsmasq`` process it will look
``dnsmasq-kill`` script. If such a file exists there, it will be called for a ``dnsmasq-kill`` script. If such a file exists there, it will be called
instead of using the ``kill`` command. instead of using the ``kill`` command.
Kill scripts are called with two parameters: Kill scripts are called with two parameters:

6
doc/source/admin/config-sfc.rst
View File

@ -323,9 +323,9 @@ Update a port chain or port pair group
SFC steers traffic matching the additional flow classifier to the SFC steers traffic matching the additional flow classifier to the
port pair groups in the port chain. port pair groups in the port chain.
* Use the :command:`openstack sfc port pair group set` command to perform dynamic * Use the :command:`openstack sfc port pair group set` command to perform
scale-out or scale-in operations by adding or removing port pairs on a port dynamic scale-out or scale-in operations by adding or removing port pairs
pair group. on a port pair group.
.. code-block:: console .. code-block:: console

56
doc/source/admin/config-sriov.rst
View File

@ -493,17 +493,17 @@ Once configuration is complete, you can launch instances with SR-IOV ports.
SR-IOV with ConnectX-3/ConnectX-3 Pro Dual Port Ethernet SR-IOV with ConnectX-3/ConnectX-3 Pro Dual Port Ethernet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In contrast to Mellanox newer generation NICs, ConnectX-3 family network adapters expose a single In contrast to Mellanox newer generation NICs, ConnectX-3 family network
PCI device (PF) in the system regardless of the number of physical ports. adapters expose a single PCI device (PF) in the system regardless of the number
When the device is **dual port** and SR-IOV is enabled and configured we can observe some inconsistencies of physical ports. When the device is **dual port** and SR-IOV is enabled and
in linux networking subsystem. configured we can observe some inconsistencies in linux networking subsystem.
.. note:: .. note::
In the example below ``enp4s0`` represents PF net device associated with physical port 1 and In the example below ``enp4s0`` represents PF net device associated with physical port 1 and
``enp4s0d1`` represents PF net device associated with physical port 2. ``enp4s0d1`` represents PF net device associated with physical port 2.
**Example:** A system with ConnectX-3 dual port device and a total of four VFs configured, **Example:** A system with ConnectX-3 dual port device and a total of four VFs
two VFs assigned to port one and two VFs assigned to port two. configured, two VFs assigned to port one and two VFs assigned to port two.
.. code-block:: console .. code-block:: console
@ -532,18 +532,20 @@ Four VFs are available in the system, however,
vf 2 MAC 00:00:00:00:00:00, vlan 4095, spoof checking off, link-state auto vf 2 MAC 00:00:00:00:00:00, vlan 4095, spoof checking off, link-state auto
vf 3 MAC 00:00:00:00:00:00, vlan 4095, spoof checking off, link-state auto vf 3 MAC 00:00:00:00:00:00, vlan 4095, spoof checking off, link-state auto
**ip** command identifies each PF associated net device as having four VFs *each*. **ip** command identifies each PF associated net device as having four VFs
*each*.
.. note:: .. note::
Mellanox ``mlx4`` driver allows *ip* commands to perform configuration of *all* Mellanox ``mlx4`` driver allows *ip* commands to perform configuration of *all*
VFs from either PF associated network devices. VFs from either PF associated network devices.
To allow neutron SR-IOV agent to properly identify the VFs that belong to the correct PF network device To allow neutron SR-IOV agent to properly identify the VFs that belong to the
(thus to the correct network port) Admin is required to provide the ``exclude_devices`` configuration option correct PF network device (thus to the correct network port) Admin is required
in ``sriov_agent.ini`` to provide the ``exclude_devices`` configuration option in ``sriov_agent.ini``
**Step 1**: derive the VF to Port mapping from mlx4 driver configuration file: ``/etc/modprobe.d/mlnx.conf`` or ``/etc/modprobe.d/mlx4.conf`` **Step 1**: derive the VF to Port mapping from mlx4 driver configuration file:
``/etc/modprobe.d/mlnx.conf`` or ``/etc/modprobe.d/mlx4.conf``
.. code-block:: console .. code-block:: console
@ -554,12 +556,15 @@ Where:
``num_vfs=n1,n2,n3`` - The driver will enable ``n1`` VFs on physical port 1, ``num_vfs=n1,n2,n3`` - The driver will enable ``n1`` VFs on physical port 1,
``n2`` VFs on physical port 2 and ``n2`` VFs on physical port 2 and
``n3`` dual port VFs (applies only to dual port HCA when all ports are Ethernet ports). ``n3`` dual port VFs (applies only to dual port HCA when all ports are
Ethernet ports).
``probe_vfs=m1,m2,m3`` - the driver probes ``m1`` single port VFs on physical port 1, ``probe_vfs=m1,m2,m3`` - the driver probes ``m1`` single port VFs on
physical port 1,
``m2`` single port VFs on physical port 2 (applies only if such a port exist) ``m2`` single port VFs on physical port 2 (applies only if such a port exist)
``m3`` dual port VFs. Those VFs are attached to the hypervisor. (applies only if all ports are configured as Ethernet). ``m3`` dual port VFs. Those VFs are attached to the hypervisor. (applies only
if all ports are configured as Ethernet).
The VFs will be enumerated in the following order: The VFs will be enumerated in the following order:
@ -575,7 +580,8 @@ In our example:
| 04:00.3 : VF associated to port **2** | 04:00.3 : VF associated to port **2**
| 04:00.4 : VF associated to port **2** | 04:00.4 : VF associated to port **2**
**Step 2:** Update ``exclude_devices`` configuration option in ``sriov_agent.ini`` with the correct mapping **Step 2:** Update ``exclude_devices`` configuration option in
``sriov_agent.ini`` with the correct mapping
Each PF associated net device shall exclude the **other** port's VFs Each PF associated net device shall exclude the **other** port's VFs
@ -637,18 +643,20 @@ Known limitations
* SR-IOV is not integrated into the OpenStack Dashboard (horizon). Users must * SR-IOV is not integrated into the OpenStack Dashboard (horizon). Users must
use the CLI or API to configure SR-IOV interfaces. use the CLI or API to configure SR-IOV interfaces.
* Live migration support has been added to the Libvirt Nova virt-driver in the Train * Live migration support has been added to the Libvirt Nova virt-driver in the
release for instances with neutron SR-IOV ports. Indirect mode SR-IOV interfaces Train release for instances with neutron SR-IOV ports. Indirect mode SR-IOV
(vnic-type: macvtap or virtio-forwarder) can now be migrated transparently to interfaces (vnic-type: macvtap or virtio-forwarder) can now be migrated
the guest. Direct mode SR-IOV interfaces (vnic-type: direct or direct-physical) transparently to the guest. Direct mode SR-IOV interfaces (vnic-type: direct
are detached before the migration and reattached after the migration so this is not or direct-physical) are detached before the migration and reattached after
transparent to the guest. To avoid loss of network connectivy when live migrating the migration so this is not transparent to the guest. To avoid loss of
with direct mode sriov the user should create a failover bond in the guest with a network connectivy when live migrating with direct mode sriov the user should
transparently live migration port type e.g. vnic-type normal or indirect mode SR-IOV. create a failover bond in the guest with a transparently live migration port
type e.g. vnic-type normal or indirect mode SR-IOV.
.. note:: .. note::
SR-IOV features may require a specific NIC driver version, depending on the vendor. SR-IOV features may require a specific NIC driver version, depending on the vendor.
Intel NICs, for example, require ixgbe version 4.4.6 or greater, and ixgbevf version Intel NICs, for example, require ixgbe version 4.4.6 or greater, and ixgbevf version
3.2.2 or greater. 3.2.2 or greater.
* Attaching SR-IOV ports to existing servers is supported starting with the Victoria release. * Attaching SR-IOV ports to existing servers is supported starting with the
Victoria release.

4
doc/source/admin/config-wsgi.rst
View File

@ -95,8 +95,8 @@ Create ``/etc/apache2/neutron.conf`` with content below:
.. end .. end
For deb-based systems copy or symlink the file to ``/etc/apache2/sites-available``. For deb-based systems copy or symlink the file to
Then enable the neutron site: ``/etc/apache2/sites-available``. Then enable the neutron site:
.. code-block:: console .. code-block:: console

2
doc/source/admin/deploy-lb-provider.rst
View File

@ -231,7 +231,7 @@ Create initial networks
Verify network operation Verify network operation
------------------------ ------------------------
.. include:: shared/deploy-provider-verifynetworkoperation.txt .. include:: deploy-provider-verifynetworkoperation.txt
Network traffic flow Network traffic flow
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~

2
doc/source/admin/deploy-lb-selfservice.rst
View File

@ -211,7 +211,7 @@ Create initial networks
Verify network operation Verify network operation
------------------------ ------------------------
.. include:: shared/deploy-selfservice-verifynetworkoperation.txt .. include:: deploy-selfservice-verifynetworkoperation.txt
.. _deploy-lb-selfservice-networktrafficflow: .. _deploy-lb-selfservice-networktrafficflow:

2
doc/source/admin/deploy-ovs-provider.rst
View File

@ -261,7 +261,7 @@ Create initial networks
Verify network operation Verify network operation
------------------------ ------------------------
.. include:: shared/deploy-provider-verifynetworkoperation.txt .. include:: deploy-provider-verifynetworkoperation.txt
Network traffic flow Network traffic flow
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~

2
doc/source/admin/deploy-ovs-selfservice.rst
View File

@ -207,7 +207,7 @@ Create initial networks
Verify network operation Verify network operation
------------------------ ------------------------
.. include:: shared/deploy-selfservice-verifynetworkoperation.txt .. include:: deploy-selfservice-verifynetworkoperation.txt
.. _deploy-ovs-selfservice-networktrafficflow: .. _deploy-ovs-selfservice-networktrafficflow:

0
doc/source/admin/shared/deploy-provider-verifynetworkoperation.txt → doc/source/admin/deploy-provider-verifynetworkoperation.txt
View File

0
doc/source/admin/shared/deploy-selfservice-verifynetworkoperation.txt → doc/source/admin/deploy-selfservice-verifynetworkoperation.txt
View File

10
doc/source/admin/intro-os-networking.rst
View File

@ -236,11 +236,11 @@ filtering technology such as ``iptables``.
Each project contains a ``default`` security group that by default allows all Each project contains a ``default`` security group that by default allows all
egress traffic and denies all ingress traffic. You can change the rules in the egress traffic and denies all ingress traffic. You can change the rules in the
``default`` security group. Admin user can also define own set of security group ``default`` security group. Admin user can also define own set of security
rules which will be added by default to each new ``default`` and each new non group rules which will be added by default to each new ``default`` and each new
default (custom) security group created for every project in the cloud. There is non-default (custom) security group created for every project in the cloud.
``security-group-default-rules`` API extension which allows to define such own There is ``security-group-default-rules`` API extension which allows to define
set of the default security group rules. such own set of the default security group rules.
If you launch an instance without specifying a security group, the ``default`` If you launch an instance without specifying a security group, the ``default``
security group automatically applies to it. Similarly, if you create a port security group automatically applies to it. Similarly, if you create a port
without specifying a security group, the ``default`` security group without specifying a security group, the ``default`` security group

3
doc/source/admin/ovn/routing.rst
View File

@ -7,7 +7,8 @@ Routing
North/South North/South
----------- -----------
The different configurations are detailed in the :doc:`/admin/ovn/refarch/refarch` The different configurations are detailed in the
:doc:`/admin/ovn/refarch/refarch`
Non distributed FIP Non distributed FIP
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~

12
doc/source/admin/ovn/smartnic_dpu.rst
View File

@ -16,12 +16,12 @@ familiar with the following specifications
Overview Overview
-------- --------
A class of devices collectively referred to as off-path SmartNIC DPUs introduces A class of devices collectively referred to as off-path SmartNIC DPUs
an important change to earlier architectures where compute and networking agents introduces an important change to earlier architectures where compute and
used to coexist at the hypervisor host: networking control plane components networking agents used to coexist at the hypervisor host: networking control
are now moved to the SmartNIC DPU's CPU side which includes ``ovs-vswitchd`` plane components are now moved to the SmartNIC DPU's CPU side which includes
and ``ovn-controller``. The following diagram provides an overview of the ``ovs-vswitchd`` and ``ovn-controller``. The following diagram provides an
components involved:: overview of the components involved::
┌────────────────────────────────────┐ ┌────────────────────────────────────┐
│ Hypervisor │ LoM Ports │ Hypervisor │ LoM Ports

12
doc/source/admin/shared/deploy-secgrouprules.txt
View File

@ -10,7 +10,8 @@
| remote_ip_prefix | 0.0.0.0/0 | | remote_ip_prefix | 0.0.0.0/0 |
+------------------+-----------+ +------------------+-----------+
$ openstack security group rule create --ethertype IPv6 --proto ipv6-icmp default $ openstack security group rule create --ethertype IPv6 \
--proto ipv6-icmp default
+-----------+-----------+ +-----------+-----------+
| Field | Value | | Field | Value |
+-----------+-----------+ +-----------+-----------+
@ -31,13 +32,14 @@
| remote_ip_prefix | 0.0.0.0/0 | | remote_ip_prefix | 0.0.0.0/0 |
+------------------+-----------+ +------------------+-----------+
$ openstack security group rule create --ethertype IPv6 --proto tcp --dst-port 22 default $ openstack security group rule create --ethertype IPv6 --proto tcp \
+------------------+-----------+ --dst-port 22 default
+----------------+---------+
| Field | Value | | Field | Value |
+------------------+-----------+ +----------------+---------+
| direction | ingress | | direction | ingress |
| ethertype | IPv6 | | ethertype | IPv6 |
| port_range_max | 22 | | port_range_max | 22 |
| port_range_min | 22 | | port_range_min | 22 |
| protocol | tcp | | protocol | tcp |
+------------------+-----------+ +----------------+---------+

16
doc/source/admin/shared/deploy-selfservice-initialnetworks.txt
View File

@ -42,7 +42,8 @@ NAT for IPv4 network traffic and directly routes IPv6 network traffic.
If you are using an MTU value on your network below 1280, please If you are using an MTU value on your network below 1280, please
read the warning listed in the read the warning listed in the
`IPv6 configuration guide <../config-ipv6.html#project-network-considerations>`__ `IPv6 configuration guide
<../config-ipv6.html#project-network-considerations>`__
before creating any subnets. before creating any subnets.
#. Create a IPv4 subnet on the self-service network. #. Create a IPv4 subnet on the self-service network.
@ -67,12 +68,13 @@ NAT for IPv4 network traffic and directly routes IPv6 network traffic.
.. code-block:: console .. code-block:: console
$ openstack subnet create --subnet-range fd00:192:0:2::/64 --ip-version 6 \ $ openstack subnet create --subnet-range fd00:192:0:2::/64 \
--ipv6-ra-mode slaac --ipv6-address-mode slaac --network selfservice1 \ --ip-version 6 --ipv6-ra-mode slaac --ipv6-address-mode slaac \
--dns-nameserver 2001:4860:4860::8844 selfservice1-v6 --network selfservice1 --dns-nameserver 2001:4860:4860::8844 \
+-------------------+------------------------------------------------------+ selfservice1-v6
+-------------------+--------------------------------------------------+
| Field | Value | | Field | Value |
+-------------------+------------------------------------------------------+ +-------------------+--------------------------------------------------+
| allocation_pools | fd00:192:0:2::2-fd00:192:0:2:ffff:ffff:ffff:ffff | | allocation_pools | fd00:192:0:2::2-fd00:192:0:2:ffff:ffff:ffff:ffff |
| cidr | fd00:192:0:2::/64 | | cidr | fd00:192:0:2::/64 |
| dns_nameservers | 2001:4860:4860::8844 | | dns_nameservers | 2001:4860:4860::8844 |
@ -82,7 +84,7 @@ NAT for IPv4 network traffic and directly routes IPv6 network traffic.
| ipv6_address_mode | slaac | | ipv6_address_mode | slaac |
| ipv6_ra_mode | slaac | | ipv6_ra_mode | slaac |
| name | selfservice1-v6 | | name | selfservice1-v6 |
+-------------------+------------------------------------------------------+ +-------------------+--------------------------------------------------+
#. Create a router. #. Create a router.

18
doc/source/admin/vpnaas-scenario.rst
View File

@ -25,7 +25,8 @@ they provide their version of manuals.
set suitable plugin for your own deployment. set suitable plugin for your own deployment.
#. Configure the VPNaaS service provider by creating the #. Configure the VPNaaS service provider by creating the
``/etc/neutron/neutron_vpnaas.conf`` file as follows, ``strongswan`` used in Ubuntu distribution: ``/etc/neutron/neutron_vpnaas.conf`` file as follows, ``strongswan`` used
in Ubuntu distribution:
.. code-block:: ini .. code-block:: ini
@ -41,7 +42,8 @@ they provide their version of manuals.
Consider to use the appropriate one for your deployment. Consider to use the appropriate one for your deployment.
#. Configure the VPNaaS plugin for the L3 agent by adding to #. Configure the VPNaaS plugin for the L3 agent by adding to
``/etc/neutron/l3_agent.ini`` the following section, ``StrongSwanDriver`` used in Ubuntu distribution: ``/etc/neutron/l3_agent.ini`` the following section, ``StrongSwanDriver``
used in Ubuntu distribution:
.. code-block:: ini .. code-block:: ini
@ -78,13 +80,13 @@ Using VPNaaS with endpoint group (recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
IPsec site-to-site connections will support multiple local subnets, IPsec site-to-site connections will support multiple local subnets,
in addition to the current multiple peer CIDRs. The multiple local subnet feature in addition to the current multiple peer CIDRs. The multiple local subnet
is triggered by not specifying a local subnet, when creating a VPN service. feature is triggered by not specifying a local subnet, when creating a VPN
Backwards compatibility is maintained with single local subnets, by providing service. Backwards compatibility is maintained with single local subnets, by
the subnet in the VPN service creation. providing the subnet in the VPN service creation.
To support multiple local subnets, a new capability called "End Point Groups" has To support multiple local subnets, a new capability called "End Point Groups"
been added. Each endpoint group will define one or more endpoints of has been added. Each endpoint group will define one or more endpoints of
a specific type, and can be used to specify both local and peer endpoints for a specific type, and can be used to specify both local and peer endpoints for
IPsec connections. The endpoint groups separate the "what gets connected" from IPsec connections. The endpoint groups separate the "what gets connected" from
the "how to connect" for a VPN service, and can be used for different flavors the "how to connect" for a VPN service, and can be used for different flavors

30
doc/source/contributor/alembic_migrations.rst
View File

@ -319,7 +319,9 @@ Expand and Contract Scripts
The obsolete "branchless" design of a migration script included that it The obsolete "branchless" design of a migration script included that it
indicates a specific "version" of the schema, and includes directives that indicates a specific "version" of the schema, and includes directives that
apply all necessary changes to the database at once. If we look for example at apply all necessary changes to the database at once. If we look for example at
the script ``2d2a8a565438_hierarchical_binding.py``, we will see:: the script ``2d2a8a565438_hierarchical_binding.py``, we will see:
.. code-block:: python
# .../alembic_migrations/versions/2d2a8a565438_hierarchical_binding.py # .../alembic_migrations/versions/2d2a8a565438_hierarchical_binding.py
@ -351,20 +353,23 @@ the script ``2d2a8a565438_hierarchical_binding.py``, we will see::
# ... more DROP instructions ... # ... more DROP instructions ...
The above script contains directives that are both under the "expand" The above script contains directives that are both under the "expand"
and "contract" categories, as well as some data migrations. the ``op.create_table`` and "contract" categories, as well as some data migrations.
directive is an "expand"; it may be run safely while the old version of the The ``op.create_table`` directive is an "expand"; it may be run safely while
application still runs, as the old code simply doesn't look for this table. the old version of the application still runs, as the old code simply doesn't
look for this table.
The ``op.drop_constraint`` and ``op.drop_column`` directives are The ``op.drop_constraint`` and ``op.drop_column`` directives are
"contract" directives (the drop column more so than the drop constraint); running "contract" directives (the drop column more so than the drop constraint);
at least the ``op.drop_column`` directives means that the old version of the running at least the ``op.drop_column`` directives means that the old version
application will fail, as it will attempt to access these columns which no longer of the application will fail, as it will attempt to access these columns which
exist. no longer exist.
The data migrations in this script are adding new The data migrations in this script are adding new
rows to the newly added ``ml2_port_binding_levels`` table. rows to the newly added ``ml2_port_binding_levels`` table.
Under the new migration script directory structure, the above script would be Under the new migration script directory structure, the above script would be
stated as two scripts; an "expand" and a "contract" script:: stated as two scripts; an "expand" and a "contract" script:
.. code-block:: python
# expansion operations # expansion operations
# .../alembic_migrations/versions/liberty/expand/2bde560fc638_hierarchical_binding.py # .../alembic_migrations/versions/liberty/expand/2bde560fc638_hierarchical_binding.py
@ -427,7 +432,9 @@ For such cases, we use the ``contract_creation_exceptions`` that should be
implemented as part of such migrations. This is needed to get functional tests implemented as part of such migrations. This is needed to get functional tests
pass. pass.
Usage:: Usage:
.. code-block:: python
def contract_creation_exceptions(): def contract_creation_exceptions():
"""Docstring should explain why we allow such exception for contract """Docstring should explain why we allow such exception for contract
@ -445,7 +452,8 @@ HEAD files for conflict management
In directory ``neutron/db/migration/alembic_migrations/versions`` there are two In directory ``neutron/db/migration/alembic_migrations/versions`` there are two
files, ``CONTRACT_HEAD`` and ``EXPAND_HEAD``. These files contain the ID of the files, ``CONTRACT_HEAD`` and ``EXPAND_HEAD``. These files contain the ID of the
head revision in each branch. The purpose of these files is to validate the head revision in each branch. The purpose of these files is to validate the
revision timelines and prevent non-linear changes from entering the merge queue. revision timelines and prevent non-linear changes from entering the merge
queue.
When you create a new migration script by neutron-db-manage these files will be When you create a new migration script by neutron-db-manage these files will be
updated automatically. But if another migration script is merged while your updated automatically. But if another migration script is merged while your

4
doc/source/contributor/client_command_extensions.rst
View File

@ -24,8 +24,8 @@
Client command extension support Client command extension support
================================ ================================
The client command extension adds support for extending the neutron client while The client command extension adds support for extending the neutron client
considering ease of creation. while considering ease of creation.
The full document can be found in the python-neutronclient repository: The full document can be found in the python-neutronclient repository:
https://docs.openstack.org/python-neutronclient/latest/contributor/client_command_extensions.html https://docs.openstack.org/python-neutronclient/latest/contributor/client_command_extensions.html

48
doc/source/contributor/contribute.rst
View File

@ -142,10 +142,10 @@ code base.
potentially breaks your code. It is then up to you maintaining the affected potentially breaks your code. It is then up to you maintaining the affected
plugin/driver to determine whether the failure is transient or real, and plugin/driver to determine whether the failure is transient or real, and
resolve the problem if it is. resolve the problem if it is.
* it communicates to a patch author that they may be breaking a plugin/driver. * it communicates to a patch author that they may be breaking a
If they have the time/energy/relationship with the maintainer of the plugin/driver. If they have the time/energy/relationship with the
plugin/driver in question, then they can (at their discretion) work to maintainer of the plugin/driver in question, then they can (at their
resolve the breakage. discretion) work to resolve the breakage.
* it communicates to the community at large whether a given plugin/driver * it communicates to the community at large whether a given plugin/driver
is being actively maintained. is being actively maintained.
* A maintainer that is perceived to be responsive to failures in their * A maintainer that is perceived to be responsive to failures in their
@ -251,12 +251,14 @@ it does not affect Neutron core code stability.
DevStack Integration Strategies DevStack Integration Strategies
------------------------------- -------------------------------
When developing and testing a new or existing plugin or driver, the aid provided When developing and testing a new or existing plugin or driver, the aid
by DevStack is incredibly valuable: DevStack can help get all the software bits provided by DevStack is incredibly valuable: DevStack can help get all the
installed, and configured correctly, and more importantly in a predictable way. software bits installed, and configured correctly, and more importantly in a
For DevStack integration there are a few options available, and they may or may not predictable way.
make sense depending on whether you are contributing a new or existing plugin or
driver. For DevStack integration there are a few options available, and they may or
may not make sense depending on whether you are contributing a new or
existing plugin or driver.
If you are contributing a new plugin, the approach to choose should be based on If you are contributing a new plugin, the approach to choose should be based on
`Extras.d Hooks' externally hosted plugins `Extras.d Hooks' externally hosted plugins
@ -290,15 +292,16 @@ find on http://docs.openstack.org/infra/manual/creators.html. They are meant to
be the bare minimum you have to complete in order to get you off the ground. be the bare minimum you have to complete in order to get you off the ground.
* Create a public repository: this can be a personal opendev.org repo or any * Create a public repository: this can be a personal opendev.org repo or any
publicly available git repo, e.g. ``https://github.com/john-doe/foo.git``. This publicly available git repo, e.g. ``https://github.com/john-doe/foo.git``.
would be a temporary buffer to be used to feed the one on opendev.org. This would be a temporary buffer to be used to feed the one on opendev.org.
* Initialize the repository: if you are starting afresh, you may *optionally* * Initialize the repository: if you are starting afresh, you may *optionally*
want to use cookiecutter to get a skeleton project. You can learn how to use want to use cookiecutter to get a skeleton project. You can learn how to use
cookiecutter on https://opendev.org/openstack-dev/cookiecutter. cookiecutter on https://opendev.org/openstack-dev/cookiecutter.
If you want to build the repository from an existing Neutron module, you may If you want to build the repository from an existing Neutron module, you may
want to skip this step now, build the history first (next step), and come back want to skip this step now, build the history first (next step), and come
here to initialize the remainder of the repository with other files being back here to initialize the remainder of the repository with other files
generated by the cookiecutter (like tox.ini, setup.cfg, setup.py, etc.). being generated by the cookiecutter (like tox.ini, setup.cfg,
setup.py, etc.).
* Create a repository on opendev.org. For * Create a repository on opendev.org. For
this you need the help of the OpenStack infra team. It is worth noting that this you need the help of the OpenStack infra team. It is worth noting that
you only get one shot at creating the repository on opendev.org. This you only get one shot at creating the repository on opendev.org. This
@ -328,8 +331,8 @@ Internationalization support
---------------------------- ----------------------------
OpenStack is committed to broad international support. OpenStack is committed to broad international support.
Internationalization (I18n) is one of important areas to make OpenStack ubiquitous. Internationalization (I18n) is one of important areas to make OpenStack
Each project is recommended to support i18n. ubiquitous. Each project is recommended to support i18n.
This section describes how to set up translation support. This section describes how to set up translation support.
The description in this section uses the following variables: The description in this section uses the following variables:
@ -485,9 +488,9 @@ For example, for the ``networking-foo`` repo::
neutron.ml2.extension_drivers = neutron.ml2.extension_drivers =
foo_ext = networking_foo.plugins.ml2.drivers.foo:FooExtensionDriver foo_ext = networking_foo.plugins.ml2.drivers.foo:FooExtensionDriver
* Note: It is advisable to include ``foo`` in the names of these entry points to * Note: It is advisable to include ``foo`` in the names of these entry points
avoid conflicts with other third-party packages that may get installed in the to avoid conflicts with other third-party packages that may get installed in
same environment. the same environment.
API Extensions API Extensions
@ -531,8 +534,9 @@ Interface (VIF) drivers for the reference implementations are defined in
``neutron/agent/linux/interface.py``. Third-party interface drivers shall be ``neutron/agent/linux/interface.py``. Third-party interface drivers shall be
defined in a similar location within their own repo. defined in a similar location within their own repo.
The entry point for the interface driver is a Neutron config option. It is up to The entry point for the interface driver is a Neutron config option. It is up
the installer to configure this item in the ``[default]`` section. For example:: to the installer to configure this item in the ``[default]`` section.
For example::
[default] [default]
interface_driver = networking_foo.agent.linux.interface.FooInterfaceDriver interface_driver = networking_foo.agent.linux.interface.FooInterfaceDriver

52
doc/source/contributor/contributing.rst
View File

@ -4,9 +4,9 @@ So You Want to Contribute...
For general information on contributing to OpenStack, please check out the For general information on contributing to OpenStack, please check out the
`contributor guide <https://docs.openstack.org/contributors/>`_ to get started. `contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
It covers all the basics that are common to all OpenStack projects: the accounts It covers all the basics that are common to all OpenStack projects: the
you need, the basics of interacting with our Gerrit review system, how we accounts you need, the basics of interacting with our Gerrit review system,
communicate as a community, etc. how we communicate as a community, etc.
Below will cover the more project specific information you need to get started Below will cover the more project specific information you need to get started
with Neutron. with Neutron.
@ -21,9 +21,9 @@ Communication
- Team Meeting: - Team Meeting:
This is general Neutron team meeting. The discussion in this meeting is about This is general Neutron team meeting. The discussion in this meeting is about
all things related to the Neutron project, like community goals, progress with all things related to the Neutron project, like community goals, progress
blueprints, bugs, etc. There is also ``On Demand Agenda`` at the end of this with blueprints, bugs, etc. There is also ``On Demand Agenda`` at the end of
meeting, where anyone can add a topic to discuss with the Neutron team. this meeting, where anyone can add a topic to discuss with the Neutron team.
- time: http://eavesdrop.openstack.org/#Neutron_Team_Meeting - time: http://eavesdrop.openstack.org/#Neutron_Team_Meeting
- agenda: https://wiki.openstack.org/wiki/Network/Meetings - agenda: https://wiki.openstack.org/wiki/Network/Meetings
@ -47,9 +47,9 @@ Communication
Contacting the Core Team Contacting the Core Team
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
.. This section should list the core team, their irc nicks, emails, timezones etc. If .. This section should list the core team, their irc nicks, emails, timezones
all this info is maintained elsewhere (i.e. a wiki), you can link to that instead of etc. If all this info is maintained elsewhere (i.e. a wiki), you can link
enumerating everyone here. to that instead of enumerating everyone here.
The list of current Neutron core reviewers is available on `gerrit The list of current Neutron core reviewers is available on `gerrit
<https://review.opendev.org/#/admin/groups/38,members>`_. <https://review.opendev.org/#/admin/groups/38,members>`_.
@ -68,14 +68,15 @@ RFE should be submitted as a Launchpad bug first (see section
:ref:`reporting_a_bug`). The title of RFE bug should starts with ``[RFE]`` tag. :ref:`reporting_a_bug`). The title of RFE bug should starts with ``[RFE]`` tag.
Such RFEs need to be discussed and approved by the :ref:`Neutron drivers Such RFEs need to be discussed and approved by the :ref:`Neutron drivers
team<drivers_team>`. In some cases an additional spec proposed to the `Neutron team<drivers_team>`. In some cases an additional spec proposed to the `Neutron
specs <https://opendev.org/openstack/neutron-specs>`_ repo may be necessary. The specs <https://opendev.org/openstack/neutron-specs>`_ repo may be necessary.
complete process is described in detail in :ref:`Blueprints The complete process is described in detail in :ref:`Blueprints
guide<neutron_blueprints>`. guide<neutron_blueprints>`.
Task Tracking Task Tracking
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
.. This section is about where you track tasks- launchpad? storyboard? is there more .. This section is about where you track tasks- launchpad? storyboard? is
than one launchpad project? what's the name of the project group in storyboard? there more than one launchpad project? What's the name of the project group
in storyboard?
We track our tasks in `Launchpad <https://bugs.launchpad.net/neutron>`__. We track our tasks in `Launchpad <https://bugs.launchpad.net/neutron>`__.
If you're looking for some smaller, easier work item to pick up and get started If you're looking for some smaller, easier work item to pick up and get started
@ -85,16 +86,16 @@ List of all official tags which Neutron team is using is available on
:ref:`bugs<neutron_bugs>`. :ref:`bugs<neutron_bugs>`.
Every week, one of our team members is the :ref:`bug Every week, one of our team members is the :ref:`bug
deputy<neutron_bug_deputy>` and at the end of the week such person usually deputy<neutron_bug_deputy>` and at the end of the week such person usually
sends report about new bugs to the mailing list openstack-discuss@lists.openstack.org sends report about new bugs to the mailing list
or talks about it on our team meeting. This is also good place to look for some openstack-discuss@lists.openstack.org or talks about it on our team meeting.
work to do. This is also good place to look for some work to do.
.. _reporting_a_bug: .. _reporting_a_bug:
Reporting a Bug Reporting a Bug
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
.. Pretty self explanatory section, link directly to where people should report bugs for .. Pretty self explanatory section, link directly to where people should
your project. report bugs for your project.
You found an issue and want to make sure we are aware of it? You can do so on You found an issue and want to make sure we are aware of it? You can do so on
`Launchpad <https://bugs.launchpad.net/neutron/+filebug>`__. `Launchpad <https://bugs.launchpad.net/neutron/+filebug>`__.
@ -103,9 +104,9 @@ More info about Launchpad usage can be found on `OpenStack docs page
Getting Your Patch Merged Getting Your Patch Merged
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
.. This section should have info about what it takes to get something merged. Do .. This section should have info about what it takes to get something merged.
you require one or two +2's before +W? Do some of your repos require unit test Do you require one or two +2's before +W? Do some of your repos require
changes with all patches? etc. unit test changes with all patches? etc.
All changes proposed to the Neutron or one of the Neutron stadium projects All changes proposed to the Neutron or one of the Neutron stadium projects
require two +2 votes from Neutron core reviewers before one of the core require two +2 votes from Neutron core reviewers before one of the core
@ -127,16 +128,17 @@ Additionally to what is described in this guide, Neutron's PTL duties are:
- triage new RFEs and prepare `Neutron drivers team meeting - triage new RFEs and prepare `Neutron drivers team meeting
<http://eavesdrop.openstack.org/#Neutron_drivers_Meeting>`_, <http://eavesdrop.openstack.org/#Neutron_drivers_Meeting>`_,
- maintain list of the :ref:`stadium projects<neutron_stadium>` health - if each - maintain list of the :ref:`stadium projects<neutron_stadium>` health - if
project has gotten active team members and if it is following community and each project has gotten active team members and if it is following community
Neutron's guidelines and goals, and Neutron's guidelines and goals,
- maintain list of the :ref:`stadium projects - maintain list of the :ref:`stadium projects
lieutenants<subproject_lieutenants>` - check if those people are still active lieutenants<subproject_lieutenants>` - check if those people are still active
in the projects, if their contact data are correct, maybe there is someone in the projects, if their contact data are correct, maybe there is someone
new who is active in the stadium project and could be added to this list. new who is active in the stadium project and could be added to this list.
Over the past few years, the Neutron team has followed a mentoring approach for: Over the past few years, the Neutron team has followed a mentoring
approach for:
- new contributors, - new contributors,
- potential new core reviewers, - potential new core reviewers,

3
doc/source/contributor/dashboards/index.rst
View File

@ -18,7 +18,8 @@ Useful dashboard definitions are found in ``dashboards`` directory.
Grafana Dashboards Grafana Dashboards
------------------ ------------------
Look for neutron and networking-* dashboard by names by going to the following link: Look for neutron and networking-* dashboard by names by going to the following
link:
`Grafana <https://grafana.opendev.org/>`_ `Grafana <https://grafana.opendev.org/>`_

234
doc/source/contributor/effective_neutron.rst
View File

@ -34,8 +34,8 @@ By reading and collaboratively contributing to such a knowledge base, your
development and review cycle becomes shorter, because you will learn (and teach development and review cycle becomes shorter, because you will learn (and teach
to others after you) what to watch out for, and how to be proactive in order to others after you) what to watch out for, and how to be proactive in order
to prevent negative feedback, minimize programming errors, writing better to prevent negative feedback, minimize programming errors, writing better
tests, and so on and so forth...in a nutshell, how to become an effective Neutron tests, and so on and so forth...in a nutshell, how to become an effective
developer. Neutron developer.
The notes below are meant to be free-form and brief by design. They are not meant The notes below are meant to be free-form and brief by design. They are not meant
to replace or duplicate `OpenStack documentation <http://docs.openstack.org>`_, to replace or duplicate `OpenStack documentation <http://docs.openstack.org>`_,
@ -57,7 +57,8 @@ Developing better software
Plugin development Plugin development
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done during plugin development. Document common pitfalls as well as good practices done during plugin
development.
* Use mixin classes as last resort. They can be a powerful tool to add behavior * Use mixin classes as last resort. They can be a powerful tool to add behavior
but their strength is also a weakness, as they can introduce `unpredictable <https://review.opendev.org/#/c/121290/>`_ but their strength is also a weakness, as they can introduce `unpredictable <https://review.opendev.org/#/c/121290/>`_
@ -75,23 +76,26 @@ Document common pitfalls as well as good practices done during plugin developmen
there is an agent on the other side of the message broker that interacts there is an agent on the other side of the message broker that interacts
with the server. Plugins may not rely on `agents <https://review.opendev.org/#/c/174020/>`_ at all. with the server. Plugins may not rely on `agents <https://review.opendev.org/#/c/174020/>`_ at all.
* Be mindful of required capabilities when you develop plugin extensions. The * Be mindful of required capabilities when you develop plugin extensions. The
`Extension description <https://github.com/openstack/neutron/blob/b14c06b5/neutron/api/extensions.py#L122>`_ provides the ability to specify the list of required capabilities `Extension description <https://github.com/openstack/neutron/blob/b14c06b5/neutron/api/extensions.py#L122>`_
provides the ability to specify the list of required capabilities
for the extension you are developing. By declaring this list, the server will for the extension you are developing. By declaring this list, the server will
not start up if the requirements are not met, thus avoiding leading the system not start up if the requirements are not met, thus avoiding leading the
to experience undetermined behavior at runtime. system to experience undetermined behavior at runtime.
Database interaction Database interaction
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done during database development. Document common pitfalls as well as good practices done during database
development.
* `first() <http://docs.sqlalchemy.org/en/rel_1_0/orm/query.html#sqlalchemy.orm.query.Query.first>`_ * `first() <http://docs.sqlalchemy.org/en/rel_1_0/orm/query.html#sqlalchemy.orm.query.Query.first>`_
does not raise an exception. does not raise an exception.
* Do not use `delete() <http://docs.sqlalchemy.org/en/rel_1_0/orm/query.html#sqlalchemy.orm.query.Query.delete>`_ * Do not use `delete() <http://docs.sqlalchemy.org/en/rel_1_0/orm/query.html#sqlalchemy.orm.query.Query.delete>`_
to remove objects. A delete query does not load the object so no sqlalchemy events to remove objects. A delete query does not load the object so no sqlalchemy
can be triggered that would do things like recalculate quotas or update revision events can be triggered that would do things like recalculate quotas or
numbers of parent objects. For more details on all of the things that can go wrong update revision numbers of parent objects. For more details on all of the
using bulk delete operations, see the "Warning" sections in the link above. things that can go wrong using bulk delete operations, see the "Warning"
sections in the link above.
* For PostgreSQL if you're using GROUP BY everything in the SELECT list must be * For PostgreSQL if you're using GROUP BY everything in the SELECT list must be
an aggregate SUM(...), COUNT(...), etc or used in the GROUP BY. an aggregate SUM(...), COUNT(...), etc or used in the GROUP BY.
@ -170,8 +174,8 @@ Document common pitfalls as well as good practices done during database developm
System development System development
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when invoking system commands Document common pitfalls as well as good practices done when invoking system
and interacting with linux utils. commands and interacting with linux utils.
* When a patch requires a new platform tool or a new feature in an existing * When a patch requires a new platform tool or a new feature in an existing
tool, check if common platforms ship packages with the aforementioned tool, check if common platforms ship packages with the aforementioned
@ -179,37 +183,39 @@ and interacting with linux utils.
visibility (as these patches are brought up to the attention of the core team visibility (as these patches are brought up to the attention of the core team
during team meetings). during team meetings).
More details in :ref:`review guidelines <spec-review-practices>`. More details in :ref:`review guidelines <spec-review-practices>`.
* When a patch or the code depends on a new feature in the kernel or in any platform tools * When a patch or the code depends on a new feature in the kernel or in any
(dnsmasq, ip, Open vSwitch etc.), consider introducing a new sanity check to platform tools (dnsmasq, ip, Open vSwitch etc.), consider introducing a new
validate deployments for the expected features. Note that sanity checks *must sanity check to validate deployments for the expected features. Note that
not* check for version numbers of underlying platform tools because sanity checks *must not* check for version numbers of underlying platform
distributions may decide to backport needed features into older versions. tools because distributions may decide to backport needed features into older
Instead, sanity checks should validate actual features by attempting to use them. versions. Instead, sanity checks should validate actual features by
attempting to use them.
Eventlet concurrent model Eventlet concurrent model
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when using eventlet and monkey Document common pitfalls as well as good practices done when using eventlet
patching. and monkey patching.
* Do not use with_lockmode('update') on SQL queries without protecting the operation * Do not use with_lockmode('update') on SQL queries without protecting the
with a lockutils semaphore. For some SQLAlchemy database drivers that operators may operation with a lockutils semaphore. For some SQLAlchemy database drivers
choose (e.g. MySQLdb) it may result in a temporary deadlock by yielding to another that operators may choose (e.g. MySQLdb) it may result in a temporary
coroutine while holding the DB lock. The following wiki provides more details: deadlock by yielding to another coroutine while holding the DB lock.
The following wiki provides more details:
https://wiki.openstack.org/wiki/OpenStack_and_SQLAlchemy#MySQLdb_.2B_eventlet_.3D_sad https://wiki.openstack.org/wiki/OpenStack_and_SQLAlchemy#MySQLdb_.2B_eventlet_.3D_sad
Mocking and testing Mocking and testing
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when writing tests, any test. Document common pitfalls as well as good practices done when writing tests,
For anything more elaborate, please visit the testing section. any test. For anything more elaborate, please visit the testing section.
* Preferring low level testing versus full path testing (e.g. not testing database * Preferring low level testing versus full path testing (e.g. not testing
via client calls). The former is to be favored in unit testing, whereas the latter database via client calls). The former is to be favored in unit testing,
is to be favored in functional testing. whereas the latter is to be favored in functional testing.
* Prefer specific assertions (assert(Not)In, assert(Not)IsInstance, assert(Not)IsNone, * Prefer specific assertions (assert(Not)In, assert(Not)IsInstance,
etc) over generic ones (assertTrue/False, assertEqual) because they raise more assert(Not)IsNone, etc) over generic ones (assertTrue/False, assertEqual)
meaningful errors: because they raise more meaningful errors:
.. code:: python .. code:: python
@ -221,28 +227,30 @@ For anything more elaborate, please visit the testing section.
self.assertTrue(3 in [1, 2]) self.assertTrue(3 in [1, 2])
# raise meaningless error: "AssertionError: False is not true" # raise meaningless error: "AssertionError: False is not true"
* Use the pattern "self.assertEqual(expected, observed)" not the opposite, it helps * Use the pattern "self.assertEqual(expected, observed)" not the opposite, it
reviewers to understand which one is the expected/observed value in non-trivial helps reviewers to understand which one is the expected/observed value in
assertions. The expected and observed values are also labeled in the output when non-trivial assertions. The expected and observed values are also labeled
the assertion fails. in the output when the assertion fails.
* Prefer specific assertions (assertTrue, assertFalse) over assertEqual(True/False, observed). * Prefer specific assertions (assertTrue, assertFalse) over
* Don't write tests that don't test the intended code. This might seem silly but assertEqual(True/False, observed).
it's easy to do with a lot of mocks in place. Ensure that your tests break as * Don't write tests that don't test the intended code. This might seem silly
expected before your code change. but it is easy to do with a lot of mocks in place. Ensure that your tests
* Avoid heavy use of the mock library to test your code. If your code requires more break as expected before your code change.
than one mock to ensure that it does the correct thing, it needs to be refactored * Avoid heavy use of the mock library to test your code. If your code requires
into smaller, testable units. Otherwise we depend on fullstack/tempest/api tests more than one mock to ensure that it does the correct thing, it needs to be
to test all of the real behavior and we end up with code containing way too many refactored into smaller, testable units. Otherwise we depend on
hidden dependencies and side effects. fullstack/tempest/api tests to test all of the real behavior and we end up
with code containing way too many hidden dependencies and side effects.
* All behavior changes to fix bugs should include a test that prevents a * All behavior changes to fix bugs should include a test that prevents a
regression. If you made a change and it didn't break a test, it means the regression. If you made a change and it didn't break a test, it means the
code was not adequately tested in the first place, it's not an excuse to leave code was not adequately tested in the first place, it's not an excuse to
it untested. leave it untested.
* Test the failure cases. Use a mock side effect to throw the necessary * Test the failure cases. Use a mock side effect to throw the necessary
exceptions to test your 'except' clauses. exceptions to test your 'except' clauses.
* Don't mimic existing tests that violate these guidelines. We are attempting to * Don't mimic existing tests that violate these guidelines. We are attempting
replace all of these so more tests like them create more work. If you need help to replace all of these so more tests like them create more work. If you
writing a test, reach out to the testing lieutenants and the team on IRC. need help writing a test, reach out to the testing lieutenants and the team
on IRC.
* Mocking open() is a dangerous practice because it can lead to unexpected * Mocking open() is a dangerous practice because it can lead to unexpected
bugs like `bug 1503847 <https://bugs.launchpad.net/neutron/+bug/1503847>`_. bugs like `bug 1503847 <https://bugs.launchpad.net/neutron/+bug/1503847>`_.
In fact, when the built-in open method is mocked during tests, some In fact, when the built-in open method is mocked during tests, some
@ -269,14 +277,17 @@ down into the following directories based on content:
Additional documentation resides in the neutron-lib repository: Additional documentation resides in the neutron-lib repository:
* api-ref - API reference documentation for Neutron resource and API extensions. * api-ref - API reference documentation for Neutron resource and API
extensions.
Backward compatibility Backward compatibility
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when extending the RPC Interfaces. Document common pitfalls as well as good practices done when extending the
RPC Interfaces.
* Make yourself familiar with :ref:`Upgrade review guidelines <upgrade_review_guidelines>`. * Make yourself familiar with
:ref:`Upgrade review guidelines <upgrade_review_guidelines>`.
Deprecation Deprecation
+++++++++++ +++++++++++
@ -304,13 +315,14 @@ In terms of neutron development, this means:
Scalability issues Scalability issues
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when writing code that needs to process Document common pitfalls as well as good practices done when writing code
a lot of data. that needs to process a lot of data.
Translation and logging Translation and logging
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when instrumenting your code. Document common pitfalls as well as good practices done when instrumenting
your code.
* Make yourself familiar with `OpenStack logging guidelines <http://specs.openstack.org/openstack/openstack-specs/specs/log-guidelines.html#definition-of-log-levels>`_ * Make yourself familiar with `OpenStack logging guidelines <http://specs.openstack.org/openstack/openstack-specs/specs/log-guidelines.html#definition-of-log-levels>`_
to avoid littering the logs with traces logged at inappropriate levels. to avoid littering the logs with traces logged at inappropriate levels.
@ -326,13 +338,14 @@ Document common pitfalls as well as good practices done when instrumenting your
Project interfaces Project interfaces
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when writing code that is used Document common pitfalls as well as good practices done when writing code
to interface with other projects, like Keystone or Nova. that is used to interface with other projects, like Keystone or Nova.
Documenting your code Documenting your code
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when writing docstrings. Document common pitfalls as well as good practices done when writing
docstrings.
Landing patches more rapidly Landing patches more rapidly
---------------------------- ----------------------------
@ -363,17 +376,19 @@ Nits and pedantic comments
Document common nits and pedantic comments to watch out for. Document common nits and pedantic comments to watch out for.
* Make sure you spell correctly, the best you can, no-one wants rebase generators at * Make sure you spell correctly, the best you can, no-one wants rebase
the end of the release cycle! generators at the end of the release cycle!
* The odd pep8 error may cause an entire CI run to be wasted. Consider running * The odd pep8 error may cause an entire CI run to be wasted. Consider running
validation (pep8 and/or tests) before submitting your patch. If you keep forgetting validation (pep8 and/or tests) before submitting your patch. If you keep
consider installing a git `hook <https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks>`_ forgetting consider installing a git
`hook <https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks>`_
so that Git will do it for you. so that Git will do it for you.
* Sometimes, new contributors want to dip their toes with trivial patches, but we * Sometimes, new contributors want to dip their toes with trivial patches,
at OpenStack *love* bike shedding and their patches may sometime stall. In but we at OpenStack *love* bike shedding and their patches may sometime
some extreme cases, the more trivial the patch, the higher the chances it fails stall. In some extreme cases, the more trivial the patch, the higher the
to merge. To ensure we as a team provide/have a frustration-free experience chances it fails to merge. To ensure we as a team provide/have a
new contributors should be redirected to fixing `low-hanging-fruit bugs <https://bugs.launchpad.net/neutron/+bugs?field.tag=low-hanging-fruit>`_ frustration-free experience new contributors should be redirected to fixing
`low-hanging-fruit bugs <https://bugs.launchpad.net/neutron/+bugs?field.tag=low-hanging-fruit>`_
that have a tangible positive impact to the codebase. Spelling mistakes, and that have a tangible positive impact to the codebase. Spelling mistakes, and
docstring are fine, but there is a lot more that is relatively easy to fix docstring are fine, but there is a lot more that is relatively easy to fix
and has a direct impact to Neutron users. and has a direct impact to Neutron users.
@ -381,36 +396,39 @@ Document common nits and pedantic comments to watch out for.
Reviewer comments Reviewer comments
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
* Acknowledge them one by one by either clicking 'Done' or by replying extensively. * Acknowledge them one by one by either clicking 'Done' or by replying
If you do not, the reviewer won't know whether you thought it was not important, extensively. If you do not, the reviewer won't know whether you thought it
or you simply forgot. If the reply satisfies the reviewer, consider capturing the was not important, or you simply forgot. If the reply satisfies the reviewer,
input in the code/document itself so that it's for reviewers of newer patchsets to consider capturing the input in the code/document itself so that it's for
see (and other developers when the patch merges). reviewers of newer patchsets to see (and other developers when the
patch merges).
* Watch for the feedback on your patches. Acknowledge it promptly and act on it * Watch for the feedback on your patches. Acknowledge it promptly and act on it
quickly, so that the reviewer remains engaged. If you disappear for a week after quickly, so that the reviewer remains engaged. If you disappear for a week
you posted a patchset, it is very likely that the patch will end up being after you posted a patchset, it is very likely that the patch will end up
neglected. being neglected.
* Do not take negative feedback personally. Neutron is a large project with lots * Do not take negative feedback personally. Neutron is a large project with
of contributors with different opinions on how things should be done. Many come lots of contributors with different opinions on how things should be done.
from widely varying cultures and languages so the English, text-only feedback Many come from widely varying cultures and languages so the English,
can unintentionally come across as harsh. Getting a -1 means reviewers are text-only feedback can unintentionally come across as harsh. Getting a -1
trying to help get the patch into a state that can be merged, it doesn't just means reviewers are trying to help get the patch into a state that can be
mean they are trying to block it. It's very rare to get a patch merged on the merged, it doesn't just mean they are trying to block it. It's very rare to
first iteration that makes everyone happy. get a patch merged on the first iteration that makes everyone happy.
Code Review Code Review
~~~~~~~~~~~ ~~~~~~~~~~~
* You should visit `OpenStack How To Review wiki <https://wiki.openstack.org/wiki/How_To_Contribute#Reviewing>`_ * You should visit `OpenStack How To Review wiki <https://wiki.openstack.org/wiki/How_To_Contribute#Reviewing>`_
* Stay focussed and review what matters for the release. Please check out the Neutron * Stay focussed and review what matters for the release. Please check out the
section for the `Gerrit dashboard <http://status.openstack.org/reviews/>`_. The output Neutron section for the
is generated by this `tool <https://github.com/openstack-infra/reviewday/blob/master/bin/neutron>`_. `Gerrit dashboard <http://status.openstack.org/reviews/>`_. The output
is generated by this
`tool <https://github.com/openstack-infra/reviewday/blob/master/bin/neutron>`_.
IRC IRC
~~~~ ~~~~
* IRC is a place where you can speak with many of the Neutron developers and core * IRC is a place where you can speak with many of the Neutron developers
reviewers. For more information you should visit and core reviewers. For more information you should visit
`OpenStack IRC wiki <http://wiki.openstack.org/wiki/IRC>`_ `OpenStack IRC wiki <http://wiki.openstack.org/wiki/IRC>`_
Neutron IRC channel is #openstack-neutron Neutron IRC channel is #openstack-neutron
* There are weekly IRC meetings related to many different projects/teams * There are weekly IRC meetings related to many different projects/teams
@ -428,8 +446,9 @@ IRC
up the feedback loop. up the feedback loop.
* Each area of Neutron or sub-project of Neutron has a specific lieutenant * Each area of Neutron or sub-project of Neutron has a specific lieutenant
in charge of it. in charge of it.
You can most likely find these lieutenants on IRC, it is advised however to try You can most likely find these lieutenants on IRC, it is advised however to
and send public questions to the channel rather then to a specific person if possible. try and send public questions to the channel rather then to a specific person
if possible.
(This increase the chances of getting faster answers to your questions). (This increase the chances of getting faster answers to your questions).
A list of the areas and lieutenants nicknames can be found at A list of the areas and lieutenants nicknames can be found at
:doc:`Core Reviewers <policies/neutron-teams>`. :doc:`Core Reviewers <policies/neutron-teams>`.
@ -437,7 +456,8 @@ IRC
Commit messages Commit messages
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when writing commit messages. Document common pitfalls as well as good practices done when writing commit
messages.
For more details see `Git commit message best practices <https://wiki.openstack.org/wiki/GitCommitMessages>`_. For more details see `Git commit message best practices <https://wiki.openstack.org/wiki/GitCommitMessages>`_.
This is the TL;DR version with the important points for committing to Neutron. This is the TL;DR version with the important points for committing to Neutron.
@ -456,13 +476,13 @@ This is the TL;DR version with the important points for committing to Neutron.
code will fix the problem. If it's part of a feature implementation, explain code will fix the problem. If it's part of a feature implementation, explain
what component of the feature the patch implements. Do not just describe the what component of the feature the patch implements. Do not just describe the
bug, that's what launchpad is for. bug, that's what launchpad is for.
* Use the "Closes-Bug: #BUG-NUMBER" tag if the patch addresses a bug. Submitting * Use the "Closes-Bug: #BUG-NUMBER" tag if the patch addresses a bug.
a bugfix without a launchpad bug reference is unacceptable, even if it's Submitting a bugfix without a launchpad bug reference is unacceptable, even
trivial. Launchpad is how bugs are tracked so fixes without a launchpad bug are if it's trivial. Launchpad is how bugs are tracked so fixes without a
a nightmare when users report the bug from an older version and the Neutron team launchpad bug are a nightmare when users report the bug from an older
can't tell if/why/how it's been fixed. Launchpad is also how backports are version and the Neutron team can't tell if/why/how it's been fixed.
identified and tracked so patches without a bug report cannot be picked to stable Launchpad is also how backports are identified and tracked so patches
branches. without a bug report cannot be picked to stable branches.
* Use the "Implements: blueprint NAME-OF-BLUEPRINT" or "Partially-Implements: * Use the "Implements: blueprint NAME-OF-BLUEPRINT" or "Partially-Implements:
blueprint NAME-OF-BLUEPRINT" for features so reviewers can determine if the blueprint NAME-OF-BLUEPRINT" for features so reviewers can determine if the
code matches the spec that was agreed upon. This also updates the blueprint code matches the spec that was agreed upon. This also updates the blueprint
@ -482,12 +502,14 @@ This is the TL;DR version with the important points for committing to Neutron.
Dealing with Zuul Dealing with Zuul
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
Document common pitfalls as well as good practices done when dealing with OpenStack CI. Document common pitfalls as well as good practices done when dealing with
OpenStack CI.
* When you submit a patch, consider checking its `status <http://status.openstack.org/zuul/>`_ * When you submit a patch, consider checking its `status <http://status.openstack.org/zuul/>`_
in the queue. If you see a job failures, you might as well save time and try to figure out in the queue. If you see a job failures, you might as well save time and try
in advance why it is failing. to figure out in advance why it is failing.
* Excessive use of 'recheck' to get test to pass is discouraged. Please examine the logs for * Excessive use of 'recheck' to get test to pass is discouraged. Please examine
the failing test(s) and make sure your change has not tickled anything that might be causing the logs for the failing test(s) and make sure your change has not tickled
a new failure or race condition. Getting your change in could make it even harder to debug anything that might be causing a new failure or race condition. Getting your
what is actually broken later on. change in could make it even harder to debug what is actually broken
later on.

3
doc/source/contributor/internals/agent_extensions.rst
View File

@ -40,7 +40,8 @@ Interactions with the agent API object are in the following order:
#. The agent initializes the agent API object. #. The agent initializes the agent API object.
#. The agent passes the agent API object into the extension manager. #. The agent passes the agent API object into the extension manager.
#. The manager passes the agent API object into each extension. #. The manager passes the agent API object into each extension.
#. An extension calls the new agent API object method to receive, for instance, bridge wrappers with cookies allocated. #. An extension calls the new agent API object method to receive, for instance,
bridge wrappers with cookies allocated.
:: ::

3
doc/source/contributor/internals/api_extensions.rst
View File

@ -76,4 +76,5 @@ Current API resources extended by standard attr extensions:
- ports: neutron.db.models_v2.Port - ports: neutron.db.models_v2.Port
- security_groups: neutron.db.models.securitygroup.SecurityGroup - security_groups: neutron.db.models.securitygroup.SecurityGroup
- floatingips: neutron.db.l3_db.FloatingIP - floatingips: neutron.db.l3_db.FloatingIP
- network_segment_ranges: neutron.db.models.network_segment_range.NetworkSegmentRange - network_segment_ranges:
neutron.db.models.network_segment_range.NetworkSegmentRange

10
doc/source/contributor/internals/db_layer.rst
View File

@ -40,9 +40,10 @@ The explanation is quite simple:
* `server_default <http://docs.sqlalchemy.org/en/rel_0_9/core/metadata.html#sqlalchemy.schema.Column.params.server_default>`_ - the default value for a column that SQLAlchemy will specify in DDL. * `server_default <http://docs.sqlalchemy.org/en/rel_0_9/core/metadata.html#sqlalchemy.schema.Column.params.server_default>`_ - the default value for a column that SQLAlchemy will specify in DDL.
Summarizing, 'default' is useless in migrations and only 'server_default' Summarizing, 'default' is useless in migrations and only 'server_default'
should be used. For synchronizing migrations with models server_default parameter should be used. For synchronizing migrations with models server_default
should also be added in model. If default value in database is not needed, parameter should also be added in model. If default value in database is not
'server_default' should not be used. The declarative approach can be bypassed needed, 'server_default' should not be used. The declarative approach can be
bypassed
(i.e. 'default' may be omitted in the model) if default is enforced through (i.e. 'default' may be omitted in the model) if default is enforced through
business logic. business logic.
@ -97,7 +98,8 @@ A model that supports tag mechanism must implement the property
The introduction of a new standard attribute only requires one column addition The introduction of a new standard attribute only requires one column addition
to the 'standardattribute' table for one-to-one relationships or a new table to the 'standardattribute' table for one-to-one relationships or a new table
for one-to-many or one-to-zero relationships. Then all of the models using the for one-to-many or one-to-zero relationships. Then all of the models using the
'HasStandardAttribute' mixin will automatically gain access to the new attribute. 'HasStandardAttribute' mixin will automatically gain access to the new
attribute.
Any attributes that will apply to every neutron resource (e.g. timestamps) Any attributes that will apply to every neutron resource (e.g. timestamps)
can be added directly to the 'standardattribute' table. For things that will can be added directly to the 'standardattribute' table. For things that will

4
doc/source/contributor/internals/external_dns_integration.rst
View File

@ -49,8 +49,8 @@ Pre-configured domains for projects and users
ML2 plugin extension ``dns_domain_keywords`` provides same dns integration as ML2 plugin extension ``dns_domain_keywords`` provides same dns integration as
``dns_domain_ports`` and ``subnet_dns_publish_fixed_ip`` and it also allows to ``dns_domain_ports`` and ``subnet_dns_publish_fixed_ip`` and it also allows to
configure network's dns_domain with some specific keywords: ``<project_id>``, configure network's dns_domain with some specific keywords: ``<project_id>``,
``<project_name>``, ``<user_id>``, ``<user_name>``. Please see example below for ``<project_name>``, ``<user_id>``, ``<user_name>``. Please see example below
more details. for more details.
* Create DNS zone. ``0511951bd56e4a0aac27ac65e00bddd0`` is ID of the project * Create DNS zone. ``0511951bd56e4a0aac27ac65e00bddd0`` is ID of the project
used in the example used in the example

16
doc/source/contributor/internals/layer3.rst
View File

@ -141,7 +141,8 @@ Neutron Routers are realized in OpenVSwitch
.. image:: images/under-the-hood-scenario-1-ovs-network.png .. image:: images/under-the-hood-scenario-1-ovs-network.png
"router1" in the Neutron logical network is realized through a port ("qr-0ba8700e-da") in OpenVSwitch - attached to "br-int":: "router1" in the Neutron logical network is realized through a port
("qr-0ba8700e-da") in OpenVSwitch - attached to "br-int"::
vagrant@bionic64:~/devstack$ sudo ovs-vsctl show vagrant@bionic64:~/devstack$ sudo ovs-vsctl show
b9b27fc3-5057-47e7-ba64-0b6afe70a398 b9b27fc3-5057-47e7-ba64-0b6afe70a398
@ -202,13 +203,16 @@ Neutron Routers are realized in OpenVSwitch
Finding the router in ip/ipconfig Finding the router in ip/ipconfig
--------------------------------- ---------------------------------
The neutron-l3-agent uses the Linux IP stack and iptables to perform L3 forwarding and NAT. The neutron-l3-agent uses the Linux IP stack and iptables to perform L3
In order to support multiple routers with potentially overlapping IP addresses, neutron-l3-agent forwarding and NAT. In order to support multiple routers with potentially
defaults to using Linux network namespaces to provide isolated forwarding contexts. As a result, overlapping IP addresses, neutron-l3-agent defaults to using Linux network
the IP addresses of routers will not be visible simply by running "ip addr list" or "ifconfig" on namespaces to provide isolated forwarding contexts. As a result,
the IP addresses of routers will not be visible simply by running
"ip addr list" or "ifconfig" on
the node. Similarly, you will not be able to directly ping fixed IPs. the node. Similarly, you will not be able to directly ping fixed IPs.
To do either of these things, you must run the command within a particular router's network To do either of these things, you must run the command within a particular
router's network
namespace. The namespace will have the name "qrouter-<UUID of the router>. namespace. The namespace will have the name "qrouter-<UUID of the router>.
.. image:: images/under-the-hood-scenario-1-ovs-netns.png .. image:: images/under-the-hood-scenario-1-ovs-netns.png

4
doc/source/contributor/internals/objects_usage.rst
View File

@ -374,8 +374,8 @@ types that can be used to implement them.
# implemented in some object-specific way. # implemented in some object-specific way.
synthetic_fields = ['dhcp_agents', 'shared', 'subnets'] synthetic_fields = ['dhcp_agents', 'shared', 'subnets']
:code:`ObjectField` and :code:`ListOfObjectsField` take the name of object class :code:`ObjectField` and :code:`ListOfObjectsField` take the name of object
as an argument. class as an argument.
Implementing custom synthetic fields Implementing custom synthetic fields

152
doc/source/contributor/internals/openvswitch_agent.rst
View File

@ -44,8 +44,8 @@ VLAN Tags
GRE Tunnels GRE Tunnels
----------- -----------
GRE Tunneling is documented in depth in the `Networking in too much GRE Tunneling is documented in depth in the `Networking in too much detail
detail <http://openstack.redhat.com/networking/networking-in-too-much-detail/>`_ <http://openstack.redhat.com/networking/networking-in-too-much-detail/>`_
by RedHat. by RedHat.
VXLAN Tunnels VXLAN Tunnels
@ -327,28 +327,28 @@ br-int or into the firewall bridge if using iptables firewall. In the
external-ids of the port Nova will store the port ID of the parent port. external-ids of the port Nova will store the port ID of the parent port.
The OVS agent detects that a new vif has been plugged. It gets The OVS agent detects that a new vif has been plugged. It gets
the details of the new port and wires it. the details of the new port and wires it.
The agent configures it in the same way as a traditional port: packets coming out The agent configures it in the same way as a traditional port: packets coming
from the VM will be tagged using the internal VLAN ID associated to the network, out from the VM will be tagged using the internal VLAN ID associated to the
packets going to the VM will be stripped of the VLAN ID. network, packets going to the VM will be stripped of the VLAN ID.
After wiring it successfully the OVS agent will send a message notifying Neutron After wiring it successfully the OVS agent will send a message notifying
server that the parent port is up. Neutron will send back to Nova an event to Neutron server that the parent port is up. Neutron will send back to Nova an
signal that the wiring was successful. event to signal that the wiring was successful.
If the parent port is associated with one or more subports the agent will process If the parent port is associated with one or more subports the agent will
them as described in the next paragraph. process them as described in the next paragraph.
Subport creation Subport creation
++++++++++++++++ ++++++++++++++++
If a subport is added to a parent port but no VM was booted using that parent port If a subport is added to a parent port but no VM was booted using that parent
yet, no L2 agent will process it (because at that point the parent port is port yet, no L2 agent will process it (because at that point the parent port is
not bound to any host). not bound to any host).
When a subport is created for a parent port and a VM that uses that parent port is When a subport is created for a parent port and a VM that uses that parent port
already running, the OVS agent will create a VLAN interface on the VM tap is already running, the OVS agent will create a VLAN interface on the VM tap
using the VLAN ID specified in the subport segmentation id. There's a small possibility using the VLAN ID specified in the subport segmentation id. There's a small
that a race might occur: the firewall bridge might be created and plugged while the vif possibility that a race might occur: the firewall bridge might be created and
is not there yet. The OVS agent needs to check if the vif exists before trying to create plugged while the vif is not there yet. The OVS agent needs to check if the
a subinterface. vif exists before trying to create a subinterface.
Let's see how the models differ when using the iptables firewall or the ovs native Let's see how the models differ when using the iptables firewall or the OVS
firewall. native firewall.
Iptables Firewall Iptables Firewall
''''''''''''''''' '''''''''''''''''
@ -393,10 +393,11 @@ and the packet will finally get to eth0.100.
*Outbound traffic from the VM point of view* *Outbound traffic from the VM point of view*
The untagged traffic will flow from eth0 to port1 going through qbr1 where The untagged traffic will flow from eth0 to port1 going through qbr1 where
firewall rules will be applied. Traffic tagged with VLAN 100 will leave eth0.100, firewall rules will be applied. Traffic tagged with VLAN 100 will leave
go through tap1.100 where the VLAN 100 is stripped. It will reach qbr2 where eth0.100, go through tap1.100 where the VLAN 100 is stripped. It will reach
iptables rules will be applied and go to port 2. The internal VLAN of network2 qbr2 where iptables rules will be applied and go to port 2. The internal VLAN
will be pushed by br-int when the packet enters port2 because it's a tagged port. of network2 will be pushed by br-int when the packet enters port2 because it's
a tagged port.
OVS Firewall case OVS Firewall case
@ -422,56 +423,59 @@ OVS Firewall case
| br-int | | br-int |
+----------------------------+ +----------------------------+
When a subport is created the OVS agent will create the VLAN interface tap1.100 and When a subport is created the OVS agent will create the VLAN interface tap1.100
plug it into br-int. Let's assume the subport is on network2. and plug it into br-int. Let's assume the subport is on network2.
*Inbound traffic from the VM point of view* *Inbound traffic from the VM point of view*
The traffic will flow untagged from port 1 to eth0. The traffic going out from port 2 The traffic will flow untagged from port 1 to eth0. The traffic going out from
will be stripped of the VLAN ID assigned to network2. It will be filtered by the rules port 2 will be stripped of the VLAN ID assigned to network2. It will be
installed by the firewall and reach tap1.100. filtered by the rules installed by the firewall and reach tap1.100.
tap1.100 will tag the traffic using VLAN 100. It will then reach the VM's eth0.100. tap1.100 will tag the traffic using VLAN 100. It will then reach the VM's
eth0.100.
*Outbound traffic from the VM point of view* *Outbound traffic from the VM point of view*
The untagged traffic will flow and reach port 1 where it will be tagged using the The untagged traffic will flow and reach port 1 where it will be tagged using
VLAN ID associated to the network. Traffic tagged with VLAN 100 will leave eth0.100 the VLAN ID associated to the network. Traffic tagged with VLAN 100 will leave
reach tap1.100 where VLAN 100 will be stripped. It will then reach port2. eth0.100 and reach tap1.100 where VLAN 100 will be stripped. It will then reach
It will be filtered by the rules installed by the firewall on port 2. Then the packets port2. It will be filtered by the rules installed by the firewall on port 2.
will be tagged using the internal VLAN associated to network2 by br-int since port 2 is a Then the packets will be tagged using the internal VLAN associated to network2
tagged port. by br-int since port 2 is a tagged port.
Parent port deletion Parent port deletion
++++++++++++++++++++ ++++++++++++++++++++
Deleting a port that is an active parent in a trunk is forbidden. If the parent port has Deleting a port that is an active parent in a trunk is forbidden. If the parent
no trunk associated (it's a "normal" port), it can be deleted. port has no trunk associated (it's a "normal" port), it can be deleted.
The OVS agent doesn't need to perform any action, the deletion will result in a removal The OVS agent doesn't need to perform any action, the deletion will result in
of the port data from the DB. a removal of the port data from the DB.
Trunk deletion Trunk deletion
++++++++++++++ ++++++++++++++
When Nova deletes a VM, it deletes the VM's corresponding Neutron ports only if they were When Nova deletes a VM, it deletes the VM's corresponding Neutron ports only if
created by Nova when booting the VM. In the vlan-aware-vm case the parent port is passed to Nova, so they were created by Nova when booting the VM. In the vlan-aware-vm case the
the port data will remain in the DB after the VM deletion. Nova will delete parent port is passed to Nova, so the port data will remain in the DB after the
the VIF of the VM (in the example tap1) as part of the VM termination. The OVS agent VM deletion. Nova will delete the VIF of the VM (in the example tap1) as part
will detect that deletion and notify the Neutron server that the parent port is down. of the VM termination. The OVS agent will detect that deletion and notify the
The OVS agent will clean up the corresponding subports as explained in the next paragraph. Neutron server that the parent port is down. The OVS agent will clean up the
corresponding subports as explained in the next paragraph.
The deletion of a trunk that is used by a VM is not allowed. The deletion of a trunk that is used by a VM is not allowed.
The trunk can be deleted (leaving the parent port intact) when the parent port is not The trunk can be deleted (leaving the parent port intact) when the parent port
used by any VM. After the trunk is deleted, the parent port can also be deleted. is not used by any VM. After the trunk is deleted, the parent port can also be
deleted.
Subport deletion Subport deletion
++++++++++++++++ ++++++++++++++++
Removing a subport that is associated with a parent port that was not used to boot any Removing a subport that is associated with a parent port that was not used to
VM is a no op from the OVS agent perspective. boot any VM is a no op from the OVS agent perspective.
When a subport associated with a parent port that was used to boot a VM is deleted, When a subport associated with a parent port that was used to boot a VM is
the OVS agent will take care of removing the firewall bridge if using iptables firewall deleted, the OVS agent will take care of removing the firewall bridge if using
and the port on br-int. the iptables firewall, and the port on br-int.
Implementation Trunk Bridge (Option C) Implementation Trunk Bridge (Option C)
@ -539,11 +543,11 @@ will process them as described in the next paragraph.
Subport creation Subport creation
++++++++++++++++ ++++++++++++++++
If a subport is added to a parent port but no VM was booted using that parent port If a subport is added to a parent port but no VM was booted using that parent
yet, the agent won't process the subport (because at this point there's no node port yet, the agent won't process the subport (because at this point there's
associated with the parent port). no node associated with the parent port).
When a subport is added to a parent port that is used by a VM the OVS agent will When a subport is added to a parent port that is used by a VM the OVS agent
create a new patch port: will create a new patch port:
:: ::
@ -555,7 +559,8 @@ spt-subport-id, the trunk bridge side of the patch is tagged using VLAN 100.
We assume that the segmentation ID of the subport is 100. We assume that the segmentation ID of the subport is 100.
spi-subport-id, the br-int side of the patch port is tagged with VLAN 5. We spi-subport-id, the br-int side of the patch port is tagged with VLAN 5. We
assume that the subport is on network2 that on this host uses VLAN 5. assume that the subport is on network2 that on this host uses VLAN 5.
The OVS agent will set the subport ID in the external-ids of spt-subport-id and spi-subport-id. The OVS agent will set the subport ID in the external-ids of spt-subport-id
and spi-subport-id.
*Inbound traffic from the VM point of view* *Inbound traffic from the VM point of view*
@ -577,34 +582,37 @@ will reach spi-subport-id, where it's tagged using VLAN 5.
Parent port deletion Parent port deletion
++++++++++++++++++++ ++++++++++++++++++++
Deleting a port that is an active parent in a trunk is forbidden. If the parent port has Deleting a port that is an active parent in a trunk is forbidden. If the parent
no trunk associated, it can be deleted. The OVS agent doesn't need to perform any action. port has no trunk associated, it can be deleted. The OVS agent doesn't need to
perform any action.
Trunk deletion Trunk deletion
++++++++++++++ ++++++++++++++
When Nova deletes a VM, it deletes the VM's corresponding Neutron ports only if they were When Nova deletes a VM, it deletes the VM's corresponding Neutron ports only if
created by Nova when booting the VM. In the vlan-aware-vm case the parent port is passed to Nova, so they were created by Nova when booting the VM. In the vlan-aware-vm case the
the port data will remain in the DB after the VM deletion. Nova will delete parent port is passed to Nova, so the port data will remain in the DB after the
the port on the trunk bridge where the VM is plugged. The L2 agent VM deletion. Nova will delete the port on the trunk bridge where the VM is
will detect that and delete the trunk bridge. It will notify the Neutron server that the parent plugged. The L2 agent will detect that and delete the trunk bridge. It will
port is down. notify the Neutron server that the parent port is down.
The deletion of a trunk that is used by a VM is not allowed. The deletion of a trunk that is used by a VM is not allowed.
The trunk can be deleted (leaving the parent port intact) when the parent port is not The trunk can be deleted (leaving the parent port intact) when the parent port
used by any VM. After the trunk is deleted, the parent port can also be deleted. is not used by any VM. After the trunk is deleted, the parent port can also be
deleted.
Subport deletion Subport deletion
++++++++++++++++ ++++++++++++++++
The OVS agent will delete the patch port pair corresponding to the subport deleted. The OVS agent will delete the patch port pair corresponding to the subport
deleted.
Agent resync Agent resync
~~~~~~~~~~~~ ~~~~~~~~~~~~
During resync the agent should check that all the trunk and subports are During resync the agent should check that all the trunk and subports are
still valid. It will delete the stale trunk and subports using the procedure specified still valid. It will delete the stale trunk and subports using the procedure
in the previous paragraphs according to the implementation. specified in the previous paragraphs according to the implementation.
Local IP Local IP

6
doc/source/contributor/internals/openvswitch_firewall.rst
View File

@ -239,9 +239,9 @@ SLAAC, NDP) for egress traffic, and allows ARP replies. Also identifies not
tracked connections which are processed later with information obtained from tracked connections which are processed later with information obtained from
conntrack. Notice the ``zone=NXM_NX_REG6[0..15]`` in ``actions`` when obtaining conntrack. Notice the ``zone=NXM_NX_REG6[0..15]`` in ``actions`` when obtaining
information from conntrack. It says every port has its own conntrack zone information from conntrack. It says every port has its own conntrack zone
defined by the value in ``register 6`` (OVSDB port tag identifying the network). defined by the value in ``register 6`` (OVSDB port tag identifying the
It's there to avoid accepting established traffic that belongs to a different network). It's there to avoid accepting established traffic that belongs to a
port with the same conntrack parameters. different port with the same conntrack parameters.
The very first rule in |table_71| is a rule removing conntrack information for The very first rule in |table_71| is a rule removing conntrack information for
a use-case where a Neutron logical port is placed directly to the hypervisor. a use-case where a Neutron logical port is placed directly to the hypervisor.

3
doc/source/contributor/internals/ovn/l3_ha_rescheduling.rst
View File

@ -109,7 +109,8 @@ Similar approach has been implemeneted for DHCP rescheduling `[4]`_.
The primary chassis gateway could be moved only to other, previously scheduled The primary chassis gateway could be moved only to other, previously scheduled
gateway. Rebalancing of chassis occurs only if number of scheduled primary gateway. Rebalancing of chassis occurs only if number of scheduled primary
chassis ports per each provider network hosted by given chassis is higher than chassis ports per each provider network hosted by given chassis is higher than
average number of hosted primary gateway ports per chassis per provider network. average number of hosted primary gateway ports per chassis per provider
network.
This dependency is determined by formula: This dependency is determined by formula:

49
doc/source/contributor/internals/ovn/ovn_network_logging.rst
View File

@ -10,7 +10,7 @@ manage affected security group rules. Thus, there is no need for an agent.
It is good to keep in mind that Openstack Security Groups (SG) and their rules It is good to keep in mind that Openstack Security Groups (SG) and their rules
(SGR) map 1:1 into OVN's Port Groups (PG) and Access Control Lists (ACL): (SGR) map 1:1 into OVN's Port Groups (PG) and Access Control Lists (ACL):
.. code-block:: none .. code-block::
Openstack Security Group <=> OVN Port Group Openstack Security Group <=> OVN Port Group
Openstack Security Group Rule <=> OVN ACL Openstack Security Group Rule <=> OVN ACL
@ -33,16 +33,16 @@ Meter Table
----------- -----------
Meters are how network logging events get throttled, so they do not negatively Meters are how network logging events get throttled, so they do not negatively
affect the control plane. Logged events are sent to the ovn-controller that runs affect the control plane. Logged events are sent to the ovn-controller that
locally on each compute node. Thus, the throttle keeps ovn-controller from getting runs locally on each compute node. Thus, the throttle keeps ovn-controller
overwhelmed. Note that the meters used for network logging do from getting overwhelmed. Note that the meters used for network logging do
not rate-limit the datapath; they only affect the logs themselves. not rate-limit the datapath; they only affect the logs themselves.
With the addition of 'fair meters', multiple ACLs can refer to the same With the addition of 'fair meters', multiple ACLs can refer to the same
meter without competing with each other for what logs get rate limited. meter without competing with each other for what logs get rate limited.
This attribute is a pre-requisite for this feature, as the design aspires This attribute is a pre-requisite for this feature, as the design aspires
to keep the complexity associated with the management of meters outside Openstack. to keep the complexity associated with the management of meters outside
The benefit of ACLs sharing a 'fair' meter is that a noisy neighbor (ACL) Openstack. The benefit of ACLs sharing a 'fair' meter is that a noisy
will not consume all the available capacity set for the meter. neighbor (ACL) will not consume all the available capacity set for the meter.
For more info on fair meters, see: For more info on fair meters, see:
https://github.com/ovn-org/ovn/commit/880dca99eaf73db7e783999c29386d03c82093bf https://github.com/ovn-org/ovn/commit/880dca99eaf73db7e783999c29386d03c82093bf
@ -78,7 +78,7 @@ Moreover, there are a few attributes in each ACL that makes it able to
provide the networking logging feature. Let's use the example below provide the networking logging feature. Let's use the example below
to point out the relevant fields: to point out the relevant fields:
.. code-block:: none .. code-block:: bash
$ openstack network log create --resource-type security_group \ $ openstack network log create --resource-type security_group \
--resource ${SG} --event ACCEPT logme -f value -c ID --resource ${SG} --event ACCEPT logme -f value -c ID
@ -112,23 +112,26 @@ to point out the relevant fields:
priority : 1002 priority : 1002
severity : info severity : info
The first command creates a networking-log for a given SG. The second shows an SGR from that SG. The first command creates a networking-log for a given SG. The second shows an
The third shell command is where we can see how the ACL with the meter information gets populated. SGR from that SG. The third shell command is where we can see how the ACL with
the meter information gets populated.
These are the attributes pertinent to network logging: These are the attributes pertinent to network logging:
* log: a boolean that dictates whether a log will be generated. Even if the NLE applies to the SGR * log: a boolean that dictates whether a log will be generated. Even if the
via its associated SG, this may be 'false' if the action is not a match. That would be the case NLE applies to the SGR via its associated SG, this may be 'false' if the
if the NLE specified "--event DROP", in this example. action is not a match. That would be the case if the NLE specified
"--event DROP", in this example.
* meter: this is the name of the fair meter. It is the same for all ACLs. * meter: this is the name of the fair meter. It is the same for all ACLs.
* name: This is a string composed of the prefix "neutron-" and the id of the NLE. It will be part of * name: This is a string composed of the prefix "neutron-" and the id of the
the generated logs. NLE. It will be part of the generated logs.
* severity: this is the log severity that will be used by the ovn-controller. It is currently hard * severity: this is the log severity that will be used by the ovn-controller.
coded in Neutron, but can be made configurable in future releases. It is currently hard coded in Neutron, but can be made configurable in
future releases.
If we poked the SGR with packets that match its criteria, the ovn-controller local to where the ACLs If we poked the SGR with packets that match its criteria, the ovn-controller
is enforced will log something that looks like this: local to where the ACLs is enforced will log something that looks like this:
.. code-block:: none .. code-block:: bash
2021-02-16T11:59:00.640Z|00045|acl_log(ovn_pinctrl0)|INFO| 2021-02-16T11:59:00.640Z|00045|acl_log(ovn_pinctrl0)|INFO|
name="neutron-2e456c7f-154e-40a8-bb10-f88ba51b90b5", name="neutron-2e456c7f-154e-40a8-bb10-f88ba51b90b5",
@ -137,8 +140,8 @@ is enforced will log something that looks like this:
nw_src=10.0.0.12,nw_dst=10.0.0.11,nw_tos=0,nw_ecn=0,nw_ttl=64,icmp_type=8, nw_src=10.0.0.12,nw_dst=10.0.0.11,nw_tos=0,nw_ecn=0,nw_ttl=64,icmp_type=8,
icmp_code=0 icmp_code=0
It is beyond the scope of this document to talk about what happens after the logs are generated It is beyond the scope of this document to talk about what happens after the
by ovn-controllers. The harvesting of files across compute nodes is something a project like logs are generated by ovn-controllers. The harvesting of files across compute
`Monasca`_ may be a good fit. nodes is something a project like `Monasca`_ may be a good fit.
.. _`Monasca`: https://wiki.openstack.org/wiki/Monasca .. _`Monasca`: https://wiki.openstack.org/wiki/Monasca

2
doc/source/contributor/internals/ovn/port_forwarding.rst
View File

@ -14,7 +14,7 @@ load_balancer table for all mappings for a given FIP+protocol. All PFs
for the same FIP+protocol are kept as Virtual IP (VIP) mappings inside a for the same FIP+protocol are kept as Virtual IP (VIP) mappings inside a
LB entry. See the diagram below for an example of how that looks like: LB entry. See the diagram below for an example of how that looks like:
.. code-block:: none .. code-block::
VIP:PORT = MEMBER1:MPORT1, MEMBER2:MPORT2 VIP:PORT = MEMBER1:MPORT1, MEMBER2:MPORT2

12
doc/source/contributor/internals/policy.rst
View File

@ -130,10 +130,10 @@ before returning it to the API client.
The neutron.policy API The neutron.policy API
---------------------- ----------------------
The ``neutron.policy`` module exposes a simple API whose main goal if to allow the The ``neutron.policy`` module exposes a simple API whose main goal if to allow
REST API controllers to implement the authorization workflow discussed in this the REST API controllers to implement the authorization workflow discussed inu
document. It is a bad practice to call the policy engine from within the plugin this document. It is a bad practice to call the policy engine from within the
layer, as this would make request authorization dependent on configured plugin layer, as this would make request authorization dependent on configured
plugins, and therefore make API behaviour dependent on the plugin itself, which plugins, and therefore make API behaviour dependent on the plugin itself, which
defies Neutron tenet of being backend agnostic. defies Neutron tenet of being backend agnostic.
@ -360,7 +360,7 @@ projects. Each neutron related project should register the following two entry
points ``oslo.policy.policies`` and ``neutron.policies`` in ``setup.cfg`` like points ``oslo.policy.policies`` and ``neutron.policies`` in ``setup.cfg`` like
below: below:
.. code-block:: none .. code-block:: ini
oslo.policy.policies = oslo.policy.policies =
neutron = neutron.conf.policies:list_rules neutron = neutron.conf.policies:list_rules
@ -381,7 +381,7 @@ projects, so the second entry point is required.
The recommended entry point name is a repository name: For example, The recommended entry point name is a repository name: For example,
'neutron-fwaas' for FWaaS and 'networking-sfc' for SFC: 'neutron-fwaas' for FWaaS and 'networking-sfc' for SFC:
.. code-block:: none .. code-block:: ini
oslo.policy.policies = oslo.policy.policies =
neutron-fwaas = neutron_fwaas.policies:list_rules neutron-fwaas = neutron_fwaas.policies:list_rules

64
doc/source/contributor/internals/quality_of_service.rst
View File

@ -82,9 +82,10 @@ QoS plugin implementation guide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The neutron.extensions.qos.QoSPluginBase class uses method proxies for methods The neutron.extensions.qos.QoSPluginBase class uses method proxies for methods
relating to QoS policy rules. Each of these such methods is generic in the sense relating to QoS policy rules. Each of these such methods is generic in the
that it is intended to handle any rule type. For example, QoSPluginBase has a sense that it is intended to handle any rule type. For example, QoSPluginBase
create_policy_rule method instead of both create_policy_dscp_marking_rule and has a create_policy_rule method instead of both
create_policy_dscp_marking_rule and
create_policy_bandwidth_limit_rule methods. The logic behind the proxies allows create_policy_bandwidth_limit_rule methods. The logic behind the proxies allows
a call to a plugin's create_policy_dscp_marking_rule to be handled by the a call to a plugin's create_policy_dscp_marking_rule to be handled by the
create_policy_rule method, which will receive a QosDscpMarkingRule object as an create_policy_rule method, which will receive a QosDscpMarkingRule object as an
@ -168,11 +169,13 @@ For QoS, the following neutron objects are implemented:
* QosPolicyDefault: defines a default QoS policy per project. * QosPolicyDefault: defines a default QoS policy per project.
* QosBandwidthLimitRule: defines the instance bandwidth limit rule type, * QosBandwidthLimitRule: defines the instance bandwidth limit rule type,
characterized by a max kbps and a max burst kbits. This rule has also a characterized by a max kbps and a max burst kbits. This rule has also a
direction parameter to set the traffic direction, from the instance's point of view. direction parameter to set the traffic direction, from the instance's point
* QosDscpMarkingRule: defines the DSCP rule type, characterized by an even integer of view.
between 0 and 56. These integers are the result of the bits in the DiffServ section * QosDscpMarkingRule: defines the DSCP rule type, characterized by an even
of the IP header, and only certain configurations are valid. As a result, the list integer between 0 and 56. These integers are the result of the bits in the
of valid DSCP rule types is: 0, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, DiffServ section of the IP header, and only certain configurations are valid.
As a result, the list of valid DSCP rule types is:
0, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32,
34, 36, 38, 40, 46, 48, and 56. 34, 36, 38, 40, 46, 48, and 56.
* QosMinimumBandwidthRule: defines the minimum assured bandwidth rule type, * QosMinimumBandwidthRule: defines the minimum assured bandwidth rule type,
characterized by a min_kbps parameter. This rule has also a direction characterized by a min_kbps parameter. This rule has also a direction
@ -223,8 +226,8 @@ instantiated (and to suggest just that, the base rule class is marked as ABC).
QoS objects rely on some primitive database API functions that are added in: QoS objects rely on some primitive database API functions that are added in:
* neutron_lib.db.api: those can be reused to fetch other models that do not have * neutron_lib.db.api: those can be reused to fetch other models that do not
corresponding versioned objects yet, if needed. have corresponding versioned objects yet, if needed.
* neutron.db.qos.api: contains database functions that are specific to QoS * neutron.db.qos.api: contains database functions that are specific to QoS
models. models.
@ -342,9 +345,9 @@ The DSCP markings are in fact configured on the port by means of
openflow rules. openflow rules.
.. note:: .. note::
As of Ussuri release, the QoS rules can be applied for direct ports with hardware As of Ussuri release, the QoS rules can be applied for direct ports with
offload capability (switchdev), this requires Open vSwitch version 2.11.0 or newer hardware offload capability (switchdev), this requires Open vSwitch
and Linux kernel based on kernel 5.4.0 or newer. version 2.11.0 or newer and Linux kernel based on kernel 5.4.0 or newer.
SR-IOV SR-IOV
++++++ ++++++
@ -380,10 +383,10 @@ For egress bandwidth limit rule:
The egress bandwidth limit is configured on the tap port by setting traffic The egress bandwidth limit is configured on the tap port by setting traffic
policing on tc ingress queueing discipline (qdisc). Details about ingress policing on tc ingress queueing discipline (qdisc). Details about ingress
qdisc can be found on `lartc how-to <http://lartc.org/howto/lartc.adv-qdisc.ingress.html>`__. qdisc can be found on `lartc how-to <http://lartc.org/howto/lartc.adv-qdisc.ingress.html>`__.
The reason why ingress qdisc is used to configure egress bandwidth limit is that The reason why ingress qdisc is used to configure egress bandwidth limit is
tc is working on traffic which is visible from "inside bridge" perspective. So that tc is working on traffic which is visible from "inside bridge"
traffic incoming to bridge via tap interface is in fact outgoing from Neutron's perspective. So traffic incoming to bridge via tap interface is in fact
port. outgoing from Neutron's port.
This implementation is the same as what Open vSwitch is doing when This implementation is the same as what Open vSwitch is doing when
ingress_policing_rate and ingress_policing_burst are set for port. ingress_policing_rate and ingress_policing_burst are set for port.
@ -394,12 +397,12 @@ For ingress bandwidth limit rule:
* delete_tbf_bw_limit * delete_tbf_bw_limit
The ingress bandwidth limit is configured on the tap port by setting a simple The ingress bandwidth limit is configured on the tap port by setting a simple
`tc-tbf <http://linux.die.net/man/8/tc-tbf>`_ queueing discipline (qdisc) on the `tc-tbf <http://linux.die.net/man/8/tc-tbf>`_ queueing discipline (qdisc) on
port. It requires a value of HZ parameter configured in kernel on the host. the port. It requires a value of HZ parameter configured in kernel on the host.
This value is necessary to calculate the minimal burst value which is set in This value is necessary to calculate the minimal burst value which is set in
tc. Details about how it is calculated can be found in tc. Details about how it is calculated can be found in
`here <http://unix.stackexchange.com/a/100797>`_. This solution is similar to Open `here <http://unix.stackexchange.com/a/100797>`_.
vSwitch implementation. This solution is similar to Open vSwitch implementation.
The Linux bridge DSCP marking implementation relies on the The Linux bridge DSCP marking implementation relies on the
linuxbridge_extension_api to request access to the IptablesManager class linuxbridge_extension_api to request access to the IptablesManager class
@ -408,17 +411,18 @@ and to manage chains in the ``mangle`` table in iptables.
QoS driver design QoS driver design
----------------- -----------------
QoS framework is flexible enough to support any third-party vendor. To integrate a QoS framework is flexible enough to support any third-party vendor. To
third party driver (that just wants to be aware of the QoS create/update/delete API integrate a third party driver (that just wants to be aware of the QoS
calls), one needs to implement 'neutron.services.qos.drivers.base', and register create/update/delete API calls), one needs to implement
'neutron.services.qos.drivers.base', and register
the driver during the core plugin or mechanism driver load, see the driver during the core plugin or mechanism driver load, see
neutron.services.qos.drivers.openvswitch.driver register method for an example. neutron.services.qos.drivers.openvswitch.driver register method for an example.
.. note:: .. note::
All the functionality MUST be implemented by the vendor, neutron's QoS framework All the functionality MUST be implemented by the vendor, neutron's QoS
will just act as an interface to bypass the received QoS API request and help with framework will just act as an interface to bypass the received QoS API
database persistence for the API operations. request and help with database persistence for the API operations.
.. note:: .. note::
L3 agent ``fip_qos`` extension does not have a driver implementation, L3 agent ``fip_qos`` extension does not have a driver implementation,
@ -441,7 +445,8 @@ On agent side (OVS):
On L3 agent side: On L3 agent side:
* For for floating IPs QoS support, add 'fip_qos' to extensions in [agent] section. * For for floating IPs QoS support, add 'fip_qos' to extensions in [agent]
section.
Testing strategy Testing strategy
@ -498,6 +503,7 @@ New functional tests for L3 agent floating IP rate limit:
API tests API tests
~~~~~~~~~ ~~~~~~~~~
API tests for basic CRUD operations for ports, networks, policies, and rules were added in: API tests for basic CRUD operations for ports, networks, policies, and rules
were added in:
* neutron-tempest-plugin.api.test_qos * neutron-tempest-plugin.api.test_qos

64
doc/source/contributor/internals/quota.rst
View File

@ -43,8 +43,8 @@ limits are currently not enforced on RPC interfaces listening on the AMQP
bus. bus.
Plugin and ML2 drivers are not supposed to enforce quotas for resources they Plugin and ML2 drivers are not supposed to enforce quotas for resources they
manage. However, the ``subnet_allocation`` [1]_ extension is an exception and will manage. However, the ``subnet_allocation`` [1]_ extension is an exception and
be discussed below. will be discussed below.
The quota management and enforcement mechanisms discussed here apply to every The quota management and enforcement mechanisms discussed here apply to every
resource which has been registered with the Quota engine, regardless of resource which has been registered with the Quota engine, regardless of
@ -69,12 +69,12 @@ configuration option ``quota_driver``.
The Quota API extension handles quota management, whereas the Quota Engine The Quota API extension handles quota management, whereas the Quota Engine
component handles quota enforcement. This API extension is loaded like any component handles quota enforcement. This API extension is loaded like any
other extension. For this reason plugins must explicitly support it by including other extension. For this reason plugins must explicitly support it by
"quotas" in the supported_extension_aliases attribute. including "quotas" in the supported_extension_aliases attribute.
In the Quota API simple CRUD operations are used for managing project quotas. In the Quota API simple CRUD operations are used for managing project quotas.
Please note that the current behaviour when deleting a project quota is to reset Please note that the current behaviour when deleting a project quota is to
quota limits for that project to configuration defaults. The API reset quota limits for that project to configuration defaults. The API
extension does not validate the project identifier with the identity service. extension does not validate the project identifier with the identity service.
In addition, the Quota Detail API extension complements the Quota API extension In addition, the Quota Detail API extension complements the Quota API extension
@ -107,7 +107,8 @@ delete operations are implemented by the usual index, show, update and
delete methods. These method simply call into the quota driver for either delete methods. These method simply call into the quota driver for either
fetching project quotas or updating them. fetching project quotas or updating them.
The ``_update_attributes`` method is called only once in the controller lifetime. The ``_update_attributes`` method is called only once in the controller
lifetime.
This method dynamically updates Neutron's resource attribute map [4]_ so that This method dynamically updates Neutron's resource attribute map [4]_ so that
an attribute is added for every resource managed by the quota engine. an attribute is added for every resource managed by the quota engine.
Request authorisation is performed in this controller, and only 'admin' users Request authorisation is performed in this controller, and only 'admin' users
@ -119,11 +120,11 @@ The driver operations dealing with quota management are:
* ``delete_tenant_quota``, which simply removes all entries from the 'quotas' * ``delete_tenant_quota``, which simply removes all entries from the 'quotas'
table for a given project identifier; table for a given project identifier;
* ``update_quota_limit``, which adds or updates an entry in the 'quotas' project * ``update_quota_limit``, which adds or updates an entry in the 'quotas'
for a given project identifier and a given resource name; project for a given project identifier and a given resource name;
* ``_get_quotas``, which fetches limits for a set of resource and a given project * ``_get_quotas``, which fetches limits for a set of resource and a given
identifier project identifier;
* ``_get_all_quotas``, which behaves like ``_get_quotas``, but for all projects. * ``_get_all_quotas``, which behaves like ``_get_quotas``, but for all projects
Resource Usage Info Resource Usage Info
@ -145,15 +146,16 @@ Neutron has two ways of tracking resource usage info:
``TrackedResource`` depends on one single database model (table) and the ``TrackedResource`` depends on one single database model (table) and the
resource count is done directly on this table only. resource count is done directly on this table only.
Another difference between ``CountableResource`` and ``TrackedResource`` is that the Another difference between ``CountableResource`` and ``TrackedResource`` is
former invokes a plugin method to count resources. ``CountableResource`` should be that the former invokes a plugin method to count resources.
``CountableResource`` should be
therefore employed for plugins which do not leverage the Neutron database. therefore employed for plugins which do not leverage the Neutron database.
The actual class that the Neutron quota engine will use is determined by the The actual class that the Neutron quota engine will use is determined by the
``track_quota_usage`` variable in the quota configuration section. If ``True``, ``track_quota_usage`` variable in the quota configuration section. If ``True``,
``TrackedResource`` instances will be created, otherwise the quota engine will ``TrackedResource`` instances will be created, otherwise the quota engine will
use ``CountableResource`` instances. use ``CountableResource`` instances.
Resource creation is performed by the ``create_resource_instance`` factory method Resource creation is performed by the ``create_resource_instance`` factory
in the ``neutron.quota.resource`` module. method in the ``neutron.quota.resource`` module.
DbQuotaDriver description DbQuotaDriver description
------------------------- -------------------------
@ -164,9 +166,9 @@ executing queries to explicitly count objects will increase with the number of
records in the table. On the other hand, using ``TrackedResource`` will fetch a records in the table. On the other hand, using ``TrackedResource`` will fetch a
single record, but has the drawback of having to execute an UPDATE statement single record, but has the drawback of having to execute an UPDATE statement
once the operation is completed. once the operation is completed.
Nevertheless, ``CountableResource`` instances do not simply perform a SELECT query Nevertheless, ``CountableResource`` instances do not simply perform a SELECT
on the relevant table for a resource, but invoke a plugin method, which might query on the relevant table for a resource, but invoke a plugin method, which
execute several statements and sometimes even interacts with the backend might execute several statements and sometimes even interacts with the backend
before returning. before returning.
Resource usage tracking also becomes important for operational correctness Resource usage tracking also becomes important for operational correctness
when coupled with the concept of resource reservation, discussed in another when coupled with the concept of resource reservation, discussed in another
@ -227,10 +229,10 @@ the chances of overcommiting resources over the quota limits are low. Neutron
does not enforce quota in such way that a quota limit violation could never does not enforce quota in such way that a quota limit violation could never
occur [5]_. occur [5]_.
Regardless of whether ``CountableResource`` or ``TrackedResource`` is used, the quota Regardless of whether ``CountableResource`` or ``TrackedResource`` is used,
engine always invokes its ``count()`` method to retrieve resource usage. the quota engine always invokes its ``count()`` method to retrieve resource
Therefore, from the perspective of the Quota engine there is absolutely no usage. Therefore, from the perspective of the Quota engine there is absolutely
difference between ``CountableResource`` and ``TrackedResource``. no difference between ``CountableResource`` and ``TrackedResource``.
Quota Enforcement in DbQuotaDriver Quota Enforcement in DbQuotaDriver
---------------------------------- ----------------------------------
@ -266,13 +268,13 @@ In order to ensure correct operations, a row-level lock is acquired in
the transaction which creates the reservation. The lock is acquired when the transaction which creates the reservation. The lock is acquired when
reading usage data. In case of write-set certification failures, reading usage data. In case of write-set certification failures,
which can occur in active/active clusters such as MySQL galera, the decorator which can occur in active/active clusters such as MySQL galera, the decorator
``neutron_lib.db.api.retry_db_errors`` will retry the transaction if a DBDeadLock ``neutron_lib.db.api.retry_db_errors`` will retry the transaction if a
exception is raised. DBDeadLock exception is raised.
While non-locking approaches are possible, it has been found out that, since While non-locking approaches are possible, it has been found out that, since
a non-locking algorithms increases the chances of collision, the cost of a non-locking algorithms increases the chances of collision, the cost of
handling a ``DBDeadlock`` is still lower than the cost of retrying the operation handling a ``DBDeadlock`` is still lower than the cost of retrying the
when a collision is detected. A study in this direction was conducted for operation when a collision is detected. A study in this direction was conducted
IP allocation operations, but the same principles apply here as well [7]_. for IP allocation operations, but the same principles apply here as well [7]_.
Nevertheless, moving away for DB-level locks is something that must happen Nevertheless, moving away for DB-level locks is something that must happen
for quota enforcement in the future. for quota enforcement in the future.
@ -366,9 +368,9 @@ Please be aware of the following limitations of the quota enforcement engine:
in resource usage. Since the event mechanism monitors the data model class, in resource usage. Since the event mechanism monitors the data model class,
it is paramount for a correct quota enforcement, that resources are always it is paramount for a correct quota enforcement, that resources are always
created and deleted using object relational mappings. For instance, deleting created and deleted using object relational mappings. For instance, deleting
a resource with a ``query.delete`` call will not trigger the event. SQLAlchemy a resource with a ``query.delete`` call will not trigger the event.
events should be considered as a temporary measure adopted as Neutron lacks SQLAlchemy events should be considered as a temporary measure adopted as
persistent API objects. Neutron lacks persistent API objects.
* As ``CountableResource`` instance do not track usage data, when making a * As ``CountableResource`` instance do not track usage data, when making a
reservation no write-intent lock is acquired. Therefore the quota engine reservation no write-intent lock is acquired. Therefore the quota engine
with ``CountableResource`` is not concurrency-safe. with ``CountableResource`` is not concurrency-safe.

4
doc/source/contributor/internals/rpc_api.rst
View File

@ -113,8 +113,8 @@ Example Change
As an example minor API change, let's assume we want to add a new parameter to As an example minor API change, let's assume we want to add a new parameter to
my_remote_method_2. First, we add the argument on the server side. To be my_remote_method_2. First, we add the argument on the server side. To be
backwards compatible, the new argument must have a default value set so that the backwards compatible, the new argument must have a default value set so that
interface will still work even if the argument is not supplied. Also, the the interface will still work even if the argument is not supplied. Also, the
interface's minor version number must be incremented. So, the new server side interface's minor version number must be incremented. So, the new server side
code would look like this: code would look like this:

30
doc/source/contributor/internals/rpc_callbacks.rst
View File

@ -101,7 +101,8 @@ Resource push notifications
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
Agents will subscribe to the neutron-vo-<resource_type>-<version> fanout queue Agents will subscribe to the neutron-vo-<resource_type>-<version> fanout queue
which carries updated objects for the version they know about. The versions which carries updated objects for the version they know about. The versions
they know about depend on the runtime Neutron versioned objects they started with. they know about depend on the runtime Neutron versioned objects they started
with.
When the server upgrades, it should be able to instantly calculate a census of When the server upgrades, it should be able to instantly calculate a census of
agent versions per object (we will define a mechanism for this in a later agent versions per object (we will define a mechanism for this in a later
@ -257,26 +258,27 @@ Unsubscribing from resources
To unsubscribe registered callbacks: To unsubscribe registered callbacks:
* unsubscribe(callback, resource_type): unsubscribe from specific resource type. * unsubscribe(callback, resource_type): unsubscribe from specific
resource type.
* unsubscribe_all(): unsubscribe from all resources. * unsubscribe_all(): unsubscribe from all resources.
Sending resource events Sending resource events
----------------------- -----------------------
On the server side, resource updates could come from anywhere, a service plugin, On the server side, resource updates could come from anywhere, a service
an extension, anything that updates, creates, or destroys the resources and that plugin, an extension, anything that updates, creates, or destroys the
is of any interest to subscribed agents. resources and that is of any interest to subscribed agents.
A callback is expected to receive a list of resources. When resources in the list A callback is expected to receive a list of resources. When resources in the
belong to the same resource type, a single push RPC message is sent; if the list list belong to the same resource type, a single push RPC message is sent;
contains objects of different resource types, resources of each type are grouped if the list contains objects of different resource types, resources of each
and sent separately, one push RPC message per type. On the receiver side, type are grouped and sent separately, one push RPC message per type. On the
resources in a list always belong to the same type. In other words, a server-side receiver side, resources in a list always belong to the same type. In other
push of a list of heterogeneous objects will result into N messages on bus and words, a server-side push of a list of heterogeneous objects will result into
N client-side callback invocations, where N is the number of unique resource N messages on bus and N client-side callback invocations, where N is the number
types in the given list, e.g. L(A, A, B, C, C, C) would be fragmented into of unique resource types in the given list, e.g. L(A, A, B, C, C, C) would be
L1(A, A), L2(B), L3(C, C, C), and each list pushed separately. fragmented into L1(A, A), L2(B), L3(C, C, C), and each list pushed separately.
Note: there is no guarantee in terms of order in which separate resource lists Note: there is no guarantee in terms of order in which separate resource lists
will be delivered to consumers. will be delivered to consumers.

35
doc/source/contributor/internals/security_group_api.rst
View File

@ -30,7 +30,8 @@ https://wiki.openstack.org/wiki/Neutron/SecurityGroups
API Extension API Extension
------------- -------------
The API extension is the 'front' end portion of the code, which handles defining a `REST-ful API`_, which is used by projects. The API extension is the 'front' end portion of the code, which handles
defining a `REST-ful API`_, which is used by projects.
.. _`REST-ful API`: https://opendev.org/openstack/neutron/src/neutron/extensions/securitygroup.py .. _`REST-ful API`: https://opendev.org/openstack/neutron/src/neutron/extensions/securitygroup.py
@ -39,35 +40,47 @@ The API extension is the 'front' end portion of the code, which handles defining
Database API Database API
------------ ------------
The Security Group API extension adds a number of `methods to the database layer`_ of Neutron The Security Group API extension adds a number of
`methods to the database layer`_ of Neutron
.. _`methods to the database layer`: https://opendev.org/openstack/neutron/src/neutron/db/securitygroups_db.py .. _`methods to the database layer`: https://opendev.org/openstack/neutron/src/neutron/db/securitygroups_db.py
Agent RPC Agent RPC
--------- ---------
This portion of the code handles processing requests from projects, after they have been stored in the database. It involves messaging all the L2 agents This portion of the code handles processing requests from projects, after they
running on the compute nodes, and modifying the IPTables rules on each hypervisor. have been stored in the database. It involves messaging all the L2 agents
running on the compute nodes, and modifying the IPTables rules on each
hypervisor.
* `Plugin RPC classes <https://opendev.org/openstack/neutron/src/neutron/db/securitygroups_rpc_base.py>`_ * `Plugin RPC classes <https://opendev.org/openstack/neutron/src/neutron/db/securitygroups_rpc_base.py>`_
* `SecurityGroupServerRpcMixin <https://opendev.org/openstack/neutron/src/neutron/db/securitygroups_rpc_base.py>`_ - defines the RPC API that the plugin uses to communicate with the agents running on the compute nodes * `SecurityGroupServerRpcMixin <https://opendev.org/openstack/neutron/src/neutron/db/securitygroups_rpc_base.py>`_ - defines the RPC API that the plugin uses to communicate with the agents running on the compute nodes
* SecurityGroupServerRpcMixin - Defines the API methods used to fetch data from the database, in order to return responses to agents via the RPC API * SecurityGroupServerRpcMixin - Defines the API methods used to fetch data
from the database, in order to return responses to agents via the RPC API
* `Agent RPC classes <https://opendev.org/openstack/neutron/src/neutron/api/rpc/handlers/securitygroups_rpc.py>`_ * `Agent RPC classes <https://opendev.org/openstack/neutron/src/neutron/api/rpc/handlers/securitygroups_rpc.py>`_
* The SecurityGroupServerRpcApi defines the API methods that can be called by agents, back to the plugin that runs on the Neutron controller * The SecurityGroupServerRpcApi defines the API methods that can be called
* The SecurityGroupAgentRpcCallbackMixin defines methods that a plugin uses to call back to an agent after performing an action called by an agent. by agents, back to the plugin that runs on the Neutron controller
* The SecurityGroupAgentRpcCallbackMixin defines methods that a plugin uses
to call back to an agent after performing an action called by an agent.
IPTables Driver IPTables Driver
--------------- ---------------
* ``prepare_port_filter`` takes a ``port`` argument, which is a ``dictionary`` object that contains information about the port - including the ``security_group_rules`` * ``prepare_port_filter`` takes a ``port`` argument, which is a ``dictionary``
object that contains information about the port - including the
``security_group_rules``
* ``prepare_port_filter`` appends the port to an internal dictionary, ``filtered_ports`` which is used to track the internal state. * ``prepare_port_filter`` appends the port to an internal dictionary,
``filtered_ports`` which is used to track the internal state.
* Each security group has a `chain <http://www.thegeekstuff.com/2011/01/iptables-fundamentals/>`_ in Iptables. * Each security group has a
`chain <http://www.thegeekstuff.com/2011/01/iptables-fundamentals/>`_
in Iptables.
* The ``IptablesFirewallDriver`` has a method to convert security group rules into iptables statements. * The ``IptablesFirewallDriver`` has a method to convert security group rules
into iptables statements.

4
doc/source/contributor/internals/services_and_agents.rst
View File

@ -32,8 +32,8 @@ services. Among those of special interest:
#. neutron-server that provides API endpoints and serves as a single point of #. neutron-server that provides API endpoints and serves as a single point of
access to the database. It usually runs on nodes called Controllers. access to the database. It usually runs on nodes called Controllers.
#. Layer2 agent that can utilize Open vSwitch, Linuxbridge or other vendor #. Layer2 agent that can utilize Open vSwitch, Linuxbridge or other vendor
specific technology to provide network segmentation and isolation for project specific technology to provide network segmentation and isolation for
networks. The L2 agent should run on every node where it is deemed project networks. The L2 agent should run on every node where it is deemed
responsible for wiring and securing virtual interfaces (usually both Compute responsible for wiring and securing virtual interfaces (usually both Compute
and Network nodes). and Network nodes).
#. Layer3 agent that runs on Network node and provides East-West and #. Layer3 agent that runs on Network node and provides East-West and

16
doc/source/contributor/internals/sriov_nic_agent.rst
View File

@ -26,9 +26,11 @@ SR-IOV Networking L2 Agent
SR-IOV (Single Root I/O Virtualization) is a specification that allows SR-IOV (Single Root I/O Virtualization) is a specification that allows
a PCIe device to appear to be multiple separate physical PCIe devices. a PCIe device to appear to be multiple separate physical PCIe devices.
SR-IOV works by introducing the idea of physical functions (PFs) and virtual functions (VFs). SR-IOV works by introducing the idea of physical functions (PFs) and virtual
functions (VFs).
Physical functions (PFs) are full-featured PCIe functions. Physical functions (PFs) are full-featured PCIe functions.
Virtual functions (VFs) are “lightweight” functions that lack configuration resources. Virtual functions (VFs) are “lightweight” functions that lack configuration
resources.
SR-IOV supports VLANs for L2 network isolation, other networking technologies SR-IOV supports VLANs for L2 network isolation, other networking technologies
such as VXLAN/GRE may be supported in the future. such as VXLAN/GRE may be supported in the future.
@ -37,11 +39,13 @@ SR-IOV NIC agent manages configuration of SR-IOV Virtual Functions that connect
VM instances running on the compute node to the public network. VM instances running on the compute node to the public network.
In most common deployments, there are compute and a network nodes. In most common deployments, there are compute and a network nodes.
Compute node can support VM connectivity via SR-IOV enabled NIC. SR-IOV NIC Agent manages Compute node can support VM connectivity via SR-IOV enabled NIC. SR-IOV NIC
Virtual Functions admin state. Quality of service is partially implemented with the bandwidth limit Agent manages Virtual Functions admin state. Quality of service is partially
and minimum bandwidth rules. In the future it will manage additional settings, such as additional implemented with the bandwidth limit and minimum bandwidth rules. In the future
it will manage additional settings, such as additional
quality of service rules, rate limit settings, spoofcheck and more. quality of service rules, rate limit settings, spoofcheck and more.
Network node will be usually deployed with either Open vSwitch or Linux Bridge to support network node functionality. Network node will be usually deployed with either Open vSwitch or Linux Bridge
to support network node functionality.
Further Reading Further Reading

3
doc/source/contributor/internals/upgrade.rst
View File

@ -35,7 +35,8 @@ Upgrade strategy
There are two general upgrade scenarios supported by Neutron: There are two general upgrade scenarios supported by Neutron:
#. All services are shut down, code upgraded, then all services are started again. #. All services are shut down, code upgraded, then all services are started
again.
#. Services are upgraded gradually, based on operator service windows. #. Services are upgraded gradually, based on operator service windows.
The latter is the preferred way to upgrade an OpenStack cloud, since it allows The latter is the preferred way to upgrade an OpenStack cloud, since it allows

24
doc/source/contributor/neutron_api.rst
View File

@ -32,7 +32,8 @@ plugin/driver repositories do it.
Neutron modules differ in their API stability a lot, and there is no part of it Neutron modules differ in their API stability a lot, and there is no part of it
that is explicitly marked to be consumed by other projects. that is explicitly marked to be consumed by other projects.
That said, there are modules that other projects should definitely avoid relying on. That said, there are modules that other projects should definitely avoid
relying on.
Breakages Breakages
@ -61,39 +62,44 @@ The changes are listed in reverse chronological order (newer at the top).
* change: Consume sslutils and wsgi modules from oslo.service. * change: Consume sslutils and wsgi modules from oslo.service.
- commit: Ibfdf07e665fcfcd093a0e31274e1a6116706aec2 - commit: Ibfdf07e665fcfcd093a0e31274e1a6116706aec2
- solution: switch using oslo_service.wsgi.Router; stop using neutron.wsgi.Router. - solution: switch using oslo_service.wsgi.Router; stop using
neutron.wsgi.Router.
- severity: Low (some out-of-tree plugins might be affected). - severity: Low (some out-of-tree plugins might be affected).
* change: oslo.service adopted. * change: oslo.service adopted.
- commit: 6e693fc91dd79cfbf181e3b015a1816d985ad02c - commit: 6e693fc91dd79cfbf181e3b015a1816d985ad02c
- solution: switch using oslo_service.* namespace; stop using ANY neutron.openstack.* contents. - solution: switch using oslo_service.* namespace; stop using ANY
neutron.openstack.* contents.
- severity: low (plugins must not rely on that subtree). - severity: low (plugins must not rely on that subtree).
* change: oslo.utils.fileutils adopted. * change: oslo.utils.fileutils adopted.
- commit: I933d02aa48260069149d16caed02b020296b943a - commit: I933d02aa48260069149d16caed02b020296b943a
- solution: switch using oslo_utils.fileutils module; stop using neutron.openstack.fileutils module. - solution: switch using oslo_utils.fileutils module; stop using
neutron.openstack.fileutils module.
- severity: low (plugins must not rely on that subtree). - severity: low (plugins must not rely on that subtree).
* change: Reuse caller's session in DB methods. * change: Reuse caller's session in DB methods.
- commit: 47dd65cf986d712e9c6ca5dcf4420dfc44900b66 - commit: 47dd65cf986d712e9c6ca5dcf4420dfc44900b66
- solution: Add context to args and reuse. - solution: Add context to args and reuse.
- severity: High (mostly undetected, because 3rd party CI run Tempest tests only). - severity: High (mostly undetected, as 3rd party CI run Tempest tests only).
* change: switches to oslo.log, removes neutron.openstack.common.log. * change: switches to oslo.log, removes neutron.openstack.common.log.
- commit: 22328baf1f60719fcaa5b0fbd91c0a3158d09c31 - commit: 22328baf1f60719fcaa5b0fbd91c0a3158d09c31
- solution: a) switch to oslo.log; b) copy log module into your tree and use it - solution: a) switch to oslo.log; b) copy log module into your tree and
(may not work due to conflicts between the module and oslo.log configuration options). use it (may not work due to conflicts between the module
and oslo.log configuration options).
- severity: High (most CI systems are affected). - severity: High (most CI systems are affected).
* change: Implements reorganize-unit-test-tree spec. * change: Implements reorganize-unit-test-tree spec.
- commit: 1105782e3914f601b8f4be64939816b1afe8fb54 - commit: 1105782e3914f601b8f4be64939816b1afe8fb54
- solution: Code affected need to update existing unit tests to reflect new locations. - solution: Code affected needs to update existing unit tests to reflect
- severity: High (mostly undetected, because 3rd party CI run Tempest tests only). new locations.
- severity: High (mostly undetected, as 3rd party CI run Tempest tests only).
* change: drop linux/ovs_lib compat layer. * change: drop linux/ovs_lib compat layer.

8
doc/source/contributor/ovn/tools.rst
View File

@ -74,10 +74,10 @@ be converted to/from the
`legacy networking-ovn <https://review.opendev.org/#/q/project:openstack/networking-ovn>`__ and `legacy networking-ovn <https://review.opendev.org/#/q/project:openstack/networking-ovn>`__ and
`Neutron <https://review.opendev.org/#/q/project:openstack/neutron>`__ repositories. `Neutron <https://review.opendev.org/#/q/project:openstack/neutron>`__ repositories.
The mapping of how the files are renamed is based on ``migrate_names.txt``, which is located The mapping of how the files are renamed is based on ``migrate_names.txt``,
in the same directory where ``migrate_names.py`` is installed. That behavior can be modified which is located in the same directory where ``migrate_names.py`` is installed.
via the ``--mapfile`` option. More information on how the map is parsed is provided in the header That behavior can be modified via the ``--mapfile`` option. More information on
section of that file. how the map is parsed is provided in the header section of that file.
.. code-block:: console .. code-block:: console

3
doc/source/contributor/ovn_vagrant/index.rst
View File

@ -6,7 +6,8 @@ Deploying an OVN Development Environment with vagrant
The vagrant directory contains a set of vagrant configurations which will The vagrant directory contains a set of vagrant configurations which will
help you deploy Neutron with the OVN driver for testing or development purposes. help you deploy Neutron with the OVN driver for testing or development
purposes.
We provide a sparse multinode architecture with clear separation between We provide a sparse multinode architecture with clear separation between
services. In the future we will include all-in-one and multi-gateway services. In the future we will include all-in-one and multi-gateway

111
doc/source/contributor/policies/blueprints.rst
View File

@ -99,13 +99,13 @@ The workflow for the life an RFE in Launchpad is as follows:
* Risky implementations that may require complex and/or pervasive * Risky implementations that may require complex and/or pervasive
changes to API and the logical model; changes to API and the logical model;
Low priority is to be chosen for everything else. RFEs without an associated Low priority is to be chosen for everything else. RFEs without an
blueprint are effectively equivalent to low priority items. Bear in mind that, associated blueprint are effectively equivalent to low priority items.
even though staffing should take priorities into account (i.e. by giving more Bear in mind that, even though staffing should take priorities into
resources to high priority items over low priority ones), the open source account (i.e. by giving more resources to high priority items over low
reality is that they can both proceed at their own pace and low priority items priority ones), the open source reality is that they can both proceed at
can indeed complete faster than high priority ones, even though they are their own pace and low priority items can indeed complete faster than high
given fewer resources. priority ones, even though they are given fewer resources.
* Drafter: who is going to submit and iterate on the spec proposal; he/she * Drafter: who is going to submit and iterate on the spec proposal; he/she
may be the RFE submitter. may be the RFE submitter.
@ -155,22 +155,23 @@ The workflow for the life an RFE in Launchpad is as follows:
will have to be deferred. will have to be deferred.
* In either case (a spec being required or not), once the discussion has * In either case (a spec being required or not), once the discussion has
happened and there is positive consensus on the RFE, the report is 'approved', happened and there is positive consensus on the RFE, the report is
and its tag will move from `rfe-triaged` to `rfe-approved`. 'approved', and its tag will move from `rfe-triaged` to `rfe-approved`.
* An RFE can be occasionally marked as 'rfe-postponed' if the team identifies * An RFE can be occasionally marked as 'rfe-postponed' if the team identifies
a dependency between the proposed RFE and other pending tasks that prevent a dependency between the proposed RFE and other pending tasks that prevent
the RFE from being worked on immediately. the RFE from being worked on immediately.
* Once an RFE is approved, it needs volunteers. Approved RFEs that do not have an * Once an RFE is approved, it needs volunteers. Approved RFEs that do not have
assignee but sound relatively simple or limited in scope (e.g. the addition of an assignee but sound relatively simple or limited in scope (e.g. the
a new API with no ramification in the plugin backends), should be promoted addition of a new API with no ramification in the plugin backends), should be
during team meetings or the ML so that volunteers can pick them up and get promoted during team meetings or the ML so that volunteers can pick them up
started with neutron development. The team will regularly scan `rfe-approved` and get started with neutron development. The team will regularly scan
or `rfe-postponed` RFEs to see what their latest status is and mark them `rfe-approved` or `rfe-postponed` RFEs to see what their latest status is and
incomplete if no assignees can be found, or they are no longer relevant. mark them incomplete if no assignees can be found, or they are no longer
relevant.
* As for setting the milestone (both for RFE bugs or blueprints), the current * As for setting the milestone (both for RFE bugs or blueprints), the current
milestone is always chosen, assuming that work will start as soon as the feature milestone is always chosen, assuming that work will start as soon as the
is approved. Work that fails to complete by the defined milestone will roll feature is approved. Work that fails to complete by the defined milestone
over automatically until it gets completed or abandoned. will roll over automatically until it gets completed or abandoned.
* If the code fails to merge, the bug report may be marked as incomplete, * If the code fails to merge, the bug report may be marked as incomplete,
unassigned and untargeted, and it will be garbage collected by unassigned and untargeted, and it will be garbage collected by
the Launchpad Janitor if no-one takes over in time. Renewed interest in the the Launchpad Janitor if no-one takes over in time. Renewed interest in the
@ -178,27 +179,32 @@ The workflow for the life an RFE in Launchpad is as follows:
In summary: In summary:
+------------+-----------------------------------------------------------------------------+ +------------+-----------------------------------------------------------+
| State | Meaning | | State | Meaning |
+============+=============================================================================+ +============+===========================================================+
|New | This is where all RFE's start, as filed by the community. | | New | This is where all RFE's start, as filed by the community |
+------------+-----------------------------------------------------------------------------+ +------------+-----------------------------------------------------------+
|Incomplete | Drivers/LTs - Move to this state to mean, "more needed before proceeding" | | Incomplete | Drivers/LTs - Move to this state to mean, |
+------------+-----------------------------------------------------------------------------+ | | "more information needed before proceeding" |
|Confirmed | Drivers/LTs - Move to this state to mean, "yeah, I see that you filed it" | +------------+-----------------------------------------------------------+
+------------+-----------------------------------------------------------------------------+ | Confirmed | Drivers/LTs - Move to this state to mean, |
|Triaged | Drivers/LTs - Move to this state to mean, "discussion is ongoing" | | | "yes, I see that you filed it" |
+------------+-----------------------------------------------------------------------------+ +------------+-----------------------------------------------------------+
|Won't Fix | Drivers/LTs - Move to this state to reject an RFE. | | Triaged | Drivers/LTs - Move to this state to mean, |
+------------+-----------------------------------------------------------------------------+ | | "discussion is ongoing" |
+------------+-----------------------------------------------------------+
| Won't Fix | Drivers/LTs - Move to this state to reject an RFE |
+------------+-----------------------------------------------------------+
Once the triaging (discussion is complete) and the RFE is approved, the tag goes from 'rfe' Once the triaging (discussion is complete) and the RFE is approved, the tag
to 'rfe-approved', and at this point the bug report goes through the usual state transition. goes from 'rfe' to 'rfe-approved', and at this point the bug report goes
Note, that the importance will be set to 'wishlist', to reflect the fact that the bug report through the usual state transition. Note, that the importance will be set to
is indeed not a bug, but a new feature or enhancement. This will also help have RFEs that are 'wishlist', to reflect the fact that the bug report is indeed not a bug, but
not followed up by a blueprint standout in the Launchpad `milestone dashboards <https://launchpad.net/neutron/+milestones>`_. a new feature or enhancement. This will also help have RFEs that are not
followed up by a blueprint standout in the Launchpad `milestone dashboards <https://launchpad.net/neutron/+milestones>`_.
The drivers team will be discussing the following bug reports during their IRC meeting: The drivers team will be discussing the following bug reports during their
IRC meeting:
* `New RFE's <https://bugs.launchpad.net/neutron/+bugs?field.status%3Alist=NEW&field.tag=rfe>`_ * `New RFE's <https://bugs.launchpad.net/neutron/+bugs?field.status%3Alist=NEW&field.tag=rfe>`_
* `Incomplete RFE's <https://bugs.launchpad.net/neutron/+bugs?field.status%3Alist=INCOMPLETE&field.tag=rfe>`_ * `Incomplete RFE's <https://bugs.launchpad.net/neutron/+bugs?field.status%3Alist=INCOMPLETE&field.tag=rfe>`_
@ -209,17 +215,18 @@ The drivers team will be discussing the following bug reports during their IRC m
RFE Submission Guidelines RFE Submission Guidelines
------------------------- -------------------------
Before we dive into the guidelines for writing a good RFE, it is worth mentioning Before we dive into the guidelines for writing a good RFE, it is worth
that depending on your level of engagement with the Neutron project and your role mentioning that depending on your level of engagement with the Neutron project
(user, developer, deployer, operator, etc.), you are more than welcome to have and your role (user, developer, deployer, operator, etc.), you are more than
a preliminary discussion of a potential RFE by reaching out to other people involved welcome to have a preliminary discussion of a potential RFE by reaching out to
in the project. This usually happens by posting mails on the relevant mailing other people involved in the project. This usually happens by posting mails on
lists (e.g. `openstack-discuss <http://lists.openstack.org>`_ - include [neutron] in the relevant mailing lists
(e.g. `openstack-discuss <http://lists.openstack.org>`_ - include [neutron] in
the subject) or on #openstack-neutron IRC channel on OFTC. If current ongoing the subject) or on #openstack-neutron IRC channel on OFTC. If current ongoing
code reviews are related to your feature, posting comments/questions on gerrit code reviews are related to your feature, posting comments/questions on gerrit
may also be a way to engage. Some amount of interaction with Neutron developers may also be a way to engage. Some amount of interaction with Neutron developers
will give you an idea of the plausibility and form of your RFE before you submit will give you an idea of the plausibility and form of your RFE before you
it. That said, this is not mandatory. submit it. That said, this is not mandatory.
When you submit a bug report on https://bugs.launchpad.net/neutron/+filebug, When you submit a bug report on https://bugs.launchpad.net/neutron/+filebug,
there are two fields that must be filled: 'summary' and 'further information'. there are two fields that must be filled: 'summary' and 'further information'.
@ -229,14 +236,14 @@ RFE at once, or that you are having a hard time defining what you are trying to
solve at all. solve at all.
The 'further information' section must be a description of what you would like The 'further information' section must be a description of what you would like
to see implemented in Neutron. The description should provide enough details for to see implemented in Neutron. The description should provide enough details
a knowledgeable developer to understand what is the existing problem in the for a knowledgeable developer to understand what is the existing problem in the
current platform that needs to be addressed, or what is the enhancement that current platform that needs to be addressed, or what is the enhancement that
would make the platform more capable, both for a functional and a non-functional would make the platform more capable, both for a functional and a
standpoint. To this aim it is important to describe 'why' you believe the RFE non-functional standpoint. To this aim it is important to describe 'why' you
should be accepted, and motivate the reason why without it Neutron is a poorer believe the RFE should be accepted, and motivate the reason why without it
platform. The description should be self contained, and no external references Neutron is a poorer platform. The description should be self contained, and no
should be necessary to further explain the RFE. external references should be necessary to further explain the RFE.
In other words, when you write an RFE you should ask yourself the following In other words, when you write an RFE you should ask yourself the following
questions: questions:

49
doc/source/contributor/policies/code-reviews.rst
View File

@ -3,16 +3,17 @@
Code Reviews Code Reviews
============ ============
Code reviews are a critical component of all OpenStack projects. Neutron accepts patches from many Code reviews are a critical component of all OpenStack projects. Neutron
diverse people with diverse backgrounds, employers, and experience levels. Code reviews provide a accepts patches from many diverse people with diverse backgrounds, employers,
way to enforce a level of consistency across the project, and also allow for the careful on boarding and experience levels. Code reviews provide a way to enforce a level of
consistency across the project, and also allow for the careful on boarding
of contributions from new contributors. of contributions from new contributors.
Neutron Code Review Practices Neutron Code Review Practices
----------------------------- -----------------------------
Neutron follows the `code review guidelines <https://wiki.openstack.org/wiki/ReviewChecklist>`_ as Neutron follows the `code review guidelines <https://wiki.openstack.org/wiki/ReviewChecklist>`_ as
set forth for all OpenStack projects. It is expected that all reviewers are following the guidelines set forth for all OpenStack projects. It is expected that all reviewers are
set forth on that page. following the guidelines set forth on that page.
In addition to that, the following rules are to follow: In addition to that, the following rules are to follow:
@ -88,8 +89,8 @@ In addition to that, the following rules are to follow:
scenario tests be added where it is appropriate. scenario tests be added where it is appropriate.
Scenario tests should cover not only the base level of new functionality, but Scenario tests should cover not only the base level of new functionality, but
also standard ways in which the functionality can be used. For example, if the also standard ways in which the functionality can be used. For example, if
feature adds a new kind of networking (like e.g. trunk ports) then tests the feature adds a new kind of networking (like e.g. trunk ports) then tests
should make sure that instances can use IPs provided by that networking, should make sure that instances can use IPs provided by that networking,
can be migrated, etc. can be migrated, etc.
@ -99,33 +100,37 @@ In addition to that, the following rules are to follow:
* It is usually enough for any "mechanical" changes, like e.g. translation * It is usually enough for any "mechanical" changes, like e.g. translation
imports or imports of updated CI templates, to have only one +2 Code-Review imports or imports of updated CI templates, to have only one +2 Code-Review
vote to be approved. If there is any uncertainty about a specific patch, it is vote to be approved. If there is any uncertainty about a specific patch, it
better to wait for review from another core reviewer before approving the patch. is better to wait for review from another core reviewer before approving the
patch.
.. _spec-review-practices: .. _spec-review-practices:
Neutron Spec Review Practices Neutron Spec Review Practices
----------------------------- -----------------------------
In addition to code reviews, Neutron also maintains a BP specification git repository. Detailed In addition to code reviews, Neutron also maintains a BP specification git
instructions for the use of this repository are provided `here <https://wiki.openstack.org/wiki/Blueprints>`_. repository. Detailed instructions for the use of this repository are provided
It is expected that Neutron core team members are actively reviewing specifications which are pushed out `here <https://wiki.openstack.org/wiki/Blueprints>`_.
for review to the specification repository. In addition, there is a neutron-drivers team, composed of a It is expected that Neutron core team members are actively reviewing
specifications which are pushed out for review to the specification repository.
In addition, there is a neutron-drivers team, composed of a
handful of Neutron core reviewers, who can approve and merge Neutron specs. handful of Neutron core reviewers, who can approve and merge Neutron specs.
Some guidelines around this process are provided below: Some guidelines around this process are provided below:
* Once a specification has been pushed, it is expected that it will not be approved for at least 3 days * Once a specification has been pushed, it is expected that it will not be
after a first Neutron core reviewer has reviewed it. This allows for additional cores to review the approved for at least 3 days after a first Neutron core reviewer has reviewed
specification. it. This allows for additional cores to review the specification.
* For blueprints which the core team deems of High or Critical importance, core reviewers may be assigned * For blueprints which the core team deems of High or Critical importance,
based on their subject matter expertise. core reviewers may be assigned based on their subject matter expertise.
* Specification priority will be set by the PTL with review by the core team once the specification is * Specification priority will be set by the PTL with review by the core team
approved. once the specification is approved.
Tracking Review Statistics Tracking Review Statistics
-------------------------- --------------------------
Stackalytics provides some nice interfaces to track review statistics. The links are provided below. These Stackalytics provides some nice interfaces to track review statistics. The
statistics are used to track not only Neutron core reviewer statistics, but also to track review statistics links are provided below. These statistics are used to track not only Neutron
core reviewer statistics, but also to track review statistics
for potential future core members. for potential future core members.
* `30 day review stats <https://www.stackalytics.io/report/contribution?module=neutron-group&project_type=openstack&days=30>`_ * `30 day review stats <https://www.stackalytics.io/report/contribution?module=neutron-group&project_type=openstack&days=30>`_

17
doc/source/contributor/policies/contributor-onboarding.rst
View File

@ -6,14 +6,17 @@ For new contributors, the following are useful onboarding information.
Contributing to Neutron Contributing to Neutron
----------------------- -----------------------
Work within Neutron is discussed on the openstack-discuss mailing list, as well as in the Work within Neutron is discussed on the openstack-discuss mailing list, as
#openstack-neutron IRC channel. While these are great channels for engaging Neutron, well as in the #openstack-neutron IRC channel. While these are great channels
the bulk of discussion of patches and code happens in gerrit itself. for engaging Neutron, the bulk of discussion of patches and code happens in
gerrit itself.
With regards to gerrit, code reviews are a great way to learn about the project. There With regards to gerrit, code reviews are a great way to learn about the
is also a list of `low or wishlist <https://bugs.launchpad.net/neutron/+bugs?field.searchtext=&orderby=-importance&field.status%3Alist=NEW&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=FIXCOMMITTED&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.importance%3Alist=LOW&field.importance%3Alist=WISHLIST&assignee_option=any&field.assignee=&field.bug_reporter=&field.bug_commenter=&field.subscriber=&field.structural_subscriber=&field.tag=&field.tags_combinator=ANY&field.has_cve.used=&field.omit_dupes.used=&field.omit_dupes=on&field.affects_me.used=&field.has_patch.used=&field.has_branches.used=&field.has_branches=on&field.has_no_branches.used=&field.has_no_branches=on&field.has_blueprints.used=&field.has_blueprints=on&field.has_no_blueprints.used=&field.has_no_blueprints=on&search=Search>`_ priority bugs which are ideal for a new contributor to take project. There is also a list of
on. If you haven't done so you should setup a Neutron development environment so you `low or wishlist <https://bugs.launchpad.net/neutron/+bugs?field.searchtext=&orderby=-importance&field.status%3Alist=NEW&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=FIXCOMMITTED&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.importance%3Alist=LOW&field.importance%3Alist=WISHLIST&assignee_option=any&field.assignee=&field.bug_reporter=&field.bug_commenter=&field.subscriber=&field.structural_subscriber=&field.tag=&field.tags_combinator=ANY&field.has_cve.used=&field.omit_dupes.used=&field.omit_dupes=on&field.affects_me.used=&field.has_patch.used=&field.has_branches.used=&field.has_branches=on&field.has_no_branches.used=&field.has_no_branches=on&field.has_blueprints.used=&field.has_blueprints=on&field.has_no_blueprints.used=&field.has_no_blueprints=on&search=Search>`_
can actually run the code. Devstack is the usual convenient environment to setup such priority bugs which are ideal for a new contributor to take on. If you haven't
done so you should setup a Neutron development environment so you can actually
run the code. Devstack is the usual convenient environment to setup such
an environment. See `devstack.org <http://devstack.org/>`_ or `NeutronDevstack <https://wiki.openstack.org/wiki/NeutronDevstack#Basic_Setup>`_ an environment. See `devstack.org <http://devstack.org/>`_ or `NeutronDevstack <https://wiki.openstack.org/wiki/NeutronDevstack#Basic_Setup>`_
for more information on using Neutron with devstack. for more information on using Neutron with devstack.

86
doc/source/contributor/policies/gate-failure-triage.rst
View File

@ -2,8 +2,8 @@
Gate Failure Triage Gate Failure Triage
=================== ===================
This page provides guidelines for spotting and assessing neutron gate failures. Some hints for triaging This page provides guidelines for spotting and assessing neutron gate failures.
failures are also provided. Some hints for triaging failures are also provided.
Spotting Gate Failures Spotting Gate Failures
---------------------- ----------------------
@ -15,34 +15,44 @@ This can be achieved using several tools:
For checking gate failures with opensearch please see `documentation <https://docs.openstack.org/project-team-guide/testing.html#checking-status-of-other-job-results>`_. For checking gate failures with opensearch please see `documentation <https://docs.openstack.org/project-team-guide/testing.html#checking-status-of-other-job-results>`_.
The following query will return failures for a specific job: The following query will return failures for a specific job:
> build_status:FAILURE AND message:Finished AND build_name:"check-tempest-dsvm-neutron" AND build_queue:"gate" > build_status:FAILURE AND message:Finished AND
build_name:"check-tempest-dsvm-neutron" AND build_queue:"gate"
And divided by the total number of jobs executed: And divided by the total number of jobs executed:
> message:Finished AND build_name:"check-tempest-dsvm-neutron" AND build_queue:"gate" > message:Finished AND build_name:"check-tempest-dsvm-neutron" AND
build_queue:"gate"
It will return the failure rate in the selected period for a given job. It is important to remark that It will return the failure rate in the selected period for a given job. It is
failures in the check queue might be misleading as the problem causing the failure is most of the time in important to remark that failures in the check queue might be misleading as
the patch being checked. Therefore it is always advisable to work on failures occurred in the gate queue. the problem causing the failure is most of the time in the patch being checked.
However, these failures are a precious resource for assessing frequency and determining root cause of Therefore it is always advisable to work on failures occurred in the gate
failures which manifest in the gate queue. queue. However, these failures are a precious resource for assessing frequency
and determining root cause of failures which manifest in the gate queue.
The step above will provide a quick outlook of where things stand. When the failure rate raises above 10% for The step above will provide a quick outlook of where things stand. When the
a job in 24 hours, it's time to be on alert. 25% is amber alert. 33% is red alert. Anything above 50% means failure rate raises above 10% for a job in 24 hours, it's time to be on alert.
that probably somebody from the infra team has already a contract out on you. Whether you are relaxed, in 25% is amber alert. 33% is red alert. Anything above 50% means that probably
alert mode, or freaking out because you see a red dot on your chest, it is always a good idea to check on somebody from the infra team has already a contract out on you. Whether you
daily bases the elastic-recheck pages. are relaxed, in alert mode, or freaking out because you see a red dot on your
chest, it is always a good idea to check on daily bases the elastic-recheck
pages.
Under the `gate pipeline <http://status.openstack.org/elastic-recheck/gate.html>`_ tab, you can see gate Under the
failure rates for already known bugs. The bugs in this page are ordered by decreasing failure rates (for the `gate pipeline <http://status.openstack.org/elastic-recheck/gate.html>`_
past 24 hours). If one of the bugs affecting Neutron is among those on top of that list, you should check tab, you can see gate failure rates for already known bugs. The bugs in this
that the corresponding bug is already assigned and somebody is working on it. If not, and there is not a good page are ordered by decreasing failure rates (for the past 24 hours). If one
reason for that, it should be ensured somebody gets a crack at it as soon as possible. The other part of the of the bugs affecting Neutron is among those on top of that list, you should
check that the corresponding bug is already assigned and somebody is working
on it. If not, and there is not a good reason for that, it should be ensured
somebody gets a crack at it as soon as possible. The other part of the
story is to check for `uncategorized <http://status.openstack.org/elastic-recheck/data/uncategorized.html>`_ story is to check for `uncategorized <http://status.openstack.org/elastic-recheck/data/uncategorized.html>`_
failures. This is where failures for new (unknown) gate breaking bugs end up; on the other hand also infra failures. This is where failures for new (unknown) gate breaking bugs end up;
error causing job failures end up here. It should be duty of the diligent Neutron developer to ensure the on the other hand also infra error causing job failures end up here. It should
classification rate for neutron jobs is as close as possible to 100%. To this aim, the diligent Neutron be duty of the diligent Neutron developer to ensure the classification rate
developer should adopt the procedure outlined in the following sections. for neutron jobs is as close as possible to 100%. To this aim, the diligent
Neutron developer should adopt the procedure outlined in the following
sections.
.. _troubleshooting-tempest-jobs: .. _troubleshooting-tempest-jobs:
@ -50,15 +60,19 @@ Troubleshooting Tempest jobs
---------------------------- ----------------------------
1. Open logs for failed jobs and look for logs/testr_results.html.gz. 1. Open logs for failed jobs and look for logs/testr_results.html.gz.
2. If that file is missing, check console.html and see where the job failed. 2. If that file is missing, check console.html and see where the job failed.
1. If there is a failure in devstack-gate-cleanup-host.txt it's likely to be an infra issue. 1. If there is a failure in devstack-gate-cleanup-host.txt it's likely to
2. If the failure is in devstacklog.txt it could a devstack, neutron, or infra issue. be an infra issue.
3. However, most of the time the failure is in one of the tempest tests. Take note of the error message and go to 2. If the failure is in devstacklog.txt it could a devstack, neutron, or
opensearch. infra issue.
4. On opensearch, search for occurrences of this error message, and try to identify the root cause for the failure 3. However, most of the time the failure is in one of the tempest tests. Take
(see below). note of the error message and go to opensearch.
5. File a bug for this failure, and push an :ref:`Elastic Recheck Query <elastic-recheck-query>` for it. 4. On opensearch, search for occurrences of this error message, and try to
6. If you are confident with the area of this bug, and you have time, assign it to yourself; otherwise look for an identify the root cause for the failure (see below).
assignee or talk to the Neutron's bug czar to find an assignee. 5. File a bug for this failure, and push an
:ref:`Elastic Recheck Query <elastic-recheck-query>` for it.
6. If you are confident with the area of this bug, and you have time, assign
it to yourself; otherwise look for an assignee or talk to the Neutron's
bug deputy to find an assignee.
Troubleshooting functional/fullstack job Troubleshooting functional/fullstack job
---------------------------------------- ----------------------------------------
@ -110,10 +124,10 @@ The difference is that in the logs of the Grenade job, there is always
of the Devstack's stack.sh script. of the Devstack's stack.sh script.
In the "logs/grenade.sh_log.txt" file there is a full log of the grenade.sh run In the "logs/grenade.sh_log.txt" file there is a full log of the grenade.sh run
and you should always start checking failures from that file. and you should always start checking failures from that file.
Logs of the Neutron services for "old" and "new" versions are in the same files, Logs of the Neutron services for "old" and "new" versions are in the same
like, for example, "logs/screen-q-svc.txt" for neutron-server logs. You will files, like, for example, "logs/screen-q-svc.txt" for neutron-server logs.
find in that log when the service was restarted - that is the moment when it You will find in that log when the service was restarted - that is the moment
was upgraded by Grenade and it is now running the new version. when it was upgraded by Grenade and it is now running the new version.
Advanced Troubleshooting of Gate Jobs Advanced Troubleshooting of Gate Jobs
------------------------------------- -------------------------------------

26
doc/source/contributor/policies/neutron-teams.rst
View File

@ -8,8 +8,8 @@ Neutron Core Reviewers
====================== ======================
The `Neutron Core Reviewer Team <https://review.opendev.org/#/admin/groups/38,members>`_ The `Neutron Core Reviewer Team <https://review.opendev.org/#/admin/groups/38,members>`_
is responsible for many things related to Neutron. A lot of these things include mundane is responsible for many things related to Neutron. A lot of these things
tasks such as the following: include mundane tasks such as the following:
* Ensuring the bug count is low * Ensuring the bug count is low
* Curating the gate and triaging failures * Curating the gate and triaging failures
@ -120,8 +120,9 @@ Some notes on the above:
Sub-project Lieutenants Sub-project Lieutenants
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Neutron also consists of several plugins, drivers, and agents that are developed Neutron also consists of several plugins, drivers, and agents that are
effectively as sub-projects within Neutron in their own git repositories. developed effectively as sub-projects within Neutron in their own git
repositories.
Lieutenants are also named for these sub-projects to identify a clear point of Lieutenants are also named for these sub-projects to identify a clear point of
contact and leader for that area. The Lieutenant is also responsible for contact and leader for that area. The Lieutenant is also responsible for
updating the core review team for the sub-project's repositories. updating the core review team for the sub-project's repositories.
@ -221,10 +222,10 @@ have +2 rights to the following git repositories:
* `openstack/neutron-specs <https://opendev.org/openstack/neutron-specs/>`_ * `openstack/neutron-specs <https://opendev.org/openstack/neutron-specs/>`_
The Neutron specs core reviewer team is responsible for reviewing specs targeted to The Neutron specs core reviewer team is responsible for reviewing specs
all Neutron git repositories (Neutron + Advanced Services). It is worth noting that targeted to all Neutron git repositories (Neutron + Advanced Services).
specs reviewers have the following attributes which are potentially different than It is worth noting that specs reviewers have the following attributes which
code reviewers: are potentially different than code reviewers:
* Broad understanding of cloud and networking technologies * Broad understanding of cloud and networking technologies
* Broad understanding of core OpenStack projects and technologies * Broad understanding of core OpenStack projects and technologies
@ -240,11 +241,12 @@ Drivers Team
------------ ------------
The `drivers team <https://review.opendev.org/#/admin/groups/464,members>`_ is The `drivers team <https://review.opendev.org/#/admin/groups/464,members>`_ is
the group of people who have full rights to the specs repo. This team, which matches the group of people who have full rights to the specs repo. This team, which
matches
`Launchpad Neutron Drivers team <https://launchpad.net/~neutron-drivers>`_, is `Launchpad Neutron Drivers team <https://launchpad.net/~neutron-drivers>`_, is
instituted to ensure a consistent architectural vision for the Neutron project, and instituted to ensure a consistent architectural vision for the Neutron
to continue to disaggregate and share the responsibilities of the Neutron PTL. project, and to continue to disaggregate and share the responsibilities of
The team is in charge of reviewing and commenting on the Neutron PTL. The team is in charge of reviewing and commenting on
:ref:`RFEs <request-for-feature-enhancement>`, :ref:`RFEs <request-for-feature-enhancement>`,
and working with specification contributors to provide guidance on the process and working with specification contributors to provide guidance on the process
that govern contributions to the Neutron project as a whole. The team that govern contributions to the Neutron project as a whole. The team

6
doc/source/contributor/policies/release-checklist.rst
View File

@ -142,9 +142,9 @@ a patch which introduces for example:
#. requirement change, #. requirement change,
#. API visible change, #. API visible change,
The above list doesn't cover all possible cases. Those are only examples of fixes The above list doesn't cover all possible cases. Those are only examples of
which require bump of minor version number but there can be also other types of fixes which require bump of minor version number but there can be also other
changes requiring the same. types of changes requiring the same.
Changes that require the minor version number to be bumped should always have a Changes that require the minor version number to be bumped should always have a
release note added. release note added.

10
doc/source/contributor/policies/thirdparty-ci.rst
View File

@ -81,11 +81,11 @@ systems.
A third party system can have it's voting rights removed as well. If the A third party system can have it's voting rights removed as well. If the
system becomes unstable (stops running, voting, or start providing inaccurate system becomes unstable (stops running, voting, or start providing inaccurate
results), the Neutron PTL or any core reviewer will make an attempt to contact results), the Neutron PTL or any core reviewer will make an attempt to contact
the owner and copy the openstack-discuss mailing list. If no response is received the owner and copy the openstack-discuss mailing list. If no response is
within 2 days, the Neutron PTL will remove voting rights for the third party received within 2 days, the Neutron PTL will remove voting rights for the
CI system. If a response is received, the owner will work to correct the third party CI system. If a response is received, the owner will work to
issue. If the issue cannot be addressed in a reasonable amount of time, the correct the issue. If the issue cannot be addressed in a reasonable amount of
voting rights will be temporarily removed. time, the voting rights will be temporarily removed.
Log & Test Results Filesystem Layout Log & Test Results Filesystem Layout
------------------------------------ ------------------------------------

14
doc/source/contributor/stadium/governance.rst
View File

@ -87,10 +87,10 @@ mature OpenStack projects:
using OpenStack CI (upstream) resources so that `Grafana <https://grafana.opendev.org/d/f913631585/neutron-failure-rate>`_ using OpenStack CI (upstream) resources so that `Grafana <https://grafana.opendev.org/d/f913631585/neutron-failure-rate>`_
support is available. Access to CI resources and historical data by the support is available. Access to CI resources and historical data by the
team is key to ensuring stability and robustness of a project. team is key to ensuring stability and robustness of a project.
In particular, it is of paramount importance to ensure that DB models/migrations In particular, it is of paramount importance to ensure that DB
are tested functionally to prevent data inconsistency issues or unexpected models/migrations are tested functionally to prevent data inconsistency
DB logic errors due to schema/models mismatch. For more details, please issues or unexpected DB logic errors due to schema/models mismatch.
look at the following resources: For more details, please look at the following resources:
* https://review.opendev.org/#/c/346091/ * https://review.opendev.org/#/c/346091/
* https://review.opendev.org/#/c/346272/ * https://review.opendev.org/#/c/346272/
@ -152,9 +152,9 @@ the PTL and Neutron team do release planning, and have the most time available
to discuss governance issues. to discuss governance issues.
Projects part of the Neutron Stadium have typically the first milestone to get Projects part of the Neutron Stadium have typically the first milestone to get
their house in order, during which time reassessment happens; if removed, because their house in order, during which time reassessment happens; if removed,
of substantial lack of meeting the criteria, a project cannot reapply within because of substantial lack of meeting the criteria, a project cannot reapply
the same release cycle it has been evicted. within the same release cycle it has been evicted.
The process for proposing a repo into openstack/ and under the Neutron The process for proposing a repo into openstack/ and under the Neutron
governance is to propose a patch to the openstack/governance repository. governance is to propose a patch to the openstack/governance repository.

10
doc/source/contributor/stadium/index.rst
View File

@ -19,14 +19,14 @@ Neutron Stadium
================ ================
This section contains information on policies and procedures for the so called This section contains information on policies and procedures for the so called
Neutron Stadium. The Neutron Stadium is the list of projects that show up in the Neutron Stadium. The Neutron Stadium is the list of projects that show up in
OpenStack `Governance Document <https://governance.openstack.org/tc/reference/projects/neutron.html>`_. the OpenStack `Governance Document <https://governance.openstack.org/tc/reference/projects/neutron.html>`_.
The list includes projects that the Neutron PTL and core team are directly The list includes projects that the Neutron PTL and core team are directly
involved in, and manage on a day to day basis. To do so, the PTL and team involved in, and manage on a day to day basis. To do so, the PTL and team
ensure that common practices and guidelines are followed throughout the Stadium, ensure that common practices and guidelines are followed throughout the
for all aspects that pertain software development, from inception, to coding, Stadium, for all aspects that pertain software development, from inception,
testing, documentation and more. to coding, testing, documentation and more.
The Stadium is not to be intended as a VIP club for OpenStack networking The Stadium is not to be intended as a VIP club for OpenStack networking
projects, or an upper tier within OpenStack. It is simply the list of projects projects, or an upper tier within OpenStack. It is simply the list of projects

13
doc/source/contributor/testing/ci_scenario_jobs.rst
View File

@ -28,9 +28,9 @@ Neutron Jobs Running in Zuul CI
Tempest jobs running in Neutron CI Tempest jobs running in Neutron CI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In upstream Neutron CI there are various tempest and neutron-tempest-plugin jobs In upstream Neutron CI there are various tempest and neutron-tempest-plugin
running. jobs running. Each of those jobs runs on slightly different configuration of
Each of those jobs runs on slightly different configuration of Neutron services. Neutron services.
Below is a summary of those jobs. Below is a summary of those jobs.
:: ::
@ -91,7 +91,8 @@ Grenade jobs running in Neutron CI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In upstream Neutron CI there are various Grenade jobs running. In upstream Neutron CI there are various Grenade jobs running.
Each of those jobs runs on slightly different configuration of Neutron services. Each of those jobs runs on slightly different configuration of Neutron
services.
Below is summary of those jobs. Below is summary of those jobs.
:: ::
@ -109,8 +110,8 @@ Tempest jobs running in Neutron experimental CI
In upstream Neutron CI there is also queue called ``experimental``. It includes In upstream Neutron CI there is also queue called ``experimental``. It includes
jobs which are not needed to be run on every patch and/or jobs which isn't jobs which are not needed to be run on every patch and/or jobs which isn't
stable enough to be run always. stable enough to be run always.
Those jobs can be run by making comment ``check experimental`` in the comment to Those jobs can be run by making comment ``check experimental`` in the comment
the patch in Gerrit. to the patch in Gerrit.
Currently we have in that queue jobs like listed below. Currently we have in that queue jobs like listed below.
:: ::

49
doc/source/contributor/testing/coverage.rst
View File

@ -54,43 +54,44 @@ such as what L2 agent to use or what type of routers to create.
* A name - That person has committed to work on an item * A name - That person has committed to work on an item
* Implicit - The code is executed, yet no assertions are made * Implicit - The code is executed, yet no assertions are made
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| Area | Unit | Functional | API | Fullstack | Scenario | Gate | | Area | Unit | Functional | API | Fullstack | Scenario | Gate |
+========================+============+============+============+============+============+============+ +====================+======+============+=====+===========+==========+======+
| DVR | V | L3-V OVS-X | V | X | X | V | | DVR | V | L3-V OVS-X | V | X | X | V |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| L3 HA | V | V | X | 286087 | X | X | | L3 HA | V | V | X | 286087* | X | X |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| L2pop | V | X | | Implicit | | | | L2pop | V | X | | Implicit | | |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| DHCP HA | V | | | amuller | | | | DHCP HA | V | | | | | |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| OVS ARP responder | V | X* | | Implicit | | | | OVS ARP responder | V | X | | Implicit | | |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| OVS agent | V | V | | V | | V | | OVS agent | V | V | | V | | V |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| OVN | V | V | | | | V |
+--------------------+------+------------+-----+-----------+----------+------+
| Linux Bridge agent | V | X | | V | | V | | Linux Bridge agent | V | X | | V | | V |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| Metering | V | X | V | X | | | | Metering | V | X | V | X | | |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| DHCP agent | V | V | | amuller | | V | | DHCP agent | V | V | | | | V |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| rpc_workers | | | | | | X | | rpc_workers | | | | | | X |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| Reference ipam driver | V | | | | | X | | Ref IPAM driver | V | | | | | X |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| MTU advertisement | V | | | X | | | | MTU advertisement | V | | | X | | |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| VLAN transparency | V | | X | X | | | | VLAN transparency | V | | X | X | | |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
| Prefix delegation | V | X | | X | | | | Prefix delegation | V | X* | | X | | |
+------------------------+------------+------------+------------+------------+------------+------------+ +--------------------+------+------------+-----+-----------+----------+------+
* Patch https://review.opendev.org/c/openstack/neutron/+/286087 was abandoned.
* Prefix delegation doesn't have functional tests for the dibbler and pd * Prefix delegation doesn't have functional tests for the dibbler and pd
layers, nor for the L3 agent changes. This has been an area of repeated layers, nor for the L3 agent changes. This has been an area of repeated
regressions. regressions.
* The functional job now compiles OVS 2.5 from source, enabling testing
features that we previously could not.
Missing Infrastructure Missing Infrastructure
---------------------- ----------------------

4
doc/source/contributor/testing/db_transient_failure_injection.rst
View File

@ -34,5 +34,5 @@ neutron-server neutron.conf file.
The plugin will inject a Deadlock exception on database flushes with a 1/50 The plugin will inject a Deadlock exception on database flushes with a 1/50
probability and a delay of 1 second with a 1/200 probability when SQLAlchemy probability and a delay of 1 second with a 1/200 probability when SQLAlchemy
objects are loaded into the persistent state from the DB. The goal is to ensure objects are loaded into the persistent state from the DB. The goal is to ensure
the code is tolerant of these transient delays/failures that will be experienced the code is tolerant of these transient delays/failures that will be
in busy production (and Galera) systems. experienced in busy production (and Galera) systems.

25
doc/source/contributor/testing/fullstack.rst
View File

@ -96,12 +96,12 @@ Neutron offers a Quality of Service API, initially offering bandwidth
capping at the port level. In the reference implementation, it does this by capping at the port level. In the reference implementation, it does this by
utilizing an OVS feature. utilizing an OVS feature.
neutron.tests.fullstack.test_qos.TestBwLimitQoSOvs.test_bw_limit_qos_policy_rule_lifecycle neutron.tests.fullstack.test_qos.TestBwLimitQoSOvs.test_bw_limit_qos_policy_rule_lifecycle
is a positive example of how the fullstack testing infrastructure should be used. is a positive example of how the fullstack testing infrastructure should be
It creates a network, subnet, QoS policy & rule and a port utilizing that policy. used. It creates a network, subnet, QoS policy & rule and a port utilizing
It then asserts that the expected bandwidth limitation is present on the OVS that policy. It then asserts that the expected bandwidth limitation is present
bridge connected to that port. The test is a true integration test, in the on the OVS bridge connected to that port. The test is a true integration test,
sense that it invokes the API and then asserts that Neutron interacted with in the sense that it invokes the API and then asserts that Neutron interacted
the hypervisor appropriately. with the hypervisor appropriately.
How to run fullstack tests locally? How to run fullstack tests locally?
+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++
@ -141,9 +141,9 @@ done you should see a message like:
That means that all went well and you should be ready to run fullstack tests That means that all went well and you should be ready to run fullstack tests
locally. locally.
Fullstack tests execute a custom dhclient-script. From kernel version 4.14 onward, Fullstack tests execute a custom dhclient-script. From kernel version 4.14
apparmor on certain distros could deny the execution of this script. To be sure, onward, apparmor on certain distros could deny the execution of this script.
check journalctl :: To be sure, check journalctl ::
sudo journalctl | grep DENIED | grep fullstack-dhclient-script sudo journalctl | grep DENIED | grep fullstack-dhclient-script
@ -260,7 +260,8 @@ Each fullstack test is spawning its own, isolated environment with needed
services. So, for example, it can be ``neutron-server``, ``neutron-ovs-agent`` services. So, for example, it can be ``neutron-server``, ``neutron-ovs-agent``
or ``neutron-dhcp-agent``. And often there is a need to check logs of some of or ``neutron-dhcp-agent``. And often there is a need to check logs of some of
those processes. That is of course possible when running fullstack tests those processes. That is of course possible when running fullstack tests
locally. By default, logs are stored in ``/opt/stack/logs/dsvm-fullstack-logs``. locally. By default, logs are stored in
``/opt/stack/logs/dsvm-fullstack-logs``.
The logs directory can be defined by the environment variable ``OS_LOG_PATH``. The logs directory can be defined by the environment variable ``OS_LOG_PATH``.
In that directory there are directories with names matching names of the In that directory there are directories with names matching names of the
tests, for example: tests, for example:
@ -299,8 +300,8 @@ Debugging fullstack failures in the gate
Sometimes there is a need to investigate reason that a test failed in the gate. Sometimes there is a need to investigate reason that a test failed in the gate.
After every ``neutron-fullstack`` job run, on the Zuul job page there are logs After every ``neutron-fullstack`` job run, on the Zuul job page there are logs
available. In the directory ``controller/logs/dsvm-fullstack-logs`` you can find available. In the directory ``controller/logs/dsvm-fullstack-logs`` you can
exactly the same files with logs from each test case as mentioned above. find exactly the same files with logs from each test case as mentioned above.
You can also check, for example, the journal log from the node where the tests You can also check, for example, the journal log from the node where the tests
were run. All those logs are available in the file were run. All those logs are available in the file

4
doc/source/contributor/testing/ml2_ovn_devstack.rst
View File

@ -591,8 +591,8 @@ On the compute nodes, enable it as follows:
Troubleshooting Troubleshooting
--------------- ---------------
If you run into any problems, take a look at our :doc:`/admin/ovn/troubleshooting` If you run into any problems, take a look at our
page. :doc:`/admin/ovn/troubleshooting` page.
Additional Resources Additional Resources
-------------------- --------------------

7
doc/source/contributor/testing/ml2_ovs_devstack.rst
View File

@ -4,8 +4,8 @@
ML2 OVS with DevStack ML2 OVS with DevStack
===================== =====================
This document describes how to test OpenStack Neutron with ML2 OpenvSwitch using This document describes how to test OpenStack Neutron with ML2 OpenvSwitch
DevStack. We will start by describing how to test on a single host. using DevStack. We will start by describing how to test on a single host.
Single Node Test Environment Single Node Test Environment
---------------------------- ----------------------------
@ -22,7 +22,8 @@ to use either CentOS 8 or the latest Ubuntu LTS.
$ git clone https://opendev.org/openstack/devstack.git $ git clone https://opendev.org/openstack/devstack.git
$ sudo ./devstack/tools/create-stack-user.sh $ sudo ./devstack/tools/create-stack-user.sh
3. Switch to the ``stack`` user, copy Devstack to stack folder and clone Neutron. 3. Switch to the ``stack`` user, copy Devstack to stack folder and clone
Neutron.
:: ::

17
doc/source/contributor/testing/tempest.rst
View File

@ -35,7 +35,8 @@ this is `neutron-tempest-plugin <https://opendev.org/openstack/neutron-tempest-p
neutron-tempest-plugin covers API and scenario tests not just for core Neutron neutron-tempest-plugin covers API and scenario tests not just for core Neutron
functionality, but for stadium projects as well. functionality, but for stadium projects as well.
For reference please read `Testing Neutron\'s related sections <testing.html#api-tests>`_ For reference please read
`Testing Neutron\'s related sections <testing.html#api-tests>`_
API Tests API Tests
~~~~~~~~~ ~~~~~~~~~
@ -56,9 +57,10 @@ should be validated, and all interaction with the daemon should be via
a REST client. a REST client.
The neutron-tempest-plugin/neutron_tempest_plugin directory was copied from the The neutron-tempest-plugin/neutron_tempest_plugin directory was copied from the
Tempest project around the Kilo timeframe. At the time, there was an overlap of tests Tempest project around the Kilo timeframe. At the time, there was an overlap
between the Tempest and Neutron repositories. This overlap was then eliminated by carving of tests between the Tempest and Neutron repositories. This overlap was then
out a subset of resources that belong to Tempest, with the rest in Neutron. eliminated by carving out a subset of resources that belong to Tempest, with
the rest in Neutron.
API tests that belong to Tempest deal with a subset of Neutron's resources: API tests that belong to Tempest deal with a subset of Neutron's resources:
@ -91,9 +93,10 @@ define a list of required extensions for a particular test class.
Scenario Tests Scenario Tests
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
Scenario tests (neutron-tempest-plugin/neutron_tempest_plugin/scenario), like API tests, Scenario tests (neutron-tempest-plugin/neutron_tempest_plugin/scenario),
use the Tempest test infrastructure and have the same requirements. Guidelines for like API tests, use the Tempest test infrastructure and have the same
writing a good scenario test may be found at the Tempest developer guide: requirements. Guidelines for writing a good scenario test may be found in
the Tempest developer guide:
https://docs.openstack.org/tempest/latest/field_guide/scenario.html https://docs.openstack.org/tempest/latest/field_guide/scenario.html
Scenario tests, like API tests, are split between the Tempest and Neutron Scenario tests, like API tests, are split between the Tempest and Neutron

13
doc/source/contributor/testing/template_model_sync_test.rst
View File

@ -37,9 +37,10 @@ This test compares models with the result of existing migrations. It is based on
<https://docs.openstack.org/oslo.db/latest/reference/api/oslo_db.sqlalchemy.test_migrations.html>`_ <https://docs.openstack.org/oslo.db/latest/reference/api/oslo_db.sqlalchemy.test_migrations.html>`_
which is provided by oslo.db and was adapted for Neutron. It compares core which is provided by oslo.db and was adapted for Neutron. It compares core
Neutron models and vendor specific models with migrations from Neutron core and Neutron models and vendor specific models with migrations from Neutron core and
migrations from the driver/plugin repo. This test is functional - it runs against migrations from the driver/plugin repo. This test is functional - it runs
MySQL and PostgreSQL dialects. The detailed description of this test can be against MySQL and PostgreSQL dialects. The detailed description of this test
found in Neutron Database Layer section - :ref:`testing-database-migrations`. can be found in Neutron Database Layer
section - :ref:`testing-database-migrations`.
Steps for implementing the test Steps for implementing the test
------------------------------- -------------------------------
@ -84,9 +85,9 @@ names, which were moved out of Neutron: ::
Also the test uses **VERSION_TABLE**, it is the name of table in database which Also the test uses **VERSION_TABLE**, it is the name of table in database which
contains revision id of head migration. It is preferred to keep this variable in contains revision id of head migration. It is preferred to keep this variable
``networking_foo/db/migration/alembic_migrations/__init__.py`` so it will be easy in ``networking_foo/db/migration/alembic_migrations/__init__.py`` so it will
to use in test. be easy to use in test.
Create a module ``networking_foo/tests/functional/db/test_migrations.py`` Create a module ``networking_foo/tests/functional/db/test_migrations.py``
with the following content: :: with the following content: ::

3
doc/source/feature_classification/feature_classification_introduction.rst
View File

@ -3,7 +3,8 @@ Introduction
============ ============
This document describes how features are listed in This document describes how features are listed in
:doc:`general_feature_support_matrix` and :doc:`provider_network_support_matrix`. :doc:`general_feature_support_matrix` and
:doc:`provider_network_support_matrix`.
Goals Goals
~~~~~ ~~~~~

6
doc/source/install/ovn/manual_install.rst
View File

@ -60,11 +60,13 @@ Only a single instance of the ``ovsdb-server`` and ``ovn-northd`` services
can operate in a deployment. However, deployment tools can implement can operate in a deployment. However, deployment tools can implement
active/passive high-availability using a management tool that monitors active/passive high-availability using a management tool that monitors
service health and automatically starts these services on another node after service health and automatically starts these services on another node after
failure of the primary node. See the :doc:`/ovn/faq/index` for more information. failure of the primary node. See the :doc:`/ovn/faq/index` for more
information.
#. Install the ``ovn-central`` and ``openvswitch`` packages (RHEL/Fedora). #. Install the ``ovn-central`` and ``openvswitch`` packages (RHEL/Fedora).
#. Install the ``ovn-central`` and ``openvswitch-common`` packages (Ubuntu/Debian). #. Install the ``ovn-central`` and ``openvswitch-common`` packages
(Ubuntu/Debian).
#. Start the OVS service. The central OVS service starts the ``ovsdb-server`` #. Start the OVS service. The central OVS service starts the ``ovsdb-server``
service that manages OVN databases. service that manages OVN databases.

2
doc/source/install/shared/edit_hosts_file.txt
View File

@ -1,7 +1,7 @@
Edit the ``/etc/hosts`` file to contain the following: Edit the ``/etc/hosts`` file to contain the following:
.. path /etc/hosts .. path /etc/hosts
.. code-block:: none .. code-block::
# controller # controller
10.0.0.11 controller 10.0.0.11 controller

20
doc/source/ovn/gaps.rst
View File

@ -22,17 +22,17 @@ at [1]_.
* DHCP service for instances * DHCP service for instances
ML2/OVS adds packet filtering rules to every instance that allow DHCP queries ML2/OVS adds packet filtering rules to every instance that allow DHCP queries
from instances to reach the DHCP agent. For OVN this traffic has to be explicitly from instances to reach the DHCP agent. For OVN this traffic has to be
allowed by security group rules attached to the instance. Note that the default explicitly allowed by security group rules attached to the instance. Note
security group does allow all outgoing traffic, so this only becomes relevant that the default security group does allow all outgoing traffic, so this only
when using custom security groups [6]_. Proposed patch is [7]_ but it becomes relevant when using custom security groups [6]_. Proposed patch is
needs to be revived and updated. [7]_ but it needs to be revived and updated.
* DNS resolution for instances * DNS resolution for instances
OVN cannot use the host's networking for DNS resolution, so Case 2b in [8]_ can OVN cannot use the host's networking for DNS resolution, so Case 2b in [8]_
only be used when additional DHCP agents are deployed. For Case 2a a different can only be used when additional DHCP agents are deployed. For Case 2a a
configuration option has to be used in ``ml2_conf.ini``:: different configuration option has to be used in ``ml2_conf.ini``::
[ovn] [ovn]
dns_servers = 203.0.113.8, 198.51.100.53 dns_servers = 203.0.113.8, 198.51.100.53
@ -41,8 +41,8 @@ at [1]_.
responses from the configured DNS servers. This may lead to confusion in responses from the configured DNS servers. This may lead to confusion in
debugging. debugging.
OVN can only answer queries that are sent via UDP, queries that use TCP will be OVN can only answer queries that are sent via UDP, queries that use TCP will
ignored by OVN and forwarded to the configured resolvers. be ignored by OVN and forwarded to the configured resolvers.
OVN can only answer queries with no additional options being set (EDNS). Such OVN can only answer queries with no additional options being set (EDNS). Such
queries depending on the OVN version will either get broken responses or will queries depending on the OVN version will either get broken responses or will

6
doc/source/ovn/ml2ovn_trace.rst
View File

@ -46,7 +46,8 @@ Usage
Examples Examples
-------- --------
If vm1 and vm2 only have one network interface and you want to trace between them: If vm1 and vm2 only have one network interface and you want to trace between
them:
.. code-block:: console .. code-block:: console
@ -70,7 +71,8 @@ To add to the generated microflow, use -m. For example, for SSH:
$ sudo ml2ovn-trace --net net1 --from server=vm1 --to server=vm2 -m "tcp.dst==22" $ sudo ml2ovn-trace --net net1 --from server=vm1 --to server=vm2 -m "tcp.dst==22"
To pass arbitrary (non microflow) arguments to ovn-trace, place them after '--': To pass arbitrary (non microflow) arguments to ovn-trace, place them after
'--':
.. code-block:: console .. code-block:: console

10
neutron/objects/README.rst
View File

@ -6,8 +6,8 @@ Neutron Objects
Directory Directory
========= =========
This directory is designed to contain all modules which have objects definitions This directory is designed to contain all modules which have objects
shipped with core Neutron. The files and directories located inside definitions shipped with core Neutron. The files and directories located inside
of this directory should follow the guidelines below. of this directory should follow the guidelines below.
@ -17,6 +17,8 @@ Structure
The Neutron objects tree should have the following structure: The Neutron objects tree should have the following structure:
* The expected directory structure is flat, except for the ML2 plugins. All ML2 * The expected directory structure is flat, except for the ML2 plugins. All ML2
plugin objects should fall under the plugins subdirectory (i.e. plugins/ml2/gre_allocation). plugin objects should fall under the plugins subdirectory
* Module names should use singular forms for nouns (network.py, not networks.py). (i.e. plugins/ml2/gre_allocation).
* Module names should use singular forms for nouns
(network.py, not networks.py).

1
test-requirements.txt
View File

@ -10,3 +10,4 @@ stestr>=1.0.0 # Apache-2.0
ddt>=1.0.1 # MIT ddt>=1.0.1 # MIT
# Needed to run DB commands in virtualenvs # Needed to run DB commands in virtualenvs
PyMySQL>=0.7.6 # MIT License PyMySQL>=0.7.6 # MIT License
doc8>=0.6.0 # Apache-2.0

15
tox.ini
View File

@ -150,12 +150,27 @@ commands=
flake8 flake8
bash ./tools/coding-checks.sh --pylint '{posargs}' bash ./tools/coding-checks.sh --pylint '{posargs}'
neutron-db-manage --config-file neutron/tests/etc/neutron.conf check_migration neutron-db-manage --config-file neutron/tests/etc/neutron.conf check_migration
# RST linter - remove the ignores once files are updated
doc8 \
--ignore-path doc/source/admin/config-qos-min-pps.rst \
--ignore-path doc/source/admin/deploy-provider-verifynetworkoperation.txt \
--ignore-path doc/source/admin/deploy-selfservice-verifynetworkoperation.txt \
--ignore-path doc/source/admin/shared/deploy-ha-vrrp-initialnetworks.txt \
--ignore-path doc/source/admin/shared/deploy-ha-vrrp-verifynetworkoperation.txt \
--ignore-path doc/source/admin/shared/deploy-provider-initialnetworks.txt \
--ignore-path doc/source/configuration/metering-agent.rst \
--ignore-path doc/source/contributor/internals/images \
--ignore-path doc/source/contributor/policies/bugs.rst \
doc/source neutron CONTRIBUTING.rst README.rst TESTING.rst
{[testenv:genconfig]commands} {[testenv:genconfig]commands}
{[testenv:bashate]commands} {[testenv:bashate]commands}
{[testenv:bandit]commands} {[testenv:bandit]commands}
{[testenv:genpolicy]commands} {[testenv:genpolicy]commands}
allowlist_externals = bash allowlist_externals = bash
[doc8]
max-line-length = 79
[testenv:cover] [testenv:cover]
description = description =
Run unit tests and generate coverage report. Run unit tests and generate coverage report.