openstack/masakari
Code Issues Proposed changes

Reorganize masakari documentation

Browse Source 
Updated operator guide documentation for
1. segregated sections appropriately
2. referred masakariclient for CLI section
3. added detailed 'Install and configure for Ubuntu' section
4. added detailed 'Verify operation' section
5. used sphinx-build instead of the pbr sphinx extention for building docs
   as instructed by the PTI[1]
6. cleaned up build_sphinx related entries in setup.cfg

[1]: https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation

Change-Id: Iec93bebdbc7ffe1ccd27bb11f474384ff06a559c
This commit is contained in:
Shilpa Devharakar 2019-08-28 20:19:06 +05:30 committed by tpatil
parent a61319ecea
commit 596b3d142e
35 changed files with 1288 additions and 2922 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.gitignore vendored
View File

@ -60,6 +60,14 @@ releasenotes/build
# PyCharm IDE
.idea/
# configuration sample generation
etc/masakari/masakari.conf.sample
etc/masakari/masakari-custom-recovery-methods.conf.sample
# policy sample generation
etc/masakari/policy.yaml.sample
# Files created by doc build
doc/source/_static/masakari.conf.sample
doc/source/_static/masakari-custom-recovery-methods.conf.sample
doc/source/_static/masakari.policy.yaml.sample

0
doc/source/images/Masakari_spec_process.svg → doc/source/_static/Masakari_spec_process.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 45 KiB

0
doc/source/images/architecture.png → doc/source/_static/architecture.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 55 KiB

After

Width:  |  Height:  |  Size: 55 KiB

87
doc/source/_static/masakari-custom-recovery-methods.conf.sample
View File

@ -1,87 +0,0 @@
[DEFAULT]
[taskflow_driver_recovery_flows]
#
# From customized_recovery_flow_opts
#
#
# This option allows operator to customize tasks to be executed for host failure
# auto recovery workflow.
#
# Provide list of strings reflecting to the task classes that should be included
# to the host failure recovery workflow. The full classname path of all task
# classes should be defined in the 'masakari.task_flow.tasks' of setup.cfg and
# these classes may be implemented by OpenStack Masaskari project team, deployer
# or third party.
#
# By default below three tasks will be part of this config option:-
# 1. disable_compute_service_task
# 2. prepare_HA_enabled_instances_task
# 3. evacuate_instances_task
#
# The allowed values for this option is comma separated dictionary of object
# names in between ``{`` and ``}``. (dict value)
#host_auto_failure_recovery_tasks = main:['prepare_HA_enabled_instances_task'],
#post:['evacuate_instances_task'],pre:['disable_compute_service_task']
#
# This option allows operator to customize tasks to be executed for host failure
# reserved_host recovery workflow.
#
# Provide list of strings reflecting to the task classes that should be included
# to the host failure recovery workflow. The full classname path of all task
# classes should be defined in the 'masakari.task_flow.tasks' of setup.cfg and
# these classes may be implemented by OpenStack Masaskari project team, deployer
# or third party.
#
# By default below three tasks will be part of this config option:-
# 1. disable_compute_service_task
# 2. prepare_HA_enabled_instances_task
# 3. evacuate_instances_task
#
# The allowed values for this option is comma separated dictionary of object
# names in between ``{`` and ``}``. (dict value)
#host_rh_failure_recovery_tasks = main:['prepare_HA_enabled_instances_task',
#'evacuate_instances_task'],post:[],pre:['disable_compute_service_task']
#
# This option allows operator to customize tasks to be executed for instance
# failure recovery workflow.
#
# Provide list of strings reflecting to the task classes that should be included
# to the instance failure recovery workflow. The full classname path of all task
# classes should be defined in the 'masakari.task_flow.tasks' of setup.cfg and
# these classes may be implemented by OpenStack Masaskari project team, deployer
# or third party.
#
# By default below three tasks will be part of this config option:-
# 1. stop_instance_task
# 2. start_instance_task
# 3. confirm_instance_active_task
#
# The allowed values for this option is comma separated dictionary of object
# names in between ``{`` and ``}``. (dict value)
#instance_failure_recovery_tasks = main:['start_instance_task'],
#post:['confirm_instance_active_task'],pre:['stop_instance_task']
#
# This option allows operator to customize tasks to be executed for process
# failure recovery workflow.
#
# Provide list of strings reflecting to the task classes that should be included
# to the process failure recovery workflow. The full classname path of all task
# classes should be defined in the 'masakari.task_flow.tasks' of setup.cfg and
# these classes may be implemented by OpenStack Masaskari project team, deployer
# or third party.
#
# By default below two tasks will be part of this config option:-
# 1. disable_compute_node_task
# 2. confirm_compute_node_disabled_task
#
# The allowed values for this option is comma separated dictionary of object
# names in between ``{`` and ``}``. (dict value)
#process_failure_recovery_tasks = main:['confirm_compute_node_disabled_task'],
#post:[],pre:['disable_compute_node_task']

