x/gluon
Code Issues Proposed changes

Add/Update documentation for Gluon Developers

Browse Source 
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
This commit is contained in:
Darla Ahlert 2016-11-08 08:44:52 -06:00
parent 596a595a9e
commit 0e0cc14188
8 changed files with 83 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.rst
View File

@ -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

21
doc/source/devref/database_migration.rst
View File

@ -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 <http://docs.openstack.org/developer/neutron/devref/alembic_migrations.html#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 <http://docs.openstack.org/developer/neutron/devref/alembic_migrations.html>`_
*******
-------
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.
triggered by a Jenkins job and vote on the commit which changes the model.

15
doc/source/devref/index.rst Normal file
View File

@ -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

17
doc/source/devref/plugin_wrapper.rst
View File

@ -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

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

@ -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

43
doc/source/devref/service_binding_model.rst
View File

@ -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

7
doc/source/index.rst
View File

@ -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
==================

4
doc/source/usage.rst
View File

@ -1,6 +1,6 @@
========
=====
Usage
========
=====
To use gluon in a project::