openstack/masakari
Code Issues Proposed changes

Merge "Masakari API Specifications"

Browse Source
This commit is contained in:
Zuul 2017-12-12 02:30:51 +00:00 committed by Gerrit Code Review
commit 750029757b
32 changed files with 2122 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

241
api-ref/source/conf.py Normal file
View File

@ -0,0 +1,241 @@
# Copyright (c) 2017 NTT Data
# All Rights Reserved.
# 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 documentation build configuration file.
#
# 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 subprocess
import sys
import warnings
import openstackdocstheme
extensions = [
'os_api_ref',
]
html_theme = 'openstackdocs'
html_theme_path = [openstackdocstheme.get_html_theme_path()]
html_theme_options = {
"sidebar_mode": "toc",
}
html_context = {'bug_project': 'masakari', 'bug_tag': 'api-ref'}
# 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('../../'))
sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, os.path.abspath('./'))
# -- General configuration
# ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Masakari API Reference'
copyright = u'2017-present, OpenStack Foundation'
# 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.
#
from masakari.version import version_info
# The full version, including alpha/beta/rc tags.
release = version_info.release_string()
# The short X.Y version.
version = version_info.version_string()
# 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'
# 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 = False
# 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'
# -- Options for man page output
# ----------------------------------------------
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
# -- Options for HTML output
# --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# 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']
# 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'
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
"-n1"]
try:
html_last_updated_fmt = subprocess.Popen(
git_cmd, stdout=subprocess.PIPE).communicate()[0].decode()
except Exception:
warnings.warn('Cannot get last updated time from git repository. '
'Not setting "html_last_updated_fmt".')
# 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_use_modindex = 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, 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 = ''
# If nonempty, this is the file name suffix for HTML files (e.g.
# ".xhtml").
# html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'masakaridoc'
# -- Options for LaTeX output
# -------------------------------------------------
# The paper size ('letter' or 'a4').
# latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [('index', 'Masakari.tex',
u'OpenStack Masakari API Documentation',
u'OpenStack Foundation', '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
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_use_modindex = True

329
api-ref/source/failover-segments.inc Normal file
View File

@ -0,0 +1,329 @@
.. -*- rst -*-
============================
FailoverSegments (segments)
============================
**Segments**
System can be zoned from top to down levels, into Regions, Availability Zones
and Host Aggregates (or Cells). Within those zones, one or more
pacemaker/pacemaker-remote clusters may exist. In addition to those boundaries,
shared storage boundary is also important to decide the optimal host for
fail-over. Openstack zoned boundaries (such as Regions, AZ, Host Aggregates,
etc..) can be managed by the nova scheduler. However, shared storage
boundaries are difficult to manage. Moreover, the operator may want to use
other types of boundary such as rack layout and powering. Therefore, operator
may want to define the segment of hypervisor hosts and assign the failover
host/hosts for each of them. Those segment can be define based on the shared
storage boundaries or any other limitations may critical for selection of the
failover host.
Lists, creates, shows details for, updates, and deletes segments.
List FailoverSegments
=====================
.. rest_method:: GET /segments
Lists IDs, names, description, recovery_method, service_type for all segments.
Segments contains `service_type` and `recovery_method` attributes.
`service_type` attribute indicates for which service (e.g. compute, cinder
etc) this segment belongs to. `recovery_method` attribute indicates the
recovery action to be followed when any host in a segment goes down. The
possible `recovery_method` values are:
- ``AUTO``. Auto recovery action.
- ``RESEVED_HOST``. Reserved host recovery action.
- ``AUTO_PRIORITY``. First executes auto and if auto fails then retried with
reserved host recover action.
- ``RH_PRIORITY``. First executes reserved host and if it fails then retried
with reserved host recover action.
You can filter on the `service_type` and `recovery_method` when you complete a
list segments request.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- limit: limit
- marker: marker
- recovery_method: recovery_method_query_segment
- service_type: service_type_query_segment
- sort_dir: sort_dir
- sort_key: sort_key_segment
Response
--------
.. rest_parameters:: parameters.yaml
- segments: segments
- name: segment_name
- uuid: segment_uuid
**Example List Segments**
.. literalinclude:: ../../doc/api_samples/segments/segments-list-resp.json
:language: javascript
Create Segment
==============
.. rest_method:: POST /segments
Creates a segment.
Creates a FailoverSegment with name, description, service_type and
recovery_method. For `service_type` user can mention the name of service for
which this segment is created. As of now user can mention `COMPUTE` as
`service_type`. For `recovery_method` user can mention either `AUTO`,
`RESERVED_HOST`, `AUTO_PRIORITY` or `RH_PRIORITY`. Segment name should be
unique.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 409
..
A conflict(409) is returned if segment with same name is already present.
Request
-------
.. rest_parameters:: parameters.yaml
- sgement: segment
- description: segment_description
- name: segment_name
- recovery_method: segment_recovery_method
- service_type: segment_service_type
**Example Create Segment**
.. literalinclude:: ../../doc/api_samples/segments/segment-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- segment: segment
- created: created
- description: segment_description
- id: segment_id
- name: segment_name
- recovery_method: segment_recovery_method
- service_type: segment_service_type
- updated: updated
- uuid: segment_uuid
**Example Create Segment**
.. literalinclude:: ../../doc/api_samples/segments/segment-create-resp.json
:language: javascript
Show Segment Details
====================
.. rest_method:: GET /segments/{segment_id}
Shows details for a segment.
**Preconditions**
The segment must exist.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- segment: segment
- created: created
- description: segment_description
- id: segment_id
- name: segment_name
- recovery_method: segment_recovery_method
- service_type: segment_service_type
- updated: updated
- uuid: segment_uuid
**Example Show Segment Details**
.. literalinclude:: ../../doc/api_samples/segments/segment-get-resp.json
:language: javascript
Update Segment
==============
.. rest_method:: PUT /segments/{segment_id}
Updates the editable attributes of an existing host.
**Preconditions**
- The segment must exist.
- User can not update segment if any host from the segment has any usage in
the notification table i.e. any host from the failover segment has
notification status as new/error/running.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
..
A conflict(409) is returned if user tries to update segment name which is
already assigned to segment or if any host from the segment has any usage in
the notification table i.e. any host from the failover segment has
notification status as new/error/running.
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
- description: segment_description
- name: segment_name
- recovery_method: segment_recovery_method
- service_type: segment_service_type
**Example Update segment name**
.. literalinclude:: ../../doc/api_samples/segments/segment-update-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- segment: segment
- created: created
- description: segment_description
- id: segment_id
- name: segment_name
- recovery_method: segment_recovery_method
- service_type: segment_service_type
- updated: updated
- uuid: segment_uuid
**Example Update Segment name**
.. literalinclude:: ../../doc/api_samples/segments/segment-update-resp.json
:language: javascript
Delete Segment
==============
.. rest_method:: DELETE /segments/{segment_id}
Deletes a segment.
**Preconditions**
- The segment must exist.
- User can not delete segment if any host from the segment has any usage in
the notification table i.e. any host from the failover segment has
notification status as new/error/running.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
..
A conflict(409) is returned if user tries to delete the segment if any host
from the segment has any usage in the notification table i.e. any host from
the failover segment has notification status as new/error/running.
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
Response
--------
There is no body content for the response of a successful DELETE query.

