First commit with initial WG information added

Change-Id: Ia48a5d069188c6096d4e6165a232edf7365cb361
This commit is contained in:
Dina Belova 2016-11-04 09:11:56 -07:00
parent f39d24bf07
commit fc46d7d2f6
12 changed files with 710 additions and 0 deletions

7
.gitignore vendored Normal file
View File

@ -0,0 +1,7 @@
doc/build/
.tox/
.idea
AUTHORS
ChangeLog
.testrepository/
*.pyc

4
.testr.conf Normal file
View File

@ -0,0 +1,4 @@
[DEFAULT]
test_command=OS_STDOUT_CAPTURE=1 OS_STDERR_CAPTURE=1 OS_TEST_TIMEOUT=60 ${PYTHON:-python} -m subunit.run discover -t ./ . $LISTOPT $IDOPTION
test_id_option=--load-list $IDFILE
test_list_option=--list

24
README.rst Normal file
View File

@ -0,0 +1,24 @@
==========================
Architecture Working Group
==========================
This repository if for storing Architecture Working Group resources,
investigation documents and methodologies. All documents are in RST format and
located in `doc/source/` sub-folder.
Building
========
Prerequisites
-------------
To get started, you need to install all necessary tools:
* `virtualenv`
* `pip` (use the latest from `https://bootstrap.pypa.io/get-pip.py`)
* `tox`
* system dependencies: `libjpeg-dev`
Run the build
-------------
$ tox

436
doc/source/conf.py Normal file
View File

