From c0130c57e5138a8906fad7cab9cf820b88064d72 Mon Sep 17 00:00:00 2001 From: Ankur Gupta Date: Wed, 18 May 2016 10:14:19 -0500 Subject: [PATCH] Neutron Feature Classification The feature classification matrix will provide information about plugins and the features they support. Acts as a launching point for users to read about the intent of the matrix before reviewing the matrix to find features and plugins that meet their needs. Will implement a page where users can view Neutron features and plugins and their status. Similar to Nova's implementation here: http://docs.openstack.org/developer/nova/feature_classification.html http://docs.openstack.org/developer/nova/support-matrix.html Co-Authored-By: Darek Smigiel Closes-Bug: #1580327 Change-Id: I67f4dc67883623decdbf136c598eb9e2d0bc24c4 --- doc/source/_static/support_matrix.css | 33 ++ doc/source/conf.py | 6 +- doc/source/ext/support_matrix.py | 482 ++++++++++++++++++ .../feature_classification_introduction.rst | 90 ++++ .../general_feature_support_matrix.ini | 190 +++++++ .../general_feature_support_matrix.rst | 32 ++ doc/source/feature_classification/index.rst | 43 ++ .../provider_network_support_matrix.ini | 54 ++ .../provider_network_support_matrix.rst | 31 ++ doc/source/index.rst | 8 + 10 files changed, 967 insertions(+), 2 deletions(-) create mode 100644 doc/source/_static/support_matrix.css create mode 100644 doc/source/ext/support_matrix.py create mode 100644 doc/source/feature_classification/feature_classification_introduction.rst create mode 100644 doc/source/feature_classification/general_feature_support_matrix.ini create mode 100644 doc/source/feature_classification/general_feature_support_matrix.rst create mode 100644 doc/source/feature_classification/index.rst create mode 100644 doc/source/feature_classification/provider_network_support_matrix.ini create mode 100644 doc/source/feature_classification/provider_network_support_matrix.rst diff --git a/doc/source/_static/support_matrix.css b/doc/source/_static/support_matrix.css new file mode 100644 index 00000000000..267c3425f6c --- /dev/null +++ b/doc/source/_static/support_matrix.css @@ -0,0 +1,33 @@ + +.sp_feature_required { + font-weight: bold; +} + +.sp_impl_complete { + color: rgb(0, 120, 0); + font-weight: normal; +} + +.sp_impl_missing { + color: rgb(120, 0, 0); + font-weight: normal; +} + +.sp_impl_partial { + color: rgb(170, 170, 0); + font-weight: normal; +} + +.sp_impl_unknown { + color: rgb(170, 170, 170); + font-weight: normal; +} + +.sp_impl_summary { + font-size: 2em; +} + +.sp_cli { + font-family: monospace; + background-color: #F5F5F5; +} diff --git a/doc/source/conf.py b/doc/source/conf.py index 7f6aa2a5ba4..513e2255298 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -37,6 +37,7 @@ import warnings BASE_DIR = os.path.dirname(os.path.abspath(__file__)) NEUTRON_DIR = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) sys.path.insert(0, NEUTRON_DIR) +sys.path.append(os.path.abspath("ext")) # -- General configuration --------------------------------------------------- @@ -47,7 +48,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.ifconfig', 'sphinx.ext.graphviz', 'sphinx.ext.todo', - 'oslosphinx'] + 'oslosphinx', + 'support_matrix'] todo_include_todos = True @@ -152,7 +154,7 @@ modindex_common_prefix = ['neutron.'] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/source/ext/support_matrix.py b/doc/source/ext/support_matrix.py new file mode 100644 index 00000000000..28fa1411070 --- /dev/null +++ b/doc/source/ext/support_matrix.py @@ -0,0 +1,482 @@ +# 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. +""" +This provides a sphinx extension able to render the +source/general_feature_support_matrix.ini +file into the developer documentation. + +It is used via a single directive in the .rst file + + .. support_matrix:: + +""" + +import re + +from docutils import nodes +from docutils.parsers import rst +from six.moves import configparser + +RE_PATTERN = re.compile("[^a-zA-Z0-9_]") + + +class SupportMatrix(object): + """Represents the entire support matrix for Neutron drivers""" + + def __init__(self): + self.features = [] + self.targets = {} + + +class SupportMatrixFeature(object): + STATUS_IMMATURE = "immature" + STATUS_MATURE = "mature" + STATUS_REQUIRED = "required" + STATUS_DEPRECATED = "deprecated" + + STATUS_ALL = [STATUS_IMMATURE, STATUS_MATURE, + STATUS_REQUIRED, STATUS_DEPRECATED] + + def __init__(self, key, title, status=STATUS_IMMATURE, + group=None, notes=None, cli=(), api=None): + self.key = key + self.title = title + self.status = status + self.group = group + self.notes = notes + self.cli = cli + self.api = api + + self.implementations = {} + + +class SupportMatrixImplementation(object): + STATUS_COMPLETE = "complete" + STATUS_PARTIAL = "partial" + STATUS_INCOMPLETE = "incomplete" + STATUS_UNKNOWN = "unknown" + + STATUS_ALL = [STATUS_COMPLETE, STATUS_INCOMPLETE, + STATUS_PARTIAL, STATUS_UNKNOWN] + + def __init__(self, status=STATUS_INCOMPLETE, notes=None): + + self.status = status + self.notes = notes + + +STATUS_DICT = { + SupportMatrixImplementation.STATUS_COMPLETE: u"\u2714", + SupportMatrixImplementation.STATUS_INCOMPLETE: u"\u2716", + SupportMatrixImplementation.STATUS_PARTIAL: u"\u2714", + SupportMatrixImplementation.STATUS_UNKNOWN: u"?" +} + + +class SupportMatrixTarget(object): + def __init__(self, key, title, driver, plugin=None, + architecture=None, api=None): + """:param key: Unique identifier for plugin + :param title: Human readable name for plugin + :param driver: name of the driver + :param plugin: optional name of plugin + :param architecture: optional name of architecture + """ + self.api = api + self.key = key + self.title = title + self.driver = driver + self.plugin = plugin + self.architecture = architecture + + +class SupportMatrixDirective(rst.Directive): + + # general_feature_support_matrix.ini is the arg + required_arguments = 1 + + def run(self): + matrix = self._load_support_matrix() + return self._build_markup(matrix) + + def _load_support_matrix(self): + """Reads the support-matrix.ini file and populates an instance + of the SupportMatrix class with all the data. + + :returns: SupportMatrix instance + """ + + cfg = configparser.SafeConfigParser() + env = self.state.document.settings.env + fname = self.arguments[0] + rel_fpath, fpath = env.relfn2path(fname) + with open(fpath) as fp: + cfg.readfp(fp) + + # This ensures that the docs are rebuilt whenever the + # .ini file changes + env.note_dependency(rel_fpath) + + matrix = SupportMatrix() + matrix.targets = self._get_targets(cfg) + matrix.features = self._get_features(cfg, matrix.targets) + + return matrix + + def _get_targets(self, cfg): + # The 'targets' section is special - it lists all the + # backend drivers that this file records data for + + targets = {} + network_target = "networking-" + + for item in cfg.options("targets"): + if not item.startswith(network_target): + continue + + # The driver string will optionally contain + # 'networking-*' qualifier + # so we expect between 1 and 3 components + # in the name + key = item[len(network_target):] + title = cfg.get("targets", item) + name = key.split("-") + if len(name) > 3: + raise Exception("'%s' field is malformed in '[%s]' section" % + (item, "DEFAULT")) + else: + target = SupportMatrixTarget(key, title, *name) + + targets[key] = target + + return targets + + def _get_features(self, cfg, targets): + # All sections except 'targets' describe some feature of + # the Neutron backend driver. + + features = [] + + for section in cfg.sections(): + if section == "targets": + continue + if not cfg.has_option(section, "title"): + raise Exception( + "'title' field missing in '[%s]' section" % section) + + title = cfg.get(section, "title") + + status = SupportMatrixFeature.STATUS_IMMATURE + if cfg.has_option(section, "status"): + # The value is a string "status(group)" where + # the 'group' part is optional + status = cfg.get(section, "status") + offset = status.find("(") + group = None + if offset != -1: + group = status[offset + 1:-1] + status = status[0:offset] + + if status not in SupportMatrixFeature.STATUS_ALL: + raise Exception( + "'status' field value '%s' in ['%s']" + "section must be %s" % + (status, section, + ",".join(SupportMatrixFeature.STATUS_ALL))) + + cli = [] + if cfg.has_option(section, "cli"): + cli = cfg.get(section, "cli") + + api = None + if cfg.has_option(section, "api"): + api = cfg.get(section, "api") + + notes = None + if cfg.has_option(section, "notes"): + notes = cfg.get(section, "notes") + feature = SupportMatrixFeature(section, title, status, group, + notes, cli, api) + + # Now we've got the basic feature details, we must process + # the backend driver implementation for each feature + for item in cfg.options(section): + network_target = "networking-" + network_notes = "networking-notes-" + + if not item.startswith(network_target): + continue + + key = item[len(network_target):] + if key not in targets: + raise Exception( + "networking-'%s' in '[%s]' not declared" % + (item, section)) + + status = cfg.get(section, item) + if status not in SupportMatrixImplementation.STATUS_ALL: + raise Exception( + "'%s' value '%s' in '[%s]' section must be %s" % + (item, status, section, + ",".join(SupportMatrixImplementation.STATUS_ALL))) + notes_key = network_notes + item[len(network_notes):] + notes = None + if cfg.has_option(section, notes_key): + notes = cfg.get(section, notes_key) + + target = targets[key] + impl = SupportMatrixImplementation(status, notes) + feature.implementations[target.key] = impl + + for key in targets: + if key not in feature.implementations: + raise Exception("'%s' missing in '[%s]' section" % + (target.key, section)) + + features.append(feature) + + return features + + def _build_markup(self, matrix): + """Constructs the docutils content for the support matrix + """ + content = [] + self._build_summary(matrix, content) + self._build_details(matrix, content) + self._build_notes(content) + return content + + def _build_summary(self, matrix, content): + """Constructs the docutils content for the summary of + the support matrix. + + The summary consists of a giant table, with one row + for each feature, and a column for each backend + driver. It provides an 'at a glance' summary of the + status of each driver + """ + + summary_title = nodes.subtitle(text="Summary") + summary = nodes.table() + cols = len(matrix.targets.keys()) + cols += 2 + summary_group = nodes.tgroup(cols=cols) + summary_body = nodes.tbody() + summary_head = nodes.thead() + + for i in range(cols): + summary_group.append(nodes.colspec(colwidth=1)) + summary_group.append(summary_head) + summary_group.append(summary_body) + summary.append(summary_group) + content.append(summary_title) + content.append(summary) + + # This sets up all the column headers - two fixed + # columns for feature name & status + header = nodes.row() + blank = nodes.entry() + blank.append(nodes.emphasis(text="Feature")) + header.append(blank) + blank = nodes.entry() + blank.append(nodes.emphasis(text="Status")) + header.append(blank) + summary_head.append(header) + + # then one column for each backend driver + impls = matrix.targets.keys() + impls.sort() + for key in impls: + target = matrix.targets[key] + implcol = nodes.entry() + header.append(implcol) + implcol.append(nodes.strong(text=target.title)) + + # We now produce the body of the table, one row for + # each feature to report on + for feature in matrix.features: + item = nodes.row() + + # the hyperlink target name linking to details + feature_id = re.sub(RE_PATTERN, "_", feature.key) + + # first the fixed columns for title/status + key_col = nodes.entry() + item.append(key_col) + key_ref = nodes.reference(refid=feature_id) + key_txt = nodes.inline() + key_col.append(key_txt) + key_txt.append(key_ref) + key_ref.append(nodes.strong(text=feature.title)) + + status_col = nodes.entry() + item.append(status_col) + status_col.append(nodes.inline( + text=feature.status, + classes=["sp_feature_" + feature.status])) + + # and then one column for each backend driver + impls = matrix.targets.keys() + impls.sort() + for key in impls: + target = matrix.targets[key] + impl = feature.implementations[key] + impl_col = nodes.entry() + item.append(impl_col) + + key_id = re.sub(RE_PATTERN, "_", + "{}_{}".format(feature.key, key)) + + impl_ref = nodes.reference(refid=key_id) + impl_txt = nodes.inline() + impl_col.append(impl_txt) + impl_txt.append(impl_ref) + + status = STATUS_DICT.get(impl.status, "") + + impl_ref.append(nodes.literal( + text=status, + classes=["sp_impl_summary", "sp_impl_" + impl.status])) + + summary_body.append(item) + + def _build_details(self, matrix, content): + """Constructs the docutils content for the details of + the support matrix. + """ + + details_title = nodes.subtitle(text="Details") + details = nodes.bullet_list() + + content.append(details_title) + content.append(details) + + # One list entry for each feature we're reporting on + for feature in matrix.features: + item = nodes.list_item() + + status = feature.status + if feature.group is not None: + status += "({})".format(feature.group) + + feature_id = re.sub(RE_PATTERN, "_", feature.key) + + # Highlight the feature title name + item.append(nodes.strong(text=feature.title, ids=[feature_id])) + + # Add maturity status + para = nodes.paragraph() + para.append(nodes.strong(text="Status: {} ".format(status))) + item.append(para) + + # If API Alias exists add it + if feature.api is not None: + para = nodes.paragraph() + para.append( + nodes.strong(text="API Alias: {} ".format(feature.api))) + item.append(para) + + if feature.cli: + item.append(self._create_cli_paragraph(feature)) + + if feature.notes is not None: + item.append(self._create_notes_paragraph(feature.notes)) + + para_divers = nodes.paragraph() + para_divers.append(nodes.strong(text="Driver Support:")) + # A sub-list giving details of each backend driver target + impls = nodes.bullet_list() + for key in feature.implementations: + target = matrix.targets[key] + impl = feature.implementations[key] + subitem = nodes.list_item() + + key_id = re.sub(RE_PATTERN, "_", + "{}_{}".format(feature.key, key)) + + subitem += [ + nodes.strong(text="{}: ".format(target.title)), + nodes.literal(text=impl.status, + classes=["sp_impl_{}".format(impl.status)], + ids=[key_id]), + ] + if impl.notes is not None: + subitem.append(self._create_notes_paragraph(impl.notes)) + impls.append(subitem) + + para_divers.append(impls) + item.append(para_divers) + details.append(item) + + def _build_notes(self, content): + """Constructs a list of notes content for the support matrix. + + This is generated as a bullet list. + """ + notes_title = nodes.subtitle(text="Notes:") + notes = nodes.bullet_list() + + content.append(notes_title) + content.append(notes) + + for note in ["This document is a continuous work in progress"]: + item = nodes.list_item() + item.append(nodes.strong(text=note)) + notes.append(item) + + def _create_cli_paragraph(self, feature): + """Create a paragraph which represents the CLI commands of the feature + + The paragraph will have a bullet list of CLI commands. + """ + para = nodes.paragraph() + para.append(nodes.strong(text="CLI commands:")) + commands = nodes.bullet_list() + for c in feature.cli.split(";"): + cli_command = nodes.list_item() + cli_command += nodes.literal(text=c, classes=["sp_cli"]) + commands.append(cli_command) + para.append(commands) + return para + + def _create_notes_paragraph(self, notes): + """Constructs a paragraph which represents the implementation notes + + The paragraph consists of text and clickable URL nodes if links were + given in the notes. + """ + para = nodes.paragraph() + para.append(nodes.strong(text="Notes: ")) + # links could start with http:// or https:// + link_idxs = [m.start() for m in re.finditer('https?://', notes)] + start_idx = 0 + for link_idx in link_idxs: + # assume the notes start with text (could be empty) + para.append(nodes.inline(text=notes[start_idx:link_idx])) + # create a URL node until the next text or the end of the notes + link_end_idx = notes.find(" ", link_idx) + if link_end_idx == -1: + # In case the notes end with a link without a blank + link_end_idx = len(notes) + uri = notes[link_idx:link_end_idx + 1] + para.append(nodes.reference("", uri, refuri=uri)) + start_idx = link_end_idx + 1 + + # get all text after the last link (could be empty) or all of the + # text if no link was given + para.append(nodes.inline(text=notes[start_idx:])) + return para + + +def setup(app): + app.add_directive('support_matrix', SupportMatrixDirective) + app.add_stylesheet('support_matrix.css') diff --git a/doc/source/feature_classification/feature_classification_introduction.rst b/doc/source/feature_classification/feature_classification_introduction.rst new file mode 100644 index 00000000000..27ac7facd9b --- /dev/null +++ b/doc/source/feature_classification/feature_classification_introduction.rst @@ -0,0 +1,90 @@ +============ +Introduction +============ + +This document describes how features are listed in +:doc:`general_feature_support_matrix` and :doc:`provider_network_support_matrix`. + +Goals +~~~~~ + +The object of this document is to inform users whether or not +features are complete, well-documented, stable, and tested. +This approach ensures a good user-experience for those well-maintained features. + +.. note:: + + Tests are specific to particular combinations of technologies. + The plugins chosen for deployment make a big difference to whether + or not features will work. + + +Concepts +~~~~~~~~ + +These definitions clarify the terminology used throughout this document. + +Feature status +~~~~~~~~~~~~~~ + +* Immature +* Mature +* Required +* Deprecated (scheduled to be removed in a future release) + +Immature +-------- + +Immature features do not have enough functionality to satisfy real-world +use cases. + +An immature feature is a feature being actively developed, which is only +partially functional and upstream tested, most likely introduced in a +recent release, and that will take time to mature thanks to feedback +from downstream QA. + +Users of these features will likely identify gaps and/or defects +that were not identified during specification and code review. + +Mature +------ + +A feature is considered mature if it satisfies the following criteria: + +* Complete API documentation including concept and REST call definition. +* Complete Administrator documentation. +* Tempest tests that define the correct functionality of the feature. +* Enough functionality and reliability to be useful in real-world scenarios. +* Low probability of support for the feature being dropped. + +Required +-------- + +Required features are core networking principles that have been thoroughly +tested and have been implemented in real-world use cases. + +In addition they satisfy the same criteria for any mature features. + +.. note:: + + Any new drivers must prove that they support all required features + before they are merged into neutron. + + +Deprecated +---------- + +Deprecated features are no longer supported and only security related fixes +or development will happen towards them. + +Deployment rating of features +----------------------------- + +The deployment rating shows only the state of the tests for each +feature on a particular deployment. + +.. important:: + + Despite the obvious parallels that could be drawn, this list is + unrelated to the DefCore effort. + See `InteropWG `_ diff --git a/doc/source/feature_classification/general_feature_support_matrix.ini b/doc/source/feature_classification/general_feature_support_matrix.ini new file mode 100644 index 00000000000..b2b3dfdde7e --- /dev/null +++ b/doc/source/feature_classification/general_feature_support_matrix.ini @@ -0,0 +1,190 @@ +# 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. + +[targets] +networking-ovs=Open vSwitch +networking-linux-bridge=Linux Bridge +networking-odl=Networking ODL +networking-midonet=Networking MidoNet +networking-ovn=Networking OVN + +[operation.Networks] +title=Networks +status=required +api=core +cli=openstack network * +notes=The ability to create, modify and delete networks. + Other OpenStack Client commands are create, delete, list, + segment list, segment show, set, show. +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=complete +networking-ovn=complete + +[operation.Subnets] +title=Subnets +status=required +api=core +cli=openstack subnet * +notes=The ability to create and manipulate subnets and subnet pools. + Other OpenStack Client commands are create, delete, list, + pool create, pool delete, pool list, pool set, pool show, + set, show. +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=complete +networking-ovn=complete + +[operation.Ports] +title=Ports +status=required +api=core +cli=openstack port * +notes=The ability to create and manipulate ports. + Other OpenStack Client commands are create, delete, list, set, + show. +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=complete +networking-ovn=complete + +[operation.Router] +title=Routers +status=required +api=router +cli=openstack router * +notes=The ability to create and manipulate routers. + Other OpenStack Client commands are create, add port, + add subnet, delete, list, remove port, remove subnet, + set, show. +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=complete +networking-ovn=complete + +[operation.Security_Groups] +title=Security Groups +status=mature +api=security-group +cli=openstack security group * +notes=Security groups are set by default, and can be modified to control + ingress & egress traffic. + Other OpenStack Client commands are create, delete, list, rule create, + rule delete, rule list, rule show, set, show. +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=complete +networking-ovn=complete + +[operation.External_Nets] +title=External Networks +status=mature +api=external-net +notes=The ability to create an external network to provide internet access + to and from instances using floating IP addresses and security group rules. +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=complete +networking-ovn=complete + +[operation.DVR] +title=Distributed Virtual Routers +status=immature +api=dvr +notes=The ability to support the distributed virtual routers. +networking-ovs=complete +networking-linux-bridge=incomplete +networking-odl=partial +networking-midonet=complete +networking-ovn=partial + +[operation.L3_HA] +title=L3 High Availability +status=immature +api=l3-ha +notes=The ability to support the High Availability features and extensions. + https://wiki.openstack.org/wiki/Neutron/L3_High_Availability_VRRP. +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=partial +networking-midonet=incomplete +networking-ovn=partial + +[operation.QoS] +title=Quality of Service +status=mature +api=qos +notes=Support for Neutron Quality of Service policies and API. +networking-ovs=complete +networking-linux-bridge=partial +networking-odl=partial +networking-midonet=complete +networking-ovn=complete + +[operation.BGP] +title=Border Gateway Protocol +status=immature +networking-ovs=complete +networking-linux-bridge=unknown +networking-odl=unknown +networking-midonet=complete +networking-ovn=unknown + +[operation.DNS] +title=DNS +status=mature +api=dns-integration +notes=The ability to integrate with an external DNS + as a Service. http://docs.openstack.org/newton/ + networking-guide/config-dns-int.html +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=incomplete +networking-ovn=complete + +[operation.Trunk_Ports] +title=Trunk Ports +status=mature +api=trunk +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=incomplete +networking-midonet=incomplete +networking-ovn=complete + +[operation.Metering] +title=Metering +status=mature +api=metering +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=incomplete +networking-midonet=incomplete +networking-ovn=unknown + +[operations.Routed_Provider_Networks] +title=Routed Provider Networks +status=immature +notes=The ability to present a multi-segment layer-3 + network as a single entity +networking-ovs=partial +networking-linux-bridge=partial +networking-odl=incomplete +networking-midonet=incomplete +networking-ovn=partial diff --git a/doc/source/feature_classification/general_feature_support_matrix.rst b/doc/source/feature_classification/general_feature_support_matrix.rst new file mode 100644 index 00000000000..21d753142a5 --- /dev/null +++ b/doc/source/feature_classification/general_feature_support_matrix.rst @@ -0,0 +1,32 @@ +======================= +General Feature Support +======================= + +.. warning:: + Please note, while this document is still being maintained, this is slowly + being updated to re-group and classify features using the definitions + described in here: :doc:`feature_classification_introduction`. + +This document covers the maturity and support of the Neutron API +and its API extensions. Details about the API can be found at +`Networking API v2.0 `_. + +When considering which capabilities should be marked as mature the +following general guiding principles were applied: + +* **Inclusivity** - people have shown ability to make effective + use of a wide range of network plugins and drivers with broadly + varying feature sets. Aiming to keep the requirements as inclusive + as possible, avoids second-guessing how a user wants to use their + networks. + +* **Bootstrapping** - a practical use case test is to consider that + starting point for the network deploy is an empty data center + with new machines and network connectivity. Then look at what + are the minimum features required of the network service, in order + to get user instances running and connected over the network. + +* **Reality** - there are many networking drivers and plugins compatible with + neutron. Each with their own supported feature set. + +.. support_matrix:: general_feature_support_matrix.ini diff --git a/doc/source/feature_classification/index.rst b/doc/source/feature_classification/index.rst new file mode 100644 index 00000000000..b3fb5e7c2b5 --- /dev/null +++ b/doc/source/feature_classification/index.rst @@ -0,0 +1,43 @@ +.. + Copyright 2010-2011 United States Government as represented by the + Administrator of the National Aeronautics and Space Administration. + All Rights Reserved. + + 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. + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Neutron Feature Classification +============================== + +.. toctree:: + :maxdepth: 3 + + feature_classification_introduction + general_feature_support_matrix + provider_network_support_matrix + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/feature_classification/provider_network_support_matrix.ini b/doc/source/feature_classification/provider_network_support_matrix.ini new file mode 100644 index 00000000000..0ed74bd5076 --- /dev/null +++ b/doc/source/feature_classification/provider_network_support_matrix.ini @@ -0,0 +1,54 @@ +# 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. + +[targets] +networking-ovs=Open vSwitch +networking-linux-bridge=Linux Bridge +networking-odl=Networking ODL +networking-midonet=Networking MidoNet +networking-ovn=Networking OVN + +[operation.VLAN] +title=VLAN provider network support +status=mature +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=unknown +networking-midonet=incomplete +networking-ovn=complete + +[operation.VXLAN] +title=VXLAN provider network support +status=mature +networking-ovs=complete +networking-linux-bridge=complete +networking-odl=complete +networking-midonet=incomplete +networking-ovn=incomplete + +[operation.GRE] +title=GRE provider network support +status=immature +networking-ovs=complete +networking-linux-bridge=unknown +networking-odl=complete +networking-midonet=incomplete +networking-ovn=incomplete + +[operation.Geneve] +title=Geneve provider network support +status=immature +networking-ovs=complete +networking-linux-bridge=unknown +networking-odl=incomplete +networking-midonet=incomplete +networking-ovn=complete diff --git a/doc/source/feature_classification/provider_network_support_matrix.rst b/doc/source/feature_classification/provider_network_support_matrix.rst new file mode 100644 index 00000000000..19fb3c4d598 --- /dev/null +++ b/doc/source/feature_classification/provider_network_support_matrix.rst @@ -0,0 +1,31 @@ +======================== +Provider Network Support +======================== + +.. warning:: + Please note, while this document is still being maintained, this is slowly + being updated to re-group and classify features using the definitions + described in here: :doc:`feature_classification_introduction`. + +This document covers the maturity and support for various +network isolation technologies. + +When considering which capabilities should be marked as mature the +following general guiding principles were applied: + +* **Inclusivity** - people have shown ability to make effective + use of a wide range of network plugins and drivers with broadly + varying feature sets. Aiming to keep the requirements as inclusive + as possible, avoids second-guessing how a user wants to use their + networks. + +* **Bootstrapping** - a practical use case test is to consider that + starting point for the network deploy is an empty data center + with new machines and network connectivity. Then look at what + are the minimum features required of the network service, in order + to get user instances running and connected over the network. + +* **Reality** - there are many networking drivers and plugins compatible with + neutron. Each with their own supported feature set. + +.. support_matrix:: provider_network_support_matrix.ini diff --git a/doc/source/index.rst b/doc/source/index.rst index 8c3825a8fea..0a243853da0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -55,6 +55,14 @@ Neutron Stadium stadium/index +Neutron Feature Classification +============================== + +.. toctree:: + :maxdepth: 3 + + feature_classification/index + Developer Docs ==============