diff --git a/doc/source/devref/api_extensions.rst b/doc/source/devref/api_extensions.rst index f0c171b99ea..7af6d0fd2f7 100644 --- a/doc/source/devref/api_extensions.rst +++ b/doc/source/devref/api_extensions.rst @@ -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. diff --git a/doc/source/devref/callbacks.rst b/doc/source/devref/callbacks.rst index 026d51d44e4..42ebf52a452 100644 --- a/doc/source/devref/callbacks.rst +++ b/doc/source/devref/callbacks.rst @@ -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? diff --git a/doc/source/devref/quality_of_service.rst b/doc/source/devref/quality_of_service.rst index 37197fd4294..8e3e6d81d25 100644 --- a/doc/source/devref/quality_of_service.rst +++ b/doc/source/devref/quality_of_service.rst @@ -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 `_. @@ -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: diff --git a/doc/source/devref/rpc_api.rst b/doc/source/devref/rpc_api.rst index 1a5fca034b7..951085db8e4 100644 --- a/doc/source/devref/rpc_api.rst +++ b/doc/source/devref/rpc_api.rst @@ -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/. diff --git a/doc/source/devref/rpc_callbacks.rst b/doc/source/devref/rpc_callbacks.rst index 97ca772aec4..020b521228e 100644 --- a/doc/source/devref/rpc_callbacks.rst +++ b/doc/source/devref/rpc_callbacks.rst @@ -100,7 +100,7 @@ Serialized versioned objects look like:: 'versioned_object.namespace': 'versionedobjects'} Topic names for every resource type RPC endpoint -================================================ +------------------------------------------------ neutron-vo-- @@ -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