1913
doc/source/_static/masakari.conf.sample
View File

File diff suppressed because it is too large Load Diff

90
doc/source/_static/masakari.policy.yaml.sample
View File

@ -1,90 +0,0 @@
# Decides what is required for the 'is_admin:True' check to succeed.
#"context_is_admin": "role:admin"
# Default rule for most non-Admin APIs.
#"admin_or_owner": "is_admin:True or project_id:%(project_id)s"
# Default rule for most Admin APIs.
#"admin_api": "is_admin:True"
# List available extensions.
# GET /extensions
#"os_masakari_api:extensions:index": "rule:admin_api"
# Shows information for an extension.
# GET /extensions/{extensions_id}
#"os_masakari_api:extensions:detail": "rule:admin_api"
# Extension Info API extensions to change the API.
#"os_masakari_api:extensions:discoverable": "rule:admin_api"
# Lists IDs, names, type, reserved, on_maintenance for all hosts.
# GET /segments/{segment_id}/hosts
#"os_masakari_api:os-hosts:index": "rule:admin_api"
# Shows details for a host.
# GET /segments/{segment_id}/hosts/{host_id}
#"os_masakari_api:os-hosts:detail": "rule:admin_api"
# Creates a host under given segment.
# POST /segments/{segment_id}/hosts
#"os_masakari_api:os-hosts:create": "rule:admin_api"
# Updates the editable attributes of an existing host.
# PUT /segments/{segment_id}/hosts/{host_id}
#"os_masakari_api:os-hosts:update": "rule:admin_api"
# Deletes a host from given segment.
# DELETE /segments/{segment_id}/hosts/{host_id}
#"os_masakari_api:os-hosts:delete": "rule:admin_api"
# Host API extensions to change the API.
#"os_masakari_api:os-hosts:discoverable": "rule:admin_api"
# Lists IDs, notification types, host_name, generated_time, payload
# and status for all notifications.
# GET /notifications
#"os_masakari_api:notifications:index": "rule:admin_api"
# Shows details for a notification.
# GET /notifications/{notification_id}
#"os_masakari_api:notifications:detail": "rule:admin_api"
# Creates a notiification.
# POST /notifications
#"os_masakari_api:notifications:create": "rule:admin_api"
# Notification API extensions to change the API.
#"os_masakari_api:notifications:discoverable": "rule:admin_api"
# Lists IDs, names, description, recovery_method, service_type for all
# segments.
# GET /segments
#"os_masakari_api:segments:index": "rule:admin_api"
# Shows details for a segment.
# GET /segments/{segment_id}
#"os_masakari_api:segments:detail": "rule:admin_api"
# Creates a segment.
# POST /segments
#"os_masakari_api:segments:create": "rule:admin_api"
# Updates the editable attributes of an existing host.
# PUT /segments/{segment_id}
#"os_masakari_api:segments:update": "rule:admin_api"
# Deletes a segment.
# DELETE /segments/{segment_id}
#"os_masakari_api:segments:delete": "rule:admin_api"
# Segment API extensions to change the API.
#"os_masakari_api:segments:discoverable": "rule:admin_api"
# List all versions.
# GET /
#"os_masakari_api:versions:index": "@"
# Version API extensions to change the API.
#"os_masakari_api:versions:discoverable": "@"

2
doc/source/cli/index.rst
View File

@ -9,3 +9,5 @@ interface.
:maxdepth: 1
masakari-status
masakari-manage
openstack-masakari

52
doc/source/cli/masakari-manage.rst Normal file
View File

@ -0,0 +1,52 @@
===============
masakari-manage
===============
-------------------------------------
Control and manage masakari database
-------------------------------------
Synopsis
========
::
masakari-manage <category> <action> [<args>]
Description
===========
:program:`masakari-manage` controls DB by managing various admin-only aspects
of masakari.
Options
=======
The standard pattern for executing a masakari-manage command is::
masakari-manage <category> <command> [<args>]
Run without arguments to see a list of available command categories::
masakari-manage
You can also run with a category argument such as db to see a list of all
commands in that category::
masakari-manage db
These sections describe the available categories and arguments for masakari-manage.
Masakari Database
~~~~~~~~~~~~~~~~~
``masakari-manage db version``
Print the current main database version.
``masakari-manage db sync [--version <version>]``
Upgrade the main database schema up to the most recent version or
``--version`` if specified.
``masakari-manage db purge``
Deleting rows older than 30 day(s) from table hosts, failover_segments and
notifications.