349
api-ref/source/hosts.inc Normal file
View File

@ -0,0 +1,349 @@
.. -*- rst -*-
==============
Hosts (hosts)
==============
**Hosts**
A host belongs to segment. Host can be any kind of virtual machine which can
have compute service running on it.
Lists, creates, shows details for, updates, and deletes hosts.
List Hosts
==========
.. rest_method:: GET /segments/{segment_id}/hosts
Lists IDs, names, type, reserved, on_maintenance for all hosts.
You can filter on the type, on_maintenance and reserved when you
complete a list hosts request.
**Preconditions**
The segment must exist.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
- limit: limit
- marker: marker
- on_maintenance: on_maintenance_query_host
- reserved: reserved_query_host
- sort_dir: sort_dir
- sort_key: sort_key_host
- type: type_query_host
Response
--------
.. rest_parameters:: parameters.yaml
- hosts: hosts
- name: host_name
- uuid: host_uuid
- failover_segment_id: segment_uuid
- deleted: deleted
- on_maintenance: on_maintenance
- reserved: reserved
- created_at: created
- control_attributes: control_attributes
- updated_at: updated
- failover_segment: segment
- type: host_type
- id: host_id
**Example List hosts**
.. literalinclude:: ../../doc/api_samples/hosts/hosts-list-resp.json
:language: javascript
Create Host
===========
.. rest_method:: POST /segments/{segment_id}/hosts
Creates a host under given segment.
Creates a Host under given segment with name, type, control_attributes.
User can set sepcific hosts as reserved by setting reserved attribute to True.
By default `on_maintenance` mode which indicates whether host is under
maintenance or not is False when host is created.
**Preconditions**
The segment must exist.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 201
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
..
A conflict(409) is returned if host with same name is already present under
given segment.
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
- host: host
- type: host_type
- name: host_name
- reserved: reserved
- on_maintenance: on_maintenance
**Example Create Host**
.. literalinclude:: ../../doc/api_samples/hosts/host-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- host: host
- name: host_name
- uuid: host_uuid
- failover_segment_id: segment_uuid
- deleted: deleted
- on_maintenance: on_maintenance
- reserved: reserved
- created_at: created
- control_attributes: control_attributes
- updated_at: updated
- failover_segment: segment
- type: host_type
- id: host_id
**Example Create Host**
.. literalinclude:: ../../doc/api_samples/hosts/host-create-resp.json
:language: javascript
Show Host Details
=================
.. rest_method:: GET /segments/{segment_id}/hosts/{host_id}
Shows details for a host.
**Preconditions**
The segment must exist.
The host must exist.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
- host_id: host_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- host: host
- name: host_name
- uuid: host_uuid
- failover_segment_id: segment_uuid
- deleted: deleted
- on_maintenance: on_maintenance
- reserved: reserved
- created_at: created
- control_attributes: control_attributes
- updated_at: updated
- failover_segment: segment
- type: host_type
- id: host_id
**Example Show Host Details**
.. literalinclude:: ../../doc/api_samples/hosts/host-get-resp.json
:language: javascript
Update Host
===========
.. rest_method:: PUT /segments/{segment_id}hosts/{host_id}
Updates the editable attributes of an existing host.
**Preconditions**
- The segment must exist.
- The host must exist.
- User can not update host if that host or any host from
the failover segment has any usage in the notification
table i.e. any host from the failover segment has
notification status as new/error/running.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
..
A conflict(409) is returned if user tries to update host name which is
already assigned to host under given segment or user tries to update the
host or any other host from the failover segment has any usage in the
notification table i.e. any host from the failover segment has
notification status as new/error/running.
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
- host_id: host_id_path
- type: host_type
- name: segment_name
- on_maintenance: on_maintenance
- reserved: reserved
**Example Update host reserved flag**
.. literalinclude:: ../../doc/api_samples/hosts/host-update-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- host: host
- name: host_name
- uuid: host_uuid
- failover_segment_id: segment_uuid
- deleted: deleted
- on_maintenance: on_maintenance
- reserved: reserved
- created_at: created
- control_attributes: control_attributes
- updated_at: updated
- failover_segment: segment
- type: host_type
- id: host_id
**Example Update host reserved flag**
.. literalinclude:: ../../doc/api_samples/hosts/host-update-resp.json
:language: javascript
Delete Host
===========
.. rest_method:: DELETE /segments/{segment_id}hosts/{host_id}
Deletes a host from given segment.
**Preconditions**
- The segment must exist.
- The host must exist.
- User can not delete host if that host or any host from
the failover segment has any usage in the notification
table i.e. any host from the failover segment has
notification status as new/error/running.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
..
A conflict(409) is returned if user tries to delete the
host or any other host from the failover segment has any usage in the
notification table i.e. any host from the failover segment has
notification status as new/error/running.
Request
-------
.. rest_parameters:: parameters.yaml
- segment_id: segment_id_path
- host_id: host_id_path
Response
--------
There is no body content for the response of a successful DELETE query.

