Merge "6wind-virtual-accelerator-plugin: adding documentation and spec"
This commit is contained in:
commit
df82128140
|
@ -0,0 +1,178 @@
|
|||
# Makefile for Sphinx documentation
|
||||
# Copy of Mirantis example (https://github.com/openstack/fuel-plugin-openbook/blob/7.0/doc/Makefile)
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = build
|
||||
|
||||
# User-friendly check for sphinx-build
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||
endif
|
||||
|
||||
# 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 " 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 " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
|
||||
@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 " xml to make Docutils-native XML files"
|
||||
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
|
||||
@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/fuel-plugin-openbook.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/fuel-plugin-openbook.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/fuel-plugin-openbook"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/fuel-plugin-openbook"
|
||||
@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."
|
||||
|
||||
latexpdfja:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through platex and dvipdfmx..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
|
||||
@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."
|
||||
|
||||
xml:
|
||||
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
|
||||
@echo
|
||||
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
|
||||
|
||||
pseudoxml:
|
||||
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
|
||||
@echo
|
||||
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Appendix
|
||||
========
|
||||
|
||||
#. `6WIND virtual accelerator overview <http://www.6wind.com/products/6wind-virtual-accelerator/>`_
|
|
@ -0,0 +1,343 @@
|
|||
#
|
||||
# Copyright 2016 6WIND S.A.
|
||||
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# fuel-plugin-openbook documentation build configuration file, created by
|
||||
# sphinx-quickstart on Wed Oct 7 12:48:35 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 = [
|
||||
# 'sphinx.ext.todo',
|
||||
# 'sphinx.ext.coverage',
|
||||
]
|
||||
|
||||
# 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'The 6WIND virtual accelerator plugin for Fuel'
|
||||
copyright = u'2016, 6WIND SA.'
|
||||
|
||||
# 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 1.0-1.0.0-1 version.
|
||||
version = '1.0'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '1.0-1.0.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 ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
html_theme = 'default'
|
||||
|
||||
# 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 = 'fuel-plugin-6wind-virtual-accelerator'
|
||||
|
||||
|
||||
# -- 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', 'fuel-plugin-6wind-va.tex', u'The 6WIND virtual accelerator Plugin for Fuel Documentation',
|
||||
u'6WIND SA', '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
|
||||
|
||||
# make latex stop printing blank pages between sections
|
||||
# http://stackoverflow.com/questions/5422997/sphinx-docs-remove-blank-pages-from-generated-pdfs
|
||||
latex_elements = { 'classoptions': ',openany,oneside', 'babel' : '\\usepackage[english]{babel}' }
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
('index', 'fuel-plugin-6wind-va', u'Guide to the 6WIND virtual accelerator Plugin ver. 1.0-1.0.0-1 for Fuel',
|
||||
[u'6WIND SA'], 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', 'fuel-plugin-6wind-va', u'The 6WIND virtual accelerator Plugin for Fuel Documentation',
|
||||
u'6WIND SA', 'fuel-plugin-6wind-va', 'The 6WIND virtual accelerator Plugin for Fuel Documentation',
|
||||
'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
|
||||
|
||||
# Insert footnotes where they are defined instead of
|
||||
# at the end.
|
||||
pdf_inline_footnotes = True
|
||||
|
||||
|
||||
|
||||
# -- Options for Epub output ----------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = u'The 6WIND virtual accelerator Plugin for Fuel'
|
||||
epub_author = u'6WIND SA'
|
||||
epub_publisher = u'6WIND SA'
|
||||
epub_copyright = u'2016, 6WIND SA'
|
||||
|
||||
# The basename for the epub file. It defaults to the project name.
|
||||
#epub_basename = u'fuel-plugin-openbook'
|
||||
|
||||
# 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
|
Binary file not shown.
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
After Width: | Height: | Size: 91 KiB |
Binary file not shown.
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
After Width: | Height: | Size: 64 KiB |
Binary file not shown.
After Width: | Height: | Size: 100 KiB |
|
@ -0,0 +1,13 @@
|
|||
.. _fuel-plugin-6wind-virtual-accelerator:
|
||||
|
||||
Guide to the 6WIND virtual accelerator plugin for Fuel 7.0
|
||||
==========================================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
introduction
|
||||
installation
|
||||
user-guide
|
||||
appendix
|
|
@ -0,0 +1,143 @@
|
|||
Installation Guide
|
||||
==================
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
This guide assumes that you have `installed Fuel <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html>`_
|
||||
and all the nodes of your future environment are discovered and functional.
|
||||
Note, the 6WIND virtual accelerator Fuel plugin will download virtual
|
||||
accelerator packages from a remote repository. Make sure that nodes can correctly
|
||||
reach Internet.
|
||||
|
||||
To correctly deploy the 6WIND virtual accelerator Fuel plugin you will need
|
||||
a credentials package (in base64 format).
|
||||
|
||||
If you have already purchased 6WIND software you should have this package,
|
||||
otherwise contact 6WIND support team.
|
||||
On the other hand, if you just want to evaluate the 6WIND virtual accelerator
|
||||
you still need to `contact 6WIND <http://www.6wind.com/company-profile/contact-us/>`_.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
This plugin is intended to be installed on nodes running Fuel 7.0 (version 7.0.0)
|
||||
Verify this typing the following command:
|
||||
::
|
||||
|
||||
fuel --version
|
||||
|
||||
In order to correctly install the 6WIND virtual accelerator plugin on Fuel
|
||||
compute(s) the following requirements are mandatory:
|
||||
|
||||
#. Use KVM as hypervisor virtualization driver
|
||||
#. Deploy on compute node(s) with **at least 4GB of RAM and 2 cpus**
|
||||
#. Internet connectivity on Master node (since the plugin will download software from 6WIND remote repositories)
|
||||
#. A dedicated link for Neutron networking tunnels between Compute and Network
|
||||
|
||||
For networking all tunneling options are supported, namely VLAN, VXLAN and GRE.
|
||||
It is mandatory to use a dedicated physical network interface for your tunnels
|
||||
instead of the default Fuel setup that puts this interface on the same used
|
||||
for pxe and management.
|
||||
|
||||
The 6WIND virtual accelerator needs qemu and libvirt supporting vhostuser and
|
||||
multiqueue features to correclty run its fast packet processing stack.
|
||||
In particular on the compute nodes the following packages are needed:
|
||||
|
||||
#. libvirt-bin (1.3.1-1ubuntu6)
|
||||
#. qemu (2.5+dfsg-5ubuntu6)
|
||||
|
||||
Note that Mirantis official repositories do not provide these packages.
|
||||
For this reason the default behavior for the plugin is to retrieve the
|
||||
6WIND libvirt and qemu packages and replace the Mirantis ones in the early
|
||||
stages of deployment.
|
||||
|
||||
|
||||
Installing 6WIND virtual accelerator Plugin
|
||||
-------------------------------------------
|
||||
|
||||
#. Download 6WIND virtual accelerator plugin from the `Fuel Plugins Catalog <https://software.mirantis.com/download-mirantis-openstack-fuel-plug-ins/>`_.
|
||||
#. Copy the downloaded rpm to the Fuel Master node:
|
||||
::
|
||||
|
||||
scp 6wind-virtual-accelerator-1.0-1.0.0-1.noarch.rpm <Fuel Master node ip>:/tmp/
|
||||
|
||||
#. Log into the Fuel Master node and install the plugin
|
||||
::
|
||||
|
||||
ssh <the Fuel Master node ip>
|
||||
fuel plugins --install /tmp/6wind-virtual-accelerator-1.0-1.0.0-1.noarch.rpm
|
||||
|
||||
#. Now verify that the plugin is correctly installed
|
||||
::
|
||||
|
||||
fuel plugins
|
||||
3 | 6wind-virtual-accelerator | 1.0.0 | 3.0.0
|
||||
|
||||
..
|
||||
|
||||
|
||||
Configuring 6WIND virtual accelerator Plugin
|
||||
--------------------------------------------
|
||||
|
||||
#. First you have to `create environment <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#create-a-new-openstack-environment>`_ in Fuel Web UI.
|
||||
|
||||
.. image:: images/name_release.png
|
||||
:width: 70%
|
||||
|
||||
#. Please select KVM hypervisor type for your environment.
|
||||
|
||||
.. image:: images/hypervisor.png
|
||||
:width: 80%
|
||||
|
||||
#. Please select Neutron networking.
|
||||
The 6WIND virtual accelerator supports all tunneling models (VXLAN, GRE) and
|
||||
VLAN segmentation.
|
||||
For GRE segmentation you need to enable it from Fuel CLI
|
||||
|
||||
.. image:: images/network.png
|
||||
:width: 80%
|
||||
|
||||
#. Activate the plugin in the Fuel Web UI Settings tab
|
||||
|
||||
.. image:: images/activation.png
|
||||
:width: 90%
|
||||
|
||||
#. Configure fields with correct values:
|
||||
|
||||
* Provide base64 credentials package you received from 6WIND support team
|
||||
|
||||
* Refer to next chapter for detailed field description and configuration
|
||||
|
||||
|
||||
#. Add nodes and assign them the following roles:
|
||||
|
||||
* At least 1 Controller
|
||||
|
||||
* At least one node with both Compute and 6WIND Virtual Accelerator roles.
|
||||
Make sure that the chosen node has **at least 2 cpus and 4 GB of RAM**
|
||||
|
||||
.. image:: images/node-roles.png
|
||||
:width: 100%
|
||||
|
||||
#. Configure nodes to use a dedicated link for Neutron networking:
|
||||
|
||||
* Select the Compute and 6WIND Virtual Accelerator node and configre its
|
||||
interfaces.
|
||||
|
||||
.. image:: images/configure.png
|
||||
:width: 100%
|
||||
|
||||
* Drag the Private interface to the dedicated NIC used to connect to Controller.
|
||||
|
||||
.. image:: images/interface.png
|
||||
:width: 100%
|
||||
|
||||
* Perform these two steps for the Controller node too and choose the NIC
|
||||
accordingly.
|
||||
|
||||
#. Press **Deploy changes** to `deploy the environment <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#
|
||||
deploy-changes>`_.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
This document contains instructions for installing and configuring 6WIND virtual
|
||||
accelerator plugin for Fuel.
|
||||
|
||||
Key terms, acronyms and abbreviations
|
||||
-------------------------------------
|
||||
|
||||
+---------------------------+---------------------------+
|
||||
| 6WIND virtual accelerator | |
|
||||
| | |
|
||||
+---------------------------+---------------------------+
|
||||
| VA | 6WIND Virtual Accelerator |
|
||||
+---------------------------+---------------------------+
|
||||
| MOS | Mirantis Openstack |
|
||||
+---------------------------+---------------------------+
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
|
||||
Licensing information
|
||||
---------------------
|
||||
|
||||
+---------------------------+------------+
|
||||
| 6WIND virtual accelerator | Commercial |
|
||||
+---------------------------+------------+
|
|
@ -0,0 +1,125 @@
|
|||
User Guide
|
||||
==========
|
||||
|
||||
This section provides a deeper explanation of plugin parameters and a description
|
||||
of required steps to verify that everything is working fine after deployment.
|
||||
|
||||
Note that this User Guide provides information on 6WIND virtual accelerator
|
||||
plugin for Fuel (and not on the 6WIND virtual accelerator software itself).
|
||||
`Contact 6WIND <http://www.6wind.com/company-profile/contact-us/>`_
|
||||
to obtain more details on how to retrieve the virtual accelerator software and
|
||||
its documentation.
|
||||
|
||||
When configuring the 6WIND virtual accelerator Fuel plugin, you have to provide
|
||||
credentials for virtual accelerator software download.
|
||||
The plugin will then install and run the virtual accelerator using its default
|
||||
configuration values.
|
||||
|
||||
Configuring 6WIND virtual accelerator parameters
|
||||
------------------------------------------------
|
||||
|
||||
The 6WIND virtual accelerator plugin makes possible to modify these default
|
||||
configuration parameters before deployment.
|
||||
In order to do this you need to activate the **Advanced parameters** checkbox
|
||||
in the 6WIND Virtual Accelerator fuel plugin section in the Web UI Settings tab.
|
||||
|
||||
.. image:: images/advanced.png
|
||||
:width: 100%
|
||||
|
||||
At this point some additional fields will show up and you will be able to edit
|
||||
with your desired values.
|
||||
Please contact 6WIND support team or refer to 6WIND virtual accelerator documentation
|
||||
for more information on the meaning of these fields.
|
||||
|
||||
|
||||
If you already have a virtual accelerator configuration file,
|
||||
you can upload it to the nodes having the 6WIND Virtual Accelerator role enabled.
|
||||
Note, this file will replace the default virtual accelerator configuration file
|
||||
and overload all the defined configuration paramaters.
|
||||
|
||||
Use updated libvirt and qemu packages
|
||||
-------------------------------------
|
||||
|
||||
As briefly described in the installation section, in order to correctly spawn
|
||||
virtual machines using the accelerated network stack 6WIND virtual accelerator
|
||||
provides, the compute nodes need to run recent versions of libvirt and qemu
|
||||
packages.
|
||||
|
||||
|
||||
By default the 6WIND virtual accelerator Fuel plugin retrieves and installs
|
||||
its updated libvirt and qemu packages from a remote repository maintained by 6WIND.
|
||||
It is possible to force the plugin to keep the default libvirt and qemu packages
|
||||
provided by the Linux distribution.
|
||||
|
||||
|
||||
To do this simply unselect the **Use updated external packages** checkbox.
|
||||
Note, default libvirt and qemu packages on MOS 7.0 do not have all the features
|
||||
required for proper 6WIND virtual accelerator integration. Thus we strongly
|
||||
advise to keep the **Use updated external packages** enabled.
|
||||
|
||||
Sanity checks after deployment
|
||||
------------------------------
|
||||
|
||||
The installation section of this document described how to correctly start a
|
||||
Fuel deployment using the 6WIND virtual accelerator plugin.
|
||||
At the end of this process the 6WIND virtual accelerator and its dependent
|
||||
components should be all up and running.
|
||||
|
||||
As first step make sure that the system uses the proper libvirt and qemu
|
||||
versions.
|
||||
|
||||
#. Check libvirt version (should be **1.3.1-1ubuntu6**)
|
||||
|
||||
::
|
||||
|
||||
aptitude show libvirt-bin | grep Version
|
||||
|
||||
#. Check qemu version (should be **2.5+dfsg-5ubuntu6**)
|
||||
|
||||
::
|
||||
|
||||
aptitude show qemu-system-x86 | grep Version
|
||||
|
||||
The next step is checking that the 6WIND virtual accelerator software and
|
||||
its Openstack extensions have been correctly installed.
|
||||
|
||||
#. Check 6WIND virtual accelerator package status (should be **State: installed**)
|
||||
|
||||
::
|
||||
|
||||
aptitude show virtual-accelerator | grep State
|
||||
|
||||
#. Check 6WIND openstack extensions package status (should be **State: installed**)
|
||||
|
||||
::
|
||||
|
||||
aptitude show 6wind-openstack-extension | grep State
|
||||
|
||||
|
||||
If this check is successful, verify that that ALL the following services are
|
||||
correctly running (each of them should be **start/running**):
|
||||
|
||||
::
|
||||
|
||||
service virtual-accelerator status
|
||||
service openvswitch-switch status
|
||||
service neutron-plugin-openvswitch-agent status
|
||||
service libvirtd status
|
||||
service nova-compute status
|
||||
|
||||
If some of the services are not properly running, please restart ALL of them
|
||||
in the same order used before for their status check.
|
||||
Otherwise if everything is active you should be able to correctly spawn
|
||||
virtual machines.
|
||||
To do that please refer to `6WIND Openstack extensions official documentation <http://www.6wind.com/company-profile/contact-us/>`_.
|
||||
|
||||
Known issues
|
||||
============
|
||||
|
||||
The current implementation of the 6WIND virtual accelerator plugin uses a credentials
|
||||
package in base64 format for 6WIND software download.
|
||||
This behavior should be replaced using a regular credentials package instead of
|
||||
its base64 encoding.
|
||||
Unfortunately a bug in Fuel 7.0 does not make possible to correctly retrieve
|
||||
this package from the upload utility.
|
||||
`<https://bugs.launchpad.net/fuel/+bug/1545795>`_
|
|
@ -0,0 +1,134 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
======================================================
|
||||
Fuel Plugin for 6WIND virtual accelerator installation
|
||||
======================================================
|
||||
|
||||
The Fuel plugin for 6WIND virtual accelerator allows to install and integrate
|
||||
the virtual accelerator on desired nodes (compute) running Mirantis Openstack 7.0.
|
||||
|
||||
This plugin uses the Fuel pluggable architecture and it must be compatible with
|
||||
(at least) the version 7.0 of Mirantis OpenStack.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Implement a Fuel plugin which will perform all the necessary steps to install
|
||||
and configure Mirantis OpenStack nodes to use the 6WIND virtual accelerator.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
SR-IOV
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
|
||||
None
|
||||
|
||||
Upgrade impact
|
||||
--------------
|
||||
|
||||
When upgrading to newer versions of Mirantis Openstack, this plugin should be
|
||||
upgraded accordingly.
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
None. Nova security groups are still supported for deployed VMs on all compute
|
||||
nodes running 6WIND VA.
|
||||
|
||||
Notifications impact
|
||||
--------------------
|
||||
|
||||
None
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
After plugin installation, the end user can enable it on the Setting tab of the
|
||||
Fuel web UI and customize plugin settings.
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
|
||||
- Francesco Santoro <francesco.santoro@6wind.com>
|
||||
|
||||
Other contributors:
|
||||
|
||||
- Samuel Gauthier <samuel.gauthier@6wind.com> - developer
|
||||
- Karim Mchirki <karim.mchirki@6wind.com> - developer
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
* Create test environment (physical servers or KVM based vms)
|
||||
* Create Fuel plugin bundle (containing deployments scripts, puppet modules and
|
||||
metadata)
|
||||
* Implement puppet modules with the following functions:
|
||||
|
||||
- Retrieve 6WIND virtual accelerator software from repository
|
||||
- Eventually updates libvirt and qemu Mirantis Openstack packages on compute nodes
|
||||
- 6WIND virtual accelerator deployment on selected OpenStack nodes
|
||||
- Configure Mirantis Openstack to support 6WIND virtual accelerator
|
||||
|
||||
* Test 6WIND virtual accelerator plugin
|
||||
* Create Documentation
|
||||
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
* Fuel 7.0
|
||||
* Hypervisor with KVM capability
|
||||
* Qemu with vhost-user and hugepage support
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
* Sanity checks including plugin build
|
||||
* Syntax check
|
||||
* Functional testing
|
||||
* Non-functional testing (Destructive and Negative)
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
* Deployment Guide (how to prepare environment for plugin installation and configuration before MOS deployment)
|
||||
* User Guide (list of features the plugin provides, how to customize them in the deployed MOS environment)
|
||||
* Test Plan
|
||||
* Test Report
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* Fuel 7.0 Plug-in Guide https://docs.mirantis.com/openstack/fuel/fuel-7.0/plugin-dev.html
|
||||
* 6WIND virtual accelerator product info http://www.6wind.com/products/6wind-virtual-accelerator/
|
Loading…
Reference in New Issue