7
doc/source/cli/openstack-masakari.rst Normal file
View File

@ -0,0 +1,7 @@
==================
openstack masakari
==================
To control and manage masakari operations, the extended `command list
<https://docs.openstack.org/python-masakariclient/latest/cli/index.html>`_
available in openstack command.

19
doc/source/conf.py
View File

@ -24,9 +24,26 @@ sys.path.insert(0, os.path.abspath('../'))
extensions = [
'openstackdocstheme',
'sphinx.ext.autodoc',
'ext.versioned_notifications'
'ext.versioned_notifications',
'oslo_config.sphinxconfiggen',
'oslo_config.sphinxext',
'oslo_policy.sphinxpolicygen',
'oslo_policy.sphinxext',
]
config_generator_config_file = [
('../../etc/masakari/masakari-config-generator.conf',
'_static/masakari'),
('../../etc/masakari/masakari-customized-recovery-flow-config-generator.conf',
'_static/masakari-custom-recovery-methods'),
]
sample_config_basename = '_static/masakari'
policy_generator_config_file = [
('../../etc/masakari/masakari-policy-generator.conf', '_static/masakari'),
]
sample_policy_basename = '_static/masakari'
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable

8
doc/source/configuration/api-paste.ini.rst Normal file
View File

@ -0,0 +1,8 @@
=============
api-paste.ini
=============
The masakari service stores its API configuration settings in the
``api-paste.ini`` file.
.. literalinclude:: /../../etc/masakari/api-paste.ini

9
doc/source/configuration/config.rst Normal file
View File

@ -0,0 +1,9 @@
=====================
Configuration Options
=====================
The following is an overview of all available configuration options in
Masakari. For a sample configuration file, refer to :doc:`sample_config`.
.. show-options::
:config-file: etc/masakari/masakari-config-generator.conf

42
doc/source/configuration/index.rst Normal file
View File

@ -0,0 +1,42 @@
===================
Configuration Guide
===================
The configuration for masakari lies in below described files.
Configuration
-------------
Masakari has two main config files:
``masakari.conf`` and ``recovery_workflow_sample_config.conf``.
* :doc:`Config Reference <config>`: A complete reference of all
config points in masakari and what they impact.
* :doc:`Sample Config File <sample_config>`: A sample config
file with inline documentation.
* :doc:`Recovery Config Reference <recovery_config>`: A complete reference of all
config points in masakari and what they impact.
* :doc:`Sample recovery workflow File <recovery_workflow_sample_config>`: A
complete reference of defining the monitoring processes.
Policy
------
Masakari, like most OpenStack projects, uses a policy language to restrict
permissions on REST API actions.
* :doc:`Policy Reference <policy>`: A complete reference of all
policy points in masakari and what they impact.
* :doc:`Sample policy File <sample_policy>`: A sample policy
file with inline documentation.
API configuration settings
--------------------------
* :doc:`API configuration <api-paste.ini>`: A complete reference of API
configuration settings.

9
doc/source/configuration/policy.rst Normal file
View File

@ -0,0 +1,9 @@
=================
Masakari Policies
=================
The following is an overview of all available policies in masakari.
For a sample configuration file, refer to :doc:`sample_policy`.
.. show-policy::
:config-file: etc/masakari/masakari-policy-generator.conf

9
doc/source/configuration/recovery_config.rst Normal file
View File

@ -0,0 +1,9 @@
=====================
Configuration Options
=====================
The following is an overview of all available configuration options in
Masakari. For a sample configuration file, refer to :doc:`recovery_workflow_sample_config`.
.. show-options::
:config-file: etc/masakari/masakari-customized-recovery-flow-config-generator.conf

0
doc/source/recovery_workflow_custom_task.rst → doc/source/configuration/recovery_workflow_custom_task.rst
View File

11
doc/source/configuration/recovery_workflow_sample_config.rst Normal file
View File

@ -0,0 +1,11 @@
===========================================================
Masakari Customized Recovery Workflow Configuration Options
===========================================================
masakari-custom-recovery-methods.conf.sample
The following is a sample Masakari recovery workflow configuration for
adaptation and use.
The sample configuration can also be downloaded from :download:`here
</_static/masakari-custom-recovery-methods.conf.sample>`.
.. literalinclude:: /_static/masakari-custom-recovery-methods.conf.sample

5
doc/source/sample_config.rst → doc/source/configuration/sample_config.rst
View File

@ -7,7 +7,10 @@ auto-generated from Masakari when this documentation is built, so
if you are having issues with an option, please compare your version of
Masakari with the version of this documentation.
.. literalinclude:: _static/masakari.conf.sample
The sample configuration can also be downloaded from :download:`here
</_static/masakari.conf.sample>`.
.. literalinclude:: /_static/masakari.conf.sample
Minimal Configuration
=====================