15
api-ref/source/index.rst Normal file
View File

@ -0,0 +1,15 @@
:tocdepth: 2
==============
Masakari API
==============
This is a reference for the OpenStack Masakari API which is provided by the
Masakari project.
.. rest_expand_all::
.. include:: versions.inc
.. include:: failover-segments.inc
.. include:: hosts.inc
.. include:: notifications.inc

225
api-ref/source/notifications.inc Normal file
View File

@ -0,0 +1,225 @@
.. -*- rst -*-
==============================
Notifications (notifications)
==============================
**Notifications**
A notification is a kind of alert provided by monitoring services
(masakari-monitors) for failure of either host, process or instance.
Lists, creates and shows details for notifications.
List Notifications
==================
.. rest_method:: GET /notifications
Lists IDs, notification types, host_name, generated_time, payload and status
for all notifications.
Notifications contain a `status` attribute that indicates the current
notification state. You can filter on the notification `status` when you
complete a list notifications request. The notification `status` is returned
in the response body. The possible notification `status` values are:
- ``NEW``. The notification is in new state and yet to be processed.
- ``RUNNING``. The notification is in progress.
- ``FINISHED``. The notification is completed successfully.
- ``ERROR``. The notification is ended up in error.
- ``FAILED``. The notification is not processed successfully after failed once.
- ``IGNORED``. The notification is ignored by masakari engine.
You can also filter on the basis of `source_host_uuid`, `generated_since` and
`type` when you complete a list notifications request.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- generated_since: generated_since_query_notifications
- limit: limit
- marker: marker
- sort_dir: sort_dir
- sort_key: sort_key_notification
- source_host_uuid: source_host_uuid_query_notifications
- type: type_query_notifications
Response
--------
.. rest_parameters:: parameters.yaml
- notifications: notifications
- notification_uuid: notification_uuid
- deleted: deleted
- created_at: created
- updated_at: updated
- status: notification_status
- uuid: notification_uuid
- source_host_uuid: source_host_uuid
- generated_time: generated_time
- type: notification_type
- payload: notification_payload
- id: notification_id
**Example List Notifications**
.. literalinclude:: ../../doc/api_samples/notifications/notifcations-list-resp.json
:language: javascript
Create Notification
===================
.. rest_method:: POST /notifications
Creates a notiification.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 409
..
A conflict(409) is returned if notification with same payload is exists or
host for which notification is generated is under maintenance.
Request
-------
.. rest_parameters:: parameters.yaml
- notification: notification
- type: notification_type
- generated_time: generated_time
- payload: notification_payload
- host_name: notification_host_name
**Example create Process failure notification**
.. literalinclude:: ../../doc/api_samples/notifications/process-notification-create-req.json
:language: javascript
**Example create VM failure notification**
.. literalinclude:: ../../doc/api_samples/notifications/vm-notification-create-req.json
:language: javascript
**Example create COMPUTE_HOST failure notification**
.. literalinclude:: ../../doc/api_samples/notifications/host-notification-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- notification: notification
- type: notification_type
- generated_time: generated_time
- payload: notification_payload
- source_host_uuid: source_host_uuid
- uuid: notification_uuid
- deleted: deleted
- created_at: created
- status: notification_status
- updated_at: updated
- id: notification_id
**Example create Process failure notification**
.. literalinclude:: ../../doc/api_samples/notifications/process-notification-create-resp.json
:language: javascript
**Example create VM failure notification**
.. literalinclude:: ../../doc/api_samples/notifications/vm-notification-create-resp.json
:language: javascript
**Example create COMPUTE_HOST failure notification**
.. literalinclude:: ../../doc/api_samples/notifications/host-notification-create-resp.json
:language: javascript
Show Notification Details
=========================
.. rest_method:: GET /notifications/{notification_id}
Shows details for a notification.
**Preconditions**
The notification must exist.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- notification_id: notification_id_path
Response
--------
.. rest_parameters:: parameters.yaml
- notification: notification
- type: notification_type
- generated_time: generated_time
- payload: notification_payload
- source_host_uuid: source_host_uuid
- uuid: notification_uuid
- deleted: deleted
- created_at: created
- status: notification_status
- updated_at: updated
- id: notification_id
**Example Show Notification Details**
.. literalinclude:: ../../doc/api_samples/notifications/notification-get-resp.json
:language: javascript

