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. determine if they wish to support the functionality or not.
Examples Examples
======== --------
The easiest way to demonstrate how an API extension is written, is The easiest way to demonstrate how an API extension is written, is
by studying an existing API extension and explaining the different layers. 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 Subscribing to events
===================== ---------------------
Imagine that you have entity A, B, and C that have some common business over router creation. 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 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 Subscribing and aborting events
=============================== -------------------------------
Interestingly in Neutron, certain events may need to be forbidden from happening due to the 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 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 Unsubscribing to events
======================= -----------------------
There are a few options to unsubscribe registered callbacks: There are a few options to unsubscribe registered callbacks:
@ -320,7 +320,7 @@ The output is:
FAQ FAQ
=== ---
Can I use the callbacks registry to subscribe and notify non-core resources and events? 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 Service side design
=================== -------------------
* neutron.extensions.qos: * neutron.extensions.qos:
base extension + API controller definition. Note that rules are subattributes base extension + API controller definition. Note that rules are subattributes
of policies and hence embedded into their URIs. of policies and hence embedded into their URIs.
@ -76,7 +77,7 @@ Service side design
Supported QoS rule types Supported QoS rule types
------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~
Any plugin or Ml2 mechanism driver can claim support for some QoS rule types by 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 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 Database models
--------------- ~~~~~~~~~~~~~~~
QoS design defines the following two conceptual resources to apply QoS rules QoS design defines the following two conceptual resources to apply QoS rules
for a port or a network: for a port or a network:
@ -129,7 +130,7 @@ All database models are defined under:
QoS versioned objects QoS versioned objects
--------------------- ~~~~~~~~~~~~~~~~~~~~~
There is a long history of passing database dictionaries directly into business 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 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 RPC communication
----------------- ~~~~~~~~~~~~~~~~~
Details on RPC communication implemented in reference backend driver are Details on RPC communication implemented in reference backend driver are
discussed in `a separate page <rpc_callbacks.html>`_. discussed in `a separate page <rpc_callbacks.html>`_.
@ -252,7 +254,7 @@ The flow of updates is as follows:
Agent side design Agent side design
================= -----------------
To ease code reusability between agents and to avoid the need to patch an agent 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 for each new core resource extension, pluggable L2 agent extensions were
@ -279,7 +281,7 @@ with them.
Agent backends Agent backends
-------------- ~~~~~~~~~~~~~~
At the moment, QoS is supported by Open vSwitch and SR-IOV ml2 drivers. At the moment, QoS is supported by Open vSwitch and SR-IOV ml2 drivers.
@ -291,7 +293,7 @@ interface:
Open vSwitch Open vSwitch
~~~~~~~~~~~~ ++++++++++++
Open vSwitch implementation relies on the new ovs_lib OVSBridge functions: 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. combination with openflow rules.
SR-IOV SR-IOV
~~~~~~ ++++++
SR-IOV bandwidth limit implementation relies on the new pci_lib function: SR-IOV bandwidth limit implementation relies on the new pci_lib function:
@ -326,7 +328,7 @@ value.
Configuration Configuration
============= -------------
To enable the service, the following steps should be followed: To enable the service, the following steps should be followed:
@ -342,14 +344,14 @@ On agent side (OVS):
Testing strategy Testing strategy
================ ----------------
All the code added or extended as part of the effort got reasonable unit test All the code added or extended as part of the effort got reasonable unit test
coverage. coverage.
Neutron objects Neutron objects
--------------- ~~~~~~~~~~~~~~~
Base unit test classes to validate neutron objects were implemented in a way Base unit test classes to validate neutron objects were implemented in a way
that allows code reuse when introducing a new object type. 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 Functional tests
---------------- ~~~~~~~~~~~~~~~~
Additions to ovs_lib to set bandwidth limits on ports are covered in: 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
--------- ~~~~~~~~~
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:

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. RPC APIs are defined in Neutron in two parts: client side and server side.
Client Side Client Side
=========== -----------
Here is an example of an rpc client definition: 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. this request.
Server Side Server Side
=========== -----------
The server side of an rpc interface looks like this: 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. version 1.1 of the interface.
Versioning Versioning
========== ----------
Note that changes to rpc interfaces must always be done in a backwards 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 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. https://wiki.openstack.org/wiki/RpcMajorVersionUpdates.
Example Change 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
@ -167,7 +167,7 @@ successful. The updated client side would look like this:
arg1=arg1, arg2=arg2) arg1=arg1, arg2=arg2)
Neutron RPC APIs Neutron RPC APIs
================ ----------------
As discussed before, RPC APIs are defined in two parts: a client side and a 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 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. that indicates where the corresponding server or client code is located.
Example: DHCP Example: DHCP
------------- ~~~~~~~~~~~~~
The DHCP agent includes a client API, neutron.agent.dhcp.agent.DhcpPluginAPI. 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 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. neutron.agent.dhcp.agent.DhcpAgent.
More Info More Info
========= ---------
For more information, see the oslo.messaging documentation: For more information, see the oslo.messaging documentation:
http://docs.openstack.org/developer/oslo.messaging/. 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'} 'versioned_object.namespace': 'versionedobjects'}
Topic names for every resource type RPC endpoint Topic names for every resource type RPC endpoint
================================================ ------------------------------------------------
neutron-vo-<resource_class_name>-<version> 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. to only get interesting information to them.
Subscribing to resources Subscribing to resources
======================== ------------------------
Imagine that you have agent A, which just got to handle a new port, which Imagine that you have agent A, which just got to handle a new port, which
has an associated security group, and QoS policy. 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. which are uninteresting to them.
Unsubscribing from resources Unsubscribing from resources
============================ ----------------------------
To unsubscribe registered callbacks: To unsubscribe registered callbacks:
@ -174,7 +174,7 @@ To unsubscribe registered callbacks:
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 plugin,
an extension, anything that updates, creates, or destroys the resource and that an extension, anything that updates, creates, or destroys the resource and that
@ -202,7 +202,8 @@ The server/publisher side may look like::
References References
========== ----------
.. [#ov_serdes] https://github.com/openstack/oslo.versionedobjects/blob/master/oslo_versionedobjects/tests/test_objects.py#L621 .. [#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_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 .. [#vo_mkcptests] https://github.com/openstack/oslo.versionedobjects/blob/master/oslo_versionedobjects/tests/test_objects.py#L111