15
doc/source/configuration/sample_policy.rst Normal file
View File

@ -0,0 +1,15 @@
===========================
Sample Masakari Policy File
===========================
The following is a sample masakari policy file for adaptation and use.
The sample policy can also be viewed in :download:`file form
</_static/masakari.policy.yaml.sample>`.
.. important::
The sample policy file is auto-generated from masakari when this
documentation is built.
.. literalinclude:: /_static/masakari.policy.yaml.sample

120
doc/source/index.rst
View File

@ -13,76 +13,84 @@
License for the specific language governing permissions and limitations
under the License.
=======================================================
Welcome to Masakari's developer/operator documentation!
=======================================================
====================================
Welcome to Masakari's documentation!
====================================
Masakari is an OpenStack project designed to assure high availability of
Masakari is an OpenStack project designed to ensure high availability of
instances and compute processes running on hosts.
The developer documentation provided here is continually kept up-to-date
based on the latest code, and may not represent the state of the project at
any specific prior release.
This documentation is intended to help explain what the Masakari developers
think is the current scope of the Masakari project, as well as the
architectural decisions we have made in order to support that scope. We also
document our plans for evolving our architecture over time. Finally, we
documented our current development process and policies.
This documentation is intended to help explain the current scope of the
Masakari project and the architectural decisions made to support this scope.
The documentation will include the future architectural roadmap and the
current development process and policies.
Masakari API References
=======================
The Masakari API is quite large, we provide a concept guide which
gives some of the high level details, as well as a more detailed API
reference.
To generate API reference guide issue the following command while
the masakari directory is current.
.. code-block:: bash
$ tox -e api-ref
Developer Guide
===============
If you are new to Masakari, this should help you start to understand what
masakari actually does, and why.
.. toctree::
:maxdepth: 1
how_to_get_involved
architecture
development.environment
The `Masakari API <https://docs.openstack.org/api-ref/instance-ha/>`_ is
extensive. We provide a concept guide which gives some of the high level
details, as well as a more detailed API reference.
Operator Guide
==============
This section will help you in configuring masakari mannualy.
Architecture Overview
---------------------
* :doc:`Masakari architecture </user/architecture>`: An overview of how all
the components in masakari work together.
Installation
------------
A detailed install guide for masakari.
.. toctree::
:maxdepth: 1
:maxdepth: 2
install/index
Reference Material
------------------
* :doc:`Configuration Guide <configuration/index>`: Information on configuration files.
* :doc:`Custom Recovery Workflow Configuration Guide <configuration/recovery_workflow_custom_task>`
* :doc:`CLI Commands for Masakari </cli/index>`: The complete command
reference for Masakari.
* :doc:`Versioned Notifications </user/notifications>`: This provides the list
of existing versioned notifications with sample payloads.
* :doc:`Masakari team process <user/process>`
* :doc:`Getting started with Masakari <user/how_to_get_involved>`:
This will help newcomers understand basics of Masakari
* `Nova Docs <https://docs.openstack.org/nova/latest/index.html>`_: A collection of guides for Nova.
.. # NOTE(shilpasd): This is the section where we hide things that we don't
# actually want in the table of contents but sphinx build would fail if
# they aren't in the toctree somewhere.
.. toctree::
:hidden:
operators_guide
cli/index
sample_config
sample_policy
recovery_workflow_sample_config
recovery_workflow_custom_task
configuration/api-paste.ini.rst
configuration/config.rst
configuration/index.rst
configuration/policy.rst
configuration/recovery_config.rst
configuration/recovery_workflow_custom_task.rst
configuration/recovery_workflow_sample_config.rst
configuration/sample_config.rst
configuration/sample_policy.rst
install/development.environment.rst
user/architecture.rst
user/how_to_get_involved.rst
user/notifications.rst
user/process.rst
Indices and tables
==================
Search
======
* :ref:`search`
Versioned Notifications
=======================
This provides the list of existing versioned notifications with sample payloads.
.. toctree::
:maxdepth: 1
notifications
* :ref:`search`: Search the contents of this document.
* `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
set of OpenStack documentation, including forums.

41
doc/source/development.environment.rst → doc/source/install/development.environment.rst
View File

@ -24,10 +24,9 @@ These instructions assume you're already familiar with git.
Following these instructions will allow you to build the documentation
and run the masakari unit tests.
.. note:: For how to contribute to Masakari, see
`How To Contribute <http://docs.openstack.org/infra/manual/developers.html>`_.
Masakari uses the Gerrit code review system,
See `Gerrit Workflow <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
.. note:: For how to contribute to Masakari, refer: http://docs.openstack.org/infra/manual/developers.html
Masakari uses the Gerrit code review system, refer: http://docs.openstack.org/infra/manual/developers.html#development-workflow
Setup
=====
@ -79,39 +78,13 @@ Explicit Install/Clone
----------------------
DevStack installs a complete OpenStack environment. Alternatively,
you can explicitly install and clone just what you need for Masakari
development.
Getting the code
~~~~~~~~~~~~~~~~
Grab the code from git::
git clone https://opendev.org/openstack/masakari
cd masakari
Linux Systems
~~~~~~~~~~~~~
The first step of this process is to install the system (not Python)
packages that are required. Following are instructions on how to do
this on Linux.
On Debian-based distributions (e.g., Debian/Mint/Ubuntu)::
sudo apt-get install python-pip
sudo pip install tox
tox -e bindep
sudo apt-get install <indicated missing package names>
to clone and install Masakari explicitly refer: :doc:`install_and_configure_ubuntu`
Building the Documentation
==========================
Install the prerequisite packages: graphviz
To do a full documentation build, issue the following command while
the masakari directory is current.
For a full documentation build, issue the following command from the masakari
directory
.. code-block:: bash
@ -124,4 +97,4 @@ documentation in that environment.
Running unit tests
==================
See `Running Python Unit Tests <https://docs.openstack.org/project-team-guide/project-setup/python.html#running-python-unit-tests>`_.
See `Running Python Unit Tests <https://docs.openstack.org/project-team-guide/project-setup/python.html#running-python-unit-tests>`_