417
api-ref/source/parameters.yaml Normal file
View File

@ -0,0 +1,417 @@
# variables in path
api_version:
in: path
required: true
type: string
description: >
The API version as returned in the links from the ``GET /`` call.
host_id_path:
description: |
The UUID of the host.
in: path
required: true
type: string
notification_id_path:
description: |
The UUID of the notification.
in: path
required: true
type: string
segment_id_path:
description: |
The UUID of the segment.
in: path
required: true
type: string
# variables in query
generated_since_query_notifications:
description: |
Filter the notifications list result by notification generated time.
in: query
required: false
type: string
limit:
description: |
Requests a page size of items. Returns a number of items up to a limit value.
Use the ``limit`` parameter to make an initial limited request and use the ID
of the last-seen item from the response as the ``marker`` parameter value in a
subsequent limited request.
in: query
required: false
type: integer
marker:
description: |
The ID of the last-seen item. Use the ``limit`` parameter to make an initial limited
request and use the ID of the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: string
on_maintenance_query_host:
description: |
Filter the host list result by on_maintenance.
in: query
required: false
type: boolean
recovery_method_query_segment:
description: |
Filter the segment list result by recovery_method.
in: query
required: false
type: string
reserved_query_host:
description: |
Filter the host list result by reserved flag.
in: query
required: false
type: boolean
service_type_query_segment:
description: |
Filter the segment list result by service_type.
in: query
required: false
type: string
sort_dir:
description: |
Sort direction. A valid value is ``asc`` (ascending) or ``desc`` (descending).
Default is ``desc``. You can specify multiple pairs of sort key and sort direction
query parameters. If you omit the sort direction in a pair, the API uses the natural
sorting direction of the direction of the segment ``sort_key`` attribute.
in: query
required: false
type: string
sort_key_host:
description: |
Sorts by a hosts attribute. Default attribute is ``created``. You can specify
multiple pairs of sort key and sort direction query parameters. If you omit the
sort direction in a pair, the API uses the natural sorting direction of the segment
``sort_key`` attribute. The sort keys are limited to:
- ``created_at``
- ``type``
- ``name``
- ``updated_at``
- ``uuid``
- ``reserved``
- ``on_maintenance``
in: query
required: false
type: string
sort_key_notification:
description: |
Sorts by a notification attribute. Default attribute is ``created``. You can specify
multiple pairs of sort key and sort direction query parameters. If you omit the
sort direction in a pair, the API uses the natural sorting direction of the segment
``sort_key`` attribute. The sort keys are limited to:
- ``created_at``
- ``type``
- ``generated_time``
- ``updated_at``
- ``uuid``
- ``payload``
- ``status``
- ``source_host_uuid``
in: query
required: false
type: string
sort_key_segment:
description: |
Sorts by a segment attribute. Default attribute is ``created``. You can specify
multiple pairs of sort key and sort direction query parameters. If you omit the
sort direction in a pair, the API uses the natural sorting direction of the segment
``sort_key`` attribute. The sort keys are limited to:
- ``created_at``
- ``description``
- ``name``
- ``updated_at``
- ``uuid``
- ``recovery_method``
- ``service_type``
in: query
required: false
type: string
source_host_uuid_query_notifications:
description: |
Filter the notifications list result by source_host_uuid.
in: query
required: false
type: string
type_query_host:
description: |
Filter the host list result by type of host.
in: query
required: false
type: boolean
type_query_notifications:
description: |
Filter the notifications list result by notification type.
in: query
required: false
type: string
# variables in body
control_attributes:
description: |
Attributes to control host.
in: body
required: true
type: string
created:
description: |
The date and time when the resource was created. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2017-04-21T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
deleted:
description: |
A boolean indicates whether this resource is deleted or not, if it has
not been deleted, ``false`` will appear.
in: body
required: true
type: boolean
generated_time:
description: |
The date and time when the notification was created. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2017-04-21T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
host:
description: |
A ``host`` object.
in: body
required: true
type: object
host_id:
description: |
ID of host.
in: body
required: true
type: string
host_name:
description: |
The host name.
in: body
required: true
type: string
host_type:
description: |
Type of host.
in: body
required: true
type: string
host_uuid:
description: |
The UUID of the host.
in: body
required: true
type: string
hosts:
description: |
A list of ``host`` objects.
in: body
required: true
type: array
links:
description: |
Links to the resources in question.
in: body
required: true
type: array
notification:
description: |
A ``notification`` object.
in: body
required: true
type: object
notification_host_name:
description: |
A name of host for which notification is created.
in: body
required: true
type: object
notification_id:
description: |
ID of notification.
in: body
required: true
type: string
notification_payload:
description: |
Payload for notification.
.. note:: This is a JSON string.
in: body
required: true
type: string
notification_status:
description: |
The notification status.
in: body
required: true
type: string
notification_type:
description: |
Type of notification, can be either ``PROCESS``, ``COMPUTE_HOST`` or ``VM``.
in: body
required: true
type: string
notification_uuid:
description: |
The UUID of the notification.
in: body
required: true
type: string
notifications:
description: |
A list of ``notification`` objects.
in: body
required: true
type: array
on_maintenance:
description: |
A boolean indicates whether this host is on maintenance or not, if it is
not on maintenance mode, ``false`` will appear.
in: body
required: false
type: boolean
reserved:
description: |
A boolean indicates whether this host is reserved or not, if it is
not reserved, ``false`` will appear.
in: body
required: false
type: boolean
segment:
description: |
A ``segment`` object.
in: body
required: true
type: object
segment_description:
type: string
in: body
required: false
description: |
A free form description of the segment. Limited to 255 characters
in length.
segment_id:
description: |
The Id of the segment.
in: body
required: true
type: string
segment_name:
description: |
The segment name.
in: body
required: true
type: string
segment_recovery_method:
type: string
in: body
required: true
description: |
Type of recovery if any host in this segment goes down. User can mention
either 'AUTO', 'RESERVED_HOST', 'AUTO_PRIORITY' or 'RH_PRIORITY'.
segment_service_type:
type: string
in: body
required: true
description: |
The name of service which will be deployed in this segment. As of now
user can mention 'COMPUTE' as service_type.
segment_uuid:
description: |
The UUID of the segment.
in: body
required: true
type: string
segments:
description: |
A list of ``segment`` objects.
in: body
required: true
type: array
source_host_uuid:
description: |
The UUID of host for which notification is generated.
in: body
required: true
type: string
updated:
description: |
The date and time when the resource was updated. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2017-04-21T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
version:
description: |
The version.
in: body
required: true
type: string
version_id:
type: string
in: body
required: true
description: >
A common name for the version in question. Informative only, it
has no real semantic meaning.
version_max:
type: string
in: body
required: true
description: >
The maximum version supported by API.
version_min:
type: string
in: body
required: true
description: >
The minimum version supported by API.
version_status:
type: string
in: body
required: true
description: |
The status of this API version. This can be one of:
- ``CURRENT``: this is the preferred version of the API to use
- ``SUPPORTED``: this is an older, but still supported version of the API
- ``DEPRECATED``: a deprecated version of the API that is slated for removal
versions:
type: array
in: body
required: true
description: >
A list of version objects that describe the API versions available.

