Aligning install guide with the Pike doc structure

In Pike OpenStack documentation is changed in a way that the project repos
contain most of the documentation material [1]. This affcects how the doc
folder shall be strucutred inside the project repo. With this change I
align the install guide to the new structure and correct the warnings
during the document generation. The overall work is tracked in [2].

[1]: http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html
[2]: https://etherpad.openstack.org/p/doc-migration-tracking

Change-Id: Ib5400247d2ba5f8dac80ef68a43d06868bd42f1c
Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454
Signed-off-by: csatari <gergely.csatari@nokia.com>
This commit is contained in:
csatari 2017-06-26 14:03:06 +02:00
parent 0a48370270
commit c9ea8ea4a1
21 changed files with 70 additions and 628 deletions

View File

@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',
# 'sphinx.ext.intersphinx',
'oslosphinx'
'openstackdocstheme'
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
@ -38,7 +38,7 @@ master_doc = 'index'
# General information about the project.
project = u'vitrage'
copyright = u'2016, OpenStack Foundation'
copyright = u'2017, OpenStack Foundation'
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
@ -57,6 +57,14 @@ pygments_style = 'sphinx'
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static']
html_theme = 'openstackdocs'
# openstackdocstheme options
repository_name = 'openstack/vitrage'
bug_project = 'vitrage'
bug_tag = 'vitrage'
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project

View File

@ -52,6 +52,13 @@ or set a deduced state.
and states. Currently Vitrage has an Aodh notifier for raising Vitrage alarms
in Aodh, and a Nova notifier for marking that the host is down.
Installation Guide
------------------
.. toctree::
:maxdepth: 1
install/index
Developer Guide
---------------
@ -74,4 +81,5 @@ Design Documents
vitrage-use-cases
add-new-datasource
not_operator_support
template-loading
templates-loading
vitrage-ha-and-history-vision

View File

@ -1,6 +1,6 @@
============
Installation
============
==============================
Installation and configuration
==============================
Vitrage Installation
====================
@ -18,36 +18,32 @@ Enable Vitrage in Devstack
---------------------------------------------------
Manual Installation of Vitrage (not using Devstack)
---------------------------------------------------
.. toctree::
:maxdepth: 1
* `Vitrage manual installation <https://github.com/openstack/vitrage/blob/master/doc/source/vitrage-manual-installation.rst>`_
* `Vitrage-dashboard manual installation <https://github.com/openstack/vitrage-dashboard/blob/master/doc/source/installation.rst>`_
install/index
External Monitor Installation
=============================
To install Nagios or Zabbix external monitors:
* `Nagios devstack installation <http://docs.openstack.org/developer/vitrage/nagios-devstack-installation.html>`_
* `Zabbix devstack installation <http://docs.openstack.org/developer/vitrage/zabbix_vitrage.html>`_
.. toctree::
:maxdepth: 1
nagios-devstack-installation
zabbix_vitrage
Configuration
=============
* `Nagios Plugin Configuration <http://docs.openstack.org/developer/vitrage/nagios-config.html>`_
* `Static Plugin Configuration <http://docs.openstack.org/developer/vitrage/static-config.html>`_
* `Static Physical Plugin Configuration <http://docs.openstack.org/developer/vitrage/static-physical-config.html>`_
* `Resource State Configuration <http://docs.openstack.org/developer/vitrage/resource-state-config.html>`_
* `Alarm Severity Configuration <http://docs.openstack.org/developer/vitrage/alarm-severity-config.html>`_
* `Zabbix Configuration <http://docs.openstack.org/developer/vitrage/zabbix_vitrage.html>`_
* `SNMP Sender Configuration <https://github.com/openstack/vitrage/blob/master/doc/source/notifier-snmp-plugin.rst>`_
.. toctree::
:maxdepth: 1
nagios-config
static-config
static-physical-config
resource-state-config
alarm-severity-config
zabbix_vitrage
notifier-snmp-plugin

View File

@ -15,7 +15,7 @@ other linux flavours. Links for this purpose are added below.
Prerequisites
------------
-------------
Install devstack with vitrage before install Nagios via OMD due to this issue_
.. _issue: https://bugs.launchpad.net/vitrage/+bug/1629811

View File