9
doc/source/install/index.rst Normal file
View File

@ -0,0 +1,9 @@
=================
Masakari services
=================
.. toctree::
overview
install_and_configure
verify

17
doc/source/operators_guide.rst → doc/source/install/install_and_configure.rst
View File

@ -13,11 +13,20 @@
License for the specific language governing permissions and limitations
under the License.
================
Masakari Service
================
=====================
Install and configure
=====================
This section describes how to install and configure Masakari services
on the compute node.
This section assumes that you already have a :doc:`working OpenStack
environment <development.environment>` with the following components installed:
Nova, Glance, Cinder, Neutron and Identity.
The installation and configuration vary by distribution.
.. toctree::
:maxdepth: 1
masakari_overview
install_and_configure_ubuntu

250
doc/source/install/install_and_configure_ubuntu.rst Normal file
View File

@ -0,0 +1,250 @@
.. _install-ubuntu:
Install and configure for Ubuntu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure Masakari for Ubuntu
18.04 (bionic).
Prerequisites
-------------
Before you install and configure the masakari service, you must create
databases, service credentials, and API endpoints.
#. To create the masakari database, follow these steps:
* Use the database access client to connect to the database server
as the ``root`` user:
.. code-block:: console
# mysql
* Create the ``masakari`` database:
.. code-block:: console
mysql> CREATE DATABASE masakari CHARACTER SET utf8;
* Grant access privileges to the databases:
.. code-block:: console
mysql> GRANT ALL PRIVILEGES ON masakari.* TO 'username'@'localhost' \
IDENTIFIED BY 'MASAKARI_DBPASS';
mysql> GRANT ALL PRIVILEGES ON masakari.* TO 'username'@'%' \
IDENTIFIED BY 'MASAKARI_DBPASS';
Replace ``MASAKARI_DBPASS`` with a suitable password.
* Exit the database access client.
#. Source the ``admin`` credentials to gain access to admin-only CLI commands:
.. code-block:: console
$ . admin-openrc
#. Create the Masakari service credentials:
* Create the ``masakari`` user with password as ``masakari``:
.. code-block:: console
$ openstack user create --password-prompt masakari
User Password:
Repeat User Password:
+---------------------+----------------------------------+
| Field | Value |
+---------------------+----------------------------------+
| domain_id | default |
| enabled | True |
| id | 8a7dbf5279404537b1c7b86c033620fe |
| name | masakari |
| options | {} |
| password_expires_at | None |
+---------------------+----------------------------------+
* Add the ``admin`` role to the ``masakari`` user:
.. code-block:: console
$ openstack role add --project service --user masakari admin
* Create the ``masakari`` service entity:
.. code-block:: console
$ openstack service create --name masakari \
--description "masakari high availability" instance-ha
+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | masakari high availability |
| enabled | True |
| id | 060d59eac51b4594815603d75a00aba2 |
| name | masakari |
| type | instance-ha |
+-------------+----------------------------------+
#. Create the Masakari API service endpoints:
.. code-block:: console
$ openstack endpoint create --region RegionOne \
masakari public http:// <CONTROLLER_IP>/instance-ha/v1/$\(tenant_id\)s
+--------------+-------------------------------------------------------+
| Field | Value |
+--------------+-------------------------------------------------------+
| enabled | True |
| id | 38f7af91666a47cfb97b4dc790b94424 |
| interface | public |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 060d59eac51b4594815603d75a00aba2 |
| service_name | masakari |
| service_type | instance-ha |
| url | http://<CONTROLLER_IP>/instance-ha/v1/$(tenant_id)s |
+--------------+-------------------------------------------------------+
$ openstack endpoint create --region RegionOne \
masakari internal http:// <CONTROLLER_IP>/instance-ha/v1/$\(tenant_id\)s
+--------------+-------------------------------------------------------+
| Field | Value |
+--------------+-------------------------------------------------------+
| enabled | True |
| id | 38f7af91666a47cfb97b4dc790b94424 |
| interface | internal |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 060d59eac51b4594815603d75a00aba2 |
| service_name | masakari |
| service_type | instance-ha |
| url | http://<CONTROLLER_IP>/instance-ha/v1/$(tenant_id)s |
+--------------+-------------------------------------------------------+
$ openstack endpoint create --region RegionOne \
masakari admin http://<CONTROLLER_IP>/instance-ha/v1/$\(tenant_id\)s
+--------------+-------------------------------------------------------+
| Field | Value |
+--------------+-------------------------------------------------------+
| enabled | True |
| id | 38f7af91666a47cfb97b4dc790b94424 |
| interface | admin |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 060d59eac51b4594815603d75a00aba2 |
| service_name | masakari |
| service_type | instance-ha |
| url | http://<CONTROLLER_IP>/instance-ha/v1/$(tenant_id)s |
+--------------+-------------------------------------------------------+
Install and configure Masakari
------------------------------
.. note::
* You must install Masakari on the Controller Nodes only.
#. Clone masakari using:
.. code-block:: console
# git clone https://opendev.org/openstack/masakari.git
#. Prepare the masakari configuration files:
#. Generate via tox:
Go to ‘opt/stack/masakari’ and execute the command below, this will generate
``masakari.conf.sample``, sample configuration file at
``/opt/stack/masakari/etc/masakari/``
.. code-block:: console
# tox -egenconfig
#. Download from:
# :download:`masakari.conf.sample </_static/masakari.conf.sample>`
#. Rename ``masakari.conf.sample`` file to ``masakari.conf``,
and edit sections as shown below:
.. code-block:: none
[default]
transport_url = rabbit://stackrabbit:admin@<CONTROLLER_IP>:5672/
graceful_shutdown_timeout = 5
os_privileged_user_tenant = service
os_privileged_user_password = admin
os_privileged_user_auth_url = http://<CONTROLLER_IP>/identity
os_privileged_user_name = nova
logging_exception_prefix = %(color)s%(asctime)s.%(msecs)03d TRACE %(name)s [01;35m%(instance)s[00m
logging_debug_format_suffix = [00;33mfrom (pid=%(process)d) %(funcName)s %(pathname)s:%(lineno)d[00m
logging_default_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [[00;36m-%(color)s] [01;35m%(instance)s%(color)s%(message)s[00m
logging_context_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [[01;36m%(request_id)s [00;36m%(project_name)s %(user_name)s%(color)s] [01;35m%(instance)s%(color)s%(message)s[00m
use_syslog = False
debug = True
masakari_api_workers = 2
[database]
connection = mysql+pymysql://root:admin@1<CONTROLLER_IP>/masakari?charset=utf8
[keystone_authtoken]
memcached_servers = localhost:11211
cafile = /opt/stack/data/ca-bundle.pem
project_domain_name = Default
project_name = service
user_domain_name = Default
password = <MASAKARI_PASS>
username = masakari
auth_url = http://<CONTROLLER_IP>/identity
auth_type = password
[taskflow]
connection = mysql+pymysql://root:admin@<CONTROLLER_IP>/masakari?charset=utf8
.. note::
Replace ``CONTROLLER_IP`` with the IP address of controller node.
Replace ``MASAKARI_PASS`` with the password you chose for the
``masakari`` user in the Identity service.
#. Create ``masakari`` directory in /etc/:
Copy ``masakari.conf`` file to ``/etc/masakari/``
.. code-block:: console
# cp -p etc/masakari/masakari.conf.sample /etc/masakari/masakari.conf
#. To install masakari run setup.py from masakari:
.. code-block:: console
# cd masakari
# sudo python setup.py install
#. Run below db command to sync database:
.. code-block:: console
# masakari-manage db sync
Finalize installation
---------------------
* Start masakari services:
.. code-block:: console
# masakari-api
# masakari-engine

27
doc/source/install/overview.rst Normal file
View File

@ -0,0 +1,27 @@
=========================
Masakari service overview
=========================
Masakari provides Virtual Machines High Availability(VMHA), and rescues
KVM-based Virtual Machines(VM) from a failure events described below:
* VM process down - restart vm (use nova stop API, and nova start API).
Libvirt events will be also emitted by other failures.
* Provisioning process down - restarts process, changes nova-compute service
status to maintenance mode
(use nova service-disable).
* nova-compute host failure - evacuate all the VMs from failure host to
reserved host (use nova evacuate API).
The below services enables deplores to integrate with the Masakari directly
or through custom plug-ins.
The Masakari service consists of the following components:
``masakari-api``
An OpenStack-native REST API that processes API requests by sending
them to the ``masakari-engine`` over `Remote Procedure Call (RPC)`.
``masakari-engine``
Processes the notifications received from ``masakari-api`` by executing the
recovery workflow in asynchronous way.

76
doc/source/install/verify.rst Normal file
View File

@ -0,0 +1,76 @@
Verify operation
~~~~~~~~~~~~~~~~
Verify Masakari installation.
#. Source the ``admin`` credentials to gain access to admin-only CLI commands:
.. code-block:: console
$ . admin-openrc
#. List API endpoints in the Identity service to verify connectivity with the
Identity service:
.. note::
Below endpoints list may differ depending on the installation of
OpenStack components.
.. code-block:: console
$ openstack endpoint list
+-------------+----------------+--------------------------------------------------------+
| Name | Type | Endpoints |
+-------------+----------------+--------------------------------------------------------+
| nova_legacy | compute_legacy | RegionOne |
| | | public: http://controller/compute/v2/<tenant_id> |
| | | |
| nova | compute | RegionOne |
| | | public: http://controller/compute/v2.1 |
| | | |
| cinder | block-storage | RegionOne |
| | | public: http://controller/volume/v3/<tenant_id> |
| | | |
| glance | image | RegionOne |
| | | public: http://controller/image |
| | | |
| cinderv3 | volumev3 | RegionOne |
| | | public: http://controller/volume/v3/<tenant_id> |
| | | |
| masakari | instance-ha | RegionOne |
| | | internal: http://controller/instance-ha/v1/<tenant_id> |
| | | RegionOne |
| | | admin: http://controller/instance-ha/v1/<tenant_id> |
| | | RegionOne |
| | | public: http://controller/instance-ha/v1/<tenant_id> |
| | | |
| keystone | identity | RegionOne |
| | | public: http://controller/identity |
| | | RegionOne |
| | | admin: http://controller/identity |
| | | |
| cinderv2 | volumev2 | RegionOne |
| | | public: http://controller/volume/v2/<tenant_id> |
| | | |
| placement | placement | RegionOne |
| | | public: http://controller/placement |
| | | |
| neutron | network | RegionOne |
| | | public: http://controller:9696/ |
| | | |
+-------------+----------------+--------------------------------------------------------+
#. Run ``segment list`` command to verify masakari-api is running properly.
This will return empty segment list as you haven't yet configured
``Failover segments``.
.. code-block:: console
$ openstack segment list
.. note::
Since ``Failover segments`` are not configured, there is no way to
verify masakari-engine is running properly as the notification cannot
be sent from masakari-api to masakari-engine.

42
doc/source/masakari_overview.rst
View File

@ -1,42 +0,0 @@
..
Copyright 2017 NTT DATA
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.
=========================
Masakari service overview
=========================
Masakari provides a Virtual Machines High Availability(VMHA), and rescues a
KVM-based Virtual Machines(VM) from a failure events of the following:
* VM process down - restart vm (use nova stop API, and nova start API).
Libvirt events will be also emitted by other failures.
* Provisioning process down - restarts process, changes nova-compute service
status to maintenance mode
(use nova service-disable).
* nova-compute host failure - evacuate all the VMs from failure host to
reserved host (use nova evacuate API).
The service enables deployers to integrate with the Masakari service
directly or through custom plug-ins.
The Masakari service consists of the following components:
``masakari-api``
An OpenStack-native REST API that processes API requests by sending
them to the ``masakari-engine`` over `Remote Procedure Call (RPC)`.
``masakari-engine``
Processes the notifications recevied from ``masakari-api`` by execcuting the
recovery workflow in asynchronus way.

22
doc/source/recovery_workflow_sample_config.rst
View File

@ -1,22 +0,0 @@
===========================================================
Masakari Customized Recovery Workflow Configuration Options
===========================================================
The following is a sample Masakari recovery workflow configuration for
adaptation and use.
.. literalinclude:: _static/masakari-custom-recovery-methods.conf.sample
Minimal Configuration
=====================
#. To generate the sample custom-recovery-methods.conf file, run the following
command from the top level of the masakari directory::
$ tox -egenconfig
#. Copy sample file ``etc/masakari/masakari-custom-recovery-methods.conf.sample`` to
``/etc/masakari`` directory
#. Remove '.sample' from files ``masakari-custom-recovery-methods.conf.sample`` which
exist at ``etc/masakari``.

9
doc/source/sample_policy.rst
View File

@ -1,9 +0,0 @@
===============
Masakari Policy
===============
The following is a sample masakari policy file. Operator can configure policies
as per his requirement. It is recommended that all api's of masakari should
be allowed to admin user only.
.. literalinclude:: _static/masakari.policy.yaml.sample

10
doc/source/architecture.rst → doc/source/user/architecture.rst
View File

@ -16,7 +16,7 @@
Masakari System Architecture
============================
Masakari is comprised of two services api and engine, each performing different
Masakari comprises of two services api and engine, each performing different
functions. The user-facing interface is a REST API, while internally Masakari
communicates via an RPC message passing mechanism.
@ -25,9 +25,9 @@ reads/writes, sending RPC messages to other Masakari engine,
and generating responses to the REST calls.
RPC messaging is done via the **oslo.messaging** library,
an abstraction on top of message queues.
Masakari engine will run on same host where masakari api is running, and have
a `manager` that is listening for `RPC` messages.
The manager also, optionally, has periodic tasks.
The Masakari engine will run on the same host where the Masakari api is
running, and has a `manager` that is listening for `RPC` messages.
The manager too has periodic tasks.
Components
----------
@ -35,7 +35,7 @@ Components
Below you will find a helpful explanation of the key components
of a typical Masakari deployment.
.. image:: ./images/architecture.png
.. image:: /_static/architecture.png
:width: 100%
* DB: sql database for data storage.

0
doc/source/how_to_get_involved.rst → doc/source/user/how_to_get_involved.rst
View File

4
doc/source/notifications.rst → doc/source/user/notifications.rst
View File

@ -14,7 +14,7 @@
Notifications in Masakari
==========================
Similarly to other OpenStack services Masakari emits notifications to the message
Similar to other OpenStack services Masakari emits notifications to the message
bus with the Notifier class provided by `oslo.messaging-doc`_. From the notification
consumer point of view a notification consists of two parts: an envelope with a fixed
structure defined by oslo.messaging and a payload defined by the service emitting the
@ -94,7 +94,7 @@ changed. Masakari provides the following contract regarding the versioned
notification payload:
* the payload version defined by the ``masakari_object.version`` field of the
payload will be increased if and only if the syntax or the semantics of the
payload will be increased only if the syntax or the semantics of the
``masakari_object.data`` field of the payload is changed.
* a minor version bump indicates a backward compatible change which means that
only new fields are added to the payload so a well written consumer can still

10
doc/source/process.rst → doc/source/user/process.rst
View File

@ -19,10 +19,8 @@
Masakari team process
=====================
Masakari is always evolving its processes, but it's important to explain why we
have them: so we can all work to ensure that the interactions we need to
happen do happen. The process exists to make productive communication between
all members of our community easier.
Masakari is always evolving its processes to ensure productive communication
between all members of our community easily.
OpenStack Wide Patterns
=======================
@ -50,7 +48,7 @@ But let's put a Masakari specific twist on things...
Overview
~~~~~~~~
.. image:: ./images/Masakari_spec_process.svg
.. image:: /_static/Masakari_spec_process.svg
:alt: Flow chart showing the Masakari bug/feature process
Where do you track bugs?
@ -68,7 +66,7 @@ has already fixed it for you (Launchpad helps you with that, at little,
when you create the bug report).
When do I need a blueprint vs. a spec?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To understand this question, we need to understand why blueprints and
specs are useful.

13
setup.cfg
View File

@ -78,14 +78,6 @@ masakari.task_flow.tasks =
confirm_compute_node_disabled_task = masakari.engine.drivers.taskflow.process_failure:ConfirmComputeNodeDisabledTask
no_op = masakari.engine.drivers.taskflow.no_op:Noop
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
[upload_sphinx]
upload-dir = doc/build/html
[compile_catalog]
directory = masakari/locale
domain = masakari
@ -99,8 +91,3 @@ input_file = masakari/locale/masakari.pot
keywords = _ gettext ngettext l_ lazy_gettext
mapping_file = babel.cfg
output_file = masakari/locale/masakari.pot
[build_releasenotes]
all_files = 1
build-dir = releasenotes/build
source-dir = releasenotes/source

2
tox.ini
View File

@ -76,7 +76,7 @@ commands =
deps = -r{toxinidir}/doc/requirements.txt
basepython = python3
commands =
python setup.py build_sphinx
sphinx-build -W -b html doc/source doc/build/html
[testenv:releasenotes]
deps = -r{toxinidir}/doc/requirements.txt