62
api-ref/source/status.yaml Normal file
View File

@ -0,0 +1,62 @@
#################
# Success Codes #
#################
200:
default: |
Request was successful.
201:
default: |
Resource was created and is ready to use.
202:
default: |
Request was accepted for processing, but the processing has not been
completed. A 'location' header is included in the response which contains
a link to check the progress of the request.
204:
default: |
The server has fulfilled the request by deleting the resource.
300:
default: |
There are multiple choices for resources. The request has to be more
specific to successfully retrieve one of these resources.
302:
default: |
The response is about a redirection hint. The header of the response
usually contains a 'location' value where requesters can check to track
the real location of the resource.
#################
# Error Codes #
#################
400:
default: |
Some content in the request was invalid.
resource_signal: |
The target resource doesn't support receiving a signal.
401:
default: |
User must authenticate before making a request.
403:
default: |
Policy does not allow current user to do this operation.
404:
default: |
The requested resource could not be found.
405:
default: |
Method is not valid for this endpoint.
409:
default: |
This operation conflicted with another operation on this resource.
duplicate_zone: |
There is already a zone with this name.
500:
default: |
Something went wrong inside the service. This should not happen usually.
If it does happen, it means the server has experienced some serious
problems.
503:
default: |
Service is not available. This is mostly caused by service configuration
errors which prevents the service from successful start up.