@ -160,20 +160,22 @@ The Switch is attached to a Host that contains a Vm.
The Switch is also comprised to a Network which has a Port.
There is no edge between the Vm and the Port.
+---------+ +---------+
+----------- | Host | --------> | Vm |
| +---------+ +---------+
|
v |
+----------+ N
| Switch | | o
+----------+ t
|
| v
|
| +---------+ +---------+
+----------> | Network | <--------- | Port |
+---------+ +---------+
::
+---------+ +---------+
+----------- | Host | --------> | Vm |
| +---------+ +---------+
| |
v |
+----------+ | N
| Switch | | o
+----------+ | t
| |
| |
| v
| +---------+ +---------+
+----------> | Network | <-------- | Port |
+---------+ +---------+
::

View File

@ -1,94 +0,0 @@
===============================
Vitrage Notifier plugins - AODH
===============================
Overview
========
The Evaluator performs root cause analysis on the Vitrage Graph and may determine that an alarm should be created, deleted or otherwise updated.
Other components are notified of such changes by the Vitrage Notifier service. Among others, Vitrage Notifier is responsible for handling Aodh Alarms.
This document describes the implementation of Vitrage Notifier infrastructure and specifically notifying Aodh on Vitrage alarms.
Design
======
::
+----------+ +-----------+ +------+ +--------+
| Vitrage | | DataSource| |Graph | | Message| +------------------+
| Evaluator|->| Queue |-->| |-------->| Bus |------>| Vitrage Notifier |
+----------+ +-----------+ +------+ | | +------------------+
| | | | |
| | +----------+ | |
| | | Aodh |---+ |
| | | notifier | |----+
| | +--| plugin | | |
| | | +----------+ | |
+--------+ | +-----------+ |
| +------------+
+------------------+ |
| Aodh |<----------------------+
+------------------+
...
DeducedAlarmNotifier class will be subscribed to entity graph notifications. Whenever a vitrage deduced alarm is added to the graph it will post a message to the message bus.
The processor will hold an instance of the DeducedAlarmNotifier class and will subscribe this instance to entity graph notifications.
The VitrageNotifier is a new service that listens to the bus for internal vitrage notifications, then can call all the relevant notifier plugins.
1. Deduced Alarm created by the Evaluator
2. Graph vertex added/updated
3. DeducedAlarmNotifier writes to message bus
4. VitrageNotifierService receives the event and calls all plugins
5. Aodh plugin - using the ceilometer client, creates an event in aodh (with some metadata params in the query)
Deduced Alarms bus notifications
--------------------------------
Vitrage Evaluator will create a deduced alarm, sending it to the data source queue
Vitrage Evaluator will use the **vitrage.graph** message bus topic, and will post messages as follows:
- message of type ``vitrage.deduced_alarm.activate`` :
* ``name`` - is the alarm name in vitrage
* ``severity`` - is the alarm severity
* ``affected_resource_id`` - is the openstack id of the resource on which the alarm was raised
- ``vitrage.deduced_alarm.deactivate``
* ``id`` - is the alarm id
Notifier
========
- Is a new running service
- Receives notifications from the message bus
- Holds instances of all the plugins
- Upon a received notification, calls 'notify(msg)' for all the plugins
- Each plugin is responsible of how and whether to process the notification
Aodh Plugin
===========
Vitrage alarms should be reflected as possible in Aodh. The aodh plugin has ceilometer client by which it can send rest calls to aodh
Handle ``vitrage.deduced_alarm.activate``
-----------------------------------------
Create an event alarm with the specified severity, where the alarm name is ``vitrage_alarm_name+resource_id`` so to be unique
- Message does not contain aodh alarm id:
* plugin will **create** a new aodh alarm
* alarm type - event
* alarm status - alarm
* query contain resource_id, vitrage_id fields
- Message contains aodh alarm id
* plugin will **update** the aodh alarm status to alarm
Handle ``vitrage.deduced_alarm.deactivate``
-------------------------------------------
Delete an event alarm with the specified id
* message will contain the aodh alarm id - plugin will **update** the alarm status to ok

View File

@ -42,7 +42,7 @@ Static datasource use the same semantics as Vitrage template, except for the fol
- All entities configured in static datasource are considered ``RESOURCE``
- ``scenarios`` section is not applicable
There may be more than one configuration file. All files will be read from``/etc/vitrage/static_datasources/``. See
There may be more than one configuration file. All files will be read from ``/etc/vitrage/static_datasources/``. See
previous section on how to configure this location.
Notes:

