openstack/neutron
Code Issues Proposed changes

Merge "Fix heading markers for better docment toc view"

Browse Source
This commit is contained in:
Jenkins 2015-11-12 18:45:43 +00:00 committed by Gerrit Code Review
commit 8ee67e477c
5 changed files with 34 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/devref/api_extensions.rst
View File

@ -29,7 +29,7 @@ to the Neutron project, it allows plugins to
determine if they wish to support the functionality or not.
Examples
========
--------
The easiest way to demonstrate how an API extension is written, is
by studying an existing API extension and explaining the different layers.

8
doc/source/devref/callbacks.rst
View File

@ -75,7 +75,7 @@ help understand better some of the principles behind the provided mechanism.
Subscribing to events
=====================
---------------------
Imagine that you have entity A, B, and C that have some common business over router creation.
A wants to tell B and C that the router has been created and that they need to get on and
@ -156,7 +156,7 @@ are flexible to evolve their internals, dynamics, and lifecycles.
Subscribing and aborting events
===============================
-------------------------------
Interestingly in Neutron, certain events may need to be forbidden from happening due to the
nature of the resources involved. To this aim, the callback-based mechanism has been designed
@ -232,7 +232,7 @@ fact, it is best to make use of different callbacks to keep the two logic separa
Unsubscribing to events
=======================
-----------------------
There are a few options to unsubscribe registered callbacks:
@ -320,7 +320,7 @@ The output is:
FAQ
===
---
Can I use the callbacks registry to subscribe and notify non-core resources and events?

30
doc/source/devref/quality_of_service.rst
View File

