From 0e0cc14188149f624eca2ca29f54cd8cbec4a66e Mon Sep 17 00:00:00 2001 From: Darla Ahlert Date: Tue, 8 Nov 2016 08:44:52 -0600 Subject: [PATCH] Add/Update documentation for Gluon Developers This commit takes documentation previously created and splits it into multiple files. This will eventually become a one stop shop for developers needing documentation to contribute to Gluon. Change-Id: I32287913c2d7bbc42a4f8685c2e71d3a18d4e807 --- README.rst | 16 ++++---- doc/source/devref/database_migration.rst | 21 +++++----- doc/source/devref/index.rst | 15 +++++++ doc/source/devref/plugin_wrapper.rst | 17 +++++--- doc/source/devref/repo_structure.rst | 8 ++-- doc/source/devref/service_binding_model.rst | 43 ++++++++++++--------- doc/source/index.rst | 7 +++- doc/source/usage.rst | 4 +- 8 files changed, 83 insertions(+), 48 deletions(-) create mode 100644 doc/source/devref/index.rst diff --git a/README.rst b/README.rst index 47cb3fc..721b3d2 100644 --- a/README.rst +++ b/README.rst @@ -1,12 +1,14 @@ -=============================== -gluon -=============================== +===== +Gluon +===== -A Model-Driven, Extensible Framework for L3 Networking Services +A Model-Driven, Extensible Framework for Networking APIs -Please fill here a long description which must be at least 3 lines wrapped on -80 cols, so that distribution package maintainers can use it in their packages. -Note that this is a hard requirement. +Gluon provides a framework for specifying, using a model file, +APIs for network forwarding. It is intended to offer devs +the possibility of quickly prototyping any networking forwarding +system that describes how a packet moves from port to port or +port to the outside world. * Free software: Apache license * Documentation: http://docs.openstack.org/developer/gluon diff --git a/doc/source/devref/database_migration.rst b/doc/source/devref/database_migration.rst index a0fd5c3..694600b 100644 --- a/doc/source/devref/database_migration.rst +++ b/doc/source/devref/database_migration.rst @@ -2,22 +2,24 @@ Database Migration Strategy =========================== -******************************* +------------------------------- What happens on a model change? -******************************* +------------------------------- If a model is changed and this change is committed to the repo, a Jenkins -job will vote against the change until also a migration file for this change is -uploaded. +job will vote against the change until a migration file for this change is +also uploaded. Similar to Neutron migration strategy a script for auto generation is used: `Neutron Script Auto-generation `_ The big difference is that Proton will have a YAML model. So a new auto generate script is needed. -***************** + +----------------- Migration Process -***************** +----------------- + The migrations in the alembic/versions contain the changes needed to migrate from older Neutron releases to newer versions. A migration occurs by executing a script that details the changes needed to upgrade the database. The @@ -29,9 +31,10 @@ database migration. See details in the devref: `Neutron Database Migration `_ -******* + +------- Testing -******* +------- Unit test need to be written to verify the changed model. This unit test will be -triggered by a Jenkins job and vote on the commit which changes the model. \ No newline at end of file +triggered by a Jenkins job and vote on the commit which changes the model. diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst new file mode 100644 index 0000000..a09e45f --- /dev/null +++ b/doc/source/devref/index.rst @@ -0,0 +1,15 @@ +:tocdepth: 2 + +#################### +Gluon Developer Docs +#################### + +.. rest_expand_all:: + +.. include:: high_level_design.rst +.. include:: plugin_wrapper.rst +.. include:: service_binding_model.rst +.. include:: database_migration.rst +.. include:: repo_structure.rst +.. include:: task_list.rst + diff --git a/doc/source/devref/plugin_wrapper.rst b/doc/source/devref/plugin_wrapper.rst index b7efb41..781b37a 100644 --- a/doc/source/devref/plugin_wrapper.rst +++ b/doc/source/devref/plugin_wrapper.rst @@ -1,6 +1,6 @@ - +=========================== Gluon Plugin Wrapper Design -============================ +=========================== **Original Gluon Architecture** @@ -77,8 +77,11 @@ any other Core Plugin class) and override just the port-related methods. If the method call is for a Gluon port, the Gluon Wrapper Plugin code will forward the request to the Proton Server for processing. Otherwise, the superclass method will be called. The goal is to introduce the Gluon networking -functionality without breaking the existing ML2 networking. The following -diagram provides an overview of this design. +functionality without breaking the existing ML2 networking - and to ensure +that a user that doesn't need extended network functionality does not have +to install it and is not affected by Gluon development - the stability of their +system remains as before because the code they're running is no different. +The following diagram provides an overview of this design. :: @@ -131,7 +134,7 @@ diagram provides an overview of this design. The Gluon Wrapper Plugin will determine if a port belongs to Gluon by examining (looking up the UUID) the etcd database. The port registration code in the -Proton Server will be changed to update the etcd database when a new port is +Proton Server will be changed to also update the etcd database when a new port is created or deleted. When a port is registered in the etcd database, the following backend information is stored: tenant identifier, networking service identifier and Proton Server base URL. In order to forward the requests to the @@ -141,7 +144,9 @@ Wrapper Plugin as was used by the Gluon Sever. Since we can no longer replace the Networking API plugin in Nova, we must provide a consistent “Neutron” networking model to Nova. Therefore, we have to maintain the Network, Subnet and Port associations required by the logic in -the Neutron API plugin (in Nova). In the short term, we can create a “dummy” +the Neutron API plugin (in Nova), at least until we can simplify the Nova-Neutron +communication so that Nova does not need to retrieve subnet and network objects. +In the short term, we can create a “dummy” Network and Subnet object in the Neutron Server that can be associated with all Gluon ports. In the long term, it may be possible to add attributes to the Network and Subnet objects to change the semantics of the objects to reflect a diff --git a/doc/source/devref/repo_structure.rst b/doc/source/devref/repo_structure.rst index b50e907..0bba7c6 100644 --- a/doc/source/devref/repo_structure.rst +++ b/doc/source/devref/repo_structure.rst @@ -20,14 +20,14 @@ ''''''' Heading 4 (Avoid deeper levels because they do not render well.) - +========================== Gluon Repository Structure -==================================== +========================== This document describes the repository structure that was used in the initial development of Gluon and a proposed structure going forward. Current Repository Structure ------------------------------ +---------------------------- - **gluon-nova** - Networking plugin code for nova @@ -173,7 +173,7 @@ Proposed Repository Structure fly Notes ------- +----- - Right now the gluon-server uses a model file to generate its API and database classes. This may not be the best approach. The API between Nova and Gluon diff --git a/doc/source/devref/service_binding_model.rst b/doc/source/devref/service_binding_model.rst index ab34e32..893d634 100644 --- a/doc/source/devref/service_binding_model.rst +++ b/doc/source/devref/service_binding_model.rst @@ -1,3 +1,4 @@ +============================== Port and Service Binding Model ============================== @@ -11,7 +12,7 @@ creating new network service APIs. It hence supports developers in making the best use of the flexibility provided by Gluon. This model is based on the "service binding pattern" described in the NetReady -requirements document [1] and was adapted for Gluon. +requirements document [1]_ and was adapted for Gluon. The modeling tools in Gluon provide building blocks to allow the creation of arbitrarily complex networking APIs. However, some constraints are needed to @@ -37,7 +38,9 @@ Specifically, there are four basic entities: A Port object represents a vNIC which is bindable to an OpenStack instance by the compute service (Nova). It hence comprises all required information for - defining the hand-off point between a network and a VM instance. + defining the hand-off point between a network and a VM instance. Other + services may in the future bind to ports (today, this happens within Neutron + to bind things like routers and DHCP services in the ML2 world). * **Interface** @@ -77,7 +80,9 @@ Specifically, there are four basic entities: service can be specified here whereas this is not required for a pure L2 service. -The following diagram shows the relationship between these objects::: +The following diagram shows the relationship between these objects: + +:: +-----------+ @@ -109,16 +114,16 @@ The following diagram shows the relationship between these objects::: Base Object Definitions -------------------------- +----------------------- These are the base objects for defining APIs. These objects cannot be used directly in an API definition. They must be used as the base object for objects of similar type. There is an **"extends"** keyword in the YAML model to provide this capability. To have a functional networking API, -one must extend the BasePort, BaseInterface, BaseService and BaseServiceBinding -objects. It is not required that additional attributes are defined for the -extended objects. See the Interface definition in the example at the end of -this document. +one must extend the ``BasePort``, ``BaseInterface``, ``BaseService`` and +``BaseServiceBinding`` objects. It is not required that additional attributes +are defined for the extended objects. See the Interface definition in the +example_ at the end of this document. In addition, you can also define objects that do not extend any of the base objects. The proton server will provide CRUD functions on these objects but it @@ -129,7 +134,7 @@ references only valid Interface and Service objects. **BasePort** - The BasePort object must be extended in an API model. This base object + The ``BasePort`` object must be extended in an API model. This base object contains all of the attributes needed by Nova to bind the Port to a VM. The extended object may contain additional attributes needed by the API model (but not Nova). Note, the extended object does not have to define additional @@ -217,7 +222,7 @@ references only valid Interface and Service objects. **BaseInterface** - The BaseInterface object must be extended in an API model. A default + The ``BaseInterface`` object must be extended in an API model. A default Interface object will automatically be created for each Port object. Note, the extended object does not have to define additional attributes. @@ -252,7 +257,7 @@ references only valid Interface and Service objects. **BaseService** - The BaseService object must be extended in an API model. There can be + The ``BaseService`` object must be extended in an API model. There can be multiple Services defined of a given model. However, an Interface can only be bound to one Service. Note, the extended object does not have to define additional attributes. @@ -277,17 +282,17 @@ references only valid Interface and Service objects. **BaseServiceBinding** - The BaseServiceBinding object must be extended in an API model. Additional + The ``BaseServiceBinding`` object must be extended in an API model. Additional attributes can be added to the extended object that are specific for a Port bound to the Service. Note, the extended object does not have to define additional attributes. - The service_id attribute can be re-defined in the extended object to specify + The ``service_id`` attribute can be re-defined in the extended object to specify the specific type of Service that can be bound. The system will validate - that the UUID specified for the interface_id is a known Interface object. A + that the UUID specified for the ``interface_id`` is a known Interface object. A null value is also accepted to effectively "unbind" the interface from the service. The system will also validate that the UUID specified for the - service_id is a known Service object. + ``service_id`` is a known Service object. :: @@ -308,10 +313,10 @@ Example L3VPN API using proposed model: --------------------------------------- The following model defines an L3VPN service. The Port and Interface objects -extend the BasePort and BaseInterface, respectively. You can extend an object +extend the ``BasePort`` and ``BaseInterface``, respectively. You can extend an object without adding attributes. That is done with the Interface object. Even if no attributes are added, you are still required to extend these objects for a -functional API. You must also extend the BaseService and BaseServiceBinding +functional API. You must also extend the ``BaseService`` and ``BaseServiceBinding`` base objects in a similar manner. Note, the VpnAfConfig object does not extend a base class. The @@ -319,6 +324,8 @@ modeling tools allow for the creation of arbitrary objects as needed by an API model. The proton server will not enforce any constraints on the relationships between these objects and objects extended from base objects. +.. _example: + :: Port: @@ -420,5 +427,5 @@ between these objects and objects extended from base objects. References -[1] NetReady - Service Binding model: http://artifacts.opnfv.org/netready/colorado/docs/requirements/index.html#service-binding-design-pattern +.. [1] NetReady - Service Binding model: http://artifacts.opnfv.org/netready/colorado/docs/requirements/index.html#service-binding-design-pattern diff --git a/doc/source/index.rst b/doc/source/index.rst index f208aef..6a02c60 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,13 +3,14 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +================================= Welcome to gluon's documentation! -======================================================== +================================= Contents: .. toctree:: - :maxdepth: 2 + :maxdepth:2 readme high_level_design @@ -17,7 +18,9 @@ Contents: installation usage contributing + devref/index +================== Indices and tables ================== diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 6c0e7ac..6b55540 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,6 +1,6 @@ -======== +===== Usage -======== +===== To use gluon in a project::