View File

@ -67,7 +67,7 @@ The following describes all the possible status code and their messages:
| 104 | Relationship definition must contain template_id field | syntax |
+------------------+---------------------------------------------------------+-------------------------------+
| 120 | Invalid action type. Action type must be from types: | content |
| [action_types] | |
| | [action_types] | |
+------------------+---------------------------------------------------------+-------------------------------+
| 121 | At least one action must be defined | syntax |
+------------------+---------------------------------------------------------+-------------------------------+

View File

@ -1,172 +0,0 @@
===========================
Vitrage Manual Installation
===========================
Install Vitrage
===============
Install vitrage and python-vitrageclient
----------------------------------------
To install the Ocata release:
.. code:: bash
sudo pip install vitrage==1.5.1
sudo pip install python-vitrageclient==1.1.1
Or, to install the latest version:
.. code:: bash
sudo pip install vitrage
sudo pip install python-vitrageclient
Configure Vitrage
=================
Create the Vitrage folders
--------------------------
Create /etc/vitrage folder and sub folders, **with permission 755**
.. code:: bash
mkdir /etc/vitrage
chmod 755 /etc/vitrage
mkdir /etc/vitrage/static_datasources
chmod 755 /etc/vitrage/static_datasources
mkdir /etc/vitrage/templates
chmod 755 /etc/vitrage/templates
sudo mkdir /var/log/vitrage
sudo chmod 755 /var/log/vitrage
Copy `policy.json`_ to /etc/vitrage/
Copy `api-paste.ini`_ to /etc/vitrage/
Copy the `datasources_values`_ folder with its content
**Note:** You don't need to copy all files in this folder, only the ones that
belong to datasources you plan to use. The only file that **must** be copied
is vitrage.yaml
.. _policy.json: ../../etc/vitrage/policy.json
.. _api-paste.ini: ../../etc/vitrage/api-paste.ini
.. _datasources_values: ../../etc/vitrage/datasources_values
Create the vitrage.conf file
----------------------------
Create /etc/vitrage/vitrage.conf file with the following information:
.. code:: bash
[DEFAULT]
# debug = False
transport_url = <transport-url>
# notifiers = nova
[service_credentials]
auth_url = http://<ip>:5000
region_name = RegionOne
project_name = admin
password = <password>
project_domain_id = default
user_domain_id = default
username = admin
auth_type = password
[keystone_authtoken]
auth_uri = http://<ip>:5000
project_domain_name = Default
project_name = service
user_domain_name = Default
password = <password>
username = vitrage
auth_url = http://<ip>:35357
auth_type = password
Set the list of datasource you would like to use for Vitrage.
**Note:** In order for a datasource to be supported, the underlying component
(like Neutron, Heat, Zabbix, etc.) should be installed separately.
.. code:: bash
[datasources]
types = nova.host,nova.instance,nova.zone,static,aodh,cinder.volume,neutron.network,neutron.port,heat.stack,doctor
Configure notifications from other datasources
==============================================
Notifications from Aodh
-----------------------
In order to configure notifications from Aodh to Vitrage, set the following in
`/etc/aodh/aodh.conf`:
.. code:: bash
[oslo_messaging_notifications]
driver = messagingv2
topics = notifications,vitrage_notifications
Notifications from other OpenStack components
---------------------------------------------
In order to configure notifications from OpenStack components (Nova, Cinder,
Neutron, Heat and Aodh) to Vitrage, set the following in their conf files:
.. code:: bash
[DEFAULT]
notification_topics = notifications,vitrage_notifications
notification_driver=messagingv2
Initialize Vitrage
==================
Create the Vitrage account
--------------------------
.. code:: bash
openstack user create vitrage --password password --domain=Default
openstack role add admin --user vitrage --project service
openstack role add admin --user vitrage --project admin
Create the Vitrage endpoint
---------------------------
.. code:: bash
openstack service create rca --name vitrage --description="Root Cause Analysis Service"
openstack endpoint create --region <region> --publicurl http://<ip>:8999 --internalurl http://<ip>:8999 --adminurl http://<ip>:8999 vitrage
Start the Vitrage Services
==========================
Run the following commands:
.. code:: bash
vitrage-graph
vitrage-api
vitrage-notifier
Install the Vitrage Dashboard
=============================
Follow vitrage-dashboard_ installation procedure
.. _vitrage-dashboard: https://github.com/openstack/vitrage-dashboard/tree/master/doc/source/installation.rst