106
api-ref/source/versions.inc Normal file
View File

@ -0,0 +1,106 @@
.. -*- rst -*-
==============
API Versions
==============
In order to bring new features to users over time, the Masakari API
supports versioning.
- ''major versions'', which have dedicated urls
The Version APIs work differently from other APIs as they *do not*
require authentication.
List All Major Versions
=======================
.. rest_method:: GET /
This fetches all the information about all known major API versions in
the deployment. Links to more specific information will be provided
for each API version.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
Response
--------
.. rest_parameters:: parameters.yaml
- versions: versions
- id: version_id
- status: version_status
- links: links
- version: version_max
- min_version: version_min
.. note::
The ``updated`` parameter in the response is vestigial and provides
no useful information.
Response Example
----------------
This demonstrates the expected response from a bleeding edge server
that supports up to the current version.
.. literalinclude:: /../../doc/api_samples/versions/versions-get-resp.json
:language: javascript
Show Details of Specific API Version
====================================
.. rest_method:: GET /{api_version}/
This gets the details of a specific API at its root. Nearly all this
information exists at the API root, so this is mostly a redundant
operation.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
Request
-------
.. rest_parameters:: parameters.yaml
- api_version: api_version
Response
--------
.. rest_parameters:: parameters.yaml
- version: version
- id: version_id
- status: version_status
- links: links
- version: version_max
- min_version: version_min
.. note::
The ``updated`` and ``media-types`` parameters in the response are
vestigial and provide no useful information. They will probably be
deprecated and removed in the future.
Response Example
----------------
This is an example of a ``GET /v1/`` on a relatively current server.
.. literalinclude:: /../../doc/api_samples/versions/v1-version-get-resp.json
:language: javascript

7
doc/api_samples/hosts/host-create-req.json Normal file
View File

@ -0,0 +1,7 @@
{
"host": {
"control_attributes": "SSH",
"type": "COMPUTE",
"name": "openstack-VirtualBox"
}
}

28
doc/api_samples/hosts/host-create-resp.json Normal file
View File

@ -0,0 +1,28 @@
{
"hosts": {
"reserved": false,
"uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"on_maintenance": false,
"created_at": "2017-04-21T10:09:20.000000",
"control_attributes": "SSH",
"updated_at": null,
"name": "openstack-VirtualBox",
"failover_segment": {
"uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b",
"deleted": false,
"created_at": "2017-04-20T10:17:17.000000",
"description": null,
"recovery_method": "auto",
"updated_at": null,
"service_type": "COMPUTE",
"deleted_at": null,
"id": 2,
"name": "segment2"
},
"deleted_at": null,
"type": "COMPUTE_HOST",
"id": 1,
"failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b"
}
}

28
doc/api_samples/hosts/host-get-resp.json Normal file
View File

@ -0,0 +1,28 @@
{
"hosts": {
"reserved": false,
"uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"on_maintenance": false,
"created_at": "2017-04-21T10:09:20.000000",
"control_attributes": "SSH",
"updated_at": null,
"name": "openstack-VirtualBox",
"failover_segment": {
"uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b",
"deleted": false,
"created_at": "2017-04-20T10:17:17.000000",
"description": null,
"recovery_method": "auto",
"updated_at": null,
"service_type": "COMPUTE",
"deleted_at": null,
"id": 2,
"name": "segment2"
},
"deleted_at": null,
"type": "COMPUTE_HOST",
"id": 1,
"failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b"
}
}

5
doc/api_samples/hosts/host-update-req.json Normal file
View File

@ -0,0 +1,5 @@
{
"host": {
"reserved": "True"
}
}

28
doc/api_samples/hosts/host-update-resp.json Normal file
View File

@ -0,0 +1,28 @@
{
"host": {
"reserved": true,
"uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"on_maintenance": false,
"created_at": "2017-04-21T10:09:20.000000",
"control_attributes": "SSH",
"updated_at": "2017-04-21T11:12:43.351320",
"name": "openstack-VirtualBox",
"failover_segment": {
"uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b",
"deleted": false,
"created_at": "2017-04-20T10:17:17.000000",
"description": null,
"recovery_method": "auto",
"updated_at": null,
"service_type": "Compute",
"deleted_at": null,
"id": 2,
"name": "new_segment"
},
"deleted_at": null,
"type": "COMPUTE",
"id": 1,
"failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b"
}
}

