Added documentation
After migrating to the OpenStack infrastructure, the documentation was missing. This patch re-adds it. Closes-Bug: 1640285 Change-Id: I8f6f138b32483264d9ed8cdcc855b33f026097b6
This commit is contained in:
Kristi Nikolla
parent
b43d1f8418
commit
e3a948aa3c
|
|
@ -0,0 +1,155 @@
|
|||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = build
|
||||
SOURCEDIR = source
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
|
||||
|
||||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " autodoc generate the autodoc templates"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
@echo " info to make Texinfo files and run them through makeinfo"
|
||||
@echo " gettext to make PO message catalogs"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
|
||||
clean:
|
||||
-rm -rf $(BUILDDIR)/*
|
||||
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
singlehtml:
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
pickle:
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
json:
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
htmlhelp:
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
qthelp:
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/mixmatch.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/mixmatch.qhc"
|
||||
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/mixmatch"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/mixmatch"
|
||||
@echo "# devhelp"
|
||||
|
||||
epub:
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
latex:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
text:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
man:
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
texinfo:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo
|
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)."
|
||||
|
||||
info:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo "Running Texinfo files through makeinfo..."
|
||||
make -C $(BUILDDIR)/texinfo info
|
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||
|
||||
gettext:
|
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||
@echo
|
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||
|
||||
changes:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
linkcheck:
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
doctest:
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
Building Docs
|
||||
=============
|
||||
|
||||
Developer documentation is generated using Sphinx. To build this documentation,
|
||||
run the following from the root of the repository::
|
||||
|
||||
$ tox -e docs
|
||||
|
||||
The documentation will be built at ``doc/build/``.
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
============
|
||||
Architecture
|
||||
============
|
||||
|
||||
The proxy is designed to substitute an endpoint in the service catalog.
|
||||
When a user/service requests the proxied service for a specific resource
|
||||
(volume, image, etc), the proxy will analyze the URL of the request to
|
||||
figure out the type of the resource and the UUID of the resource and '
|
||||
forward the request to the correct service provider, getting a token through
|
||||
K2K and using that for the remote endpoint. It will then forward the response
|
||||
back.
|
||||
|
||||
.. image:: images/SequenceDiagram.png
|
||||
|
||||
To gather the information about the location of the resources, the proxy listens
|
||||
to the notifications message bus for messages which describe the creation of new
|
||||
resources, and stores that location information into the database.
|
||||
|
||||
.. image:: images/Notifications.png
|
||||
|
|
@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
|
|||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
#'sphinx.ext.intersphinx',
|
||||
'oslosphinx'
|
||||
#'oslosphinx'
|
||||
]
|
||||
|
||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||
|
|
@ -38,7 +38,8 @@ master_doc = 'index'
|
|||
|
||||
# General information about the project.
|
||||
project = u'mixmatch'
|
||||
copyright = u'2016, OpenStack Foundation'
|
||||
copyright = u'2016, Massachusetts Open Cloud'
|
||||
author = u'Massachusetts Open Cloud'
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
add_function_parentheses = True
|
||||
|
|
@ -55,8 +56,9 @@ pygments_style = 'sphinx'
|
|||
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
||||
# Sphinx are currently 'default' and 'sphinxdoc'.
|
||||
# html_theme_path = ["."]
|
||||
# html_theme = '_theme'
|
||||
html_theme = 'alabaster'
|
||||
# html_static_path = ['static']
|
||||
html_logo = 'images/moc.png'
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = '%sdoc' % project
|
||||
|
|
@ -68,7 +70,7 @@ latex_documents = [
|
|||
('index',
|
||||
'%s.tex' % project,
|
||||
u'%s Documentation' % project,
|
||||
u'OpenStack Foundation', 'manual'),
|
||||
u'Massachusetts Open Cloud', 'manual'),
|
||||
]
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.6 KiB |
|
|
@ -12,8 +12,8 @@ Contents:
|
|||
:maxdepth: 2
|
||||
|
||||
readme
|
||||
architecture
|
||||
installation
|
||||
usage
|
||||
contributing
|
||||
|
||||
Indices and tables
|
||||
|
|
|
|||
|
|
@ -2,11 +2,109 @@
|
|||
Installation
|
||||
============
|
||||
|
||||
At the command line::
|
||||
The proxy will be set up in one OpenStack installation, called the Identity
|
||||
Provider, or IdP, and it redirect API calls to either the local services, or
|
||||
remote services in one of several Service Provider installations (SP).
|
||||
|
||||
$ pip install mixmatch
|
||||
Install dependencies. ::
|
||||
|
||||
Or, if you have virtualenvwrapper installed::
|
||||
$ pip install -r requirements.txt
|
||||
$ python setup.py install
|
||||
|
||||
|
||||
Web Server
|
||||
==========
|
||||
The recommended way is to run the proxy using uWSGI through the
|
||||
``run_proxy.sh`` script. ::
|
||||
|
||||
$ ./run_proxy.sh
|
||||
|
||||
|
||||
It is also possible to run the proxy with Apache2 and ``mod_wsgi``, but there
|
||||
are limitations compared to running it with uWSGI.
|
||||
|
||||
- Image uploading with Glance doesn't work unless running Apache in embedded
|
||||
mode.
|
||||
- Image API v1 uses underscores in the header keys, which are silently dropped
|
||||
by Apache. Hacking the configuration to allow these through is required.
|
||||
|
||||
To run the proxy with Apache in Ubuntu: ::
|
||||
|
||||
$ apt-get install libapache2-mod-wsgi
|
||||
$ cp httpd/apache.conf /etc/apache2/sites-available/proxy.conf
|
||||
$ cp etc/k2k-proxy.conf /etc/
|
||||
$ a2ensite proxy
|
||||
$ service apache2 reload
|
||||
|
||||
|
||||
Configuration
|
||||
=============
|
||||
The proxy searches for the configuration file ``k2k-proxy.conf`` in the
|
||||
current directory, the ``etc/`` directory relative to the current directory or
|
||||
``/etc/``
|
||||
|
||||
A sample configuration file has been provided in the ``etc`` folder of the
|
||||
source code.
|
||||
|
||||
The proxy will substitute the endpoint of the service it is proxying.
|
||||
Only Cinder and Glance are supported for now.
|
||||
|
||||
For each SP, you must have a section in ``k2k-proxy.conf`` which contains the
|
||||
service provider name (as it is listed in Keystone's service catalog), and the
|
||||
URI for connecting to the notification messagebus in that OpenStack
|
||||
installation. For instance::
|
||||
|
||||
[sp_one]
|
||||
sp_name="keystone-sp1"
|
||||
messagebus="rabbit://rabbituser:rabbitpassword@192.168.7.20"
|
||||
image_endpoint="http://192.168.7.20:9292"
|
||||
volume_endpoint="http://192.168.7.20:8776"
|
||||
|
||||
Keystone Configuration
|
||||
----------------------
|
||||
|
||||
Keystone maintains the service catalog with information about all the
|
||||
configured endpoints.
|
||||
|
||||
In the IdP, delete and then recreate the endpoint which we will proxy. ::
|
||||
|
||||
$ openstack endpoint delete <endpoint_id>
|
||||
$ openstack endpoint create \
|
||||
--publicurl http://<proxy_host>:<proxy_port>/<service_type>/<api_version> \
|
||||
--internalurl http://<proxy_host>:<proxy_port>/<service_type>/<api_version> \
|
||||
--adminurl http://<proxy_host>:<proxy_port>/<service_type>/<api_version> \
|
||||
--region RegionOne \
|
||||
<endpoint_type>
|
||||
|
||||
Where service_type is ``image`` if endpoint_type is ``image``
|
||||
and ``volume`` if endpoint_type is ``volume`` or ``volumev2``
|
||||
|
||||
Nova Configuration
|
||||
------------------
|
||||
|
||||
Nova reads the endpoint address for glance from the configuration file stored
|
||||
in ``/etc/nova/nova.conf``. So, in the IdP, add the following::
|
||||
|
||||
# /etc/nova/nova.conf
|
||||
[glance]
|
||||
api_servers=<proxy_url>/image
|
||||
|
||||
Cinder Notification
|
||||
-------------------
|
||||
|
||||
Cinder reads the endpoint address for glance from the configuration file stored
|
||||
in ``/etc/cinder/cinder.conf``. So, in the IdP, add the following::
|
||||
|
||||
# /etc/cinder/cinder.conf
|
||||
[default]
|
||||
glance_api_servers=<proxy_url>/image
|
||||
|
||||
Every Cinder must be configured to emit notifications on the messagebus. So,
|
||||
in both the IdP and every SP, add the following to
|
||||
``/etc/cinder/cinder.conf``::
|
||||
|
||||
# /etc/cinder/cinder.conf
|
||||
[oslo_messaging_notifications]
|
||||
driver = messaging
|
||||
topics = notifications
|
||||
|
||||
$ mkvirtualenv mixmatch
|
||||
$ pip install mixmatch
|
||||
|
|
|
|||
|
|
@ -1,7 +0,0 @@
|
|||
========
|
||||
Usage
|
||||
========
|
||||
|
||||
To use mixmatch in a project::
|
||||
|
||||
import mixmatch
|
||||
Loading…
Reference in New Issue