From 2504016a3def2596d6985d7d6a29c3aa0d66453e Mon Sep 17 00:00:00 2001 From: Sumit Naiksatam Date: Tue, 23 Sep 2014 08:53:32 -0700 Subject: [PATCH] Initial commit with GBP spec and repo artifacts The previously approved GBP spec is being filed here. (Earlier gerrit review: https://review.openstack.org/#/c/89469) Change-Id: Ic5e212e58ff4bdfbe211eaa936ad96b0fcfbf79f --- LICENSE | 3 + README.rst | 39 + doc/source/conf.py | 283 ++++++ doc/source/index.rst | 19 + doc/source/specs/skeleton.rst | 82 ++ doc/source/specs/template.rst | 409 ++++++++ requirements.txt | 15 + setup.cfg | 23 + setup.py | 22 + specs/juno/example.rst | 407 ++++++++ specs/juno/group-based-policy-abstraction.rst | 879 ++++++++++++++++++ specs/skeleton.rst | 82 ++ specs/template.rst | 409 ++++++++ tests/__init__.py | 0 tests/test_titles.py | 104 +++ tox.ini | 17 + 16 files changed, 2793 insertions(+) create mode 100644 LICENSE create mode 100644 README.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 doc/source/specs/skeleton.rst create mode 100644 doc/source/specs/template.rst create mode 100644 requirements.txt create mode 100644 setup.cfg create mode 100755 setup.py create mode 100644 specs/juno/example.rst create mode 100644 specs/juno/group-based-policy-abstraction.rst create mode 100644 specs/skeleton.rst create mode 100644 specs/template.rst create mode 100644 tests/__init__.py create mode 100644 tests/test_titles.py create mode 100644 tox.ini diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..75a29c4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,3 @@ +This work is licensed under a Creative Commons Attribution 3.0 Unported License. + +http://creativecommons.org/licenses/by/3.0/legalcode diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..582d54b --- /dev/null +++ b/README.rst @@ -0,0 +1,39 @@ +================================== +Group Based Policy Specifications +================================== + +This git repository is used to hold approved design specifications for additions +to the Group Based Policy project. Reviews of the specs are done in gerrit, using a +similar workflow to how we review and merge changes to the code itself. + +The layout of this repository is:: + + specs// + +You can find an example spec in `doc/source/specs/template.rst`. A +skeleton that contains all the sections required for a spec +file is located in `doc/source/specs/skeleton.rst` and can +be copied, then filled in with the details of a new blueprint for +convenience. + +Specifications are proposed for a given release by adding them to the +`specs/` directory and posting it for review. The implementation +status of a blueprint for a given release can be found by looking at the +blueprint in launchpad. Not all approved blueprints will get fully implemented. + +Specifications have to be re-proposed for every release. The review may be +quick, but even if something was previously approved, it should be re-reviewed +to make sure it still makes sense as written. + +For more information about working with gerrit, see:: + + https://wiki.openstack.org/wiki/Gerrit_Workflow + +To validate that the specification is syntactically correct (i.e. get more +confidence in the Jenkins result), please execute the following command:: + + $ tox + +After running ``tox``, the documentation will be available for viewing in HTML +format in the ``doc/build/`` directory. Please do not check in the generated +HTML files as a part of your commit. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..3e5747f --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,283 @@ +# -*- coding: utf-8 -*- +# +# Tempest documentation build configuration file, created by +# sphinx-quickstart on Tue May 21 17:43:32 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import datetime +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# 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', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinxcontrib.blockdiag', + 'sphinxcontrib.actdiag', + 'sphinxcontrib.seqdiag', + 'sphinxcontrib.nwdiag', + 'oslosphinx', + 'yasfb', + ] + +# Feed configuration for yasfb +feed_base_url = 'http://specs.openstack.org/openstack/group-based-policy-specs' +feed_author = 'Group Based Policy Team' + +todo_include_todos = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Group Based Policy Specs' +copyright = u'%s, Group Based Policy Team' % datetime.date.today().year + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [ + '_build', + '**/example.rst', + '**/template.rst', + '**/skeleton.rst', +] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# 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 = False + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +modindex_common_prefix = ['group-based-policy-specs.'] + +# -- Options for man page output ---------------------------------------------- +man_pages = [] + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'nature' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1" +html_last_updated_fmt = os.popen(git_cmd).read() + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_domain_indices = False + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Group-based-policy-Specsdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Group-based-Policy-specs.tex', u'Group-based-Policy Specs', + u'Group Based Policy Team', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Group-based-policy-specs', u'Group baed Policy Design Specs', + u'Group Based Policy Team', 'group-based-policy-specs', 'Design +specifications for the Group Based Policy project.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'Group Based Policy Specs' +epub_author = u'Group Based Policy Team' +epub_publisher = u'Group Based Policy Team' +epub_copyright = u'2014, Group Based Policy Team' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..3aa611e --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,19 @@ +.. group-based-policy-specs documentation master file + +========================================= +Group Based Policy Project Specifications +========================================= + +Juno approved specs: + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/juno/* + +================== +Indices and tables +================== + +* :ref:`search` diff --git a/doc/source/specs/skeleton.rst b/doc/source/specs/skeleton.rst new file mode 100644 index 0000000..ba77613 --- /dev/null +++ b/doc/source/specs/skeleton.rst @@ -0,0 +1,82 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================== +Title of your blueprint +========================================== + + +Problem description +=================== + + +Proposed change +=============== + + +Alternatives +------------ + + +Data model impact +----------------- + + +REST API impact +--------------- + + +Security impact +--------------- + + +Notifications impact +-------------------- + + +Other end user impact +--------------------- + + +Performance Impact +------------------ + + +Other deployer impact +--------------------- + + +Developer impact +---------------- + + +Implementation +============== + +Assignee(s) +----------- + + +Work Items +---------- + + +Dependencies +============ + + +Testing +======= + + +Documentation Impact +==================== + + +References +========== + + diff --git a/doc/source/specs/template.rst b/doc/source/specs/template.rst new file mode 100644 index 0000000..a1ab473 --- /dev/null +++ b/doc/source/specs/template.rst @@ -0,0 +1,409 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================== +Example Spec - The title of your blueprint +========================================== + +Include the URL of your launchpad blueprint: + +Introduction paragraph -- why are we doing anything? A single paragraph of +prose that operators can understand. + +Some notes about using this template: + +* Your spec should be in ReSTructured text, like this template. + +* Please wrap text at 80 columns. + +* Please do not delete any of the sections in this template. If you have + nothing to say for a whole section, just write: None + +* For help with syntax, see http://sphinx-doc.org/rest.html + +* To test out your formatting, build the docs using tox, or see: + http://rst.ninjs.org + +* If you would like to provide a diagram with your spec, text representations + are preferred. http://asciiflow.com/ is a very nice tool to assist with + making ascii diagrams. blockdiag is another tool. These are described below. + If you require an image (screenshot) for your BP, attaching that to the BP + and checking it in is also accepted. However, text representations are prefered. + +* Diagram examples + +asciiflow:: + + +----------+ +-----------+ +----------+ + | A | | B | | C | + | +-----+ +--------+ | + +----------+ +-----------+ +----------+ + +blockdiag + +.. blockdiag:: + + blockdiag sample { + a -> b -> c; + } + +actdiag + +.. actdiag:: + + actdiag { + write -> convert -> image + lane user { + label = "User" + write [label = "Writing reST"]; + image [label = "Get diagram IMAGE"]; + } + lane actdiag { + convert [label = "Convert reST to Image"]; + } + } + +nwdiag + +.. nwdiag:: + + nwdiag { + network dmz { + address = "210.x.x.x/24" + + web01 [address = "210.x.x.1"]; + web02 [address = "210.x.x.2"]; + } + network internal { + address = "172.x.x.x/24"; + + web01 [address = "172.x.x.1"]; + web02 [address = "172.x.x.2"]; + db01; + db02; + } + } + + +seqdiag + +.. seqdiag:: + + seqdiag { + browser -> webserver [label = "GET /index.html"]; + browser <-- webserver; + browser -> webserver [label = "POST /blog/comment"]; + webserver -> database [label = "INSERT comment"]; + webserver <-- database; + browser <-- webserver; + } + + + +Problem description +=================== + +A detailed description of the problem: + +* For a new feature this might be use cases. Ensure you are clear about the + actors in each use case: End User vs Deployer + +* For a major reworking of something existing it would describe the + problems in that feature that are being addressed. + + +Proposed change +=============== + +Here is where you cover the change you propose to make in detail. How do you +propose to solve this problem? + +If this is one part of a larger effort make it clear where this piece ends. In +other words, what's the scope of this effort? + +Alternatives +------------ + +What other ways could we do this thing? Why aren't we using those? This doesn't +have to be a full literature review, but it should demonstrate that thought has +been put into why the proposed solution is an appropriate one. + +Data model impact +----------------- + +Changes which require modifications to the data model often have a wider impact +on the system. The community often has strong opinions on how the data model +should be evolved, from both a functional and performance perspective. It is +therefore important to capture and gain agreement as early as possible on any +proposed changes to the data model. + +Questions which need to be addressed by this section include: + +* What new data objects and/or database schema changes is this going to require? + +* What database migrations will accompany this change. + +* How will the initial set of new data objects be generated, for example if you + need to take into account existing instances, or modify other existing data + describe how that will work. + +REST API impact +--------------- + +For each API resource to be implemented using attribute map +facility, describe the resource collection and specify the name, +type, and other essential details of each new or modified attribute. +A table similar to the following may be used: + ++----------+-------+---------+---------+------------+--------------+ +|Attribute |Type |Access |Default |Validation/ |Description | +|Name | | |Value |Conversion | | ++==========+=======+=========+=========+============+==============+ +|id |string |RO, all |generated|N/A |identity | +| |(UUID) | | | | | ++----------+-------+---------+---------+------------+--------------+ +|name |string |RW, all |'' |string |human-readable| +| | | | | |name | ++----------+-------+---------+---------+------------+--------------+ +|color |string |RW, admin|'red' |'red', |color | +| | | | |'yellow', or|indicating | +| | | | |'green' |state | ++----------+-------+---------+---------+------------+--------------+ + + +Here is the other example of the table using csv-table + + +.. csv-table:: CSVTable + :header: Attribute Name,Type,Access,Default Value,Validation Conversion,Description + + id,string (UUID),"RO, all",generated,N/A,identity + name,string,"RW, all","''",string,human-readable name + color,string,"RW, admin",red,"'red', 'yellow' or 'green'",color indicating state + + +Each API method which is either added or changed that does not use +Neutron's attribute map facility should have the following: + +* Specification for the method + + * A description of what the method does suitable for use in + user documentation + + * Method type (POST/PUT/GET/DELETE) + + * Normal http response code(s) + + * Expected error http response code(s) + + * A description for each possible error code should be included + describing semantic errors which can cause it such as + inconsistent parameters supplied to the method, or when an + instance is not in an appropriate state for the request to + succeed. Errors caused by syntactic problems covered by the JSON + schema defintion do not need to be included. + + * URL for the resource + + * Parameters which can be passed via the url + + * JSON schema definition for the body data if allowed + + * JSON schema definition for the response data if any + +* Example use case including typical API samples for both data supplied + by the caller and the response + +* Discuss any API policy changes, and discuss what things a deployer needs to + think about when defining their API policy. This is in reference to the + policy.json file. + +Note that the schema should be defined as restrictively as +possible. Parameters which are required should be marked as such and +only under exceptional circumstances should additional parameters +which are not defined in the schema be permitted (eg +additionaProperties should be False). + +Reuse of existing predefined parameter types such as regexps for +passwords and user defined names is highly encouraged. + +Security impact +--------------- + +Describe any potential security impact on the system. Some of the items to +consider include: + +* Does this change touch sensitive data such as tokens, keys, or user data? + +* Does this change alter the API in a way that may impact security, such as + a new way to access sensitive information or a new way to login? + +* Does this change involve cryptography or hashing? + +* Does this change require the use of sudo or any elevated privileges? + +* Does this change involve using or parsing user-provided data? This could + be directly at the API level or indirectly such as changes to a cache layer. + +* Can this change enable a resource exhaustion attack, such as allowing a + single API interaction to consume significant server resources? Some examples + of this include launching subprocesses for each connection, or entity + expansion attacks in XML. + +For more detailed guidance, please see the OpenStack Security Guidelines as +a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These +guidelines are a work in progress and are designed to help you identify +security best practices. For further information, feel free to reach out +to the OpenStack Security Group at openstack-security@lists.openstack.org. + +Notifications impact +-------------------- + +Please specify any changes to notifications. Be that an extra notification, +changes to an existing notification, or removing a notification. + +Other end user impact +--------------------- + +Aside from the API, are there other ways a user will interact with this feature? + +* Does this change have an impact on python client? What does the user + interface there look like? + +Performance Impact +------------------ + +Describe any potential performance impact on the system, for example +how often will new code be called, and is there a major change to the calling +pattern of existing code. + +Examples of things to consider here include: + +* A periodic task might look like a small addition but if it calls conductor or + another service the load is multiplied by the number of nodes in the system. + +* A small change in a utility function or a commonly used decorator can have a + large impacts on performance. + +* Calls which result in a database queries (whether direct or via conductor) can + have a profound impact on performance when called in critical sections of the + code. + +* Will the change include any locking, and if so what considerations are there on + holding the lock? + +Other deployer impact +--------------------- + +Discuss things that will affect how you deploy and configure OpenStack +that have not already been mentioned, such as: + +* What config options are being added? Should they be more generic than + proposed (for example a flag that other hypervisor drivers might want to + implement as well)? Are the default values ones which will work well in + real deployments? + +* Is this a change that takes immediate effect after its merged, or is it + something that has to be explicitly enabled? + +* If this change is a new binary, how would it be deployed? + +* Please state anything that those doing continuous deployment, or those + upgrading from the previous release, need to be aware of. Also describe + any plans to deprecate configuration values or features. For example, if we + change the directory name that instances are stored in, how do we handle + instance directories created before the change landed? Do we move them? Do + we have a special case in the code? Do we assume that the operator will + recreate all the instances in their cloud? + +Developer impact +---------------- + +Discuss things that will affect other developers working on OpenStack, +such as: + +* If the blueprint proposes a change to the API, discussion of how other + plugins would implement the feature is required. + + +Implementation +============== + +Assignee(s) +----------- + +Who is leading the writing of the code? Or is this a blueprint where you're +throwing it out there to see who picks it up? + +If more than one person is working on the implementation, please designate the +primary author and contact. + +Primary assignee: + + +Other contributors: + + +Work Items +---------- + +Work items or tasks -- break the feature up into the things that need to be +done to implement it. Those parts might end up being done by different people, +but we're mostly trying to understand the timeline for implementation. + + +Dependencies +============ + +* Include specific references to specs and/or blueprints in other + projects, that this one either depends on or is related to. + +* If this requires functionality of another project that is not currently used + by Neutron (such as the glance v2 API when we previously only required v1), + document that fact. + +* Does this feature require any new library dependencies or code otherwise not + included in OpenStack? Or does it depend on a specific version of library? + + +Testing +======= + +Please discuss how the change will be tested. We especially want to know what +tempest tests will be added. It is assumed that unit test coverage will be +added so that doesn't need to be mentioned explicitly, but discussion of why +you think unit tests are sufficient and we don't need to add more tempest +tests would need to be included. + +Is this untestable in gate given current limitations (specific hardware / +software configurations available)? If so, are there mitigation plans (3rd +party testing, gate enhancements, etc). + + +Documentation Impact +==================== + +What is the impact on the docs team of this change? Some changes might require +donating resources to the docs team to have the documentation updated. Don't +repeat details discussed above, but please reference them here. + + +References +========== + +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable. Examples of what you could include are: + +* Links to mailing list or IRC discussions + +* Links to notes from a summit session + +* Links to relevant research, if appropriate + +* Related specifications as appropriate (e.g. link any vendor documentation) + +* Anything else you feel it is worthwhile to refer to diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..d7f5f8b --- /dev/null +++ b/requirements.txt @@ -0,0 +1,15 @@ +actdiag +blockdiag +docutils==0.9.1 +nwdiag +oslosphinx +pbr>=0.6,!=0.7,<1.0 +seqdiag +sphinx>=1.1.2,<1.2 +sphinxcontrib-actdiag +sphinxcontrib-blockdiag +sphinxcontrib-nwdiag +sphinxcontrib-seqdiag +testrepository>=0.0.18 +testtools>=0.9.34 +yasfb>=0.5.1 diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..76368cd --- /dev/null +++ b/setup.cfg @@ -0,0 +1,23 @@ +[metadata] +name = group-based-policy-specs +summary = Group based Policy Project Development Specs +description-file = + README.rst +author = OpenStack +author-email = openstack-dev@lists.openstack.org +home-page = http://www.openstack.org/ +classifier = + Intended Audience :: Developers + License :: OSI Approved :: Apache Software License + Operating System :: POSIX :: Linux + +[build_sphinx] +all_files = 1 +build-dir = doc/build +source-dir = doc/source + +[pbr] +warnerrors = True + +[wheel] +universal = 1 diff --git a/setup.py b/setup.py new file mode 100755 index 0000000..70c2b3f --- /dev/null +++ b/setup.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python +# Copyright (c) 2013 Hewlett-Packard Development Company, L.P. +# +# 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 FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT +import setuptools + +setuptools.setup( + setup_requires=['pbr'], + pbr=True) diff --git a/specs/juno/example.rst b/specs/juno/example.rst new file mode 100644 index 0000000..8c464d2 --- /dev/null +++ b/specs/juno/example.rst @@ -0,0 +1,407 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================== +Example Spec - The title of your blueprint +========================================== + +Introduction paragraph -- why are we doing anything? A single paragraph of +prose that operators can understand. + +Some notes about using this template: + +* Your spec should be in ReSTructured text, like this template. + +* Please wrap text at 80 columns. + +* Please do not delete any of the sections in this template. If you have + nothing to say for a whole section, just write: None + +* For help with syntax, see http://sphinx-doc.org/rest.html + +* To test out your formatting, build the docs using tox, or see: + http://rst.ninjs.org + +* If you would like to provide a diagram with your spec, text representations + are preferred. http://asciiflow.com/ is a very nice tool to assist with + making ascii diagrams. blockdiag is another tool. These are described below. + If you require an image (screenshot) for your BP, attaching that to the BP + and checking it in is also accepted. However, text representations are prefered. + +* Diagram examples + +asciiflow:: + + +----------+ +-----------+ +----------+ + | A | | B | | C | + | +-----+ +--------+ | + +----------+ +-----------+ +----------+ + +blockdiag + +.. blockdiag:: + + blockdiag sample { + a -> b -> c; + } + +actdiag + +.. actdiag:: + + actdiag { + write -> convert -> image + lane user { + label = "User" + write [label = "Writing reST"]; + image [label = "Get diagram IMAGE"]; + } + lane actdiag { + convert [label = "Convert reST to Image"]; + } + } + +nwdiag + +.. nwdiag:: + + nwdiag { + network dmz { + address = "210.x.x.x/24" + + web01 [address = "210.x.x.1"]; + web02 [address = "210.x.x.2"]; + } + network internal { + address = "172.x.x.x/24"; + + web01 [address = "172.x.x.1"]; + web02 [address = "172.x.x.2"]; + db01; + db02; + } + } + + +seqdiag + +.. seqdiag:: + + seqdiag { + browser -> webserver [label = "GET /index.html"]; + browser <-- webserver; + browser -> webserver [label = "POST /blog/comment"]; + webserver -> database [label = "INSERT comment"]; + webserver <-- database; + browser <-- webserver; + } + + + +Problem description +=================== + +A detailed description of the problem: + +* For a new feature this might be use cases. Ensure you are clear about the + actors in each use case: End User vs Deployer + +* For a major reworking of something existing it would describe the + problems in that feature that are being addressed. + + +Proposed change +=============== + +Here is where you cover the change you propose to make in detail. How do you +propose to solve this problem? + +If this is one part of a larger effort make it clear where this piece ends. In +other words, what's the scope of this effort? + +Alternatives +------------ + +What other ways could we do this thing? Why aren't we using those? This doesn't +have to be a full literature review, but it should demonstrate that thought has +been put into why the proposed solution is an appropriate one. + +Data model impact +----------------- + +Changes which require modifications to the data model often have a wider impact +on the system. The community often has strong opinions on how the data model +should be evolved, from both a functional and performance perspective. It is +therefore important to capture and gain agreement as early as possible on any +proposed changes to the data model. + +Questions which need to be addressed by this section include: + +* What new data objects and/or database schema changes is this going to require? + +* What database migrations will accompany this change. + +* How will the initial set of new data objects be generated, for example if you + need to take into account existing instances, or modify other existing data + describe how that will work. + +REST API impact +--------------- + +For each API resource to be implemented using the attribute map +facility, describe the resource collection and specify the name, +type, and other essential details of each new or modified attribute. +A table similar to the following may be used: + ++----------+-------+---------+---------+------------+--------------+ +|Attribute |Type |Access |Default |Validation/ |Description | +|Name | | |Value |Conversion | | ++==========+=======+=========+=========+============+==============+ +|id |string |RO, all |generated|N/A |identity | +| |(UUID) | | | | | ++----------+-------+---------+---------+------------+--------------+ +|name |string |RW, all |'' |string |human-readable| +| | | | | |name | ++----------+-------+---------+---------+------------+--------------+ +|color |string |RW, admin|'red' |'red', |color | +| | | | |'yellow', or|indicating | +| | | | |'green' |state | ++----------+-------+---------+---------+------------+--------------+ + + +Here is the other example of the table using csv-table + + +.. csv-table:: CSVTable + :header: Attribute Name,Type,Access,Default Value,Validation Conversion,Description + + id,string (UUID),"RO, all",generated,N/A,identity + name,string,"RW, all","''",string,human-readable name + color,string,"RW, admin",red,"'red', 'yellow' or 'green'",color indicating state + + +Each API method which is either added or changed that does not use +Neutron's attribute map facility should have the following: + +* Specification for the method + + * A description of what the method does suitable for use in + user documentation + + * Method type (POST/PUT/GET/DELETE) + + * Normal http response code(s) + + * Expected error http response code(s) + + * A description for each possible error code should be included + describing semantic errors which can cause it such as + inconsistent parameters supplied to the method, or when an + instance is not in an appropriate state for the request to + succeed. Errors caused by syntactic problems covered by the JSON + schema defintion do not need to be included. + + * URL for the resource + + * Parameters which can be passed via the url + + * JSON schema definition for the body data if allowed + + * JSON schema definition for the response data if any + +* Example use case including typical API samples for both data supplied + by the caller and the response + +* Discuss any API policy changes, and discuss what things a deployer needs to + think about when defining their API policy. This is in reference to the + policy.json file. + +Note that the schema should be defined as restrictively as +possible. Parameters which are required should be marked as such and +only under exceptional circumstances should additional parameters +which are not defined in the schema be permitted (eg +additionaProperties should be False). + +Reuse of existing predefined parameter types such as regexps for +passwords and user defined names is highly encouraged. + +Security impact +--------------- + +Describe any potential security impact on the system. Some of the items to +consider include: + +* Does this change touch sensitive data such as tokens, keys, or user data? + +* Does this change alter the API in a way that may impact security, such as + a new way to access sensitive information or a new way to login? + +* Does this change involve cryptography or hashing? + +* Does this change require the use of sudo or any elevated privileges? + +* Does this change involve using or parsing user-provided data? This could + be directly at the API level or indirectly such as changes to a cache layer. + +* Can this change enable a resource exhaustion attack, such as allowing a + single API interaction to consume significant server resources? Some examples + of this include launching subprocesses for each connection, or entity + expansion attacks in XML. + +For more detailed guidance, please see the OpenStack Security Guidelines as +a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These +guidelines are a work in progress and are designed to help you identify +security best practices. For further information, feel free to reach out +to the OpenStack Security Group at openstack-security@lists.openstack.org. + +Notifications impact +-------------------- + +Please specify any changes to notifications. Be that an extra notification, +changes to an existing notification, or removing a notification. + +Other end user impact +--------------------- + +Aside from the API, are there other ways a user will interact with this feature? + +* Does this change have an impact on python client? What does the user + interface there look like? + +Performance Impact +------------------ + +Describe any potential performance impact on the system, for example +how often will new code be called, and is there a major change to the calling +pattern of existing code. + +Examples of things to consider here include: + +* A periodic task might look like a small addition but if it calls conductor or + another service the load is multiplied by the number of nodes in the system. + +* A small change in a utility function or a commonly used decorator can have a + large impacts on performance. + +* Calls which result in a database queries (whether direct or via conductor) can + have a profound impact on performance when called in critical sections of the + code. + +* Will the change include any locking, and if so what considerations are there on + holding the lock? + +Other deployer impact +--------------------- + +Discuss things that will affect how you deploy and configure OpenStack +that have not already been mentioned, such as: + +* What config options are being added? Should they be more generic than + proposed (for example a flag that other hypervisor drivers might want to + implement as well)? Are the default values ones which will work well in + real deployments? + +* Is this a change that takes immediate effect after its merged, or is it + something that has to be explicitly enabled? + +* If this change is a new binary, how would it be deployed? + +* Please state anything that those doing continuous deployment, or those + upgrading from the previous release, need to be aware of. Also describe + any plans to deprecate configuration values or features. For example, if we + change the directory name that instances are stored in, how do we handle + instance directories created before the change landed? Do we move them? Do + we have a special case in the code? Do we assume that the operator will + recreate all the instances in their cloud? + +Developer impact +---------------- + +Discuss things that will affect other developers working on OpenStack, +such as: + +* If the blueprint proposes a change to the API, discussion of how other + plugins would implement the feature is required. + + +Implementation +============== + +Assignee(s) +----------- + +Who is leading the writing of the code? Or is this a blueprint where you're +throwing it out there to see who picks it up? + +If more than one person is working on the implementation, please designate the +primary author and contact. + +Primary assignee: + + +Other contributors: + + +Work Items +---------- + +Work items or tasks -- break the feature up into the things that need to be +done to implement it. Those parts might end up being done by different people, +but we're mostly trying to understand the timeline for implementation. + + +Dependencies +============ + +* Include specific references to specs and/or blueprints in other + projects, that this one either depends on or is related to. + +* If this requires functionality of another project that is not currently used + by Neutron (such as the glance v2 API when we previously only required v1), + document that fact. + +* Does this feature require any new library dependencies or code otherwise not + included in OpenStack? Or does it depend on a specific version of library? + + +Testing +======= + +Please discuss how the change will be tested. We especially want to know what +tempest tests will be added. It is assumed that unit test coverage will be +added so that doesn't need to be mentioned explicitly, but discussion of why +you think unit tests are sufficient and we don't need to add more tempest +tests would need to be included. + +Is this untestable in gate given current limitations (specific hardware / +software configurations available)? If so, are there mitigation plans (3rd +party testing, gate enhancements, etc). + + +Documentation Impact +==================== + +What is the impact on the docs team of this change? Some changes might require +donating resources to the docs team to have the documentation updated. Don't +repeat details discussed above, but please reference them here. + + +References +========== + +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable. Examples of what you could include are: + +* Links to mailing list or IRC discussions + +* Links to notes from a summit session + +* Links to relevant research, if appropriate + +* Related specifications as appropriate (e.g. link any vendor documentation) + +* Anything else you feel it is worthwhile to refer to diff --git a/specs/juno/group-based-policy-abstraction.rst b/specs/juno/group-based-policy-abstraction.rst new file mode 100644 index 0000000..7203c28 --- /dev/null +++ b/specs/juno/group-based-policy-abstraction.rst @@ -0,0 +1,879 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +=========================================== +Group-based Policy Abstractions for Neutron +=========================================== + +Launchpad blueprint: + +https://blueprints.launchpad.net/neutron/+spec/group-based-policy-abstraction + +This blueprint proposes an extension to the Neutron API with a declarative +policy driven connectivity model that presents simplified application-oriented +interfaces to the user. + +Problem description +=================== + +The current Neutron model of networks, ports, subnets, routers, and security +groups provides the necessary building blocks to build a logical network +topology for connectivity. However, it does not provide the right level +of abstraction for an application administrator who understands the +application's details (like application port numbers), but not the +infrastructure details likes networks and routes. Not only that, the current +abstraction puts the burden of maintaining the consistency of the network +topology on the user. The lack of application developer/administrator focussed +abstractions supported by a declarative model make it hard for those users +to consume Neutron as a connectivity layer. + +Proposed change +=============== + +The policy framework described in this blueprint complements the current +Neutron model with the notion of policies that can be applied between groups of +endpoints. As users look beyond basic connectivity, richer network services +with diverse implementations and network properties are naturally expressed as +policies. Examples include service chaining, QoS, path properties, access +control, etc. + +This proposal suggests a model that allows application administrators to +express their networking requirements using group and policy abstractions, with +the specifics of policy enforcement and implementation left to the underlying +policy driver. The main advantage of the extensions described in this blueprint +is that they allow for an application-centric interface to Neutron that +complements the existing network-centric interface. + +More specifically the new abstractions will achieve the following: + +* Show clear separation of concerns between application and infrastructure + administrator. + + - The application administrator can then deal with a higher level abstraction + that does not concern itself with networking specifics like + networks/routers/etc. + + - The infrastructure administrator will deal with infrastructure specific + policy abstractions and not have to understand application specific concerns + like specific ports that have been opened or which of them expect to be + limited to secure or insecure traffic. The infrastructure admin will also + have ability to direct which technologies and approaches used in rendering. + For example, if VLAN or VxLAN is used. + + - Allow the infrastructure admin to introduce connectivity constraints + without the application administrator having to be aware of it (e.g. audit + all traffic between two application tiers). + +* Allow for independent provider/consumer model with late binding and n-to-m + relationships between them. + +* Allow for automatic orchestration that can respond to changes in policy or + infrastructure without requiring human interaction to translate intent to + specific actions. + +* Complement the governance model proposed in the OpenStack Congress project by + making Policy Labels available for enforcement. + +The following new terminology is being introduced: + +**Endpoint (EP):** An L2/L3 addressable entity. + +**Endpoint Group (EPG):** A collection of endpoints. + +**Contract:** It defines how the application services provided by an EPG can be +accessed. In effect it specifies how an EPG communicates with other EPGs. A +Contract consists of Policy Rules. + +**Policy Rule:** These are individual rules used to define the communication +criteria between EPGs. Each rule contains a Filter, Classifier, and Action. + +**Classifier:** Characterizes the traffic that a particular Policy Rule acts on. +Corresponding action is taken on traffic that satisfies this classification +criteria. + +**Action:** The action that is taken for a matching Policy Rule defined in a +Contract. + +**Filter:** Provides a way to tag a Policy Rule with Capability and Role labels. + +**Capability:** It is a Policy Label that defines what part of a Contract a +particular EPG provides. + +**Role:** It is a Policy Label that defines what part of a Contract an EPG wants +to consume. + +**Contract Scope:** An EPG conveys its intent to provide or consume a Contract +(or its part) by defining a Contract Scope which references the target +Contract. + +**Selector:** A Contract Scope can define additional constraints around choosing +the matching provider or consumer EPGs for a Contract via a Selector. + +**Policy Labels:** These are labels contained within a namespace hierarchy and +used to define Capability and Role tags used in Filters. + +**Bridge Domain:** Used to define a L2 boundary and impose additional +constraints (such as no broadcast) within that L2 boundary. + +**Routing Domain:** Used to define a non-overlapping IP address space. + +Here is an example of how a three tier application would look like: + +:: + + +–––––––––+ +–––––––+ +–––––––+ +–––––––+ + | | | Web | | App | |DB | + | Outside | | EPG | | EPG | |EPG | + | Public | +––––––––+ +––+ | +––––––––+ +––+ | +––––––––+ +––+ | + | Network +–+Web | |VM| +–+App | |VM| +–+DB | |VM| | + | EPG | |Contract| +––+ | |Contract| +––+ | |Contract| +––+ | + | | +––––––––+ | +––––––––+ | +––––––––+ | + | | | +––+ | | +––+ | | +––+ | + | | | |VM| | | |VM| | | |VM| | + | | | +––+ | | +––+ | | +––+ | + +–––––––––+ +–––––––+ +–––––––+ +–––––––+ + +Example CLI: + +(exmaple only shows access to the Web Server Tier from the Outside Network) + +Create Classifier + +:: + + neutron classifier-create Insecure-Web-Access --port 80 --protocol TCP + --direction IN + +Create Contract using the Classifier + +:: + + neutron contract-create Web-Server-Contract --classifier Insecure-Web-Access + --action ALLOW + +Create EPG providing the Contract + +:: + + neutron epg-create Web-Server-EPG --provides-contract Web-Server-Contract + +Create Endpoint in EPG + +:: + + neutron ep-create --epg Web-Server-EPG + +Launch Web Server VM using Endpoint in EPG + +:: + + nova boot --image cirros --flavor m1.nano --nic port-id= Web-Server + +Specify connectivity of Outside world VMs to Web Server + +:: + + neutron epg-create Outside-EPG --consumes-contract Web-Server-Contract + +Note that the Contract Provider/Consuming Scopes are not explicitly shown in +the above diagram but define each providing and consuming relation between an +EPG and a Contract as shown below: + +:: + + +––––––––––+ + |Web | + |Contract | + |Consuming | + |Scope | + +–––+––––––+ + +–––––––––+ | +––––––––––+ + | | | | Web | + | Outside | | | EPG | + | Public | | +––––––––+ | +––+ | + | Network +–+–+Web +––+–+ |VM|EP | + | EPG | |Contract| | | +––+ | + | | +––––––––+ | | | + | | | | +––+ | + | | | | |VM|EP | + | | | | +––+ | + +–––––––––+ | | | + | +––––––––––+ + + + +––––+–––––+ + |Web | + |Contract | + |Providing | + |Scope | + +––––––––––+ + +Alternatives +------------ + +Since a new level of abstraction is being proposed here, a direct alternate +does not exist in the current model. + +Data model impact +----------------- + +New Database Objects to support Group Policy: + +:: + + +–––––––––––––+ +–––––––––––––––+ +–––––––––––+ + | | | Contract | |Contracts | + | Endpoint | | Providing/ | | | + | Groups +–––––+ Consuming +––––––+ | + | | | Scopes | +–––––+–––––+ + +––––––+––––––+ +–––––––––––––––+ | + | +–––––+–––––+ + | |Policy | + +––––––+––––––+ |Rules | + | | | | + | Endpoints | +–––––+––––––+––––+––––––––+ + | | | | | + +–––––––––––––+ | | | + | | | + +–––––+––+ +––––––+–––––+ +–––––+––+ + |Filters | |Classifiers | |Actions | + | | | | | | + +––––––––+ +––––––––––––+ +––––––––+ + +All objects have the following common attributes: + * id - standard object uuid + * name - optional name + * description - optional annotation + +Endpoint + * epg_id - UUID of the EndpointGroup (EPG) that this Endpoint (EP) belongs to + +EndpointGroup + * endpoints - list of endpoint uuids + * contract_providing_scopes - list of ContractProvidingScope uuids + * contract_consuming_scopes - list of ContractConsumingScope uuids + +Contract + * policy_rules - ordered list of PolicyRule uuids + * contract_providing_scopes - list of ContractProvidingScope uuids + * contract_consuming_scopes - list of ContractConsumingScope uuids + * child_contracts - ordered list of Contract uuids + +ContractProvidingScope + * contract_id - uuid of the Contract that is being provided by the EPG + * selectors - list of Selectors uuids + * capabilites - list of PolicyLabel uuids + * providing_epg - EndpointGroup uuid + +ContractConsumingScope + * contract_id - uuid of the Contract that is being consumed by the EPG + * selectors - list of Selectors uuids + * roles - list of PolicyLabels + * consuming_epg - EndpointGroup uuid + +Selector + * scope - enum: GLOBAL, TENANT, EPG + * value - None for GLOBAL, or uuid of tenant/EPG + +PolicyLabel + * namespace - string, a namespace identifier for policy labels + * name - string, not optional + +PolicyRule + * filter - uuid of Filter + * classifier - uuid of Classifier + * actions - list of Action uuids + +Filter + * provider_capablilities - list of PolicyLabel uuids + * consumer_roles - list of PolicyLabel uuids + +Classifier + * protocol - enum: TCP, IP, ICMP + * port_range - single port number or range (as used in FWaaS firewall_rule) + * direction - enum: IN, OUT, BI + +Action + * type - enum: ALLOW, REDIRECT, QOS, LOG, MARK, COPY + * value - uuid of a resource that performs the action, for example in the + case of REDIRECT, its the uuid of the ServiceWrapper + +ServiceWrapper + * neutron_service - uuid of service or service_chain + +L2Policy + * endpoint_groups - list of EndpointGroup uuids + * l3_policy_id - uuid of the l3_policy + +L3Policy + * l2_policies - list of L2Policy uuids + * ip_version - enum, v4 or v6 + * ip_pool - string, IPSubnet with mask, used to pull subnets from if the + user creates an EPG without specifying a subnet + * default_subnet_prefix_length - int, used as the default subnet length if + the user creates an EPG without a subnet + +The way ip_pool and default_subnet_prefix_length work is as follows: When +creating L3Policy a default ip_pool and default_subnet_prefix_length are +created. If a user creates an EPG, a subnet will be pulled from ip_pool using +default_subnet_prefix_length. + +Objects to support Mapping to existing Neutron resources + +EndpointPortBinding (extends Endpoint) + * neutron_port_id - uuid of Neutron Port that this EP maps to + +EndpointGroupNetworkBinding (extends EndpointGroup) + * neutron_subnets - list of Neutron Subnet uuids + +L2PolicyBinding (extends l2_policy) + * neutron_network_id - reference to a Neutron network + +L3PolicyBinding (extends l3_policy) + * neutron_routers - list of Neutron Router uuids + +Appropriate foreign key constraints will be added to maintain the referential +integrity of the model. + +Database migrations: +New tables are being added to the schema, however the existing schema remains +unchanged. + +REST API impact +--------------- + +The following new resources are being introduced: + +.. code-block:: python + + gp_supported_actions = [None, 'ALLOW', 'REDIRECT'] + gp_supported_directions = [None, 'IN', 'OUT', 'BI'] + gp_supported_protocols = [None, 'TCP', 'UDP', 'ICMP'] + gp_supported_scopes = [None, 'GLOBAL', 'TENANT', 'EPG'] + + ENDPOINTS = 'endpoints' + ENDPOINT_GROUPS = 'endpoint_groups' + CONTRACTS = 'contracts' + CONTRACT_PROVIDING_SCOPES = 'contract_providing_scopes' + CONTRACT_CONSUMING_SCOPES = 'contract_consuming_scopes' + POLICY_RULES = 'policy_rules' + FILTERS = 'filters' + CLASSIFIERS = 'classifiers' + ACTIONS = 'actions' + SELECTORS = 'selectors' + POLICY_LABELS = 'policy_labels' + L2_POLICIES = 'l2_policies' + L3_POLICIES = 'l3_policies' + + RESOURCE_ATTRIBUTE_MAP = { + ENDPOINTS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, 'default': '', + 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, 'is_visible': True}, + 'endpointgroup_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid__or_none': None}, + 'required': True, 'is_visible': True}, + }, + ENDPOINT_GROUPS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, 'is_visible': True}, + 'endpoints': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'default': None, 'is_visible': True}, + 'bridge_domain_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_or_none': None}, + 'default': None, 'is_visible': True}, + 'provided_contract_scopes': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_list': None}, + 'convert_to': + attr.convert_none_to_empty_list, + 'default': None, 'is_visible': True}, + 'consumed_contract_scopes': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_list': None}, + 'convert_to': + attr.convert_none_to_empty_list, + 'default': None, 'is_visible': True}, + }, + CONTRACTS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', + 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'child_contracts': {'allow_post': True, 'allow_put': True, + 'default': None, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'required': True, 'is_visible': True}, + 'policy_rules': {'allow_post': True, 'allow_put': True, + 'default': None, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'required': True, 'is_visible': True}, + }, + CONTRACT_PROVIDING_SCOPES: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', + 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'endpointgroup_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid': None}, + 'required': True, 'is_visible': True}, + 'contract_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid': None}, + 'required': True, 'is_visible': True}, + 'selector_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_or_none': None}, + 'required': True, 'is_visible': True}, + 'capabilities': {'allow_post': True, 'allow_put': True, + 'default': None, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'required': True, 'is_visible': True}, + }, + CONTRACT_CONSUMING_SCOPES: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', + 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'endpointgroup_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid': None}, + 'required': True, 'is_visible': True}, + 'contract_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid': None}, + 'required': True, 'is_visible': True}, + 'selector_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_or_none': None}, + 'required': True, 'is_visible': True}, + 'roles': {'allow_post': True, 'allow_put': True, + 'default': None, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'required': True, 'is_visible': True}, + }, + POLICY_RULES: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'enabled': {'allow_post': True, 'allow_put': True, + 'default': True, 'convert_to': attr.convert_to_boolean, + 'is_visible': True}, + 'filter_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_or_none': None}, + 'required': True, 'is_visible': True}, + 'classifier_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid': None}, + 'required': True, 'is_visible': True}, + 'actions': {'allow_post': True, 'allow_put': True, + 'default': None, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'required': True, 'is_visible': True}, + }, + FILTERS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'provider_capabilities': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_list': None}, + 'convert_to': + attr.convert_none_to_empty_list, + 'required': True, 'is_visible': True}, + 'consumer_roles': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'required': True, 'is_visible': True}, + }, + CLASSIFIERS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'protocol': {'allow_post': True, 'allow_put': True, + 'is_visible': True, 'default': None, + 'convert_to': convert_protocol, + 'validate': {'type:values': gp_supported_protocols}}, + 'port_range': {'allow_post': True, 'allow_put': True, + 'validate': {'type:port_range': None}, + 'convert_to': convert_port_to_string, + 'default': None, 'is_visible': True}, + 'direction': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': gp_supported_directions}, + 'default': None, 'is_visible': True}, + }, + ACTIONS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'action_type': {'allow_post': True, 'allow_put': True, + 'convert_to': convert_action_to_case_insensitive, + 'validate': {'type:values': gp_supported_actions}, + 'is_visible': True, 'default': 'allow'}, + 'action_value': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_or_none': None}, + 'is_visible': True}, + }, + SELECTORS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'scope': {'allow_post': True, 'allow_put': True, + 'convert_to': convert_scope_to_case_insensitive, + 'validate': {'type:values': gp_supported_scopes}, + 'is_visible': True, 'default': 'tenant'}, + 'value': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_or_none': None}, + 'is_visible': True}, + }, + POLICY_LABELS: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, + 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, + 'is_visible': True}, + 'namespace': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'required': True}, + }, + L2_POLICIES: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, 'is_visible': True}, + 'endpoint_groups': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'default': None, 'is_visible': True}, + 'routing_domain_id': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_or_none': None}, + 'default': None, 'is_visible': True, + 'required': True}, + }, + L3_POLICIES: { + 'id': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid': None}, 'is_visible': True, + 'primary_key': True}, + 'name': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'default': '', 'is_visible': True}, + 'description': {'allow_post': True, 'allow_put': True, + 'validate': {'type:string': None}, + 'is_visible': True, 'default': ''}, + 'tenant_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:string': None}, + 'required_by_policy': True, 'is_visible': True}, + 'ip_version': {'allow_post': True, 'allow_put': False, + 'convert_to': attr.convert_to_int, + 'validate': {'type:values': [4, 6]}, + 'is_visible': True}, + 'ip_pool': {'allow_post': True, 'allow_put': False, + 'validate': {'type:subnet': None}, + 'default': '10.0.0.0/8', 'is_visible': True}, + 'default_subnet_prefix_length': {'allow_post': True, 'allow_put': True, + 'convert_to': attr.convert_to_int, + 'validate': { + # ipv4 specific validation is + # performed in the plugin code. + 'type:values': range(1, 127)}, + 'default': 24, 'is_visible': True}, + 'l2_policies': {'allow_post': False, 'allow_put': False, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'default': None, 'is_visible': True}, + }, + } + +The following defines the mapping to classical (existing) Neutron resources +using attribute extension: + +.. code-block:: python + + EXTENDED_ATTRIBUTES_2_0 = { + gpolicy.ENDPOINTS: { + 'neutron_port_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:uuid_or_none': None}, + 'is_visible': True, 'default': None}, + }, + gpolicy.ENDPOINT_GROUPS: { + 'neutron_subnets': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'default': None, 'is_visible': True}, + }, + gpolicy.L2_POLICIES: { + 'neutron_network_id': {'allow_post': True, 'allow_put': False, + 'validate': {'type:uuid_or_none': None}, + 'is_visible': True, 'default': None}, + }, + gpolicy.L3_POLICIES: { + 'neutron_routers': {'allow_post': True, 'allow_put': True, + 'validate': {'type:uuid_list': None}, + 'convert_to': attr.convert_none_to_empty_list, + 'default': None, 'is_visible': True}, + }, + } + +Security impact +--------------- + +The connectivity model used here is consistent with OpenStack/Neutron's current +white list model - that is, there is no connectivity outside an EPG unless +explicitly allowed. + +The rendering of the proposed new abstractions happens via existing Security +Groups and Firewall as a Service constructs. As such, no new constructs or +implementation that will directly affect the current security framework are +being introduced. + +* Does this change touch sensitive data such as tokens, keys, or user data? + + No + +* Does this change alter the API in a way that may impact security, such as + a new way to access sensitive information or a new way to login? + + No + +* Does this change involve cryptography or hashing? + + No + +* Does this change require the use of sudo or any elevated privileges? + + No + +* Does this change involve using or parsing user-provided data? This could + be directly at the API level or indirectly such as changes to a cache layer. + + No + +* Can this change enable a resource exhaustion attack, such as allowing a + single API interaction to consume significant server resources? Some examples + of this include launching subprocesses for each connection, or entity + expansion attacks in XML. + + The exposed risk here is no different from the existing APIs and would largely + depend on the Policy Driver implementation. + +Notifications impact +-------------------- + +None + +Other end user impact +--------------------- + +Integration with following projects will be required: + +* python-neutronclient +* horizon +* heat +* devstack + +Performance Impact +------------------ + +A new layer of abstraction is being introduced. All performance considerations +that are relevant to existing Neutron will apply and be taken into +consideration during the implementation. It should be noted though that the use +of this new layer of abstraction/extensions is optional, and as such will not +affect the performance of the existing implementation if the former is not +used. + +Other deployer impact +--------------------- + +* Config additions + + - Policy Plugin class + + - Policy Plugin driver class + +Developer impact +---------------- + +This will be a new API, and will not affect existing API. + +Implementation +============== + +Assignee(s) +----------- + + Sumit Naiksatam (snaiksat) - Launchpad blueprint assignee + + Robert Kukura (rkukura) + + Mandeep Dhami (mandeep-dhami) + + Mohammad Banikazemi (banix) + + Stephen Wong (s3wong) + + Prasad Vellanki (prasad-vellanki) + + Hemanth Ravi (hemanth-ravi) + + Subrahmanyam Ongole (osms69) + + Ronak Shah (ronak-malav-shah) + + Rudra Rugge (rudrarugge) + + Kanzhe Jiang (kanzhe-jiang) + + Kevin Benton (kevinbenton) + +Work Items +---------- + + Policy Manager + Policy Driver + +Dependencies +============ + +None + +Testing +======= + +Both, functional and, system tests will be added. + +Documentation Impact +==================== + +Both, API and, Admin guide will be updated. + +References +========== + +* Weekly IRC meetings wherein this blueprint has been discussed since Nov 2013 + + - https://wiki.openstack.org/wiki/Meetings/Neutron_Group_Policy + +* Group Policy Wiki - https://wiki.openstack.org/wiki/Neutron/GroupPolicy diff --git a/specs/skeleton.rst b/specs/skeleton.rst new file mode 100644 index 0000000..ba77613 --- /dev/null +++ b/specs/skeleton.rst @@ -0,0 +1,82 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================== +Title of your blueprint +========================================== + + +Problem description +=================== + + +Proposed change +=============== + + +Alternatives +------------ + + +Data model impact +----------------- + + +REST API impact +--------------- + + +Security impact +--------------- + + +Notifications impact +-------------------- + + +Other end user impact +--------------------- + + +Performance Impact +------------------ + + +Other deployer impact +--------------------- + + +Developer impact +---------------- + + +Implementation +============== + +Assignee(s) +----------- + + +Work Items +---------- + + +Dependencies +============ + + +Testing +======= + + +Documentation Impact +==================== + + +References +========== + + diff --git a/specs/template.rst b/specs/template.rst new file mode 100644 index 0000000..a1ab473 --- /dev/null +++ b/specs/template.rst @@ -0,0 +1,409 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================== +Example Spec - The title of your blueprint +========================================== + +Include the URL of your launchpad blueprint: + +Introduction paragraph -- why are we doing anything? A single paragraph of +prose that operators can understand. + +Some notes about using this template: + +* Your spec should be in ReSTructured text, like this template. + +* Please wrap text at 80 columns. + +* Please do not delete any of the sections in this template. If you have + nothing to say for a whole section, just write: None + +* For help with syntax, see http://sphinx-doc.org/rest.html + +* To test out your formatting, build the docs using tox, or see: + http://rst.ninjs.org + +* If you would like to provide a diagram with your spec, text representations + are preferred. http://asciiflow.com/ is a very nice tool to assist with + making ascii diagrams. blockdiag is another tool. These are described below. + If you require an image (screenshot) for your BP, attaching that to the BP + and checking it in is also accepted. However, text representations are prefered. + +* Diagram examples + +asciiflow:: + + +----------+ +-----------+ +----------+ + | A | | B | | C | + | +-----+ +--------+ | + +----------+ +-----------+ +----------+ + +blockdiag + +.. blockdiag:: + + blockdiag sample { + a -> b -> c; + } + +actdiag + +.. actdiag:: + + actdiag { + write -> convert -> image + lane user { + label = "User" + write [label = "Writing reST"]; + image [label = "Get diagram IMAGE"]; + } + lane actdiag { + convert [label = "Convert reST to Image"]; + } + } + +nwdiag + +.. nwdiag:: + + nwdiag { + network dmz { + address = "210.x.x.x/24" + + web01 [address = "210.x.x.1"]; + web02 [address = "210.x.x.2"]; + } + network internal { + address = "172.x.x.x/24"; + + web01 [address = "172.x.x.1"]; + web02 [address = "172.x.x.2"]; + db01; + db02; + } + } + + +seqdiag + +.. seqdiag:: + + seqdiag { + browser -> webserver [label = "GET /index.html"]; + browser <-- webserver; + browser -> webserver [label = "POST /blog/comment"]; + webserver -> database [label = "INSERT comment"]; + webserver <-- database; + browser <-- webserver; + } + + + +Problem description +=================== + +A detailed description of the problem: + +* For a new feature this might be use cases. Ensure you are clear about the + actors in each use case: End User vs Deployer + +* For a major reworking of something existing it would describe the + problems in that feature that are being addressed. + + +Proposed change +=============== + +Here is where you cover the change you propose to make in detail. How do you +propose to solve this problem? + +If this is one part of a larger effort make it clear where this piece ends. In +other words, what's the scope of this effort? + +Alternatives +------------ + +What other ways could we do this thing? Why aren't we using those? This doesn't +have to be a full literature review, but it should demonstrate that thought has +been put into why the proposed solution is an appropriate one. + +Data model impact +----------------- + +Changes which require modifications to the data model often have a wider impact +on the system. The community often has strong opinions on how the data model +should be evolved, from both a functional and performance perspective. It is +therefore important to capture and gain agreement as early as possible on any +proposed changes to the data model. + +Questions which need to be addressed by this section include: + +* What new data objects and/or database schema changes is this going to require? + +* What database migrations will accompany this change. + +* How will the initial set of new data objects be generated, for example if you + need to take into account existing instances, or modify other existing data + describe how that will work. + +REST API impact +--------------- + +For each API resource to be implemented using attribute map +facility, describe the resource collection and specify the name, +type, and other essential details of each new or modified attribute. +A table similar to the following may be used: + ++----------+-------+---------+---------+------------+--------------+ +|Attribute |Type |Access |Default |Validation/ |Description | +|Name | | |Value |Conversion | | ++==========+=======+=========+=========+============+==============+ +|id |string |RO, all |generated|N/A |identity | +| |(UUID) | | | | | ++----------+-------+---------+---------+------------+--------------+ +|name |string |RW, all |'' |string |human-readable| +| | | | | |name | ++----------+-------+---------+---------+------------+--------------+ +|color |string |RW, admin|'red' |'red', |color | +| | | | |'yellow', or|indicating | +| | | | |'green' |state | ++----------+-------+---------+---------+------------+--------------+ + + +Here is the other example of the table using csv-table + + +.. csv-table:: CSVTable + :header: Attribute Name,Type,Access,Default Value,Validation Conversion,Description + + id,string (UUID),"RO, all",generated,N/A,identity + name,string,"RW, all","''",string,human-readable name + color,string,"RW, admin",red,"'red', 'yellow' or 'green'",color indicating state + + +Each API method which is either added or changed that does not use +Neutron's attribute map facility should have the following: + +* Specification for the method + + * A description of what the method does suitable for use in + user documentation + + * Method type (POST/PUT/GET/DELETE) + + * Normal http response code(s) + + * Expected error http response code(s) + + * A description for each possible error code should be included + describing semantic errors which can cause it such as + inconsistent parameters supplied to the method, or when an + instance is not in an appropriate state for the request to + succeed. Errors caused by syntactic problems covered by the JSON + schema defintion do not need to be included. + + * URL for the resource + + * Parameters which can be passed via the url + + * JSON schema definition for the body data if allowed + + * JSON schema definition for the response data if any + +* Example use case including typical API samples for both data supplied + by the caller and the response + +* Discuss any API policy changes, and discuss what things a deployer needs to + think about when defining their API policy. This is in reference to the + policy.json file. + +Note that the schema should be defined as restrictively as +possible. Parameters which are required should be marked as such and +only under exceptional circumstances should additional parameters +which are not defined in the schema be permitted (eg +additionaProperties should be False). + +Reuse of existing predefined parameter types such as regexps for +passwords and user defined names is highly encouraged. + +Security impact +--------------- + +Describe any potential security impact on the system. Some of the items to +consider include: + +* Does this change touch sensitive data such as tokens, keys, or user data? + +* Does this change alter the API in a way that may impact security, such as + a new way to access sensitive information or a new way to login? + +* Does this change involve cryptography or hashing? + +* Does this change require the use of sudo or any elevated privileges? + +* Does this change involve using or parsing user-provided data? This could + be directly at the API level or indirectly such as changes to a cache layer. + +* Can this change enable a resource exhaustion attack, such as allowing a + single API interaction to consume significant server resources? Some examples + of this include launching subprocesses for each connection, or entity + expansion attacks in XML. + +For more detailed guidance, please see the OpenStack Security Guidelines as +a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These +guidelines are a work in progress and are designed to help you identify +security best practices. For further information, feel free to reach out +to the OpenStack Security Group at openstack-security@lists.openstack.org. + +Notifications impact +-------------------- + +Please specify any changes to notifications. Be that an extra notification, +changes to an existing notification, or removing a notification. + +Other end user impact +--------------------- + +Aside from the API, are there other ways a user will interact with this feature? + +* Does this change have an impact on python client? What does the user + interface there look like? + +Performance Impact +------------------ + +Describe any potential performance impact on the system, for example +how often will new code be called, and is there a major change to the calling +pattern of existing code. + +Examples of things to consider here include: + +* A periodic task might look like a small addition but if it calls conductor or + another service the load is multiplied by the number of nodes in the system. + +* A small change in a utility function or a commonly used decorator can have a + large impacts on performance. + +* Calls which result in a database queries (whether direct or via conductor) can + have a profound impact on performance when called in critical sections of the + code. + +* Will the change include any locking, and if so what considerations are there on + holding the lock? + +Other deployer impact +--------------------- + +Discuss things that will affect how you deploy and configure OpenStack +that have not already been mentioned, such as: + +* What config options are being added? Should they be more generic than + proposed (for example a flag that other hypervisor drivers might want to + implement as well)? Are the default values ones which will work well in + real deployments? + +* Is this a change that takes immediate effect after its merged, or is it + something that has to be explicitly enabled? + +* If this change is a new binary, how would it be deployed? + +* Please state anything that those doing continuous deployment, or those + upgrading from the previous release, need to be aware of. Also describe + any plans to deprecate configuration values or features. For example, if we + change the directory name that instances are stored in, how do we handle + instance directories created before the change landed? Do we move them? Do + we have a special case in the code? Do we assume that the operator will + recreate all the instances in their cloud? + +Developer impact +---------------- + +Discuss things that will affect other developers working on OpenStack, +such as: + +* If the blueprint proposes a change to the API, discussion of how other + plugins would implement the feature is required. + + +Implementation +============== + +Assignee(s) +----------- + +Who is leading the writing of the code? Or is this a blueprint where you're +throwing it out there to see who picks it up? + +If more than one person is working on the implementation, please designate the +primary author and contact. + +Primary assignee: + + +Other contributors: + + +Work Items +---------- + +Work items or tasks -- break the feature up into the things that need to be +done to implement it. Those parts might end up being done by different people, +but we're mostly trying to understand the timeline for implementation. + + +Dependencies +============ + +* Include specific references to specs and/or blueprints in other + projects, that this one either depends on or is related to. + +* If this requires functionality of another project that is not currently used + by Neutron (such as the glance v2 API when we previously only required v1), + document that fact. + +* Does this feature require any new library dependencies or code otherwise not + included in OpenStack? Or does it depend on a specific version of library? + + +Testing +======= + +Please discuss how the change will be tested. We especially want to know what +tempest tests will be added. It is assumed that unit test coverage will be +added so that doesn't need to be mentioned explicitly, but discussion of why +you think unit tests are sufficient and we don't need to add more tempest +tests would need to be included. + +Is this untestable in gate given current limitations (specific hardware / +software configurations available)? If so, are there mitigation plans (3rd +party testing, gate enhancements, etc). + + +Documentation Impact +==================== + +What is the impact on the docs team of this change? Some changes might require +donating resources to the docs team to have the documentation updated. Don't +repeat details discussed above, but please reference them here. + + +References +========== + +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable. Examples of what you could include are: + +* Links to mailing list or IRC discussions + +* Links to notes from a summit session + +* Links to relevant research, if appropriate + +* Related specifications as appropriate (e.g. link any vendor documentation) + +* Anything else you feel it is worthwhile to refer to diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_titles.py b/tests/test_titles.py new file mode 100644 index 0000000..3cdcf45 --- /dev/null +++ b/tests/test_titles.py @@ -0,0 +1,104 @@ +# 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 glob + +import docutils.core +from docutils.parsers import rst +from docutils.parsers.rst import directives +import testtools + + +class FakeDirective(rst.Directive): + has_content = True + def run(self): + return [] + + +directives.register_directive('seqdiag', FakeDirective) +directives.register_directive('blockdiag', FakeDirective) +directives.register_directive('nwdiag', FakeDirective) +directives.register_directive('actdiag', FakeDirective) + + +class TestTitles(testtools.TestCase): + def _get_title(self, section_tree): + section = { + 'subtitles': [], + } + for node in section_tree: + if node.tagname == 'title': + section['name'] = node.rawsource + elif node.tagname == 'section': + subsection = self._get_title(node) + section['subtitles'].append(subsection['name']) + return section + + def _get_titles(self, spec): + titles = {} + for node in spec: + if node.tagname == 'section': + section = self._get_title(node) + titles[section['name']] = section['subtitles'] + return titles + + def _check_titles(self, titles): + problem = 'Problem description' + self.assertIn(problem, titles) + self.assertEqual(0, len(titles[problem])) + + proposed = 'Proposed change' + self.assertIn(proposed, titles) + self.assertIn('Alternatives', titles[proposed]) + self.assertIn('Data model impact', titles[proposed]) + self.assertIn('REST API impact', titles[proposed]) + self.assertIn('Security impact', titles[proposed]) + self.assertIn('Notifications impact', titles[proposed]) + self.assertIn('Other end user impact', titles[proposed]) + self.assertIn('Performance Impact', titles[proposed]) + self.assertIn('Other deployer impact', titles[proposed]) + self.assertIn('Developer impact', titles[proposed]) + + impl = 'Implementation' + self.assertIn(impl, titles) + self.assertEqual(2, len(titles[impl])) + self.assertIn('Assignee(s)', titles[impl]) + self.assertIn('Work Items', titles[impl]) + + deps = 'Dependencies' + self.assertIn(deps, titles) + self.assertEqual(0, len(titles[deps])) + + testing = 'Testing' + self.assertIn(testing, titles) + self.assertEqual(0, len(titles[testing])) + + docs = 'Documentation Impact' + self.assertIn(docs, titles) + self.assertEqual(0, len(titles[docs])) + + refs = 'References' + self.assertIn(refs, titles) + self.assertEqual(0, len(titles[refs])) + + self.assertEqual(7, len(titles)) + + def test_template(self): + files = glob.glob('specs/*.rst') + glob.glob('specs/*/*') + for filename in files: + self.assertTrue(filename.endswith(".rst"), + "spec's file must uses 'rst' extension.") + with open(filename) as f: + data = f.read() + spec = docutils.core.publish_doctree(data) + titles = self._get_titles(spec) + self._check_titles(titles) diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..b92724b --- /dev/null +++ b/tox.ini @@ -0,0 +1,17 @@ +[tox] +minversion = 1.6 +envlist = docs,py27 +skipsdist = True + +[testenv] +usedevelop = True +setenv = VIRTUAL_ENV={envdir} +install_command = pip install -U {opts} {packages} +deps = -r{toxinidir}/requirements.txt +commands = python setup.py testr --slowest --testr-args='{posargs}' + +[testenv:venv] +commands = {posargs} + +[testenv:docs] +commands = python setup.py build_sphinx