@ -0,0 +1,436 @@
# -*- coding: utf-8 -*-
#
# scale_rnd documentation build configuration file, created by
# sphinx-quickstart on Mon Nov 23 13:22:23 2015.
#
# 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 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 = [
'rst2pdf.pdfbuilder',
'sphinx.ext.autodoc',
'sphinxcontrib.httpdomain',
'oslosphinx',
]
# 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'Performance Docs'
copyright = u'2015, OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.1'
# The full version, including alpha/beta/rc tags.
release = '0.1'
# 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 = []
# 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 = True
# 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 = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# 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
# "<project> v<release> 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
# 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']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# 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 = True
# If false, no index is generated.
#html_use_index = True
# 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 <link> 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 = 'performance_docs'
# -- 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, or own class]).
latex_documents = [
('index', 'performance_docs.tex', u'Performance Documentation',
u'OpenStack Foundation', '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 manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'performance_docs', u'Performance Documentation',
[u'OpenStack Foundation'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- 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', 'performance_docs', u'Performance Documentation',
u'OpenStack Foundation', 'performance_docs', 'OpenStack performance testing plans, results and investigations.',
'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'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'performance_docs'
epub_author = u'OpenStack Foundation'
epub_publisher = u'OpenStack Foundation'
epub_copyright = u'2015, OpenStack Foundation'
# The basename for the epub file. It defaults to the project name.
#epub_basename = u'scale_rnd'
# The HTML theme for the epub output. Since the default themes are not optimized
# for small screen space, using the same theme for HTML and epub output is
# usually not wise. This defaults to 'epub', a theme designed to save visual
# space.
#epub_theme = 'epub'
# 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 = ()
# A sequence of (type, uri, title) tuples for the guide element of content.opf.
#epub_guide = ()
# 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 = ['search.html']
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True
# Choose between 'default' and 'includehidden'.
#epub_tocscope = 'default'
# Fix unsupported image types using the PIL.
#epub_fix_images = False
# Scale large images.
#epub_max_image_width = 0
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#epub_show_urls = 'inline'
# If false, no index is generated.
#epub_use_index = True
# -- Options for PDF output --------------------------------------------------
# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override
# this config per-document.
# For example,
# ('index', u'MyProject', u'My Project', u'Author Name',
# dict(pdf_compressed = True))
# would mean that specific document would be compressed
# regardless of the global pdf_compressed setting.
pdf_documents = [
('index', 'openstack_performance_docs', 'Performance Documentation', 'OpenStack Foundation'),
]
# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['pdf']
# A list of folders to search for stylesheets. Example:
pdf_style_path = ['.', '_styles', 'source/_styles', 'doc/source/_styles']
# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
#pdf_compressed = False
# A colon-separated list of folders to search for fonts. Example:
# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']
# Language to be used for hyphenation support
#pdf_language = "en_US"
# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
#pdf_fit_mode = "shrink"
# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
#pdf_break_level = 1
# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
#pdf_breakside = 'any'
# Insert footnotes where they are defined instead of
# at the end.
#pdf_inline_footnotes = True
# verbosity level. 0 1 or 2
#pdf_verbosity = 0
# If false, no index is generated.
#pdf_use_index = True
# If false, no modindex is generated.
#pdf_use_modindex = True
# If false, no coverpage is generated.
#pdf_use_coverpage = True
# Name of the cover page template to use
pdf_cover_template = 'pdf_cover.tmpl'
# Documents to append as an appendix to all manuals.
#pdf_appendices = []
# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
#pdf_splittables = False
# Set the default DPI for images
#pdf_default_dpi = 72
# Enable rst2pdf extension modules (default is only vectorpdf)
# you need vectorpdf if you want to use sphinx's graphviz support
#pdf_extensions = ['vectorpdf']
# Page template name for "regular" pages
pdf_page_template = 'cutePage'
# Show Table Of Contents at the beginning?
#pdf_use_toc = True
# How many levels deep should the table of contents be?
pdf_toc_depth = 9999
# Add section number to section references
pdf_use_numbered_links = False
# Background images fitting mode
pdf_fit_background_mode = 'scale'
pdf_default_dpi = 72

140
doc/source/index.rst Normal file
View File

@ -0,0 +1,140 @@
==========================
Architecture Working Group
==========================
Mission
=======
Be the recognized forum of expertise on the design and architecture of
OpenStack and provide guidance and resources to the Technical Committee
and the entire OpenStack community on architectural matters.
This group is be open to all volunteers who are interested in participating
in OpenStack-wide design discussions.
Also note that this is an advisory group intended to gather information
and produce recommendations. No new authority for enforcing those is
to be conferred onto this group, however accepted recommendations will
be expected to be followed for new work whenever possible.
Scope
=====
* Document the existing architecture and relationship of OpenStack projects.
* Provide information and guidance to the TC and the OpenStack community on
architectural matters.
* Provide productive spaces for architects to share their designs and gain
support across projects to move forward with, coordinate, and implement
architectural decisions.
* Start with a limited scope in order to refine the group processes and be
able to achieve visible results (positive or negative) within the upcoming
Ocata release cycle.
Communication
=============
* Email: `openstack-dev mailing list`
* IRC: #openstack-meeting-alt on Freenode
* Meetings: `OpenStack wiki`_, `weekly meeting schedule`_ (includes day/time,
logs, ICS file, agenda)
.. _openstack-dev mailing list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
.. _OpenStack wiki: https://wiki.openstack.org/wiki/Meetings/Arch-WG
.. _weekly meeting schedule: http://eavesdrop.openstack.org/#Architecture_Working_Group
Deliverables
============
* [details tbd]
How To Contribute
=================
Topics
------
The WG maintains a backlog of topics in the repo under ``backlog/``. Additions
to the backlog should be proposed using Gerrit. Approval for addition is
concerned primarily with the proposal fitting into the scope of the WG.
* A topic background document should be proposed to the WG repo under backlog/
* The proposal will be held for review for a minimum of one week to allow time
for dicussion regarding its fitness for the scope of the WG.
* The proposal should also be added to an upcoming IRC `meeting agenda`_ to
allow the proposer to make a pitch and answer questions.
* Proposals that do not receive objections after the review period will be
considered approved as in-scope and merged into the backlog.
* The WG will move proposals from the backlog to the ``active/`` work area as
it chooses to work on them.
The background document should be sufficient to describe the topic and use
cases or other reasons it should be considered, such as how it would improve
OpenStack as a whole or solve specific use cases.
.. _meeting agenda: https://wiki.openstack.org/wiki/Meetings/Arch-WG
Participation
-------------
Participation in the Architecture Working Group is voluntary and defined by
those who attend the meetings and contribute proposals, reviews and effort into
the group activities. There is a core review group (seeded with volunteers at
early meetings) that has the ability to commit changes to the WG Git repo. As
with most of OpenStack, membership of that group is merit-based with
participation and other contributions being considered.
Background
==========
OpenStack is a big system. We have debated_ what it actually is,
and there are even t-shirts to poke fun at the fact that we don't have
good answers.
But this isn't what any of us wants. We'd like to be able to point at
something and proudly tell people "This is what we designed and implemented."
.. _debated: http://lists.openstack.org/pipermail/openstack-dev/2016-May/095452.html
Problem description
-------------------
For each individual project, design is a possibility. Neutron can tell you
they designed how their agents and drivers work. Nova can tell you that they
designed the way conductors handle communication with API nodes and compute
nodes. But when we start talking about how they interact with each other,
it's clearly just a coincidental mash of de-facto standards and specs that
don't help anyone make decisions when debugging, refactoring, or adding on
to the system.
Oslo and cross-project initiatives have brought some peace and order to the
implementation and engineering processes, but not to the design process. New
ideas still start largely in the project where they are needed most, and often
conflict with similar decisions and ideas in other projects , including dlm,
taskflow, tooz, service discovery, state machines, glance tasks, messaging
patterns, database patterns, etc. etc. Often this creates a log jam where
none of the projects adopt a solution that would align with others. Most
of the time when things finally come to a head these things get done in a
piecemeal fashion, where it's half done here, 1/3 over there, 1/4 there,
and 3/4 over there..., which to the outside looks like **architecture chaos**,
because that's precisely what it is.
And this isn't always a technical design problem. OpenStack, for instance,
isn't really a micro service architecture. Of course, it might look
like on the diagram below, but we all know it really isn't.
.. image:: http://docs.openstack.org/admin-guide/_images/openstack-arch-kilo-logical-v1.png
:width: 650px
The compute node is home to agents for every single concern, and the API
interactions between the services is too tightly woven to consider many
of them functional without the same lockstep version of other services
together. A game to play is ask yourself what would happen if a service
was isolated on its own island? How functional would its API be, if at
all? Is this something that we want? No. But there doesn't seem to be
a place where we can go to actually design, discuss, debate, and build
consensus around changes that would help us get to the point of gathering
the necessary will and capability to enact these efforts.
The need for attention ranges from the above project interaction level up
to higher-level questions such as 'What other OpenStack services can any
particular service assume to be available?'

6
requirements.txt Normal file
View File

@ -0,0 +1,6 @@
oslosphinx>=4.7.0 # Apache-2.0
rst2pdf
six>=1.9.0
sphinx>=1.2.1,!=1.3b1,<1.4 # BSD
sphinxcontrib-httpdomain # BSD
sphinx_rtd_theme

20
setup.cfg Normal file
View File

@ -0,0 +1,20 @@
[metadata]
name = arch_wg
summary = OpenStack Architecture WG resources, documents and investigations
description-file =
README.rst
author = OpenStack
classifier =
Environment :: OpenStack
Intended Audience :: Developers
Intended Audience :: Information Technology
License :: OSI Approved :: Apache Software License
[files]
packages =
arch_wg
[build_sphinx]
all_files = 1
build-dir = doc/build
source-dir = doc/source

27
setup.py Normal file
View File

@ -0,0 +1,27 @@
# 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
# In python < 2.7.4, a lazy loading of package `pbr` will break
# setuptools if some other modules registered functions in `atexit`.
# solution from: http://bugs.python.org/issue15881#msg170215
try:
import multiprocessing # noqa
except ImportError:
pass
setuptools.setup(
setup_requires=['pbr>=1.8'],
pbr=True)

6
test-requirements.txt Normal file
View File

@ -0,0 +1,6 @@
hacking>=0.11.0,<0.12 # Apache-2.0
testrepository>=0.0.18 # Apache-2.0/BSD
testtools>=1.4.0 # MIT
os-testr>=0.8.0 # Apache-2.0

0
tests/__init__.py Normal file
View File

18
tests/test_fake.py Normal file
View File

@ -0,0 +1,18 @@
# 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 testtools
class TestFake(testtools.TestCase):
def test_fake(self):
pass

22
tox.ini Normal file
View File

@ -0,0 +1,22 @@
[tox]
envlist = docs,py27
skipsdist = True
[testenv]
basepython = python2.7
setenv = VIRTUAL_ENV={envdir}
LANG=en_US.UTF-8
LANGUAGE=en_US:en
LC_ALL=C
deps =
-r{toxinidir}/requirements.txt
-r{toxinidir}/test-requirements.txt
commands = ostestr {posargs}
[testenv:venv]
commands = {posargs}
[testenv:docs]
commands =
python setup.py build_sphinx