Update user-guide for sphinx format

Change-Id: Iafaf55efed1cce9a3eebc9004307b670bae4f13d
This commit is contained in:
Illia Polliul 2016-03-22 02:14:33 +02:00
parent 5117cc5144
commit d8297ef924
23 changed files with 336 additions and 62 deletions

1
doc/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
build/

197
doc/Makefile Normal file
View File

@ -0,0 +1,197 @@
# Makefile for Sphinx documentation
#
# 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
# SVG to PDF conversion
SVG2PDF = inkscape
SVG2PDF_FLAGS =
# Build a list of SVG files to convert to PDF
PDF_FILES := $(foreach dir, images, $(patsubst %.svg,%.pdf,$(wildcard $(dir)/*.svg)))
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage 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 " applehelp to make an Apple Help Book"
@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)"
@echo " coverage to run coverage check of 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/EMCpluginforFuel.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/EMCpluginforFuel.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/EMCpluginforFuel"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/EMCpluginforFuel"
@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."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.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."

View File

@ -1,34 +0,0 @@
===================================================
Guide to the EMC VNX Plugin for Fuel
===================================================
EMC VNX plugin for Fuel extends Mirantis OpenStack functionality by adding
support for EMC VNX arrays in Cinder using iSCSI protocol. It replaces Cinder
LVM driver which is the default volume backend that uses local volumes managed
by LVM. Enabling EMC VNX plugin in Mirantis OpenStack means that all Cinder
services are run on Controller nodes.
Requirements
============
+------------------------------------+----------------------------------------+
|Requirement | Version/Comment |
+====================================+========================================+
|Fuel | 7.0 and higher |
+------------------------------------+----------------------------------------+
|EMC VNX array | It should be configured and deployed. |
| | It should be reachable via one |
| | of the Mirantis OpenStack networks. |
+------------------------------------+----------------------------------------+
Limitations
============
#. Since only one storage network is available in Fuel 7.x on OpenStack nodes,
multipath will bind all storage paths from EMC on one network interface.
In case this NIC fails, the communication with storage is lost.
#. Fibre Channel driver is not supported.
#. Emc plugin cannot be used together with cinder role and/or options 'Cinder LVM over iSCSI for volumes', 'Ceph RBD for volumes (Cinder)'.

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

@ -0,0 +1,35 @@
from distutils.version import LooseVersion
from sphinx import __version__ as sphinx_version
source_suffix = '.rst'
master_doc = 'index'
project = u'EMC VNX plugin for Fuel'
copyright = u'2016, Mirantis Inc.'
version = '3.0'
release = '3.0-3.0.0-1'
pygments_style = 'sphinx'
latex_documents = [
('index','fuel-plugin-external-emc-doc.tex',
u'EMC VNX plugin for Fuel Documentation',
u'Mirantis Inc.', 'manual')
]
# Configuration for the latex/pdf docs.
latex_elements = {
'papersize': 'a4paper',
'pointsize': '11pt',
# remove blank pages
'classoptions': ',openany,oneside',
'babel': '\\usepackage[english]{babel}',
}
if LooseVersion(sphinx_version) >= LooseVersion('1.3.1'):
html_theme = "sphinx_rtd_theme"
html_add_permalinks = ""
html_show_copyright = False
highlight_language = 'none'

View File

@ -36,5 +36,5 @@ Pool name (optional) The name of the EMC VNX storage pool on
3. Adjust other environment settings to your requirements and deploy the
environment. For more information, see `Mirantis OpenStack User Guide -
deploy changes <http://docs.mirantis.com/openstack/fuel/fuel-7.0
deploy changes <http://docs.mirantis.com/openstack/fuel/fuel-8.0
/user-guide.html#deploy-changes>`_.

View File

@ -0,0 +1,46 @@
===================================================
Guide to the EMC VNX Plugin for Fuel
===================================================
EMC VNX plugin for Fuel extends Mirantis OpenStack functionality by adding
support for EMC VNX arrays in Cinder using iSCSI protocol. It replaces Cinder
LVM driver which is the default volume backend that uses local volumes managed
by LVM. Enabling EMC VNX plugin in Mirantis OpenStack means that all Cinder
services are run on Controller nodes.
Requirements
============
+-----------------+-----------------------------------------------------------+
|Requirement | Version/Comment |
+=================+===========================================================+
|Fuel | 8.0 |
+-----------------+-----------------------------------------------------------+
|EMC VNX array | #. VNX Operational Environment for Block version 5.32 |
| | or higher. |
| | #. VNX Snapshot and Thin Provisioning license should be |
| | activated for VNX. |
| | #. Array should be configured and deployed. |
| | #. Array should be reachable via one of the Mirantis |
| | OpenStack networks. |
+-----------------+-----------------------------------------------------------+
Limitations
============
#. Since only one storage network is available in Fuel 8.x on OpenStack nodes,
multipath will bind all storage paths from EMC on one network interface.
In case this NIC fails, the communication with storage is lost.
#. Fibre Channel driver is not supported.
#. EMC VNX plugin cannot be used together with cinder role and/or options
'Cinder LVM over iSCSI for volumes', 'Ceph RBD for volumes (Cinder)'.
Compatible monitoring plugins
=============================
#. zabbix_monitoring-2.5-2.5.0-1.noarch.rpm
#. zabbix_snmptrapd-1.0-1.0.1-1.noarch.rpm
#. zabbix_monitoring_extreme_networks-1.0-1.0.1-1.noarch.rpm
#. zabbix_monitoring_emc-1.0-1.0.1-1.noarch.rpm

View File

@ -13,7 +13,7 @@ volume and attach it to a newly created VM using for example
*cinder create <volume size>* command:
.. image:: images/create.png
:width: 50%
:width: 90%
#. Using *cinder list* command (see the screenshot above), lets check if the
volume was created. The output provides information on ID, Status
@ -31,7 +31,7 @@ volume and attach it to a newly created VM using for example
EMC:
.. image:: images/lunid.png
:width: 50%
:width: 90%
In the given example there is one LUN with ID: 0, name:
*volume-e1626d9e-82e8-4279-808e-5fcd18016720* (naming schema is
@ -43,7 +43,7 @@ volume and attach it to a newly created VM using for example
command):
.. image:: images/glance.png
:width: 50%
:width: 90%
Note the VMs ID which is *48e70690-2590-45c7-b01d-6d69322991c3* in the
given example.
@ -53,20 +53,20 @@ volume and attach it to a newly created VM using for example
the VM is running on the node-3 and it is active:
.. image:: images/novaShow.png
:width: 50%
:width: 90%
#. Attach the Cinder volume to the VM (use *nova volume-attach <VM id>
<volume id>*)
and verify using cinder list command:
.. image:: images/volumeAttach.png
:width: 50%
:width: 90%
#. To list storage groups configured on EMC VNX, use *naviseccli -h <SP IP>
storagegroup -list* command:
.. image:: images/storagegroup.png
:width: 50%
:width: 90%
There is one “node-3” storage group with one LUN attached. The LUN has local
ID 0 (ALU Number) and it is available as LUN 133 (HLU Number) for the
@ -76,7 +76,7 @@ volume and attach it to a newly created VM using for example
*naviseccli -h <SP IP> port -list -hba* command:
.. image:: images/hba.png
:width: 50%
:width: 90%
Look at “Logged In” parameter of each port. In the given example, all four
sessions are active (in the output, it looks like Logged In: YES).
@ -89,7 +89,7 @@ volume and attach it to a newly created VM using for example
.. image:: images/iscsiadmin.png
:width: 50%
:width: 90%
In the example, there are four active sessions (the same as on the EMC) and
the multipath device dm-2 has been created. The multipath device has four

View File

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 60 KiB

View File

Before

Width:  |  Height:  |  Size: 142 KiB

After

Width:  |  Height:  |  Size: 142 KiB

View File

Before

Width:  |  Height:  |  Size: 118 KiB

After

Width:  |  Height:  |  Size: 118 KiB

View File

Before

Width:  |  Height:  |  Size: 85 KiB

After

Width:  |  Height:  |  Size: 85 KiB

View File

Before

Width:  |  Height:  |  Size: 110 KiB

After

Width:  |  Height:  |  Size: 110 KiB

View File

Before

Width:  |  Height:  |  Size: 112 KiB

After

Width:  |  Height:  |  Size: 112 KiB

View File

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

View File

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 53 KiB

View File

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 51 KiB

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

@ -0,0 +1,20 @@
.. _fuel-plugin-external-emc:
****************************************************************
Guide to the EMC VNX Plugin version 3.0.0 for Fuel
****************************************************************
This document provides instructions for installing, configuring and using
EMC VNX plugin for Fuel.
.. toctree::
:maxdepth: 2
:numbered:
terms.rst
description.rst
installation.rst
configuration.rst
guide.rst
troubleshooting.rst
appendix.rst

View File

@ -36,19 +36,19 @@ EMC VNX plugin installation
the Fuel Master node yet, see
`Quick Start Guide <https://software.mirantis.com/quick-start/>`_::
# scp emc_vnx-2.0-2.0.0-1.noarch.rpm root@<the_Fuel_Master_node_IP>:/tmp
# scp emc_vnx-3.0-3.0.0-1.noarch.rpm root@<the_Fuel_Master_node_IP>:/tmp
#. Log into the Fuel Master node. Install the plugin::
# cd /tmp
# fuel plugins --install emc_vnx-2.0-2.0.0-1.noarch.rpm
# fuel plugins --install emc_vnx-3.0-3.0.0-1.noarch.rpm
#. Check if the plugin was installed successfully::
# fuel plugins
id | name | version | package_version
---|---------|---------|----------------
1 | emc_vnx | 2.0.0 | 2.0.0
1 | emc_vnx | 3.0.0 | 3.0.0
EMC VNX plugin removal
@ -58,7 +58,7 @@ EMC VNX plugin removal
#. Uninstall the plugin:
# fuel plugins --remove emc_vnx==2.0.0
# fuel plugins --remove emc_vnx==3.0.0
#. Check if the plugin was uninstalled successfully::

View File

@ -10,7 +10,7 @@ To uninstall Zabbix plugin, follow these steps:
1. Delete all Environments in which Zabbix plugin has been enabled.
2. Uninstall the plugin:
# fuel plugins --remove zabbix_monitoring==2.0.0
# fuel plugins --remove zabbix_monitoring==2.5.0
3. Check if the plugin was uninstalled successfully:

View File

@ -0,0 +1,23 @@
=====================
Troubleshooting Guide
=====================
Most Cinder errors are caused by incorrect volume configurations that
result in volume creation failures. To resolve these failures, review these logs
on Controller nodes:
#. cinder-api log (/var/log/cinder/api.log)
#. cinder-volume log (/var/log/cinder/volume.log)
The cinder-api log is useful for determining if you have endpoint or connectivity
issues. If you send a request to create a volume and it fails, review the cinder-api
log to determine whether the request made it to the Block Storage service.
If the request is logged and you see no errors or trace-backs, check the cinder-volume
log for errors or trace-backs.
Cinder services are running as pacemaker resources. To verify status of services,
issue following command on one of Controllers::
# pcs resource show
All Cinder services should be in "Started" mode.

View File

@ -1,14 +0,0 @@
****************************************************************
Guide to the EMC VNX Plugin version 2.0.0 for Fuel
****************************************************************
This document provides instructions for installing, configuring and using
EMC VNX plugin for Fuel.
.. contents::
.. include:: content/terms.rst
.. include:: content/description.rst
.. include:: content/installation.rst
.. include:: content/configuration.rst
.. include:: content/guide.rst
.. include:: content/appendix.rst