30
doc/api_samples/hosts/hosts-list-resp.json Normal file
View File

@ -0,0 +1,30 @@
{
"hosts": [
{
"reserved": false,
"uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"on_maintenance": false,
"created_at": "2017-04-21T10:09:20.000000",
"control_attributes": "SSH",
"updated_at": null,
"name": "openstack-VirtualBox",
"failover_segment": {
"uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b",
"deleted": false,
"created_at": "2017-04-20T10:17:17.000000",
"description": null,
"recovery_method": "auto",
"updated_at": null,
"service_type": "COMPUTE",
"deleted_at": null,
"id": 2,
"name": "segment2"
},
"deleted_at": null,
"type": "COMPUTE_HOST",
"id": 1,
"failover_segment_id": "9e800031-6946-4b43-bf09-8b3d1cab792b"
}
]
}

12
doc/api_samples/notifications/host-notification-create-req.json Normal file
View File

@ -0,0 +1,12 @@
{
"notification": {
"type": "COMPUTE_HOST",
"generated_time": "2017-04-24 08:34:46",
"payload": {
"event": "STOPPED",
"host_status": "UNKNOWN",
"cluster_status": "OFFLINE"
},
"hostname": "openstack-VirtualBox"
}
}

19
doc/api_samples/notifications/host-notification-create-resp.json Normal file
View File

@ -0,0 +1,19 @@
{
"notification": {
"notification_uuid": "9e66b95d-45da-4695-bfb6-ace68b35d955",
"status": "new",
"source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"created_at": "2017-04-24T06:37:37.396994",
"updated_at": null,
"id": 4,
"generated_time": "2017-04-24T08:34:46.000000",
"deleted_at": null,
"type": "COMPUTE_HOST",
"payload": {
"host_status": "UNKNOWN",
"event": "STOPPED",
"cluster_status": "OFFLINE"
}
}
}

20
doc/api_samples/notifications/notifcations-list-resp.json Normal file
View File

@ -0,0 +1,20 @@
{
"notifications": [
{
"notification_uuid": "32bc95ac-858d-460a-b562-7e365391be64",
"status": "new",
"source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"created_at": "2017-04-21T12:09:44.000000",
"updated_at": null,
"id": 1,
"generated_time": "2017-04-21T17:29:55.000000",
"deleted_at": null,
"type": "PROCESS",
"payload": {
"process_name": "nova-compute",
"event": "stopped"
}
}
]
}

19
doc/api_samples/notifications/notification-get-resp.json Normal file
View File

@ -0,0 +1,19 @@
{
"notification": {
"notification_uuid": "9e66b95d-45da-4695-bfb6-ace68b35d955",
"status": "new",
"source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"created_at": "2017-04-24T06:37:37.396994",
"updated_at": null,
"id": 4,
"generated_time": "2017-04-24T08:34:46.000000",
"deleted_at": null,
"type": "COMPUTE_HOST",
"payload": {
"host_status": "UNKNOWN",
"event": "STOPPED",
"cluster_status": "OFFLINE"
}
}
}

11
doc/api_samples/notifications/process-notification-create-req.json Normal file
View File

@ -0,0 +1,11 @@
{
"notification": {
"type": "PROCESS",
"generated_time": "2017-04-21 17:29:55",
"payload": {
"process_name": "nova-compute",
"event": "stopped"
},
"hostname": "openstack-VirtualBox"
}
}

18
doc/api_samples/notifications/process-notification-create-resp.json Normal file
View File

@ -0,0 +1,18 @@
{
"notification": {
"notification_uuid": "2b412acf-c55a-442d-8fd2-e823ec0d827f",
"status": "new",
"source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"created_at": "2017-04-24T06:05:29.387678",
"updated_at": null,
"id": 2,
"generated_time": "2017-04-21T17:29:55.000000",
"deleted_at": null,
"type": "PROCESS",
"payload": {
"process_name": "nova-compute",
"event": "stopped"
}
}
}

12
doc/api_samples/notifications/vm-notification-create-req.json Normal file
View File

@ -0,0 +1,12 @@
{
"notification": {
"type": "VM",
"generated_time": "2017-04-23T07:18:51.523726",
"payload": {
"instance_uuid": "96ab1c42-668c-4f2d-8689-afa3301d4ee9",
"vir_domain_event": "STOPPED_DESTROYED",
"event": "LIFECYCLE"
},
"hostname": "openstack-VirtualBox"
}
}

19
doc/api_samples/notifications/vm-notification-create-resp.json Normal file
View File