View File

@ -66,6 +66,14 @@ relationships:
- X and not (Y or Z)
- X and not X
Template validation status codes
--------------------------------
.. toctree::
:maxdepth: 1
template_validation_status_code
Examples
========
@ -346,7 +354,7 @@ Set state of specified entity. This will directly affect the state as seen in vi
add_causal_relationship
^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^
Add a causal relationship between alarms.
::
@ -361,9 +369,9 @@ mark_down
^^^^^^^^^
Set an entity marked_down field.
This can be used along with nova notifier to call force_down for a host
::
::
action:
action:
action_type : mark_down
action_target:
target: host # mandatory. entity (from the definitions section, only host) to be marked as down

View File

@ -1,10 +0,0 @@
2. Edit the ``/etc/vitrage/vitrage.conf`` file and complete the following
actions:
* In the ``[database]`` section, configure database access:
.. code-block:: ini
[database]
...
connection = mysql+pymysql://vitrage:VITRAGE_DBPASS@controller/vitrage

View File

@ -1,301 +0,0 @@
# 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 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 os
# import sys
import openstackdocstheme
# 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.
# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder'
# extensions =
# 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'Installation Guide for Root Cause Analysis Service'
bug_tag = u'install-guide'
copyright = u'2016, OpenStack contributors'
# 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'
# A few variables have to be set for the log-a-bug feature.
# giturl: The location of conf.py on Git. Must be set manually.
# gitsha: The SHA checksum of the bug description. Automatically extracted
# from git log.
# bug_tag: Tag for categorizing the bug. Must be set manually.
# These variables are passed to the logabug code via html_context.
giturl = u'http://git.openstack.org/cgit/openstack/vitrage/tree/install-guide/source' # noqa
git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
gitsha = os.popen(git_cmd).read().strip('\n')
html_context = {"gitsha": gitsha, "bug_tag": bug_tag,
"giturl": giturl,
"bug_project": "vitrage"}
# 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 = ["common_prerequisites.rst", "common_configure.rst"]
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = 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 = 'openstackdocs'
# 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 = [openstackdocstheme.get_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 = []
# 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.
# So that we can enable "log-a-bug" links from each output HTML page, this
# variable must be set to a format that includes year, month, day, hours and
# minutes.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# 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 = False
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
html_show_sourcelink = False
# 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 = 'install-guide'
# If true, publish source files
html_copy_source = False
# -- 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', 'InstallGuide.tex', u'Install Guide',
u'OpenStack contributors', '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', 'installguide', u'Install Guide',
[u'OpenStack contributors'], 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', 'InstallGuide', u'Install Guide',
u'OpenStack contributors', 'InstallGuide',
'This guide shows OpenStack end users how to install '
'an OpenStack cloud.', '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 Internationalization output ------------------------------
locale_dirs = ['locale/']
# -- Options for PDF output --------------------------------------------------
pdf_documents = [
('index', u'InstallGuide', u'Install Guide',
u'OpenStack contributors')
]

View File

@ -52,7 +52,7 @@ packages =
source-dir = doc/source
build-dir = doc/build
all_files = 1
warning-is-error = 1
[upload_sphinx]
upload-dir = doc/build/html

View File

@ -16,7 +16,6 @@ python-subunit>=0.0.18 # Apache-2.0/BSD
pyzabbix>=0.7.4 # LGPL
sphinx!=1.6.1,>=1.5.1 # BSD
oslo.log>=3.22.0 # Apache-2.0
oslosphinx>=4.7.0 # Apache-2.0
oslotest>=1.10.0 # Apache-2.0
oslo.service>=1.10.0 # Apache-2.0
oslo.config>=4.0.0 # Apache-2.0
@ -36,3 +35,4 @@ pysnmp>=4.2.3 # BSD
# Doc requirements
openstackdocstheme>=1.5.0 # Apache-2.0
oslosphinx>=4.7.0 # Apache-2.0

View File

@ -47,6 +47,3 @@ exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build
[testenv:releasenotes]
commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
[testenv:install-guide]
commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html