diff options
Diffstat (limited to 'networking-odl/doc/source')
-rw-r--r-- | networking-odl/doc/source/conf.py | 75 | ||||
-rw-r--r-- | networking-odl/doc/source/contributing.rst | 4 | ||||
-rw-r--r-- | networking-odl/doc/source/devref/hostconfig.rst | 119 | ||||
-rw-r--r-- | networking-odl/doc/source/devref/index.rst | 36 | ||||
-rw-r--r-- | networking-odl/doc/source/index.rst | 35 | ||||
-rw-r--r-- | networking-odl/doc/source/installation.rst | 12 | ||||
-rw-r--r-- | networking-odl/doc/source/readme.rst | 1 | ||||
-rw-r--r-- | networking-odl/doc/source/specs.rst | 26 | ||||
-rw-r--r-- | networking-odl/doc/source/specs/journal-recovery.rst | 152 | ||||
-rw-r--r-- | networking-odl/doc/source/specs/qos-driver.rst | 104 | ||||
-rw-r--r-- | networking-odl/doc/source/specs/sfc-driver.rst | 139 | ||||
-rw-r--r-- | networking-odl/doc/source/usage.rst | 7 |
12 files changed, 710 insertions, 0 deletions
diff --git a/networking-odl/doc/source/conf.py b/networking-odl/doc/source/conf.py new file mode 100644 index 0000000..309859f --- /dev/null +++ b/networking-odl/doc/source/conf.py @@ -0,0 +1,75 @@ +# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx', + 'oslosphinx' +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'networking-odl' +copyright = u'2013, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/networking-odl/doc/source/contributing.rst b/networking-odl/doc/source/contributing.rst new file mode 100644 index 0000000..1728a61 --- /dev/null +++ b/networking-odl/doc/source/contributing.rst @@ -0,0 +1,4 @@ +============ +Contributing +============ +.. include:: ../../CONTRIBUTING.rst diff --git a/networking-odl/doc/source/devref/hostconfig.rst b/networking-odl/doc/source/devref/hostconfig.rst new file mode 100644 index 0000000..70c8607 --- /dev/null +++ b/networking-odl/doc/source/devref/hostconfig.rst @@ -0,0 +1,119 @@ +Host Configuration +================== + +Overview +-------- + +ODL is agentless configuration. In this scenario Host Configuration is used +to specify the physical host type and other configurations for the host +system. This information is populated by the Cloud Operator is in OVSDB in +Open_vSwitch configuration data in the external_ids field as a key value pair. +This information is then read by ODL and made available to networking-odl +through REST API. Networking-odl populates this information in agent_db in +Neutron and is then used by Neutron scheduler. This information is required +for features like Port binding and Router scheduling. + +Refer to this link for detailed design for this feature. + +https://docs.google.com/presentation/d/1kq0elysCDEmIWs3omTi5RoXTSBbrewn11Je2d26cI4M/edit?pref=2&pli=1#slide=id.g108988d1e3_0_6 + +Related ODL changes: + +https://git.opendaylight.org/gerrit/#/c/36767/ + +https://git.opendaylight.org/gerrit/#/c/40143/ + +Host Configuration fields +------------------------- + +- host-id + +This represents host identification string. This string will be stored in +external_ids field with the key as odl_os_hostconfig_hostid. +Refer to Neutron config definition for host field for details on this field. + +http://docs.openstack.org/kilo/config-reference/content/section_neutron.conf.html + +- host-type + +The field is for type of the node. This value corresponds to agent_type in +agent_db. Example value are “ODL L2” and “ODL L3” for Compute and Network node +respectively. Same host can be configured to have multiple configurations and +can therefore can have both L2, L3 and other configurations at the same time. +This string will be populated by ODL based on the configurations available +on the host. See example in section below. + +- config + +This is the configuration data for the host type. Since same node can be +configured to store multiple configurations different external_ids key value +pair are used to store these configuration. The external_ids with keys as +odl_os_hostconfig_config_odl_XXXXXXXX store different configurations. +8 characters after the suffix odl_os_hostconfig_config_odl are host type. +ODL extracts these characters and store that as the host-type fields. For +example odl_os_hostconfig_config_odl_l2, odl_os_hostconfig_config_odl_l3 keys +are used to provide L2 and L3 configurations respectively. ODL will extract +"ODL L2" and "ODL L3" as host-type field from these keys and populate +host-type field. + +Config is a Json string. Some examples of config: + +:: + + {“supported_vnic_types”: [{ + “vnic_type”: “normal”, + “vif_type”: “ovs”, + “vif_details”: “{}” + }] + “allowed_network_types”: ["local", "gre", "vlan", "vxlan"]”, + “bridge_mappings”: {“physnet1":"br-ex”} + }" + + {“supported_vnic_types”: [{ + “vnic_type”: “normal”, + “vif_type”: “vhostuser”, + “vif_details”: “{“port_filter”: “False”, “vhostuser_socket”: “/var/run/openvswitch”}” + }] + “allowed_network_types”: ["local", "gre", "vlan", "vxlan"]”, + “bridge_mappings”: {“physnet1":"br-ex”} + }" + +**Host Config URL** + +Url : http://ip:odlport/restconf/operational/neutron:neutron/hostconfigs/ + +**Commands to setup host config in OVSDB** +:: + + export OVSUUID=$(ovs-vsctl get Open_vSwitch . _uuid) + ovs-vsctl set Open_vSwitch $OVSUUID external_ids:odl_os_hostconfig_hostid=test_host + ovs-vsctl set Open_vSwitch $OVSUUID external_ids:odl_os_hostconfig_config_odl_l2 = + "{“supported_vnic_types”: [{“vnic_type”: “normal”, “vif_type”: “ovs”, "vif_details": {} }], “allowed_network_types”: [“local”], “bridge_mappings”: {“physnet1":"br-ex”}}" + +Example for host configuration +------------------------------- + +:: + + { + "hostconfigs": { + "hostconfig": [ + { + "host-id": "test_host1", + "host-type": "ODL L2", + "config": + "{“supported_vnic_types”: [{ + “vnic_type”: “normal”, + “vif_type”: “ovs”, + “vif_details”: {} + }] + “allowed_network_types”: ["local", "gre", "vlan", "vxlan"], + “bridge_mappings”: {“physnet1":"br-ex”}}" + }, + { + "host-id": "test_host2", + "host-type": "ODL L3", + "config": {} + }] + } + } diff --git a/networking-odl/doc/source/devref/index.rst b/networking-odl/doc/source/devref/index.rst new file mode 100644 index 0000000..1bf7790 --- /dev/null +++ b/networking-odl/doc/source/devref/index.rst @@ -0,0 +1,36 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + +Developer Guide +=============== + +In the Developer Guide, you will find information on networking-odl's lower +level design and implementation details. + + +Contents: +-------------------------------- +.. toctree:: + :maxdepth: 2 + + hostconfig + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/networking-odl/doc/source/index.rst b/networking-odl/doc/source/index.rst new file mode 100644 index 0000000..312dbe0 --- /dev/null +++ b/networking-odl/doc/source/index.rst @@ -0,0 +1,35 @@ +.. networking-odl documentation master file, created by + sphinx-quickstart on Tue Jul 9 22:26:36 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to networking-odl's documentation! +======================================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + readme + installation + usage + contributing + specs + +Developer Docs +============== + +.. toctree:: + :maxdepth: 1 + + devref/index + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/networking-odl/doc/source/installation.rst b/networking-odl/doc/source/installation.rst new file mode 100644 index 0000000..29c6e45 --- /dev/null +++ b/networking-odl/doc/source/installation.rst @@ -0,0 +1,12 @@ +============ +Installation +============ + +At the command line:: + + $ pip install networking-odl + +Or, if you have virtualenvwrapper installed:: + + $ mkvirtualenv networking-odl + $ pip install networking-odl diff --git a/networking-odl/doc/source/readme.rst b/networking-odl/doc/source/readme.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/networking-odl/doc/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/networking-odl/doc/source/specs.rst b/networking-odl/doc/source/specs.rst new file mode 100644 index 0000000..6050296 --- /dev/null +++ b/networking-odl/doc/source/specs.rst @@ -0,0 +1,26 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + + neutron networking-odl specs documentation master file + +============================================= +Neutron networking-odl Project Specifications +============================================= + +Specs +===== + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/* + +================== +Indices and tables +================== + +* :ref:`search` diff --git a/networking-odl/doc/source/specs/journal-recovery.rst b/networking-odl/doc/source/specs/journal-recovery.rst new file mode 100644 index 0000000..1132485 --- /dev/null +++ b/networking-odl/doc/source/specs/journal-recovery.rst @@ -0,0 +1,152 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +================ +Journal Recovery +================ + +https://blueprints.launchpad.net/networking-odl/+spec/journal-recovery + +Journal entries in the failed state need to be handled somehow. This spec will +try to address the issue and propose a solution. + +Problem Description +=================== + +Currently there is no handling for Journal entries that reach the failed state. +A journal entry can reach the failed state for several reasons, some of which +are: + +* Reached maximum failed attempts for retrying the operation. + +* Inconsistency between ODL and the Neutron DB. + + * For example: An update fails because the resource doesn't exist in ODL. + +* Bugs that can lead to failure to sync up. + +These entries will be left in the journal table forever which is a bit wasteful +since they take up some space on the DB storage and also affect the performance +of the journal table. +Albeit each entry has a negligble effect on it's own, the impact of a large +number of such entries can become quite significant. + +Proposed Change +=============== + +A "journal recovery" routine will run as part of the current journal +maintenance process. +This routine will scan the journal table for rows in the "failed" state and +will try to sync the resource for that entry. + +The procedure can be best described by the following flow chart: + +asciiflow:: + + +-----------------+ + | For each entry | + | in failed state | + +-------+---------+ + | + +-------v--------+ + | Query resource | + | on ODL (REST) | + +-----+-----+----+ + | | +-----------+ + Resource | | Determine | + exists +--Resource doesn't exist--> operation | + | | type | + +-----v-----+ +-----+-----+ + | Determine | | + | operation | | + | type | | + +-----+-----+ | + | +------------+ | + +--Create------> Mark entry <--Delete--+ + | | completed | | + | +----------^-+ Create/ + | | Update + | | | + | +------------+ | +-----v-----+ + +--Delete--> Mark entry | | | Determine | + | | pending | | | parent | + | +---------^--+ | | relation | + | | | +-----+-----+ + +-----v------+ | | | + | Compare to +--Different--+ | | + | resource | | | + | in DB +--Same------------+ | + +------------+ | + | + +-------------------+ | + | Create entry for <-----Has no parent------+ + | resource creation | | + +--------^----------+ Has a parent + | | + | +---------v-----+ + +------Parent exists------+ Query parent | + | on ODL (REST) | + +---------+-----+ + +------------------+ | + | Create entry for <---Parent doesn't exist--+ + | parent creation | + +------------------+ + +For every error during the process the entry will remain in failed state but +the error shouldn't stop processing of further entries. + + +The implementation could be done in two phases where the parent handling is +done in a a second pahse. +For the first phase if we detect an entry that is in failed for a create/update +operation and the resource doesn't exist on ODL we create a new "create +resource" journal entry for the resource. + +This propsal utilises the journal mechanism for it's operation while the only +part that deviates from the standard mode of operation is when it queries ODL +directly. This direct query has to be done to get ODL's representation of the +resource. + +Performance Impact +------------------ + +The maintenance thread will have another task to handle. This can lead to +longer processing time and even cause the thread to skip an iteration. +This is not an issue since the maintenance thread runs in parallel and doesn't +directly impact the responsiveness of the system. + +Since most operations here involve I/O then CPU probably won't be impacted. + +Network traffic would be impacted slightly since we will attempt to fetch the +resource each time from ODL and we might attempt to fetch it's parent. +This is however negligble as we do this only for failed entries, which are +expected to appear rarely. + + +Alternatives +------------ + +The partial sync process could make this process obsolete (along with full +sync), but it's a far more complicated and problematic process. +It's better to start with this process which is more lightweight and doable +and consider partial sync in the future. + + +Assignee(s) +=========== + +Primary assignee: + mkolesni <mkolesni@redhat.com> + +Other contributors: + None + + +References +========== + +https://goo.gl/IOMpzJ + diff --git a/networking-odl/doc/source/specs/qos-driver.rst b/networking-odl/doc/source/specs/qos-driver.rst new file mode 100644 index 0000000..d2faad1 --- /dev/null +++ b/networking-odl/doc/source/specs/qos-driver.rst @@ -0,0 +1,104 @@ +========================================== +Quality of Service Driver for OpenDaylight +========================================== + +This spec describes the plan to implement quality of service driver for +OpenDaylight Controller. + +Problem Statement +================= +OpenStack networking project (neutron [1]) have a extension plugin implemented +and which expose api for quality of service that can be also be implemented by +any backend networking service provider to support QoS. These APIs provide a +way to integrate OpenStack Neutron QoS with any of the backend QoS providers. +OpenDaylight will provide backend for existing functionalities in neutron-QoS. +A notification driver is needed for integration of existing api in Openstack +neutron for QoS with OpenDaylight backend. + +Proposed Change +=============== +This change will introduce a new notification driver in networking-odl that +will take CRUD requests data for QoS policies from OpenStack neutron and notify +the OpenDaylight controller about the respective operation. + +Detailed Design +=============== +To enable the formal end to end integration between OpenStack QoS and +OpenDaylight requires an networking-odl QoS notification driver. QoS driver +will act as a shim layer between OpenStack and OpenDaylight that will carry +out following task: + +#. After getting QoS policy request data from neutron, It will log a operation + request in opendaylightjournal table. + +#. The operation will be picked from opendaylightjournal table and a rest call + for notifying OpenDaylight server will be prepared and sent. + +#. This request will processed by neutron northbound in OpenDaylight. +The OpenDaylight neutron northbound project. These models will be based +on the existing neutron qos plugin APIs. + +QoS providers in OpenDaylight can listen to these OpenDaylight Neutron +Northbound QoS models and translate it to their specific yang models for QoS. +The following diagram shows the high level integration between OpenStack and +the OpenDaylight QoS provider:: + + +---------------------------------------------+ + | OpenStack Network Server (neutron qos) | + | | + | +---------------------+ | + | | networking-odl | | + | | | | + | | +---------------| | + | | | Notification | | + | | | driver QoS | | + +----------------------|----------------------+ + | + | Rest Communication + | + OpenDaylight Controller | + +-----------------------|------------+ + | +----------V----+ | + | ODL | QoS Yang Model| | + | Northbound | | | + | (neutron) +---------------+ | + | | | + | | | + | ODL +----V----+ | + | Southbound | QoS | | + | (neutron) +---------+ | + +-----------------|------------------+ + | + | + +------------------------------------+ + | Network/OVS | + | | + +------------------------------------+ + +In the above diagram, the OpenDaylight components are shown just to understand +the overall architecture, but it's out of scope of this spec's work items. +This spec will only track progress related to networking-odl notification QoS +driver work. + +Dependencies +============ +It has a dependency on OpenDaylight Neutron Northbound QoS yang models, but +that is out of scope of this spec. + +Impact +====== +None + +Assignee(s) +=========== + +Following developers will be the initial contributor to the driver, but we +will be happy to have more contributor on board. + +* Manjeet Singh Bhatia (manjeet.s.bhatia@intel.com, irc: manjeets) + +References +========== + +[1] http://docs.openstack.org/developer/neutron/devref/quality_of_service.html +[2] https://wiki.opendaylight.org/view/NeutronNorthbound:Main diff --git a/networking-odl/doc/source/specs/sfc-driver.rst b/networking-odl/doc/source/specs/sfc-driver.rst new file mode 100644 index 0000000..388b2c1 --- /dev/null +++ b/networking-odl/doc/source/specs/sfc-driver.rst @@ -0,0 +1,139 @@ +================================================= +Service Function Chaining Driver for OpenDaylight +================================================= + +This spec describes the plan to implement OpenStack networking-sfc[1] driver +for OpenDaylight Controller. + +Problem Statement +=================== +OpenStack SFC project (networking-sfc [1]) exposes generic APIs[2] for Service +Function Chaining (SFC) that can be implemented by any backend networking +service provider to support SFC. These APIs provide a way to integrate +OpenStack SFC with any of the backend SFC providers. OpenDaylight SFC project +provides a very mature implementation of SFC [3], but currently there is no +formal integration mechanism present to consume OpenDaylight as an SFC provider +for networking-sfc. + +Recently Tacker project [4] has been approved as an official project in +OpenStack, that opens many possibilities to realize the NFV use cases (e.g SFC) +using OpenStack as a platform. Providing a formal end to end integration +between OpenStack and OpenDaylight for SFC use case will help NFV users +leverage OpenStack, Tacker and OpenDaylight as a solution. A POC for this +integration work has already been implemented [5][6] by Tim Rozet, but in +this POC work, Tacker directly communicates to OpenDaylight SFC & classifier +providers and not through OpenStack SFC APIs (networking-sfc). + +Proposed Change +=============== +Implementation of this spec will introduce a networking-sfc[1] driver for +OpenDaylight Controller in networking-odl project that will pass through +the networking-sfc API's call to the OpenDaylight Controller. + +Detailed Design +=============== +To enable the formal end to end integration between OpenStack SFC and +OpenDaylight requires an SFC driver for OpenDaylight. ODL SFC driver will +act as a shim layer between OpenStack and OpenDaylight that will carry out +following two main tasks: + +* Translation of OpenStack SFC Classifier API to ODL SFC classifier yang + models**. + +* Translation of OpenStack SFC API's to OpenDaylight Neutron Northbound + SFC models** [8]. + +** This work is not yet done, but the OpenDaylight neutron northbound project +needs to come up with yang models for SFC classification/chain. These models +will be based on the existing networking-sfc APIs. This work is out of scope +of networking-odl work and will be collaborated in the scope of OpenDaylight +Neutron Northbound project. + +SFC providers (E.g Net-Virt, GBP, SFC ) in OpenDaylight can listen to these +OpenDaylight Neutron Northbound SFC models and translate it to their specific +yang models for classification/sfc. The following diagram shows the high level +integration between OpenStack and the OpenDaylight SFC provider:: + + +---------------------------------------------+ + | OpenStack Network Server (networking-sfc) | + | +-------------------+ | + | | networking-odl | | + | | SFC Driver | | + | +-------------------+ | + +----------------------|----------------------+ + | REST Communication + | + ----------------------- + OpenDaylight Controller | | + +-----------------------|-----------------------|---------------+ + | +----------v----+ +---v---+ | + | Neutron | SFC Classifier| |SFC | Neutron | + | Northbound | Models | |Models | Northbound| + | Project +---------------+ +-------+ Project | + | / \ | | + | / \ | | + | / \ | | + | +-----V--+ +---V----+ +---V---+ | + | |Net-Virt| ... | GBP | | SFC | ... | + | +---------+ +--------+ +-------+ | + +-----------|----------------|------------------|---------------+ + | | | + | | | + +-----------V----------------V------------------V---------------+ + | Network/OVS | + | | + +---------------------------------------------------------------+ + +In the above architecture, the opendaylight components are shown just to +understand the overall architecture, but it's out of scope of this spec's +work items. This spec will only track progress related to networking-odl +OpenStack sfc driver work. + +Given that OpenStack SFC APIs are port-pair based API's and OpenDaylight SFC +API's are based on IETF SFC yang models[8], there might be situations where +translation might requires API enhancement from OpenStack SFC. Networking SFC +team is open for these new enhancement requirements given that they are generic +enough to be leveraged by other backend SFC providers[9]. This work will be +leveraging the POC work done by Tim [10] to come up with the first version of +SFC driver. + +Dependencies +============ +It has a dependency on OpenDaylight Neutron Northbound SFC classifier and chain +yang models, but that is out of scope of this spec. + +Impact +====== +None + +Assignee(s) +=========== + +Following developers will be the initial contributor to the driver, but we will +be happy to have more contributor on board. + +* Anil Vishnoi (vishnoianil@gmail.com, irc: vishnoianil) +* Tim Rozet (trozet@redhat.com, irc: trozet) + +References +========== + +[1] http://docs.openstack.org/developer/networking-sfc/ + +[2] https://github.com/openstack/networking-sfc/blob/master/doc/source/api.rst + +[3] https://wiki.opendaylight.org/view/Service_Function_Chaining:Main + +[4] https://wiki.openstack.org/wiki/Tacker + +[5] https://github.com/trozet/tacker/tree/SFC_brahmaputra/tacker/sfc + +[6] https://github.com/trozet/tacker/tree/SFC_brahmaputra/tacker/sfc_classifier + +[7] https://tools.ietf.org/html/draft-ietf-netmod-acl-model-05 + +[8] https://wiki.opendaylight.org/view/NeutronNorthbound:Main + +[9] http://eavesdrop.openstack.org/meetings/service_chaining/2016/service_chaining.2016-03-31-17.00.log.html + +[10] https://github.com/trozet/tacker/blob/SFC_brahmaputra/tacker/sfc/drivers/opendaylight.py diff --git a/networking-odl/doc/source/usage.rst b/networking-odl/doc/source/usage.rst new file mode 100644 index 0000000..003ed66 --- /dev/null +++ b/networking-odl/doc/source/usage.rst @@ -0,0 +1,7 @@ +======== +Usage +======== + +To use networking-odl in a project:: + + import networking_odl |