@ -35,7 +35,8 @@ Details about the DB models, API extension, and use cases can be found here: `qo
.
Service side design
===================
-------------------
* neutron.extensions.qos:
base extension + API controller definition. Note that rules are subattributes
of policies and hence embedded into their URIs.
@ -76,7 +77,7 @@ Service side design
Supported QoS rule types
------------------------
~~~~~~~~~~~~~~~~~~~~~~~~
Any plugin or Ml2 mechanism driver can claim support for some QoS rule types by
providing a plugin/driver class property called 'supported_qos_rule_types' that
@ -96,7 +97,7 @@ for QoS (at the moment of writing, linuxbridge is such a driver).
Database models
---------------
~~~~~~~~~~~~~~~
QoS design defines the following two conceptual resources to apply QoS rules
for a port or a network:
@ -129,7 +130,7 @@ All database models are defined under:
QoS versioned objects
---------------------
~~~~~~~~~~~~~~~~~~~~~
There is a long history of passing database dictionaries directly into business
logic of Neutron. This path is not the one we wanted to take for QoS effort, so
@ -207,7 +208,8 @@ QoS objects rely on some primitive database API functions that are added in:
RPC communication
-----------------
~~~~~~~~~~~~~~~~~
Details on RPC communication implemented in reference backend driver are
discussed in `a separate page <rpc_callbacks.html>`_.
@ -252,7 +254,7 @@ The flow of updates is as follows:
Agent side design
=================
-----------------
To ease code reusability between agents and to avoid the need to patch an agent
for each new core resource extension, pluggable L2 agent extensions were
@ -279,7 +281,7 @@ with them.
Agent backends
--------------
~~~~~~~~~~~~~~
At the moment, QoS is supported by Open vSwitch and SR-IOV ml2 drivers.
@ -291,7 +293,7 @@ interface:
Open vSwitch
~~~~~~~~~~~~
++++++++++++
Open vSwitch implementation relies on the new ovs_lib OVSBridge functions:
@ -308,7 +310,7 @@ which we may explore in the future, but which will need to be used in
combination with openflow rules.
SR-IOV
~~~~~~
++++++
SR-IOV bandwidth limit implementation relies on the new pci_lib function:
@ -326,7 +328,7 @@ value.
Configuration
=============
-------------
To enable the service, the following steps should be followed:
@ -342,14 +344,14 @@ On agent side (OVS):
Testing strategy
================
----------------
All the code added or extended as part of the effort got reasonable unit test
coverage.
Neutron objects
---------------
~~~~~~~~~~~~~~~
Base unit test classes to validate neutron objects were implemented in a way
that allows code reuse when introducing a new object type.
@ -370,7 +372,7 @@ object implementations on top of base semantics common to all neutron objects).
Functional tests
----------------
~~~~~~~~~~~~~~~~
Additions to ovs_lib to set bandwidth limits on ports are covered in:
@ -378,7 +380,7 @@ Additions to ovs_lib to set bandwidth limits on ports are covered in:
API tests
---------
~~~~~~~~~
API tests for basic CRUD operations for ports, networks, policies, and rules were added in:

14
doc/source/devref/rpc_api.rst
View File

@ -32,7 +32,7 @@ could be some other protocol in the future.
RPC APIs are defined in Neutron in two parts: client side and server side.
Client Side
===========
-----------
Here is an example of an rpc client definition:
@ -71,7 +71,7 @@ specifies that the remote side must implement at least version 1.1 to handle
this request.
Server Side
===========
-----------
The server side of an rpc interface looks like this:
@ -96,7 +96,7 @@ oslo_messaging.Target() defined says that this class currently implements
version 1.1 of the interface.
Versioning
==========
----------
Note that changes to rpc interfaces must always be done in a backwards
compatible way. The server side should always be able to handle older clients
@ -107,7 +107,7 @@ for backwards compatibility. For more information about how to do that, see
https://wiki.openstack.org/wiki/RpcMajorVersionUpdates.
Example Change
--------------
~~~~~~~~~~~~~~
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
@ -167,7 +167,7 @@ successful. The updated client side would look like this:
arg1=arg1, arg2=arg2)
Neutron RPC APIs
================
----------------
As discussed before, RPC APIs are defined in two parts: a client side and a
server side. Several of these pairs exist in the Neutron code base. The code
@ -175,7 +175,7 @@ base is being updated with documentation on every rpc interface implementation
that indicates where the corresponding server or client code is located.
Example: DHCP
-------------
~~~~~~~~~~~~~
The DHCP agent includes a client API, neutron.agent.dhcp.agent.DhcpPluginAPI.
The DHCP agent uses this class to call remote methods back in the Neutron
@ -191,7 +191,7 @@ server side of this interface that runs in the DHCP agent is
neutron.agent.dhcp.agent.DhcpAgent.
More Info
=========
---------
For more information, see the oslo.messaging documentation:
http://docs.openstack.org/developer/oslo.messaging/.

11
doc/source/devref/rpc_callbacks.rst
View File

@ -100,7 +100,7 @@ Serialized versioned objects look like::
'versioned_object.namespace': 'versionedobjects'}
Topic names for every resource type RPC endpoint
================================================
------------------------------------------------
neutron-vo-<resource_class_name>-<version>
@ -113,7 +113,7 @@ or something equivalent which would allow fine granularity for the receivers
to only get interesting information to them.
Subscribing to resources
========================
------------------------
Imagine that you have agent A, which just got to handle a new port, which
has an associated security group, and QoS policy.
@ -165,7 +165,7 @@ We may want to look into that later, to avoid agents receiving resource updates
which are uninteresting to them.
Unsubscribing from resources
============================
----------------------------
To unsubscribe registered callbacks:
@ -174,7 +174,7 @@ To unsubscribe registered callbacks:
Sending resource events
=======================
-----------------------
On the server side, resource updates could come from anywhere, a service plugin,
an extension, anything that updates, creates, or destroys the resource and that
@ -202,7 +202,8 @@ The server/publisher side may look like::
References
==========
----------
.. [#ov_serdes] https://github.com/openstack/oslo.versionedobjects/blob/master/oslo_versionedobjects/tests/test_objects.py#L621
.. [#vo_mkcompat] https://github.com/openstack/oslo.versionedobjects/blob/master/oslo_versionedobjects/base.py#L460
.. [#vo_mkcptests] https://github.com/openstack/oslo.versionedobjects/blob/master/oslo_versionedobjects/tests/test_objects.py#L111