From 533c0a41145ada4dc2eedd387ed68e437da885a9 Mon Sep 17 00:00:00 2001 From: Alexander Chadin Date: Tue, 3 Apr 2018 19:55:57 +0300 Subject: [PATCH] Add API Reference for Watcher This patch set adds API Reference along with some fixes to documentation. It partially fixes bug #1757423. Change-Id: I107b4fd5daf40aad63fc13864debbbbc82a9826c --- api-ref/source/conf.py | 90 ++++ api-ref/source/index.rst | 16 + api-ref/source/parameters.yaml | 411 ++++++++++++++++++ .../actionplan-cancel-request-cancelling.json | 7 + .../actionplan-cancel-request-pending.json | 7 + .../samples/actionplan-list-response.json | 24 + .../samples/actionplan-show-response.json | 20 + .../samples/actionplan-start-response.json | 22 + .../actions-list-detailed-response.json | 30 ++ .../source/samples/actions-list-response.json | 23 + .../source/samples/actions-show-response.json | 26 ++ .../source/samples/audit-cancel-request.json | 7 + .../source/samples/audit-cancel-response.json | 51 +++ .../audit-create-request-continuous.json | 12 + .../samples/audit-create-request-oneshot.json | 5 + .../source/samples/audit-create-response.json | 51 +++ .../samples/audit-list-detailed-response.json | 55 +++ .../source/samples/audit-list-response.json | 28 ++ .../source/samples/audit-show-response.json | 51 +++ .../source/samples/audit-update-request.json | 12 + .../source/samples/audit-update-response.json | 51 +++ .../audittemplate-create-request-full.json | 7 + .../audittemplate-create-request-minimal.json | 4 + .../audittemplate-create-response.json | 23 + .../audittemplate-list-detailed-response.json | 23 + .../samples/audittemplate-list-response.json | 22 + .../samples/audittemplate-show-response.json | 23 + .../samples/audittemplate-update-request.json | 7 + .../audittemplate-update-response.json | 23 + .../source/samples/goal-list-response.json | 55 +++ .../source/samples/goal-show-response.json | 19 + ...scoring_engine-list-detailed-response.json | 20 + .../samples/scoring_engine-list-response.json | 19 + .../samples/scoring_engine-show-response.json | 16 + .../service-list-detailed-response.json | 24 + .../source/samples/service-list-response.json | 36 ++ .../source/samples/service-show-response.json | 20 + .../strategy-list-detailed-response.json | 35 ++ .../samples/strategy-list-response.json | 21 + .../samples/strategy-show-response.json | 33 ++ .../samples/strategy-state-response.json | 49 +++ api-ref/source/watcher-api-v1-actionplans.inc | 209 +++++++++ api-ref/source/watcher-api-v1-actions.inc | 155 +++++++ api-ref/source/watcher-api-v1-audits.inc | 349 +++++++++++++++ .../source/watcher-api-v1-audittemplates.inc | 257 +++++++++++ api-ref/source/watcher-api-v1-goals.inc | 126 ++++++ .../source/watcher-api-v1-scoring_engines.inc | 120 +++++ api-ref/source/watcher-api-v1-services.inc | 116 +++++ api-ref/source/watcher-api-v1-strategies.inc | 164 +++++++ doc/source/admin/policy.rst | 10 + doc/source/configuration/configuring.rst | 15 +- doc/source/contributor/environment.rst | 2 + doc/source/index.rst | 48 +- tox.ini | 8 + watcher/api/controllers/v1/scoring_engine.py | 2 +- watcher/api/controllers/v1/strategy.py | 2 +- watcher/tests/api/v1/test_scoring_engines.py | 2 +- 57 files changed, 3033 insertions(+), 30 deletions(-) create mode 100644 api-ref/source/conf.py create mode 100644 api-ref/source/index.rst create mode 100644 api-ref/source/parameters.yaml create mode 100644 api-ref/source/samples/actionplan-cancel-request-cancelling.json create mode 100644 api-ref/source/samples/actionplan-cancel-request-pending.json create mode 100644 api-ref/source/samples/actionplan-list-response.json create mode 100644 api-ref/source/samples/actionplan-show-response.json create mode 100644 api-ref/source/samples/actionplan-start-response.json create mode 100644 api-ref/source/samples/actions-list-detailed-response.json create mode 100644 api-ref/source/samples/actions-list-response.json create mode 100644 api-ref/source/samples/actions-show-response.json create mode 100644 api-ref/source/samples/audit-cancel-request.json create mode 100644 api-ref/source/samples/audit-cancel-response.json create mode 100644 api-ref/source/samples/audit-create-request-continuous.json create mode 100644 api-ref/source/samples/audit-create-request-oneshot.json create mode 100644 api-ref/source/samples/audit-create-response.json create mode 100644 api-ref/source/samples/audit-list-detailed-response.json create mode 100644 api-ref/source/samples/audit-list-response.json create mode 100644 api-ref/source/samples/audit-show-response.json create mode 100644 api-ref/source/samples/audit-update-request.json create mode 100644 api-ref/source/samples/audit-update-response.json create mode 100644 api-ref/source/samples/audittemplate-create-request-full.json create mode 100644 api-ref/source/samples/audittemplate-create-request-minimal.json create mode 100644 api-ref/source/samples/audittemplate-create-response.json create mode 100644 api-ref/source/samples/audittemplate-list-detailed-response.json create mode 100644 api-ref/source/samples/audittemplate-list-response.json create mode 100644 api-ref/source/samples/audittemplate-show-response.json create mode 100644 api-ref/source/samples/audittemplate-update-request.json create mode 100644 api-ref/source/samples/audittemplate-update-response.json create mode 100644 api-ref/source/samples/goal-list-response.json create mode 100644 api-ref/source/samples/goal-show-response.json create mode 100644 api-ref/source/samples/scoring_engine-list-detailed-response.json create mode 100644 api-ref/source/samples/scoring_engine-list-response.json create mode 100644 api-ref/source/samples/scoring_engine-show-response.json create mode 100644 api-ref/source/samples/service-list-detailed-response.json create mode 100644 api-ref/source/samples/service-list-response.json create mode 100644 api-ref/source/samples/service-show-response.json create mode 100644 api-ref/source/samples/strategy-list-detailed-response.json create mode 100644 api-ref/source/samples/strategy-list-response.json create mode 100644 api-ref/source/samples/strategy-show-response.json create mode 100644 api-ref/source/samples/strategy-state-response.json create mode 100644 api-ref/source/watcher-api-v1-actionplans.inc create mode 100644 api-ref/source/watcher-api-v1-actions.inc create mode 100644 api-ref/source/watcher-api-v1-audits.inc create mode 100644 api-ref/source/watcher-api-v1-audittemplates.inc create mode 100644 api-ref/source/watcher-api-v1-goals.inc create mode 100644 api-ref/source/watcher-api-v1-scoring_engines.inc create mode 100644 api-ref/source/watcher-api-v1-services.inc create mode 100644 api-ref/source/watcher-api-v1-strategies.inc diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 000000000..0722c2787 --- /dev/null +++ b/api-ref/source/conf.py @@ -0,0 +1,90 @@ +# 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. +# +# nova documentation build configuration file, created by +# sphinx-quickstart on Sat May 1 15:17:47 2010. +# +# 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. + +from watcher import version as watcher_version + + +extensions = [ + 'openstackdocstheme', + 'os_api_ref', +] + +# -- 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 master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Infrastructure Optimization API Reference' +copyright = u'2010-present, OpenStack Foundation' + +# openstackdocstheme options +repository_name = 'openstack/watcher' +bug_project = 'watcher' +bug_tag = '' + +# 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 full version, including alpha/beta/rc tags. +release = watcher_version.version_info.release_string() +# The short X.Y version. +version = watcher_version.version_string + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- 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 = '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 = { + "sidebar_mode": "toc", +} + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + +# -- Options for LaTeX output ------------------------------------------------- + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', 'Watcher.tex', u'Infrastructure Optimization API Reference', + u'OpenStack Foundation', 'manual'), +] diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 000000000..0598c780f --- /dev/null +++ b/api-ref/source/index.rst @@ -0,0 +1,16 @@ +:tocdepth: 2 + +=========== +Watcher API +=========== + +.. rest_expand_all:: + +.. include:: watcher-api-v1-audittemplates.inc +.. include:: watcher-api-v1-audits.inc +.. include:: watcher-api-v1-actionplans.inc +.. include:: watcher-api-v1-actions.inc +.. include:: watcher-api-v1-goals.inc +.. include:: watcher-api-v1-strategies.inc +.. include:: watcher-api-v1-services.inc +.. include:: watcher-api-v1-scoring_engines.inc \ No newline at end of file diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 000000000..527ed7fd5 --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -0,0 +1,411 @@ +# Path +action_ident: + description: | + The UUID of the Action. + in: path + required: true + type: string +actionplan_ident: + description: | + The UUID of the Action Plan. + in: path + required: true + type: string +audit_ident: + description: | + The UUID or name of the Audit. + in: path + required: true + type: string +audittemplate_ident: + description: | + The UUID or name of the Audit Template. + in: path + required: true + type: string +goal_ident: + description: | + The UUID or name of the Goal. + in: path + required: true + type: string +scoring_engine_ident: + description: | + The UUID or name of the Scoring Engine. + in: path + required: true + type: string +service_ident: + description: | + The ID or name of the Service. + in: path + required: true + type: string +strategy_ident: + description: | + The UUID or name of the Strategy. + in: path + required: true + type: string + +# Query body +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 +r_action_plan: + description: | + UUID of the action plan used for filtering. + in: query + required: false + type: string +r_audit: + description: | + Optional UUID of an audit, to get only actions for that audit. + in: query + required: false + type: string +r_goal: + description: | + The UUID or name of the Goal. + in: query + required: false + type: string +r_strategy: + description: | + The UUID or name of the Strategy. + in: query + required: false + type: string +sort_dir: + description: | + Sorts the response by the requested sort direction. + A valid value is ``asc`` (ascending) or ``desc`` (descending). + Default is ``asc``. + in: query + required: false + type: string +sort_key: + description: | + Sorts the response by the this attribute value. Default is ``id``. + in: query + required: false + type: string + +# variables in the API response body + +# Action +action_action_plan_uuid: + description: | + The action plan this action belongs to. + in: body + required: true + type: string +action_description: + description: | + Action description. + in: body + required: true + type: string +action_input_parameters: + description: | + Input parameters which are used by appropriate action type. For example, + ``migration`` action takes into account such parameters as + ``migration_type``, ``destination_node``, ``resource_id`` and + ``source_node``. To see a list of supported action types and their input + parameters visit `Action plugins page `_. + in: body + required: true + type: JSON +action_parents: + description: | + UUIDs of parent actions. + in: body + required: true + type: array +action_state: + description: | + State of Action. + in: body + required: true + type: string +action_type: + description: | + Action type based on specific API action. Actions in Watcher are + pluggable, to see a list of supported action types visit + `Action plugins page `_. + in: body + required: true + type: string + +# Action Plan +actionplan_audit_uuid: + description: | + The UUID of the audit this acton plan belongs to. + in: body + required: false + type: string +actionplan_efficacy_indicators: + description: | + The list of efficacy indicators associated to this action plan. + in: body + required: false + type: array +actionplan_global_efficacy: + description: | + The global efficacy of this action plan. + in: body + required: false + type: array +actionplan_state: + description: | + State of this action plan. To get more information about states and + action plan's lifecycle, visit `Action Plan State Machine page `_. + in: body + required: false + type: string + +# Audit +audit_autotrigger: + description: | + Autoexecute action plan once audit is succeeded. + in: body + required: false + type: boolean +audit_goal: + description: | + The UUID or name of the Goal. + in: body + required: false + type: string +audit_interval: + description: | + Time interval between audit's execution. + Can be set either in seconds or cron syntax. + Should be defined only for CONTINUOUS audits. + in: body + required: false + type: string +audit_name: + description: | + Name of this audit. + in: body + required: false + type: string +audit_next_run_time: + description: | + The next time audit launch. Defined only for CONTINUOUS audits. + in: body + required: false + type: string +audit_parameters: + description: | + The strategy parameters for this audit. + in: body + required: false + type: JSON +audit_state: + description: | + State of this audit. To get more information about states and + audit's lifecycle, visit `Audit State Machine page `_. + in: body + required: true + type: string +audit_strategy: + description: | + The UUID or name of the Strategy. + in: body + required: false + type: string +audit_type: + description: | + Type of this audit. Can be either ONESHOT or CONTINUOUS. + in: body + required: true + type: string + +# Audit Template +audittemplate_description: + description: | + Short description of the Audit Template. + in: body + required: false + type: string +audittemplate_goal: + description: | + The UUID or name of the Goal. + in: body + required: true + type: string +audittemplate_name: + description: | + The name of the Audit template. + in: body + required: true + type: string +audittemplate_scope: + description: | + Audit Scope. + in: body + required: false + type: JSON +audittemplate_strategy: + description: | + The UUID or name of the Strategy. + in: body + required: false + type: string + +# Goal +goal_display_name: + description: | + Localized name of the goal. + in: body + required: true + type: string +goal_efficacy_specification: + description: | + Efficacy specifications as result of stategy's execution. + in: body + required: true + type: array +goal_name: + description: | + Name of the goal. + in: body + required: true + type: string +goal_uuid: + description: | + Unique UUID for this goal. + in: body + required: true + type: string + +links: + description: | + A list of relative links. Includes the self and bookmark links. + in: body + required: true + type: array + +# Scoring Engine +scoring_engine_description: + description: | + A human readable description of the Scoring Engine. + in: body + required: true + type: string +scoring_engine_metainfo: + description: | + A metadata associated with the scoring engine + in: body + required: true + type: string +scoring_engine_name: + description: | + The name of the scoring engine. + in: body + required: true + type: string +# Service +service_host: + description: | + Name of host where service is placed on. + in: body + required: true + type: string +service_id: + description: | + ID of service. + in: body + required: true + type: integer +service_last_seen_up: + description: | + Time when Watcher service sent latest heartbeat. + in: body + required: true + type: string +service_name: + description: | + Name of service like ``watcher-applier``. + in: body + required: true + type: string +service_status: + description: | + State of service. It can be either in ACTIVE or FAILED state. + in: body + required: true + type: string + +# Strategy +strategy_check_comment: + description: | + Requirement comment. + in: body + required: true + type: string +strategy_check_mandatory: + description: | + Whether this requirement mandatory or not. + in: body + required: true + type: boolean +strategy_check_state: + description: | + State of requirement for Strategy. + in: body + required: true + type: string or JSON +strategy_check_type: + description: | + Type of requirement for Strategy. + in: body + required: true + type: string +strategy_display_name: + description: | + Localized name of the strategy. + in: body + required: true + type: string +strategy_name: + description: | + Name of the strategy. + in: body + required: true + type: string +strategy_parameters_spec: + description: | + Parameters specifications for this strategy. + in: body + required: true + type: JSON +strategy_uuid: + description: | + Unique UUID for this strategy. + in: body + required: true + type: string + +uuid: + description: | + The UUID for the resource. + in: body + required: true + type: string \ No newline at end of file diff --git a/api-ref/source/samples/actionplan-cancel-request-cancelling.json b/api-ref/source/samples/actionplan-cancel-request-cancelling.json new file mode 100644 index 000000000..2e76225ad --- /dev/null +++ b/api-ref/source/samples/actionplan-cancel-request-cancelling.json @@ -0,0 +1,7 @@ +[ + { + "op": "replace", + "value": "CANCELLING", + "path": "/state" + } +] \ No newline at end of file diff --git a/api-ref/source/samples/actionplan-cancel-request-pending.json b/api-ref/source/samples/actionplan-cancel-request-pending.json new file mode 100644 index 000000000..6c18bf7dd --- /dev/null +++ b/api-ref/source/samples/actionplan-cancel-request-pending.json @@ -0,0 +1,7 @@ +[ + { + "op": "replace", + "value": "CANCELLED", + "path": "/state" + } +] \ No newline at end of file diff --git a/api-ref/source/samples/actionplan-list-response.json b/api-ref/source/samples/actionplan-list-response.json new file mode 100644 index 000000000..72fc757ce --- /dev/null +++ b/api-ref/source/samples/actionplan-list-response.json @@ -0,0 +1,24 @@ +{ + "action_plans": [ + { + "state": "ONGOING", + "efficacy_indicators": [], + "strategy_uuid": "7dae0eea-9df7-42b8-bb3e-313958ff2242", + "global_efficacy": [], + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/action_plans/4cbc4ede-0d25-481b-b86e-998dbbd4f8bf" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/action_plans/4cbc4ede-0d25-481b-b86e-998dbbd4f8bf" + } + ], + "updated_at": "2018-04-10T11:59:52.640067+00:00", + "strategy_name": "dummy_with_resize", + "uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf", + "audit_uuid": "7d100b05-0a86-491f-98a7-f93da19b272a" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/actionplan-show-response.json b/api-ref/source/samples/actionplan-show-response.json new file mode 100644 index 000000000..3cf57077d --- /dev/null +++ b/api-ref/source/samples/actionplan-show-response.json @@ -0,0 +1,20 @@ +{ + "state": "ONGOING", + "efficacy_indicators": [], + "strategy_uuid": "7dae0eea-9df7-42b8-bb3e-313958ff2242", + "global_efficacy": [], + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/action_plans/4cbc4ede-0d25-481b-b86e-998dbbd4f8bf" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/action_plans/4cbc4ede-0d25-481b-b86e-998dbbd4f8bf" + } + ], + "updated_at": "2018-04-10T11:59:52.640067+00:00", + "strategy_name": "dummy_with_resize", + "uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf", + "audit_uuid": "7d100b05-0a86-491f-98a7-f93da19b272a" +} \ No newline at end of file diff --git a/api-ref/source/samples/actionplan-start-response.json b/api-ref/source/samples/actionplan-start-response.json new file mode 100644 index 000000000..3261de289 --- /dev/null +++ b/api-ref/source/samples/actionplan-start-response.json @@ -0,0 +1,22 @@ +{ + "state": "PENDING", + "efficacy_indicators": [], + "strategy_uuid": "7dae0eea-9df7-42b8-bb3e-313958ff2242", + "global_efficacy": [], + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/action_plans/4cbc4ede-0d25-481b-b86e-998dbbd4f8bf" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/action_plans/4cbc4ede-0d25-481b-b86e-998dbbd4f8bf" + } + ], + "updated_at": "2018-04-10T11:59:41.602430+00:00", + "strategy_name": "dummy_with_resize", + "uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf", + "audit_uuid": "7d100b05-0a86-491f-98a7-f93da19b272a", + "created_at": "2018-04-10T11:59:12.592729+00:00", + "deleted_at": null +} \ No newline at end of file diff --git a/api-ref/source/samples/actions-list-detailed-response.json b/api-ref/source/samples/actions-list-detailed-response.json new file mode 100644 index 000000000..cd0d98677 --- /dev/null +++ b/api-ref/source/samples/actions-list-detailed-response.json @@ -0,0 +1,30 @@ +{ + "actions": [ + { + "state": "PENDING", + "description": "Wait for a given interval in seconds.", + "parents": [ + "8119d16e-b419-4729-b015-fc04c4e45783" + ], + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/actions/7182a988-e6c4-4152-a0d6-067119475c83" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/actions/7182a988-e6c4-4152-a0d6-067119475c83" + } + ], + "action_plan_uuid": "c6bba9ed-a7eb-4370-9993-d873e5e22cba", + "uuid": "7182a988-e6c4-4152-a0d6-067119475c83", + "deleted_at": null, + "updated_at": null, + "input_parameters": { + "duration": 3.2 + }, + "action_type": "sleep", + "created_at": "2018-03-26T11:56:08.235226+00:00" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/actions-list-response.json b/api-ref/source/samples/actions-list-response.json new file mode 100644 index 000000000..d3f46e800 --- /dev/null +++ b/api-ref/source/samples/actions-list-response.json @@ -0,0 +1,23 @@ +{ + "actions": [ + { + "state": "PENDING", + "parents": [ + "8119d16e-b419-4729-b015-fc04c4e45783" + ], + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/actions/7182a988-e6c4-4152-a0d6-067119475c83" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/actions/7182a988-e6c4-4152-a0d6-067119475c83" + } + ], + "action_plan_uuid": "c6bba9ed-a7eb-4370-9993-d873e5e22cba", + "uuid": "7182a988-e6c4-4152-a0d6-067119475c83", + "action_type": "sleep" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/actions-show-response.json b/api-ref/source/samples/actions-show-response.json new file mode 100644 index 000000000..b5959bd88 --- /dev/null +++ b/api-ref/source/samples/actions-show-response.json @@ -0,0 +1,26 @@ +{ + "state": "SUCCEEDED", + "description": "Logging a NOP message", + "parents": [ + "b4529294-1de6-4302-b57a-9b5d5dc363c6" + ], + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/actions/54acc7a0-91b0-46ea-a5f7-4ae2b9df0b0a" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/actions/54acc7a0-91b0-46ea-a5f7-4ae2b9df0b0a" + } + ], + "action_plan_uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf", + "uuid": "54acc7a0-91b0-46ea-a5f7-4ae2b9df0b0a", + "deleted_at": null, + "updated_at": "2018-04-10T11:59:44.026973+00:00", + "input_parameters": { + "message": "Welcome" + }, + "action_type": "nop", + "created_at": "2018-04-10T11:59:12.725147+00:00" +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-cancel-request.json b/api-ref/source/samples/audit-cancel-request.json new file mode 100644 index 000000000..6c18bf7dd --- /dev/null +++ b/api-ref/source/samples/audit-cancel-request.json @@ -0,0 +1,7 @@ +[ + { + "op": "replace", + "value": "CANCELLED", + "path": "/state" + } +] \ No newline at end of file diff --git a/api-ref/source/samples/audit-cancel-response.json b/api-ref/source/samples/audit-cancel-response.json new file mode 100644 index 000000000..4fd6f0e10 --- /dev/null +++ b/api-ref/source/samples/audit-cancel-response.json @@ -0,0 +1,51 @@ +{ + "interval": "*/2 * * * *", + "strategy_uuid": "6b3b3902-8508-4cb0-bb85-67f32866b086", + "goal_uuid": "e1a5a45b-f251-47cf-9c5f-fa1e66e1286a", + "name": "audit1", + "parameters": { + "host_choice": "retry", + "instance_metrics": { + "cpu_util": "compute.node.cpu.percent", + "memory.resident": "hardware.memory.used" + }, + "granularity": 300, + "weights": { + "cpu_util_weight": 1.0, + "memory.resident_weight": 1.0 + }, + "retry_count": 1, + "metrics": [ + "cpu_util" + ], + "periods": { + "instance": 720, + "node": 600 + }, + "thresholds": { + "cpu_util": 0.2, + "memory.resident": 0.2 + } + }, + "auto_trigger": false, + "uuid": "65a5da84-5819-4aea-8278-a28d2b489028", + "goal_name": "workload_balancing", + "scope": [], + "created_at": "2018-04-06T07:27:27.820460+00:00", + "deleted_at": null, + "state": "CANCELLED", + "audit_type": "CONTINUOUS", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audits/65a5da84-5819-4aea-8278-a28d2b489028" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audits/65a5da84-5819-4aea-8278-a28d2b489028" + } + ], + "strategy_name": "workload_stabilization", + "next_run_time": "2018-04-06T11:56:00", + "updated_at": "2018-04-06T11:54:01.266447+00:00" +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-create-request-continuous.json b/api-ref/source/samples/audit-create-request-continuous.json new file mode 100644 index 000000000..4d5202260 --- /dev/null +++ b/api-ref/source/samples/audit-create-request-continuous.json @@ -0,0 +1,12 @@ +{ + "auto_trigger": false, + "audit_template_uuid": "76fddfee-a9c4-40b0-8da0-c19ad6904f09", + "name": "test_audit", + "parameters": { + "metrics": [ + "cpu_util" + ] + }, + "audit_type": "CONTINUOUS", + "interval": "*/2 * * * *" +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-create-request-oneshot.json b/api-ref/source/samples/audit-create-request-oneshot.json new file mode 100644 index 000000000..8fa1d0f00 --- /dev/null +++ b/api-ref/source/samples/audit-create-request-oneshot.json @@ -0,0 +1,5 @@ +{ + "audit_type": "ONESHOT", + "auto_trigger": false, + "audit_template_uuid": "5e70a156-ced7-4012-b1c6-88fcb02ee0c1" +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-create-response.json b/api-ref/source/samples/audit-create-response.json new file mode 100644 index 000000000..7c43be508 --- /dev/null +++ b/api-ref/source/samples/audit-create-response.json @@ -0,0 +1,51 @@ +{ + "interval": "*/2 * * * *", + "strategy_uuid": "6b3b3902-8508-4cb0-bb85-67f32866b086", + "goal_uuid": "e1a5a45b-f251-47cf-9c5f-fa1e66e1286a", + "name": "test_audit", + "parameters": { + "host_choice": "retry", + "granularity": 300, + "thresholds": { + "cpu_util": 0.2, + "memory.resident": 0.2 + }, + "periods": { + "node": 600, + "instance": 720 + }, + "retry_count": 1, + "metrics": [ + "cpu_util" + ], + "weights": { + "cpu_util_weight": 1.0, + "memory.resident_weight": 1.0 + }, + "instance_metrics": { + "cpu_util": "compute.node.cpu.percent", + "memory.resident": "hardware.memory.used" + } + }, + "auto_trigger": false, + "uuid": "65a5da84-5819-4aea-8278-a28d2b489028", + "goal_name": "workload_balancing", + "scope": [], + "created_at": "2018-04-06T07:27:27.820460+00:00", + "deleted_at": null, + "state": "PENDING", + "audit_type": "CONTINUOUS", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audits/65a5da84-5819-4aea-8278-a28d2b489028" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audits/65a5da84-5819-4aea-8278-a28d2b489028" + } + ], + "strategy_name": "workload_stabilization", + "next_run_time": null, + "updated_at": null +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-list-detailed-response.json b/api-ref/source/samples/audit-list-detailed-response.json new file mode 100644 index 000000000..19ee6a2f6 --- /dev/null +++ b/api-ref/source/samples/audit-list-detailed-response.json @@ -0,0 +1,55 @@ +{ + "audits": [ + { + "interval": "*/2 * * * *", + "strategy_uuid": "6b3b3902-8508-4cb0-bb85-67f32866b086", + "goal_uuid": "e1a5a45b-f251-47cf-9c5f-fa1e66e1286a", + "name": "test_audit", + "parameters": { + "host_choice": "retry", + "instance_metrics": { + "cpu_util": "compute.node.cpu.percent", + "memory.resident": "hardware.memory.used" + }, + "granularity": 300, + "weights": { + "cpu_util_weight": 1.0, + "memory.resident_weight": 1.0 + }, + "retry_count": 1, + "metrics": [ + "cpu_util" + ], + "periods": { + "instance": 720, + "node": 600 + }, + "thresholds": { + "cpu_util": 0.2, + "memory.resident": 0.2 + } + }, + "auto_trigger": false, + "uuid": "65a5da84-5819-4aea-8278-a28d2b489028", + "goal_name": "workload_balancing", + "scope": [], + "created_at": "2018-04-06T07:27:27.820460+00:00", + "deleted_at": null, + "state": "ONGOING", + "audit_type": "CONTINUOUS", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audits/65a5da84-5819-4aea-8278-a28d2b489028" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audits/65a5da84-5819-4aea-8278-a28d2b489028" + } + ], + "strategy_name": "workload_stabilization", + "next_run_time": "2018-04-06T09:46:00", + "updated_at": "2018-04-06T09:44:01.604146+00:00" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-list-response.json b/api-ref/source/samples/audit-list-response.json new file mode 100644 index 000000000..36feed47f --- /dev/null +++ b/api-ref/source/samples/audit-list-response.json @@ -0,0 +1,28 @@ +{ + "audits": [ + { + "interval": null, + "strategy_uuid": "e311727b-b9b3-43ef-a5f7-8bd7ea80df25", + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "dummy-2018-03-26T11:56:07.950400", + "auto_trigger": false, + "uuid": "ccc69a5f-114e-46f4-b15e-a77eaa337b01", + "goal_name": "dummy", + "scope": [], + "state": "SUCCEEDED", + "audit_type": "ONESHOT", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audits/ccc69a5f-114e-46f4-b15e-a77eaa337b01" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audits/ccc69a5f-114e-46f4-b15e-a77eaa337b01" + } + ], + "strategy_name": "dummy", + "next_run_time": null + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-show-response.json b/api-ref/source/samples/audit-show-response.json new file mode 100644 index 000000000..ee6305e98 --- /dev/null +++ b/api-ref/source/samples/audit-show-response.json @@ -0,0 +1,51 @@ +{ + "interval": "*/2 * * * *", + "strategy_uuid": "6b3b3902-8508-4cb0-bb85-67f32866b086", + "goal_uuid": "e1a5a45b-f251-47cf-9c5f-fa1e66e1286a", + "name": "test_audit", + "parameters": { + "host_choice": "retry", + "instance_metrics": { + "cpu_util": "compute.node.cpu.percent", + "memory.resident": "hardware.memory.used" + }, + "granularity": 300, + "weights": { + "cpu_util_weight": 1.0, + "memory.resident_weight": 1.0 + }, + "retry_count": 1, + "metrics": [ + "cpu_util" + ], + "periods": { + "instance": 720, + "node": 600 + }, + "thresholds": { + "cpu_util": 0.2, + "memory.resident": 0.2 + } + }, + "auto_trigger": false, + "uuid": "65a5da84-5819-4aea-8278-a28d2b489028", + "goal_name": "workload_balancing", + "scope": [], + "created_at": "2018-04-06T07:27:27.820460+00:00", + "deleted_at": null, + "state": "ONGOING", + "audit_type": "CONTINUOUS", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audits/65a5da84-5819-4aea-8278-a28d2b489028" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audits/65a5da84-5819-4aea-8278-a28d2b489028" + } + ], + "strategy_name": "workload_stabilization", + "next_run_time": "2018-04-06T11:56:00", + "updated_at": "2018-04-06T11:54:01.266447+00:00" +} \ No newline at end of file diff --git a/api-ref/source/samples/audit-update-request.json b/api-ref/source/samples/audit-update-request.json new file mode 100644 index 000000000..e22286bf9 --- /dev/null +++ b/api-ref/source/samples/audit-update-request.json @@ -0,0 +1,12 @@ +[ + { + "value": "CANCELLED", + "path": "/state", + "op": "replace" + }, + { + "value": "audit1", + "path": "/name", + "op": "replace" + } +] \ No newline at end of file diff --git a/api-ref/source/samples/audit-update-response.json b/api-ref/source/samples/audit-update-response.json new file mode 100644 index 000000000..4fd6f0e10 --- /dev/null +++ b/api-ref/source/samples/audit-update-response.json @@ -0,0 +1,51 @@ +{ + "interval": "*/2 * * * *", + "strategy_uuid": "6b3b3902-8508-4cb0-bb85-67f32866b086", + "goal_uuid": "e1a5a45b-f251-47cf-9c5f-fa1e66e1286a", + "name": "audit1", + "parameters": { + "host_choice": "retry", + "instance_metrics": { + "cpu_util": "compute.node.cpu.percent", + "memory.resident": "hardware.memory.used" + }, + "granularity": 300, + "weights": { + "cpu_util_weight": 1.0, + "memory.resident_weight": 1.0 + }, + "retry_count": 1, + "metrics": [ + "cpu_util" + ], + "periods": { + "instance": 720, + "node": 600 + }, + "thresholds": { + "cpu_util": 0.2, + "memory.resident": 0.2 + } + }, + "auto_trigger": false, + "uuid": "65a5da84-5819-4aea-8278-a28d2b489028", + "goal_name": "workload_balancing", + "scope": [], + "created_at": "2018-04-06T07:27:27.820460+00:00", + "deleted_at": null, + "state": "CANCELLED", + "audit_type": "CONTINUOUS", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audits/65a5da84-5819-4aea-8278-a28d2b489028" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audits/65a5da84-5819-4aea-8278-a28d2b489028" + } + ], + "strategy_name": "workload_stabilization", + "next_run_time": "2018-04-06T11:56:00", + "updated_at": "2018-04-06T11:54:01.266447+00:00" +} \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-create-request-full.json b/api-ref/source/samples/audittemplate-create-request-full.json new file mode 100644 index 000000000..8fb1a7b10 --- /dev/null +++ b/api-ref/source/samples/audittemplate-create-request-full.json @@ -0,0 +1,7 @@ +{ + "name": "at2", + "goal": "dummy", + "strategy": "dummy", + "description": "the second audit template", + "scope": [] +} \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-create-request-minimal.json b/api-ref/source/samples/audittemplate-create-request-minimal.json new file mode 100644 index 000000000..297a102de --- /dev/null +++ b/api-ref/source/samples/audittemplate-create-request-minimal.json @@ -0,0 +1,4 @@ +{ + "name": "at2", + "goal": "dummy" +} \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-create-response.json b/api-ref/source/samples/audittemplate-create-response.json new file mode 100644 index 000000000..d0b54a23d --- /dev/null +++ b/api-ref/source/samples/audittemplate-create-response.json @@ -0,0 +1,23 @@ +{ + "description": null, + "strategy_uuid": null, + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "at3", + "uuid": "b4041d8c-85d7-4224-851d-649fe48b7196", + "goal_name": "dummy", + "scope": [], + "created_at": "2018-04-04T08:38:33.110432+00:00", + "deleted_at": null, + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audit_templates/b4041d8c-85d7-4224-851d-649fe48b7196" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audit_templates/b4041d8c-85d7-4224-851d-649fe48b7196" + } + ], + "strategy_name": null, + "updated_at": null +} \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-list-detailed-response.json b/api-ref/source/samples/audittemplate-list-detailed-response.json new file mode 100644 index 000000000..0d296ce8d --- /dev/null +++ b/api-ref/source/samples/audittemplate-list-detailed-response.json @@ -0,0 +1,23 @@ +{ + "audit_templates":[ + { + "strategy_uuid": null, + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "at3", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audit_templates/b4041d8c-85d7-4224-851d-649fe48b7196" + }, + { + "rel": "bookmark", "href": + "http://controller:9322/audit_templates/b4041d8c-85d7-4224-851d-649fe48b7196" + } + ], + "strategy_name": null, + "uuid": "b4041d8c-85d7-4224-851d-649fe48b7196", + "goal_name": "dummy", "scope": [], + "description": null + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-list-response.json b/api-ref/source/samples/audittemplate-list-response.json new file mode 100644 index 000000000..dd81b1f84 --- /dev/null +++ b/api-ref/source/samples/audittemplate-list-response.json @@ -0,0 +1,22 @@ +{ + "audit_templates":[ + { + "strategy_uuid": null, + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "at3", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audit_templates/b4041d8c-85d7-4224-851d-649fe48b7196" + }, + { + "rel": "bookmark", "href": + "http://controller:9322/audit_templates/b4041d8c-85d7-4224-851d-649fe48b7196" + } + ], + "strategy_name": null, + "uuid": "b4041d8c-85d7-4224-851d-649fe48b7196", + "goal_name": "dummy", "scope": [] + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-show-response.json b/api-ref/source/samples/audittemplate-show-response.json new file mode 100644 index 000000000..14ec81ba5 --- /dev/null +++ b/api-ref/source/samples/audittemplate-show-response.json @@ -0,0 +1,23 @@ +{ + "description": "test 1", + "strategy_uuid": null, + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "at1", + "uuid": "0d100c27-14af-4962-86fb-f6079287c9c6", + "goal_name": "dummy", + "scope": [], + "created_at": "2018-04-04T07:48:36.175472+00:00", + "deleted_at": null, + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audit_templates/0d100c27-14af-4962-86fb-f6079287c9c6" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audit_templates/0d100c27-14af-4962-86fb-f6079287c9c6" + } + ], + "strategy_name": null, + "updated_at": "2018-04-05T07:57:55.803650+00:00" +} \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-update-request.json b/api-ref/source/samples/audittemplate-update-request.json new file mode 100644 index 000000000..3df8e0570 --- /dev/null +++ b/api-ref/source/samples/audittemplate-update-request.json @@ -0,0 +1,7 @@ +[ + { + "op": "replace", + "value": "PENDING", + "path": "/state" + } +] \ No newline at end of file diff --git a/api-ref/source/samples/audittemplate-update-response.json b/api-ref/source/samples/audittemplate-update-response.json new file mode 100644 index 000000000..85eca5387 --- /dev/null +++ b/api-ref/source/samples/audittemplate-update-response.json @@ -0,0 +1,23 @@ +{ + "description": "test 1", + "strategy_uuid": null, + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "at11", + "uuid": "0d100c27-14af-4962-86fb-f6079287c9c6", + "goal_name": "dummy", + "scope": [], + "created_at": "2018-04-04T07:48:36.175472+00:00", + "deleted_at": null, + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/audit_templates/0d100c27-14af-4962-86fb-f6079287c9c6" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/audit_templates/0d100c27-14af-4962-86fb-f6079287c9c6" + } + ], + "strategy_name": null, + "updated_at": "2018-04-05T07:57:42.139127+00:00" +} \ No newline at end of file diff --git a/api-ref/source/samples/goal-list-response.json b/api-ref/source/samples/goal-list-response.json new file mode 100644 index 000000000..e2afcc55d --- /dev/null +++ b/api-ref/source/samples/goal-list-response.json @@ -0,0 +1,55 @@ +{ + "goals": [ + { + "efficacy_specification": [], + "uuid": "e1a5a45b-f251-47cf-9c5f-fa1e66e1286a", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/goals/e1a5a45b-f251-47cf-9c5f-fa1e66e1286a" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/goals/e1a5a45b-f251-47cf-9c5f-fa1e66e1286a" + } + ], + "name": "workload_balancing", + "display_name": "Workload Balancing" + }, + { + "efficacy_specification": [ + { + "description": "The total number of enabled compute nodes.", + "schema": "Range(min=0, max=None, min_included=True, max_included=True, msg=None)", + "name": "compute_nodes_count", + "unit": null + }, + { + "description": "The number of compute nodes to be released.", + "schema": "Range(min=0, max=None, min_included=True, max_included=True, msg=None)", + "name": "released_compute_nodes_count", + "unit": null + }, + { + "description": "The number of VM migrations to be performed.", + "schema": "Range(min=0, max=None, min_included=True, max_included=True, msg=None)", + "name": "instance_migrations_count", + "unit": null + } + ], + "uuid": "cb9afa5e-aec7-4a8c-9261-c15c33f2262b", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/goals/cb9afa5e-aec7-4a8c-9261-c15c33f2262b" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/goals/cb9afa5e-aec7-4a8c-9261-c15c33f2262b" + } + ], + "name": "server_consolidation", + "display_name": "Server Consolidation" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/goal-show-response.json b/api-ref/source/samples/goal-show-response.json new file mode 100644 index 000000000..bec80867d --- /dev/null +++ b/api-ref/source/samples/goal-show-response.json @@ -0,0 +1,19 @@ +{ + "efficacy_specification": [], + "name": "saving_energy", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/goals/6f52889a-9dd4-4dbb-8e70-39b56c4836cc" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/goals/6f52889a-9dd4-4dbb-8e70-39b56c4836cc" + } + ], + "uuid": "6f52889a-9dd4-4dbb-8e70-39b56c4836cc", + "updated_at": null, + "display_name": "Saving Energy", + "created_at": "2018-03-26T11:55:24.365584+00:00", + "deleted_at": null +} \ No newline at end of file diff --git a/api-ref/source/samples/scoring_engine-list-detailed-response.json b/api-ref/source/samples/scoring_engine-list-detailed-response.json new file mode 100644 index 000000000..ea9203b4a --- /dev/null +++ b/api-ref/source/samples/scoring_engine-list-detailed-response.json @@ -0,0 +1,20 @@ +{ + "scoring_engines": [ + { + "description": "Dummy Scorer calculating the average value", + "uuid": "5a44f007-55b1-423c-809f-6a274a9bd93b", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/scoring_engines/5a44f007-55b1-423c-809f-6a274a9bd93b" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/scoring_engines/5a44f007-55b1-423c-809f-6a274a9bd93b" + } + ], + "name": "dummy_avg_scorer", + "metainfo": "" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/scoring_engine-list-response.json b/api-ref/source/samples/scoring_engine-list-response.json new file mode 100644 index 000000000..d5d651d0b --- /dev/null +++ b/api-ref/source/samples/scoring_engine-list-response.json @@ -0,0 +1,19 @@ +{ + "scoring_engines": [ + { + "description": "Dummy Scorer calculating the average value", + "uuid": "5a44f007-55b1-423c-809f-6a274a9bd93b", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/scoring_engines/5a44f007-55b1-423c-809f-6a274a9bd93b" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/scoring_engines/5a44f007-55b1-423c-809f-6a274a9bd93b" + } + ], + "name": "dummy_avg_scorer" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/scoring_engine-show-response.json b/api-ref/source/samples/scoring_engine-show-response.json new file mode 100644 index 000000000..a0627d6df --- /dev/null +++ b/api-ref/source/samples/scoring_engine-show-response.json @@ -0,0 +1,16 @@ +{ + "description": "Dummy Scorer calculating the maximum value", + "uuid": "1ac42282-4e77-473e-898b-62ea007f1deb", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/scoring_engines/1ac42282-4e77-473e-898b-62ea007f1deb" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/scoring_engines/1ac42282-4e77-473e-898b-62ea007f1deb" + } + ], + "name": "dummy_max_scorer", + "metainfo": "" +} \ No newline at end of file diff --git a/api-ref/source/samples/service-list-detailed-response.json b/api-ref/source/samples/service-list-detailed-response.json new file mode 100644 index 000000000..b6b21564c --- /dev/null +++ b/api-ref/source/samples/service-list-detailed-response.json @@ -0,0 +1,24 @@ +{ + "services": [ + { + "status": "ACTIVE", + "name": "watcher-applier", + "host": "controller", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/services/1" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/services/1" + } + ], + "id": 1, + "deleted_at": null, + "updated_at": "2018-04-26T08:52:37.652895+00:00", + "last_seen_up": "2018-04-26T08:52:37.648572", + "created_at": "2018-03-26T11:55:24.075093+00:00" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/service-list-response.json b/api-ref/source/samples/service-list-response.json new file mode 100644 index 000000000..b781c3547 --- /dev/null +++ b/api-ref/source/samples/service-list-response.json @@ -0,0 +1,36 @@ +{ + "services": [ + { + "id": 1, + "status": "ACTIVE", + "name": "watcher-applier", + "host": "controller", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/services/1" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/services/1" + } + ] + }, + { + "id": 2, + "status": "ACTIVE", + "name": "watcher-decision-engine", + "host": "controller", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/services/2" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/services/2" + } + ] + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/service-show-response.json b/api-ref/source/samples/service-show-response.json new file mode 100644 index 000000000..d4621edec --- /dev/null +++ b/api-ref/source/samples/service-show-response.json @@ -0,0 +1,20 @@ +{ + "status": "ACTIVE", + "name": "watcher-applier", + "host": "controller", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/services/1" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/services/1" + } + ], + "id": 1, + "deleted_at": null, + "updated_at": "2018-04-26T09:45:37.653061+00:00", + "last_seen_up": "2018-04-26T09:45:37.649314", + "created_at": "2018-03-26T11:55:24.075093+00:00" +} \ No newline at end of file diff --git a/api-ref/source/samples/strategy-list-detailed-response.json b/api-ref/source/samples/strategy-list-detailed-response.json new file mode 100644 index 000000000..615997f5c --- /dev/null +++ b/api-ref/source/samples/strategy-list-detailed-response.json @@ -0,0 +1,35 @@ +{ + "strategies": [ + { + "goal_uuid": "cb9afa5e-aec7-4a8c-9261-c15c33f2262b", + "name": "vm_workload_consolidation", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/strategies/6382b2d7-259e-487d-88db-78c852ffea54" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/strategies/6382b2d7-259e-487d-88db-78c852ffea54" + } + ], + "parameters_spec": { + "properties": { + "granularity": { + "default": 300, + "type": "number", + "description": "The time between two measures in an aggregated timeseries of a metric." + }, + "period": { + "default": 3600, + "type": "number", + "description": "The time interval in seconds for getting statistic aggregation" + } + } + }, + "uuid": "6382b2d7-259e-487d-88db-78c852ffea54", + "goal_name": "server_consolidation", + "display_name": "VM Workload Consolidation Strategy" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/strategy-list-response.json b/api-ref/source/samples/strategy-list-response.json new file mode 100644 index 000000000..b63ec3c92 --- /dev/null +++ b/api-ref/source/samples/strategy-list-response.json @@ -0,0 +1,21 @@ +{ + "strategies": [ + { + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "dummy", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/strategies/e311727b-b9b3-43ef-a5f7-8bd7ea80df25" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/strategies/e311727b-b9b3-43ef-a5f7-8bd7ea80df25" + } + ], + "uuid": "e311727b-b9b3-43ef-a5f7-8bd7ea80df25", + "goal_name": "dummy", + "display_name": "Dummy strategy" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/strategy-show-response.json b/api-ref/source/samples/strategy-show-response.json new file mode 100644 index 000000000..6d0b8049c --- /dev/null +++ b/api-ref/source/samples/strategy-show-response.json @@ -0,0 +1,33 @@ +{ + "goal_uuid": "4690f8ba-18ff-45c1-99e9-159556d23810", + "name": "dummy", + "links": [ + { + "rel": "self", + "href": "http://controller:9322/v1/strategies/e311727b-b9b3-43ef-a5f7-8bd7ea80df25" + }, + { + "rel": "bookmark", + "href": "http://controller:9322/strategies/e311727b-b9b3-43ef-a5f7-8bd7ea80df25" + } + ], + "parameters_spec": { + "properties": { + "para2": { + "default": "hello", + "type": "string", + "description": "string parameter example" + }, + "para1": { + "maximum": 10.2, + "type": "number", + "minimum": 1.0, + "description": "number parameter example", + "default": 3.2 + } + } + }, + "uuid": "e311727b-b9b3-43ef-a5f7-8bd7ea80df25", + "goal_name": "dummy", + "display_name": "Dummy strategy" +} \ No newline at end of file diff --git a/api-ref/source/samples/strategy-state-response.json b/api-ref/source/samples/strategy-state-response.json new file mode 100644 index 000000000..dbc6ee797 --- /dev/null +++ b/api-ref/source/samples/strategy-state-response.json @@ -0,0 +1,49 @@ +[ + { + "state": "gnocchi: available", + "comment": "", + "mandatory": true, + "type": "Datasource" + }, + { + "state": [ + { + "compute.node.cpu.percent": "available" + }, + { + "cpu_util": "available" + }, + { + "memory.resident": "available" + }, + { + "hardware.memory.used": "available" + } + ], + "comment": "", + "mandatory": false, + "type": "Metrics" + }, + { + "state": [ + { + "compute_model": "available" + }, + { + "storage_model": "not available" + }, + { + "baremetal_model": "not available" + } + ], + "comment": "", + "mandatory": true, + "type": "CDM" + }, + { + "state": "workload_stabilization", + "mandatory": "", + "comment": "", + "type": "Name" + } +] \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-actionplans.inc b/api-ref/source/watcher-api-v1-actionplans.inc new file mode 100644 index 000000000..8a1792dda --- /dev/null +++ b/api-ref/source/watcher-api-v1-actionplans.inc @@ -0,0 +1,209 @@ +.. -*- rst -*- + +============ +Action Plans +============ + +An ``Action Plan`` specifies a flow of ``Actions`` that should be executed +in order to satisfy a given ``Goal``. It also contains an estimated +``global efficacy`` alongside a set of ``efficacy indicators``. + +An ``Action Plan`` is generated by Watcher when an ``Audit`` is successful +which implies that the ``Strategy`` which was used has found a ``Solution`` +to achieve the ``Goal`` of this ``Audit``. + +In the default implementation of Watcher, an action plan is composed of +a graph of linked ``Actions``. Each action may have parent actions, which +should be executed prior to child action. + +Start Action Plan +================= + +.. rest_method:: POST /v1/action_plans/{actionplan_ident}/start + +Starts a created Action Plan resource. + +Normal response codes: 200 + +Error codes: 400,404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - actionplan_ident: actionplan_ident + +Response +-------- + +The list and example below are representative of the response as of API +version 1: + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - state: actionplan_state + - audit_uuid: actionplan_audit_uuid + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - efficacy_indicators: actionplan_efficacy_indicators + - global_efficacy: actionplan_global_efficacy + - links: links + +**Example JSON representation of an Action Plan:** + +.. literalinclude:: samples/actionplan-start-response.json + :language: javascript + +List Action Plan +================ + +.. rest_method:: GET /v1/action_plans + +Returns a list of Action Plan resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audit_uuid: r_audit + - strategy: r_strategy + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - state: actionplan_state + - audit_uuid: actionplan_audit_uuid + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - efficacy_indicators: actionplan_efficacy_indicators + - global_efficacy: actionplan_global_efficacy + - links: links + +**Example JSON representation of an Action Plan:** + +.. literalinclude:: samples/actionplan-list-response.json + :language: javascript + +Show Action Plan +================ + +.. rest_method:: GET /v1/action_plans/{actionplan_ident} + +Shows details for an Action Plan. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - actionplan_ident: actionplan_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - state: actionplan_state + - audit_uuid: actionplan_audit_uuid + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - efficacy_indicators: actionplan_efficacy_indicators + - global_efficacy: actionplan_global_efficacy + - links: links + +**Example JSON representation of an Audit:** + +.. literalinclude:: samples/actionplan-show-response.json + :language: javascript + +Cancel Action Plan +================== + +.. rest_method:: PATCH /v1/action_plans/{actionplan_ident} + +Cancels a created Action Plan resource. + +.. note: + If Action Plan is in ONGOING state, then ``state`` attribute should be + replaced with ``CANCELLING`` value. Otherwise, ``CANCELLED`` is to be + used. + +Normal response codes: 200 + +Error codes: 400,404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - actionplan_ident: actionplan_ident + +**Example Action Plan ONGOING cancelling request:** + +.. literalinclude:: samples/actionplan-cancel-request-cancelling.json + :language: javascript + +**Example Action Plan PENDING cancelling request:** + +.. literalinclude:: samples/actionplan-cancel-request-pending.json + :language: javascript + +Response +-------- + +The list and example below are representative of the response as of API +version 1: + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - state: actionplan_state + - audit_uuid: actionplan_audit_uuid + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - efficacy_indicators: actionplan_efficacy_indicators + - global_efficacy: actionplan_global_efficacy + - links: links + +**Example JSON representation of an Action Plan:** + +.. literalinclude:: samples/actionplan-start-response.json + :language: javascript + +Delete Action Plan +================== + +.. rest_method:: DELETE /v1/action_plans/{actionplan_ident} + +Deletes an Action Plan. Action Plan can be deleted only from SUCCEEDED, RECOMMENDED, FAILED, SUPERSEDED, CANCELLED states. + +Normal response codes: 204 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - actionplan_ident: actionplan_ident \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-actions.inc b/api-ref/source/watcher-api-v1-actions.inc new file mode 100644 index 000000000..504d37466 --- /dev/null +++ b/api-ref/source/watcher-api-v1-actions.inc @@ -0,0 +1,155 @@ +.. -*- rst -*- + +======= +Actions +======= + +An ``Action`` is what enables Watcher to transform the current state of a +``Cluster`` after an ``Audit``. + +An ``Action`` is an atomic task which changes the current state of a target +Managed resource of the OpenStack ``Cluster`` such as: + +- Live migration of an instance from one compute node to another compute + node with Nova +- Changing the power level of a compute node (ACPI level, ...) +- Changing the current state of a compute node (enable or disable) with Nova + +In most cases, an ``Action`` triggers some concrete commands on an existing +OpenStack module (Nova, Neutron, Cinder, Ironic, etc.). + +An ``Action`` has a life-cycle and its current state may be one of the +following: + +- **PENDING** : the ``Action`` has not been executed yet by the + ``Watcher Applier``. +- **ONGOING** : the ``Action`` is currently being processed by the + ``Watcher Applier``. +- **SUCCEEDED** : the ``Action`` has been executed successfully +- **FAILED** : an error occurred while trying to execute the ``Action``. +- **DELETED** : the ``Action`` is still stored in the ``Watcher database`` + but is not returned any more through the Watcher APIs. +- **CANCELLED** : the ``Action`` was in **PENDING** or **ONGOING** state and + was cancelled by the ``Administrator`` + +``Actions`` are created by ``Watcher Planner`` as result of Audit's execution. +``Action`` can't be created, modified or deleted by user. + +List Action +=========== + +.. rest_method:: GET /v1/actions + +Returns a list of Action resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - action_plan_uuid: r_action_plan + - audit_uuid: r_audit + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - action_type: action_type + - state: action_state + - action_plan_uuid: action_action_plan_uuid + - parents: action_parents + - links: links + +**Example JSON representation of an Action:** + +.. literalinclude:: samples/actions-list-response.json + :language: javascript + +List Action Detailed +==================== + +.. rest_method:: GET /v1/actions/detail + +Returns a list of Action resources with complete details. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - action_plan_uuid: r_action_plan + - audit_uuid: r_audit + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - action_type: action_type + - state: action_state + - action_plan_uuid: action_action_plan_uuid + - parents: action_parents + - description: action_description + - input_parameters: action_input_parameters + - links: links + +**Example JSON representation of an Action:** + +.. literalinclude:: samples/actions-list-detailed-response.json + :language: javascript + +Show Action +=========== + +.. rest_method:: GET /v1/actions/{action_ident} + +Shows details for an Action. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - action_ident: action_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - action_type: action_type + - state: action_state + - action_plan_uuid: action_action_plan_uuid + - parents: action_parents + - description: action_description + - input_parameters: action_input_parameters + - links: links + +**Example JSON representation of an Action:** + +.. literalinclude:: samples/actions-show-response.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-audits.inc b/api-ref/source/watcher-api-v1-audits.inc new file mode 100644 index 000000000..f06181d1f --- /dev/null +++ b/api-ref/source/watcher-api-v1-audits.inc @@ -0,0 +1,349 @@ +.. -*- rst -*- + +====== +Audits +====== + +There are creating, listing, updating and deleting methods of Watcher Audit +resources which are implemented via the ``/v1/audits`` resource. + +In the Watcher system, an ``Audit`` is a request for optimizing a ``Cluster``. + +The optimization is done in order to satisfy one ``Goal`` on a given +``Cluster``. + +For each ``Audit``, the Watcher system generates an ``Action Plan``. + +Create Audit +============ + +.. rest_method:: POST /v1/audits + +Creates a new Audit resource. + +Mandatory attribute to be supplied: ``audit_type``. + +``Audit`` can be created either based on existed ``Audit Template`` or by +itself. In the first case, there also should be supplied +``audit_template_uuid``. If ``Audit`` is created without ``Audit Template``, +``goal`` should be provided. + +.. warning:: + **Only ``audit_template_uuid`` can be used to create audit so far.** + It should be fixed during the ``Rocky`` cycle. + +Normal response codes: 201 + +Error codes: 400,404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audit_template_uuid: audittemplate_name + - audit_type: audit_type + - name: audit_name + - goal: audit_goal + - strategy: audit_strategy + - parameters: audit_parameters + - interval: audit_interval + - scope: audittemplate_scope + - auto_trigger: audit_autotrigger + +**Example ONESHOT Audit creation request:** + +.. literalinclude:: samples/audit-create-request-oneshot.json + :language: javascript + +**Example CONTINUOUS Audit creation request with a specified strategy:** + +.. literalinclude:: samples/audit-create-request-continuous.json + :language: javascript + +Response +-------- + +The list and example below are representative of the response as of API +version 1: + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audit_name + - audit_type: audit_type + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - interval: audit_interval + - next_run_time: audit_next_run_time + - parameters: audit_parameters + - auto_trigger: audit_autotrigger + - state: audit_state + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit:** + +.. literalinclude:: samples/audit-create-response.json + :language: javascript + +List Audit +========== + +.. rest_method:: GET /v1/audits + +Returns a list of Audit resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - goal: r_goal + - strategy: r_strategy + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audit_name + - audit_type: audit_type + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - interval: audit_interval + - next_run_time: audit_next_run_time + - auto_trigger: audit_autotrigger + - state: audit_state + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit:** + +.. literalinclude:: samples/audit-list-response.json + :language: javascript + +List Audit Detailed +=================== + +.. rest_method:: GET /v1/audits/detail + +Returns a list of Audit resources with complete details. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - goal: r_goal + - strategy: r_strategy + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audit_name + - audit_type: audit_type + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - interval: audit_interval + - next_run_time: audit_next_run_time + - parameters: audit_parameters + - auto_trigger: audit_autotrigger + - state: audit_state + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit:** + +.. literalinclude:: samples/audit-list-detailed-response.json + :language: javascript + +Show Audit +========== + +.. rest_method:: GET /v1/audits/{audit_ident} + +Shows details for an Audit. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audit_ident: audit_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audit_name + - audit_type: audit_type + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - interval: audit_interval + - next_run_time: audit_next_run_time + - parameters: audit_parameters + - auto_trigger: audit_autotrigger + - state: audit_state + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit:** + +.. literalinclude:: samples/audit-show-response.json + :language: javascript + +Cancel Audit +============ + +.. rest_method:: PATCH /v1/audits/{audit_ident} + +Cancels an ONGOING Audit resource. + +Normal response codes: 200 + +Error codes: 400,404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audit_ident: audit_ident + +**Example Audit cancelling request:** + +.. literalinclude:: samples/audit-cancel-request.json + :language: javascript + +Response +-------- + +The list and example below are representative of the response as of API +version 1: + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audit_name + - audit_type: audit_type + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - interval: audit_interval + - next_run_time: audit_next_run_time + - parameters: audit_parameters + - auto_trigger: audit_autotrigger + - state: audit_state + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit:** + +.. literalinclude:: samples/audit-cancel-response.json + :language: javascript + +Update Audit +============ + +.. rest_method:: PATCH /v1/audits/{audit_ident} + +Updates an Audit with the given information. + +.. note: + ``audit_type`` shouldn't be changed by PATCH method. + +Normal response codes: 200 + +Error codes: 400,404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audit_ident: audit_ident + +**Example PATCH document updating Audit:** + +.. literalinclude:: samples/audit-update-request.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audit_name + - audit_type: audit_type + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - interval: audit_interval + - next_run_time: audit_next_run_time + - parameters: audit_parameters + - auto_trigger: audit_autotrigger + - state: audit_state + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit:** + +.. literalinclude:: samples/audit-update-response.json + :language: javascript + +Delete Audit +============ + +.. rest_method:: DELETE /v1/audits/{audit_ident} + +Deletes an Audit. Audit can be deleted only from FAILED, SUCCEEDED, CANCELLED, +SUSPENDED states. + +Normal response codes: 204 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audit_ident: audit_ident \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-audittemplates.inc b/api-ref/source/watcher-api-v1-audittemplates.inc new file mode 100644 index 000000000..f441b1111 --- /dev/null +++ b/api-ref/source/watcher-api-v1-audittemplates.inc @@ -0,0 +1,257 @@ +.. -*- rst -*- + +=============== +Audit Templates +=============== + +There are creating, listing, updating and deleting methods of Watcher Audit +Template resources which are implemented via the ``/v1/audit_templates`` +resource. + +An Audit may be launched several times with the same settings +(Goal, thresholds, ...). Therefore it makes sense to save those settings in +some sort of Audit preset object, which is known as an Audit Template. + +An Audit Template contains at least the Goal of the Audit. + +Create Audit Template +===================== + +.. rest_method:: POST /v1/audit_templates + +Creates a new Audit Template resource. + +It requires ``name`` and ``goal`` attributes to be supplied in the request +body. + +Normal response codes: 201 + +Error codes: 400,404,409 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - name: audittemplate_name + - goal: audittemplate_goal + - strategy: audittemplate_strategy + - description: audittemplate_description + - scope: audittemplate_scope + +**Example Audit Template creation request without a specified strategy:** + +.. literalinclude:: samples/audittemplate-create-request-minimal.json + :language: javascript + +**Example Audit Template creation request with a specified strategy:** + +.. literalinclude:: samples/audittemplate-create-request-full.json + :language: javascript + +Response +-------- + +The list and example below are representative of the response as of API +version 1: + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audittemplate_name + - description: audittemplate_description + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit Template:** + +.. literalinclude:: samples/audittemplate-create-response.json + :language: javascript + +List Audit Template +=================== + +.. rest_method:: GET /v1/audit_templates + +Returns a list of Audit Template resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - goal: r_goal + - strategy: r_strategy + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audittemplate_name + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - scope: audittemplate_scope + - links: links + +**Example JSON representation of an Audit Template:** + +.. literalinclude:: samples/audittemplate-list-response.json + :language: javascript + +List Audit Template Detailed +============================ + +.. rest_method:: GET /v1/audit_templates/detail + +Returns a list of Audit Template resources with complete details. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - goal: r_goal + - strategy: r_strategy + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audittemplate_name + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - scope: audittemplate_scope + - links: links + - description: audittemplate_description + +**Example JSON representation of an Audit Template:** + +.. literalinclude:: samples/audittemplate-list-detailed-response.json + :language: javascript + +Show Audit Template +=================== + +.. rest_method:: GET /v1/audit_templates/{audittemplate_ident} + +Shows details for an Audit Template. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audittemplate_ident: audittemplate_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audittemplate_name + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - scope: audittemplate_scope + - links: links + - description: audittemplate_description + +**Example JSON representation of an Audit Template:** + +.. literalinclude:: samples/audittemplate-show-response.json + :language: javascript + +Update Audit Template +===================== + +.. rest_method:: PATCH /v1/audit_templates/{audittemplate_ident} + +Updates an Audit Template with the given information. + +Normal response codes: 200 + +Error codes: 400,404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audittemplate_ident: audittemplate_ident + +**Example PATCH document updating Audit Template:** + +.. literalinclude:: samples/audittemplate-update-request.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: audittemplate_name + - strategy_uuid: strategy_uuid + - strategy_name: strategy_name + - goal_uuid: goal_uuid + - goal_name: goal_name + - scope: audittemplate_scope + - links: links + - description: audittemplate_description + +**Example JSON representation of an Audit Template:** + +.. literalinclude:: samples/audittemplate-update-response.json + :language: javascript + +Delete Audit Template +===================== + +.. rest_method:: DELETE /v1/audit_templates/{audittemplate_ident} + +Deletes an Audit Template. + +Normal response codes: 204 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - audittemplate_ident: audittemplate_ident \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-goals.inc b/api-ref/source/watcher-api-v1-goals.inc new file mode 100644 index 000000000..2d48c0778 --- /dev/null +++ b/api-ref/source/watcher-api-v1-goals.inc @@ -0,0 +1,126 @@ +.. -*- rst -*- + +===== +Goals +===== + +A ``Goal`` is a human readable, observable and measurable end result having +one objective to be achieved. + +Here are some examples of ``Goals``: + +- minimize the energy consumption +- minimize the number of compute nodes (consolidation) +- balance the workload among compute nodes +- minimize the license cost (some softwares have a licensing model which is + based on the number of sockets or cores where the software is deployed) +- find the most appropriate moment for a planned maintenance on a + given group of host (which may be an entire availability zone): + power supply replacement, cooling system replacement, hardware + modification, ... + +List Goal +========= + +.. rest_method:: GET /v1/goals + +Returns a list of Goal resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - efficacy_specification: goal_efficacy_specification + - name: goal_name + - display_name: goal_display_name + - links: links + +**Example JSON representation of a Goal:** + +.. literalinclude:: samples/goal-list-response.json + :language: javascript + +List Goal Detailed +================== + +.. rest_method:: GET /v1/goals/detail + +Returns a list of Goal resources with complete details. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - efficacy_specification: goal_efficacy_specification + - name: goal_name + - display_name: goal_display_name + - links: links + +**Example JSON representation of a Goal:** + +.. literalinclude:: samples/goal-list-response.json + :language: javascript + +Show Goal +========= + +.. rest_method:: GET /v1/goals/{goal_ident} + +Shows details for an Goal. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - goal_ident: goal_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - efficacy_specification: goal_efficacy_specification + - name: goal_name + - display_name: goal_display_name + - links: links + +**Example JSON representation of a Goal:** + +.. literalinclude:: samples/goal-show-response.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-scoring_engines.inc b/api-ref/source/watcher-api-v1-scoring_engines.inc new file mode 100644 index 000000000..24ec0d620 --- /dev/null +++ b/api-ref/source/watcher-api-v1-scoring_engines.inc @@ -0,0 +1,120 @@ +.. -*- rst -*- + +=============== +Scoring Engines +=============== + +A ``Scoring Engine`` is an executable that has a well-defined input, a +well-defined output, and performs a purely mathematical task. That is, +the calculation does not depend on the environment in which it is running - it +would produce the same result anywhere. + +Because there might be multiple algorithms used to build a particular data +model (and therefore a scoring engine), the usage of scoring engine might +vary. A metainfo field is supposed to contain any information which might +be needed by the user of a given scoring engine. + +List Scoring Engine +=================== + +.. rest_method:: GET /v1/scoring_engines + +Returns a list of Scoring Engine resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: scoring_engine_name + - description: scoring_engine_description + - links: links + +**Example JSON representation of a Scoring Engine:** + +.. literalinclude:: samples/scoring_engine-list-response.json + :language: javascript + +List Scoring Engine Detailed +============================ + +.. rest_method:: GET /v1/scoring_engines/detail + +Returns a list of Scoring Engine resources with complete details. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: scoring_engine_name + - description: scoring_engine_description + - metainfo: scoring_engine_metainfo + - links: links + +**Example JSON representation of a Scoring Engine:** + +.. literalinclude:: samples/scoring_engine-list-detailed-response.json + :language: javascript + +Show Scoring Engine +=================== + +.. rest_method:: GET /v1/scoring_engines/{scoring_engine_ident} + +Shows details for a Scoring Engine resource. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - scoring_engine_ident: scoring_engine_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: scoring_engine_name + - description: scoring_engine_description + - metainfo: scoring_engine_metainfo + - links: links + +**Example JSON representation of a Scoring Engine:** + +.. literalinclude:: samples/scoring_engine-show-response.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-services.inc b/api-ref/source/watcher-api-v1-services.inc new file mode 100644 index 000000000..adf5a5b19 --- /dev/null +++ b/api-ref/source/watcher-api-v1-services.inc @@ -0,0 +1,116 @@ +.. -*- rst -*- + +======== +Services +======== + +This resource represents Watcher services, their states and hosts they are +placed on. + +List Service +============ + +.. rest_method:: GET /v1/services + +Returns a list of Service resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - id: service_id + - name: service_name + - host: service_host + - status: service_status + - links: links + +**Example JSON representation of a Service:** + +.. literalinclude:: samples/service-list-response.json + :language: javascript + +List Service Detailed +===================== + +.. rest_method:: GET /v1/services/detail + +Returns a list of Service resources with complete details. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - id: service_id + - name: service_name + - host: service_host + - status: service_status + - last_seen_up: service_last_seen_up + - links: links + +**Example JSON representation of a Service:** + +.. literalinclude:: samples/service-list-detailed-response.json + :language: javascript + +Show Service +============ + +.. rest_method:: GET /v1/services/{service_ident} + +Shows details for a Service resource. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - service_ident: service_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - id: service_id + - name: service_name + - host: service_host + - status: service_status + - last_seen_up: service_last_seen_up + - links: links + +**Example JSON representation of a Service:** + +.. literalinclude:: samples/service-show-response.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/watcher-api-v1-strategies.inc b/api-ref/source/watcher-api-v1-strategies.inc new file mode 100644 index 000000000..b94f56700 --- /dev/null +++ b/api-ref/source/watcher-api-v1-strategies.inc @@ -0,0 +1,164 @@ +.. -*- rst -*- + +========== +Strategies +========== + +A ``Strategy`` is an algorithm implementation which is able to find a +``Solution`` for a given ``Goal``. To get more information about strategies +that are shipped along with Watcher, visit `strategies page`_. + +There may be several potential strategies which are able to achieve the same +``Goal``. This is why it is possible to configure which specific ``Strategy`` +should be used for each goal. + +Some strategies may provide better optimization results but may take more time +to find an optimal ``Solution``. + +.. _`strategies page`: https://docs.openstack.org/watcher/latest/strategies/index.html + +List Strategy +============= + +.. rest_method:: GET /v1/strategies + +Returns a list of Strategy resources. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - goal: r_goal + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: strategy_name + - display_name: strategy_display_name + - goal_name: goal_name + - goal_uuid: goal_uuid + - links: links + +**Example JSON representation of a Strategy:** + +.. literalinclude:: samples/strategy-list-response.json + :language: javascript + +List Strategy Detailed +====================== + +.. rest_method:: GET /v1/strategies/detail + +Returns a list of Strategy resources with complete details. + +Normal response codes: 200 + +Error codes: 400,401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - goal: r_goal + - limit: limit + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: strategy_name + - display_name: strategy_display_name + - parameters_spec: strategy_parameters_spec + - goal_name: goal_name + - goal_uuid: goal_uuid + - links: links + +**Example JSON representation of a Strategy:** + +.. literalinclude:: samples/strategy-list-detailed-response.json + :language: javascript + +Show Strategy +============= + +.. rest_method:: GET /v1/strategies/{strategy_ident} + +Shows details for a Strategy resource. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - strategy_ident: strategy_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: uuid + - name: strategy_name + - display_name: strategy_display_name + - parameters_spec: strategy_parameters_spec + - goal_name: goal_name + - goal_uuid: goal_uuid + - links: links + +**Example JSON representation of a Strategy:** + +.. literalinclude:: samples/strategy-show-response.json + :language: javascript + +Show Strategy State +=================== + +.. rest_method:: GET /v1/strategies/{strategy_ident}/state + +Retrieve an information about strategy requirements. + +Normal response codes: 200 + +Error codes: 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - strategy_ident: strategy_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - state: strategy_check_state + - comment: strategy_check_comment + - mandatory: strategy_check_mandatory + - type: strategy_check_type + +**Example JSON representation of a Strategy:** + +.. literalinclude:: samples/strategy-state-response.json + :language: javascript \ No newline at end of file diff --git a/doc/source/admin/policy.rst b/doc/source/admin/policy.rst index 458c81206..d32a275b8 100644 --- a/doc/source/admin/policy.rst +++ b/doc/source/admin/policy.rst @@ -131,6 +131,16 @@ The actions that may have a rule enforced on them are: * ``GET /v1/actions/`` +* ``service:get_all``, ``service:detail`` - List available Watcher services + + * ``GET /v1/services`` + * ``GET /v1/services/detail`` + +* ``service:get`` - Retrieve a specific Watcher service entity + + * ``GET /v1/services/`` + + To limit an action to a particular role or roles, you list the roles like so :: diff --git a/doc/source/configuration/configuring.rst b/doc/source/configuration/configuring.rst index 15d74fbef..6440340cd 100644 --- a/doc/source/configuration/configuring.rst +++ b/doc/source/configuration/configuring.rst @@ -19,11 +19,17 @@ optimize your IaaS platform. The Watcher service may, depending upon configuration, interact with several other OpenStack services. This includes: - the OpenStack Identity service (`keystone`_) for request authentication and - to locate other OpenStack services -- the OpenStack Telemetry service (`ceilometer`_) for consuming the resources - metrics + to locate other OpenStack services. +- the OpenStack Telemetry service (`ceilometer`_) for collecting the resources + metrics. +- the time series database (`gnocchi`_) for consuming the resources + metrics. - the OpenStack Compute service (`nova`_) works with the Watcher service and acts as a user-facing API for instance migration. +- the OpenStack Bare Metal service (`ironic`_) works with the Watcher service + and allows to manage power state of nodes. +- the OpenStack Block Storage service (`cinder`_) works with the Watcher + service and as an API for volume node migration. The Watcher service includes the following components: @@ -53,6 +59,9 @@ additional functionality: .. _`keystone`: https://github.com/openstack/keystone .. _`ceilometer`: https://github.com/openstack/ceilometer .. _`nova`: https://github.com/openstack/nova +.. _`gnocchi`: https://github.com/gnocchixyz/gnocchi +.. _`ironic`: https://github.com/openstack/ironic +.. _`cinder`: https://github.com/openstack/cinder .. _`python-watcherclient`: https://github.com/openstack/python-watcherclient .. _`watcher-dashboard`: https://github.com/openstack/watcher-dashboard .. _`watcher metering`: https://github.com/b-com/watcher-metering diff --git a/doc/source/contributor/environment.rst b/doc/source/contributor/environment.rst index c84579ba0..bd6508bc9 100644 --- a/doc/source/contributor/environment.rst +++ b/doc/source/contributor/environment.rst @@ -193,6 +193,8 @@ still need to configure the following sections: :ref:`Identity service ` i.e. Keystone - The ``[watcher_messaging]`` section to configure the OpenStack AMQP-based message bus +- The ``watcher_clients_auth`` section to configure Keystone client to access + related OpenStack projects So if you need some more details on how to configure one or more of these sections, please do have a look at :doc:`../configuration/configuring` before diff --git a/doc/source/index.rst b/doc/source/index.rst index f4ab80a14..2805c3eab 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -54,22 +54,6 @@ Getting Started contributor/index -API References --------------- - -.. toctree:: - :maxdepth: 1 - - api/index - -Plugins -------- - -.. toctree:: - :maxdepth: 1 - - contributor/plugin/index - Installation ============ .. toctree:: @@ -77,14 +61,6 @@ Installation install/index -Watcher Configuration Options -============================= - -.. toctree:: - :maxdepth: 2 - - configuration/index - Admin Guide =========== @@ -101,6 +77,30 @@ User Guide user/index +API References +-------------- + +.. toctree:: + :maxdepth: 1 + + api/index + +Plugins +------- + +.. toctree:: + :maxdepth: 1 + + contributor/plugin/index + +Watcher Configuration Options +============================= + +.. toctree:: + :maxdepth: 2 + + configuration/index + Watcher Manual Pages ==================== diff --git a/tox.ini b/tox.ini index ff81da8c5..f006ab7c1 100644 --- a/tox.ini +++ b/tox.ini @@ -38,6 +38,14 @@ commands = doc8 doc/source/ CONTRIBUTING.rst HACKING.rst README.rst python setup.py build_sphinx +[testenv:api-ref] +# This environment is called from CI scripts to test and publish +# the API Ref to developer.openstack.org. +whitelist_externals = bash +commands = + bash -c 'rm -rf api-ref/build' + sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html + [testenv:debug] commands = oslo_debug_helper -t watcher/tests {posargs} diff --git a/watcher/api/controllers/v1/scoring_engine.py b/watcher/api/controllers/v1/scoring_engine.py index d1b98fefb..4cf6a98b2 100644 --- a/watcher/api/controllers/v1/scoring_engine.py +++ b/watcher/api/controllers/v1/scoring_engine.py @@ -83,7 +83,7 @@ class ScoringEngine(base.APIBase): def _convert_with_links(se, url, expand=True): if not expand: se.unset_fields_except( - ['uuid', 'name', 'description', 'metainfo']) + ['uuid', 'name', 'description']) se.links = [link.Link.make_link('self', url, 'scoring_engines', se.uuid), diff --git a/watcher/api/controllers/v1/strategy.py b/watcher/api/controllers/v1/strategy.py index 32f853363..06a2a9347 100644 --- a/watcher/api/controllers/v1/strategy.py +++ b/watcher/api/controllers/v1/strategy.py @@ -292,7 +292,7 @@ class StrategiesController(rest.RestController): @wsme_pecan.wsexpose(wtypes.text, wtypes.text) def state(self, strategy): - """Retrieve a inforamation about strategy requirements. + """Retrieve an information about strategy requirements. :param strategy: name of the strategy. """ diff --git a/watcher/tests/api/v1/test_scoring_engines.py b/watcher/tests/api/v1/test_scoring_engines.py index bbf7cb706..1f3d181f5 100644 --- a/watcher/tests/api/v1/test_scoring_engines.py +++ b/watcher/tests/api/v1/test_scoring_engines.py @@ -21,7 +21,7 @@ from watcher.tests.objects import utils as obj_utils class TestListScoringEngine(api_base.FunctionalTest): def _assert_scoring_engine_fields(self, scoring_engine): - scoring_engine_fields = ['uuid', 'name', 'description', 'metainfo'] + scoring_engine_fields = ['uuid', 'name', 'description'] for field in scoring_engine_fields: self.assertIn(field, scoring_engine)