@ -0,0 +1,19 @@
{
"notification": {
"notification_uuid": "f4836386-7648-4395-89b6-75a2c5ca7ff2",
"status": "new",
"source_host_uuid": "083a8474-22c0-407f-b89b-c569134c3bfd",
"deleted": false,
"created_at": "2017-04-24T06:22:47.569979",
"updated_at": null,
"id": 3,
"generated_time": "2017-04-23T07:18:51.523726",
"deleted_at": null,
"type": "VM",
"payload": {
"instance_uuid": "96ab1c42-668c-4f2d-8689-afa3301d4ee9",
"vir_domain_event": "STOPPED_DESTROYED",
"event": "LIFECYCLE"
}
}
}

7
doc/api_samples/segments/segment-create-req.json Normal file
View File

@ -0,0 +1,7 @@
{
"segment" : {
"service_type": "COMPUTE",
"recovery_method": "AUTO",
"name": "new_segment"
}
}

14
doc/api_samples/segments/segment-create-resp.json Normal file
View File

@ -0,0 +1,14 @@
{
"segment": {
"uuid": "5fd9f925-0379-40db-a7f8-786a0b655b2a",
"deleted": false,
"created_at": "2017-04-21T08:59:53.991030",
"description": null,
"recovery_method": "AUTO",
"updated_at": null,
"service_type": "COMPUTE",
"deleted_at": null,
"id": 4,
"name": "new_segment"
}
}

14
doc/api_samples/segments/segment-get-resp.json Normal file
View File

@ -0,0 +1,14 @@
{
"segment": {
"uuid": "5fd9f925-0379-40db-a7f8-786a0b655b2a",
"deleted": false,
"created_at": "2017-04-21T08:59:53.991030",
"description": null,
"recovery_method": "AUTO",
"updated_at": null,
"service_type": "COMPUTE",
"deleted_at": null,
"id": 4,
"name": "new_segment"
}
}

5
doc/api_samples/segments/segment-update-req.json Normal file
View File

@ -0,0 +1,5 @@
{
"segment": {
"name": "new_segment"
}
}

14
doc/api_samples/segments/segment-update-resp.json Normal file
View File

@ -0,0 +1,14 @@
{
"segment": {
"uuid": "5fd9f925-0379-40db-a7f8-786a0b655b2a",
"deleted": false,
"created_at": "2017-04-21T08:59:54.000000",
"description": null,
"recovery_method": "AUTO",
"updated_at": "2017-04-21T09:47:03.748028",
"service_type": "COMPUTE",
"deleted_at": null,
"id": 4,
"name": "new_segment"
}
}

16
doc/api_samples/segments/segments-list-resp.json Normal file
View File

@ -0,0 +1,16 @@
{
"segments": [
{
"uuid": "9e800031-6946-4b43-bf09-8b3d1cab792b",
"deleted": false,
"created_at": "2017-04-20T10:17:17.000000",
"description": "Segment1",
"recovery_method": "auto",
"updated_at": null,
"service_type": "Compute",
"deleted_at": null,
"id": 1,
"name": "segment2"
}
]
}

26
doc/api_samples/versions/v1-version-get-resp.json Normal file
View File

@ -0,0 +1,26 @@
{
"version": {
"id": "v1",
"links": [
{
"href": "http://openstack.example.com/v1/",
"rel": "self"
},
{
"href": "http://docs.openstack.org/",
"rel": "describedby",
"type": "text/html"
}
],
"media-types": [
{
"base": "application/json",
"type": "application/vnd.openstack.masakari+json;version=1"
}
],
"status": "CURRENT",
"version": "1.0",
"min_version": "1.0",
"updated": "2016-07-01T11:33:21Z"
}
}

17
doc/api_samples/versions/versions-get-resp.json Normal file
View File

@ -0,0 +1,17 @@
{
"versions": [
{
"id": "v1.0",
"links": [
{
"href": "http://openstack.example.com/v1/",
"rel": "self"
}
],
"status": "CURRENT",
"version": "1.0",
"min_version": "1.0",
"updated": "2016-07-01T11:33:21Z"
}
]
}

2
test-requirements.txt
View File

@ -10,6 +10,8 @@ psycopg2>=2.6.2 # LGPL/ZPL
PyMySQL>=0.7.6 # MIT License
python-subunit>=1.0.0 # Apache-2.0/BSD
sphinx>=1.6.2 # BSD
openstackdocstheme>=1.17.0 # Apache-2.0
os-api-ref>=1.4.0 # Apache-2.0
oslosphinx>=4.7.0 # Apache-2.0
oslotest>=1.10.0 # Apache-2.0
os-testr>=1.0.0 # Apache-2.0

7
tox.ini
View File

@ -57,6 +57,13 @@ commands =
[testenv:debug]
commands = oslo_debug_helper {posargs}
[testenv:api-ref]
# This environment is called from CI scripts to test and publish
# the API Ref to developer.openstack.org.
commands =
rm -rf api-ref/build
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
[flake8]
# E123, E125 skipped as they are invalid PEP-8.