Watcher API

API versions

In order to bring new features to users over time, the Watcher API supports versioning. There are two kinds of versions in Watcher.

  • ‘’major versions’’, which have dedicated URLs.

  • ‘’microversions’’, which can be requested using the OpenStack-API-Version header.

Note

The maximum microversion depends on release. Please reference: API Microversion History for API microversion history details.

The Version API resource works differently from other API resources as they do not require authentication.

If Watcher receives a request with unsupported version, it responds with a 406 Not Acceptable, along with the -Min- and -Max- headers that it can support.

GET
/

List API versions

This fetches all the information about all known major API versions in the deployment. Links to more specific information will be provided for each major API version, as well as information about supported min and max microversions.

Normal response codes: 200

Request

Response Example

Name

In

Type

Description

description

body

string

Descriptive text about the Watcher service.

versions

body

array

Array of information about currently supported versions.

version

body

string

Versioning of this API response, eg. “1.1”.

id

body

string

Major API version, eg, “v1”

links

body

array

A list of relative links. Includes the self and bookmark links.

min_version

header

string

Minimum API microversion supported by this endpoint, eg. “1.0”

max_version

header

string

Maximum API microversion supported by this endpoint, eg. “1.1”

{
  "default_version": {
    "id": "v1",
    "links": [
      {
        "href": "http://controller:9322/v1/",
        "rel": "self"
      }
    ],
    "min_version": "1.0",
    "status": "CURRENT",
    "max_version": "1.1"
  },
  "description": "Watcher is an OpenStack project which aims to improve physical resources usage through better VM placement.",
  "name": "OpenStack Watcher API",
  "versions": [
    {
      "id": "v1",
      "links": [
        {
          "href": "http://controller:9322/v1/",
          "rel": "self"
        }
      ],
      "min_version": "1.0",
      "status": "CURRENT",
      "max_version": "1.1"
    }
  ]
}
GET
/v1/

Show v1 API

Show all the resources within the Watcher v1 API.

Normal response codes: 200

Request

Response Example

Name

In

Type

Description

id

body

string

Major API version, eg, “v1”

links

body

array

A list of relative links. Includes the self and bookmark links.

OpenStack-API-Version

header

string

Specific API microversion used to generate this response.

OpenStack-API-Minimum-Version

header

string

Minimum API microversion supported by this endpoint, eg. “1.0”

OpenStack-API-Maximum-Version

header

string

Maximum API microversion supported by this endpoint, eg. “1.1”

{
  "scoring_engines": [
    {
      "href": "http://controller:9322/v1/scoring_engines/",
      "rel": "self"
    },
    {
      "href": "http://controller:9322/scoring_engines/",
      "rel": "bookmark"
    }
  ],
  "media_types": [
    {
      "base": "application/json",
      "type": "application/vnd.openstack.watcher.v1+json"
    }
  ],
  "links": [
    {
      "href": "http://controller:9322/v1/",
      "rel": "self"
    },
    {
      "href": "http://docs.openstack.org/developer/watcher/dev/api-spec-v1.html",
      "type": "text/html",
      "rel": "describedby"
    }
  ],
  "actions": [
    {
      "href": "http://controller:9322/v1/actions/",
      "rel": "self"
    },
    {
      "href": "http://controller:9322/actions/",
      "rel": "bookmark"
    }
  ],
  "audit_templates": [
    {
      "href": "http://controller:9322/v1/audit_templates/",
      "rel": "self"
    },
    {
      "href": "http://controller:9322/audit_templates/",
      "rel": "bookmark"
    }
  ],
  "action_plans": [
    {
      "href": "http://controller:9322/v1/action_plans/",
      "rel": "self"
    },
    {
      "href": "http://controller:9322/action_plans/",
      "rel": "bookmark"
    }
  ],
  "services": [
    {
      "href": "http://controller:9322/v1/services/",
      "rel": "self"
    },
    {
      "href": "http://controller:9322/services/",
      "rel": "bookmark"
    }
  ],
  "audits": [
    {
      "href": "http://controller:9322/v1/audits/",
      "rel": "self"
    },
    {
      "href": "http://controller:9322/audits/",
      "rel": "bookmark"
    }
  ],
  "id": "v1"
}

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.

POST
/v1/audit_templates

Create Audit Template

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

Name

In

Type

Description

name

body

string

The name of the Audit template.

goal

body

string

The UUID or name of the Goal.

strategy (Optional)

body

string

The UUID or name of the Strategy.

description (Optional)

body

string

Short description of the Audit Template.

scope (Optional)

body

JSON

Audit Scope.

Example Audit Template creation request without a specified strategy:

{
    "name": "at2",
    "goal": "dummy"
}

Example Audit Template creation request with a specified strategy:

{
    "name": "at2",
    "goal": "dummy",
    "strategy": "dummy",
    "description": "the second audit template",
    "scope": []
}

Response

The list and example below are representative of the response as of API version 1:

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the Audit template.

description (Optional)

body

string

Short description of the Audit Template.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of an Audit Template:

{
    "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
}
GET
/v1/audit_templates

List Audit Template

Returns a list of Audit Template resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

goal (Optional)

query

string

The UUID or name of the Goal.

strategy (Optional)

query

string

The UUID or name of the Strategy.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the Audit template.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of an Audit Template:

{
    "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": []
        }
    ]
}
GET
/v1/audit_templates/detail

List Audit Template Detailed

Returns a list of Audit Template resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

goal (Optional)

query

string

The UUID or name of the Goal.

strategy (Optional)

query

string

The UUID or name of the Strategy.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the Audit template.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

description (Optional)

body

string

Short description of the Audit Template.

Example JSON representation of an Audit Template:

{
    "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
        }
    ]
}
GET
/v1/audit_templates/{audittemplate_ident}

Show Audit Template

Shows details for an Audit Template.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

audittemplate_ident

path

string

The UUID or name of the Audit Template.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the Audit template.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

description (Optional)

body

string

Short description of the Audit Template.

Example JSON representation of an Audit Template:

{
    "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"
}
PATCH
/v1/audit_templates/{audittemplate_ident}

Update Audit Template

Updates an Audit Template with the given information.

Normal response codes: 200

Error codes: 400,404

Request

Name

In

Type

Description

audittemplate_ident

path

string

The UUID or name of the Audit Template.

Example PATCH document updating Audit Template:

[
    {
        "op": "replace",
        "value": "PENDING",
        "path": "/state"
    }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the Audit template.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

description (Optional)

body

string

Short description of the Audit Template.

Example JSON representation of an Audit Template:

{
    "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"
}
DELETE
/v1/audit_templates/{audittemplate_ident}

Delete Audit Template

Deletes an Audit Template.

Normal response codes: 204

Error codes: 404

Request

Name

In

Type

Description

audittemplate_ident

path

string

The UUID or name of the Audit Template.

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.

POST
/v1/audits

Create Audit

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.

Normal response codes: 201

Error codes: 400,404

Request

Name

In

Type

Description

audit_template_uuid

body

string

The UUID of the Audit template.

audit_type

body

string

Type of this audit. Can only be either ONESHOT or CONTINUOUS.

name (Optional)

body

string

Name of this audit.

goal (Optional)

body

string

The UUID or name of the Goal.

strategy (Optional)

body

string

The UUID or name of the Strategy.

parameters (Optional)

body

JSON

The strategy parameters for this audit.

interval (Optional)

body

string

Time interval between audit’s execution. Can be set either in seconds or cron syntax. Should be defined only for CONTINUOUS audits.

auto_trigger (Optional)

body

boolean

Auto execute action plan once audit is succeeded.

start_time (Optional)

body

string

The local time after which audit can be executed in accordance with interval. It will be converted to UTC time by Watcher.

New in version 1.1

end_time (Optional)

body

string

The local time after which audit can’t be executed. It will be converted to UTC time by Watcher.

New in version 1.1

force (Optional)

body

boolean

Launch audit even if action plan is ongoing.

New in version 1.2

Example ONESHOT Audit creation request:

{
    "audit_type": "ONESHOT",
    "auto_trigger": false,
    "force": true,
    "audit_template_uuid": "5e70a156-ced7-4012-b1c6-88fcb02ee0c1"
}

Example CONTINUOUS Audit creation request with a specified strategy:

{
    "auto_trigger": false,
    "force": false,
    "audit_template_uuid": "76fddfee-a9c4-40b0-8da0-c19ad6904f09",
    "name": "test_audit",
    "parameters": {
        "metrics": [
            "cpu_util"
        ]
    },
    "audit_type": "CONTINUOUS",
    "interval": "*/2 * * * *",
    "start_time":"2018-04-02 20:30:00",
    "end_time": "2018-04-04 20:30:00"
}

Response

The list and example below are representative of the response as of API version 1:

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Name of this audit.

audit_type

body

string

Type of this audit. Can only be either ONESHOT or CONTINUOUS.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

interval (Optional)

body

string

Time interval between audit’s execution. Can be set either in seconds or cron syntax. Should be defined only for CONTINUOUS audits.

next_run_time (Optional)

body

string

The next time audit launch. Defined only for CONTINUOUS audits.

parameters (Optional)

body

JSON

The strategy parameters for this audit.

auto_trigger (Optional)

body

boolean

Auto execute action plan once audit is succeeded.

state

body

string

State of this audit. To get more information about states and audit’s lifecycle, visit Audit State Machine page.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the audit is running on

start_time (Optional)

body

string

The UTC time after which audit can be executed in accordance with interval.

New in version 1.1

end_time (Optional)

body

string

The UTC time after which audit can’t be executed.

New in version 1.1

force (Optional)

body

boolean

Launch audit even if action plan is ongoing.

New in version 1.2

Example JSON representation of an Audit:

{
    "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,
    "force": 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,
    "hostname": null,
    "start_time": null,
    "end_time": null
}
GET
/v1/audits

List Audit

Returns a list of Audit resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

goal (Optional)

query

string

The UUID or name of the Goal.

strategy (Optional)

query

string

The UUID or name of the Strategy.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Name of this audit.

audit_type

body

string

Type of this audit. Can only be either ONESHOT or CONTINUOUS.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

interval (Optional)

body

string

Time interval between audit’s execution. Can be set either in seconds or cron syntax. Should be defined only for CONTINUOUS audits.

next_run_time (Optional)

body

string

The next time audit launch. Defined only for CONTINUOUS audits.

auto_trigger (Optional)

body

boolean

Auto execute action plan once audit is succeeded.

state

body

string

State of this audit. To get more information about states and audit’s lifecycle, visit Audit State Machine page.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of an Audit:

{
    "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
        }
    ]
}
GET
/v1/audits/detail

List Audit Detailed

Returns a list of Audit resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

goal (Optional)

query

string

The UUID or name of the Goal.

strategy (Optional)

query

string

The UUID or name of the Strategy.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Name of this audit.

audit_type

body

string

Type of this audit. Can only be either ONESHOT or CONTINUOUS.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

interval (Optional)

body

string

Time interval between audit’s execution. Can be set either in seconds or cron syntax. Should be defined only for CONTINUOUS audits.

next_run_time (Optional)

body

string

The next time audit launch. Defined only for CONTINUOUS audits.

parameters (Optional)

body

JSON

The strategy parameters for this audit.

auto_trigger (Optional)

body

boolean

Auto execute action plan once audit is succeeded.

state

body

string

State of this audit. To get more information about states and audit’s lifecycle, visit Audit State Machine page.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the audit is running on

start_time (Optional)

body

string

The UTC time after which audit can be executed in accordance with interval.

New in version 1.1

end_time (Optional)

body

string

The UTC time after which audit can’t be executed.

New in version 1.1

force (Optional)

body

boolean

Launch audit even if action plan is ongoing.

New in version 1.2

Example JSON representation of an Audit:

{
    "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,
	    "force": 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",
            "hostname": "controller",
            "start_time": null,
            "end_time": null
        }
    ]
}
GET
/v1/audits/{audit_ident}

Show Audit

Shows details for an Audit.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

audit_ident

path

string

The UUID or name of the Audit.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Name of this audit.

audit_type

body

string

Type of this audit. Can only be either ONESHOT or CONTINUOUS.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

interval (Optional)

body

string

Time interval between audit’s execution. Can be set either in seconds or cron syntax. Should be defined only for CONTINUOUS audits.

next_run_time (Optional)

body

string

The next time audit launch. Defined only for CONTINUOUS audits.

parameters (Optional)

body

JSON

The strategy parameters for this audit.

auto_trigger (Optional)

body

boolean

Auto execute action plan once audit is succeeded.

state

body

string

State of this audit. To get more information about states and audit’s lifecycle, visit Audit State Machine page.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the audit is running on

start_time (Optional)

body

string

The UTC time after which audit can be executed in accordance with interval.

New in version 1.1

end_time (Optional)

body

string

The UTC time after which audit can’t be executed.

New in version 1.1

force (Optional)

body

boolean

Launch audit even if action plan is ongoing.

New in version 1.2

Example JSON representation of an Audit:

{
    "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,
    "force": 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",
    "hostname": "controller",
    "start_time": null,
    "end_time": null
}
PATCH
/v1/audits/{audit_ident}

Cancel Audit

Cancels an ONGOING Audit resource.

Normal response codes: 200

Error codes: 400,404

Request

Name

In

Type

Description

audit_ident

path

string

The UUID or name of the Audit.

Example Audit cancelling request:

[
    {
        "op": "replace",
        "value": "CANCELLED",
        "path": "/state"
    }
]

Response

The list and example below are representative of the response as of API version 1:

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Name of this audit.

audit_type

body

string

Type of this audit. Can only be either ONESHOT or CONTINUOUS.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

interval (Optional)

body

string

Time interval between audit’s execution. Can be set either in seconds or cron syntax. Should be defined only for CONTINUOUS audits.

next_run_time (Optional)

body

string

The next time audit launch. Defined only for CONTINUOUS audits.

parameters (Optional)

body

JSON

The strategy parameters for this audit.

auto_trigger (Optional)

body

boolean

Auto execute action plan once audit is succeeded.

state

body

string

State of this audit. To get more information about states and audit’s lifecycle, visit Audit State Machine page.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the audit is running on

start_time (Optional)

body

string

The UTC time after which audit can be executed in accordance with interval.

New in version 1.1

end_time (Optional)

body

string

The UTC time after which audit can’t be executed.

New in version 1.1

force (Optional)

body

boolean

Launch audit even if action plan is ongoing.

New in version 1.2

Example JSON representation of an Audit:

{
    "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,
    "force": 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",
    "hostname": "controller",
    "start_time": null,
    "end_time": null
}
PATCH
/v1/audits/{audit_ident}

Update Audit

Updates an Audit with the given information.

Normal response codes: 200

Error codes: 400,404

Request

Name

In

Type

Description

audit_ident

path

string

The UUID or name of the Audit.

Example PATCH document updating Audit:

[
    {
        "value": "CANCELLED",
        "path": "/state",
        "op": "replace"
    },
    {
        "value": "audit1",
        "path": "/name",
        "op": "replace"
    }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Name of this audit.

audit_type

body

string

Type of this audit. Can only be either ONESHOT or CONTINUOUS.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

goal_uuid

body

string

Unique UUID for this goal.

goal_name

body

string

Name of the goal.

interval (Optional)

body

string

Time interval between audit’s execution. Can be set either in seconds or cron syntax. Should be defined only for CONTINUOUS audits.

next_run_time (Optional)

body

string

The next time audit launch. Defined only for CONTINUOUS audits.

parameters (Optional)

body

JSON

The strategy parameters for this audit.

auto_trigger (Optional)

body

boolean

Auto execute action plan once audit is succeeded.

state

body

string

State of this audit. To get more information about states and audit’s lifecycle, visit Audit State Machine page.

scope (Optional)

body

JSON

Audit Scope.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the audit is running on

start_time (Optional)

body

string

The UTC time after which audit can be executed in accordance with interval.

New in version 1.1

end_time (Optional)

body

string

The UTC time after which audit can’t be executed.

New in version 1.1

force (Optional)

body

boolean

Launch audit even if action plan is ongoing.

New in version 1.2

Example JSON representation of an Audit:

{
    "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,
    "force": 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",
    "hostname": "controller",
    "start_time": null,
    "end_time": null
}
DELETE
/v1/audits/{audit_ident}

Delete Audit

Deletes an Audit. Audit can be deleted only from FAILED, SUCCEEDED, CANCELLED, SUSPENDED states.

Normal response codes: 204

Error codes: 404

Request

Name

In

Type

Description

audit_ident

path

string

The UUID or name of the Audit.

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.

POST
/v1/action_plans/{actionplan_ident}/start

Start Action Plan

Starts a created Action Plan resource.

Normal response codes: 200

Error codes: 400,404

Request

Name

In

Type

Description

actionplan_ident

path

string

The UUID of the Action Plan.

Response

The list and example below are representative of the response as of API version 1:

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

state (Optional)

body

string

State of this action plan. To get more information about states and action plan’s lifecycle, visit Action Plan State Machine page.

audit_uuid (Optional)

body

string

The UUID of the audit this acton plan belongs to.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

efficacy_indicators (Optional)

body

array

The list of efficacy indicators associated to this action plan.

global_efficacy (Optional)

body

array

The global efficacy of this action plan.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the actionplan is running on

Example JSON representation of an Action Plan:

{
    "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,
    "hostname": null
}
GET
/v1/action_plans

List Action Plan

Returns a list of Action Plan resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

audit_uuid (Optional)

query

string

Optional UUID of an audit, to get only actions for that audit.

strategy (Optional)

query

string

The UUID or name of the Strategy.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

state (Optional)

body

string

State of this action plan. To get more information about states and action plan’s lifecycle, visit Action Plan State Machine page.

audit_uuid (Optional)

body

string

The UUID of the audit this acton plan belongs to.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

efficacy_indicators (Optional)

body

array

The list of efficacy indicators associated to this action plan.

global_efficacy (Optional)

body

array

The global efficacy of this action plan.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of an Action Plan:

{
    "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"
        }
    ]
}
GET
/v1/action_plans/detail

List Action Plan detailed

Returns a list of Action Plan resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

audit_uuid (Optional)

query

string

Optional UUID of an audit, to get only actions for that audit.

strategy (Optional)

query

string

The UUID or name of the Strategy.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

deleted_at

body

string

The date and time when the resource was deleted. The date and time stamp format is ISO 8601

updated_at

body

string

The date and time when the resource was updated. The date and time stamp format is ISO 8601

created_at

body

string

The date and time when the resource was created. The date and time stamp format is ISO 8601

uuid

body

string

The UUID for the resource.

state (Optional)

body

string

State of this action plan. To get more information about states and action plan’s lifecycle, visit Action Plan State Machine page.

audit_uuid (Optional)

body

string

The UUID of the audit this acton plan belongs to.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

efficacy_indicators (Optional)

body

array

The list of efficacy indicators associated to this action plan.

global_efficacy (Optional)

body

array

The global efficacy of this action plan.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the actionplan is running on

Example JSON representation of an Action Plan:

{
    "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",
            "deleted_at": null,
            "uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf",
            "audit_uuid": "7d100b05-0a86-491f-98a7-f93da19b272a",
            "created_at": "2018-04-10T11:59:52.640067+00:00",
            "hostname": "controller"
        }
    ]
}
GET
/v1/action_plans/{actionplan_ident}

Show Action Plan

Shows details for an Action Plan.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

actionplan_ident

path

string

The UUID of the Action Plan.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

state (Optional)

body

string

State of this action plan. To get more information about states and action plan’s lifecycle, visit Action Plan State Machine page.

audit_uuid (Optional)

body

string

The UUID of the audit this acton plan belongs to.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

efficacy_indicators (Optional)

body

array

The list of efficacy indicators associated to this action plan.

global_efficacy (Optional)

body

array

The global efficacy of this action plan.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the actionplan is running on

Example JSON representation of an Audit:

{
    "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",
    "hostname": "controller"
}
PATCH
/v1/action_plans/{actionplan_ident}

Cancel Action Plan

Cancels a created Action Plan resource.

Normal response codes: 200

Error codes: 400,404

Request

Name

In

Type

Description

actionplan_ident

path

string

The UUID of the Action Plan.

Example Action Plan ONGOING cancelling request:

[
    {
        "op": "replace",
        "value": "CANCELLING",
        "path": "/state"
    }
]

Example Action Plan PENDING cancelling request:

[
    {
        "op": "replace",
        "value": "CANCELLED",
        "path": "/state"
    }
]

Response

The list and example below are representative of the response as of API version 1:

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

state (Optional)

body

string

State of this action plan. To get more information about states and action plan’s lifecycle, visit Action Plan State Machine page.

audit_uuid (Optional)

body

string

The UUID of the audit this acton plan belongs to.

strategy_uuid

body

string

Unique UUID for this strategy.

strategy_name

body

string

Name of the strategy.

efficacy_indicators (Optional)

body

array

The list of efficacy indicators associated to this action plan.

global_efficacy (Optional)

body

array

The global efficacy of this action plan.

links

body

array

A list of relative links. Includes the self and bookmark links.

hostname (Optional)

body

string

Hostname the actionplan is running on

Example JSON representation of an Action Plan:

{
    "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,
    "hostname": null
}
DELETE
/v1/action_plans/{actionplan_ident}

Delete Action Plan

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

Name

In

Type

Description

actionplan_ident

path

string

The UUID of the Action Plan.

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.

GET
/v1/actions

List Action

Returns a list of Action resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

action_plan_uuid (Optional)

query

string

UUID of the action plan used for filtering.

audit_uuid (Optional)

query

string

Optional UUID of an audit, to get only actions for that audit.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

action_type

body

string

Action type based on specific API action. Actions in Watcher are pluggable, to see a list of supported action types visit Action plugins page.

state

body

string

State of Action.

action_plan_uuid

body

string

The action plan this action belongs to.

parents

body

array

UUIDs of parent actions.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of an Action:

{
    "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"
        }
    ]
}
GET
/v1/actions/detail

List Action Detailed

Returns a list of Action resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

action_plan_uuid (Optional)

query

string

UUID of the action plan used for filtering.

audit_uuid (Optional)

query

string

Optional UUID of an audit, to get only actions for that audit.

limit (Optional)

query

integer

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.

marker (Optional)

query

string

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

action_type

body

string

Action type based on specific API action. Actions in Watcher are pluggable, to see a list of supported action types visit Action plugins page.

state

body

string

State of Action.

action_plan_uuid

body

string

The action plan this action belongs to.

parents

body

array

UUIDs of parent actions.

description

body

string

Action description.

input_parameters

body

JSON

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.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of an Action:

{
    "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"
        }
    ]
}
GET
/v1/actions/{action_ident}

Show Action

Shows details for an Action.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

action_ident

path

string

The UUID of the Action.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

action_type

body

string

Action type based on specific API action. Actions in Watcher are pluggable, to see a list of supported action types visit Action plugins page.

state

body

string

State of Action.

action_plan_uuid

body

string

The action plan this action belongs to.

parents

body

array

UUIDs of parent actions.

description

body

string

Action description.

input_parameters

body

JSON

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.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of an Action:

{
    "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"
}

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, …

GET
/v1/goals

List Goal

Returns a list of Goal resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

efficacy_specification

body

array

Efficacy specifications as result of stategy’s execution.

name

body

string

Name of the goal.

display_name

body

string

Localized name of the goal.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Goal:

{
    "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"
        }
    ]
}
GET
/v1/goals/detail

List Goal Detailed

Returns a list of Goal resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

efficacy_specification

body

array

Efficacy specifications as result of stategy’s execution.

name

body

string

Name of the goal.

display_name

body

string

Localized name of the goal.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Goal:

{
    "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"
        }
    ]
}
GET
/v1/goals/{goal_ident}

Show Goal

Shows details for an Goal.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

goal_ident

path

string

The UUID or name of the Goal.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

efficacy_specification

body

array

Efficacy specifications as result of stategy’s execution.

name

body

string

Name of the goal.

display_name

body

string

Localized name of the goal.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Goal:

{
    "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
}

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.

GET
/v1/strategies

List Strategy

Returns a list of Strategy resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

goal (Optional)

query

string

The UUID or name of the Goal.

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

Name of the strategy.

display_name

body

string

Localized name of the strategy.

goal_name

body

string

Name of the goal.

goal_uuid

body

string

Unique UUID for this goal.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Strategy:

{
    "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"
        }
    ]
}
GET
/v1/strategies/detail

List Strategy Detailed

Returns a list of Strategy resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

goal (Optional)

query

string

The UUID or name of the Goal.

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

Name of the strategy.

display_name

body

string

Localized name of the strategy.

parameters_spec

body

JSON

Parameters specifications for this strategy.

goal_name

body

string

Name of the goal.

goal_uuid

body

string

Unique UUID for this goal.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Strategy:

{
    "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"
        }
    ]
}
GET
/v1/strategies/{strategy_ident}

Show Strategy

Shows details for a Strategy resource.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

strategy_ident

path

string

The UUID or name of the Strategy.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

Name of the strategy.

display_name

body

string

Localized name of the strategy.

parameters_spec

body

JSON

Parameters specifications for this strategy.

goal_name

body

string

Name of the goal.

goal_uuid

body

string

Unique UUID for this goal.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Strategy:

{
    "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"
}
GET
/v1/strategies/{strategy_ident}/state

Show Strategy State

Retrieve an information about strategy requirements.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

strategy_ident

path

string

The UUID or name of the Strategy.

Response

Name

In

Type

Description

state

body

string or JSON

State of requirement for Strategy.

comment

body

string

Requirement comment.

mandatory

body

boolean

Whether this requirement mandatory or not.

type

body

string

Type of requirement for Strategy.

Example JSON representation of a Strategy:

[
    {
        "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"
    }
]

Services

This resource represents Watcher services, their states and hosts they are placed on.

GET
/v1/services

List Service

Returns a list of Service resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

id

body

integer

The ID of service.

name

body

string

The Name of service like watcher-applier.

host

body

string

The Name of host where service is placed on.

status

body

string

The State of service. It can be either in ACTIVE or FAILED state.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Service:

{
    "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"
                }
            ]
        }
    ]
}
GET
/v1/services/detail

List Service Detailed

Returns a list of Service resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

id

body

integer

The ID of service.

name

body

string

The Name of service like watcher-applier.

host

body

string

The Name of host where service is placed on.

status

body

string

The State of service. It can be either in ACTIVE or FAILED state.

last_seen_up

body

string

The Time when Watcher service sent latest heartbeat.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Service:

{
    "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"
        }
    ]
}
GET
/v1/services/{service_ident}

Show Service

Shows details for a Service resource.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

service_ident

path

string

The ID or name of the Service.

Response

Name

In

Type

Description

id

body

integer

The ID of service.

name

body

string

The Name of service like watcher-applier.

host

body

string

The Name of host where service is placed on.

status

body

string

The State of service. It can be either in ACTIVE or FAILED state.

last_seen_up

body

string

The Time when Watcher service sent latest heartbeat.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Service:

{
    "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"
}

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.

GET
/v1/scoring_engines

List Scoring Engine

Returns a list of Scoring Engine resources.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the scoring engine.

description

body

string

A human readable description of the Scoring Engine.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Scoring Engine:

{
    "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"
        }
    ]
}
GET
/v1/scoring_engines/detail

List Scoring Engine Detailed

Returns a list of Scoring Engine resources with complete details.

Normal response codes: 200

Error codes: 400,401

Request

Name

In

Type

Description

limit (Optional)

query

integer

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.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc.

sort_key (Optional)

query

string

Sorts the response by the this attribute value. Default is id.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the scoring engine.

description

body

string

A human readable description of the Scoring Engine.

metainfo

body

string

A metadata associated with the scoring engine

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Scoring Engine:

{
    "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": ""
        }
    ]
}
GET
/v1/scoring_engines/{scoring_engine_ident}

Show Scoring Engine

Shows details for a Scoring Engine resource.

Normal response codes: 200

Error codes: 404

Request

Name

In

Type

Description

scoring_engine_ident

path

string

The UUID or name of the Scoring Engine.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The name of the scoring engine.

description

body

string

A human readable description of the Scoring Engine.

metainfo

body

string

A metadata associated with the scoring engine

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Scoring Engine:

{
    "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": ""
}

Data Model

New in version 1.3.

Data Model is very important for Watcher to generate resource optimization solutions. Users can easily view the data model by the API.

GET
/v1/data_model

List Data Model

Returns the information about Data Model.

Normal response codes: 200

Error codes: 400,401,406

Request

Name

In

Type

Description

audit (Optional)

query

string

Optional UUID of an audit, to get only actions for that audit.

type (Optional)

query

string

Type of data model user want to list. Default type is compute. Supported values: compute. Future support values: storage, baremetal.

Response

Name

In

Type

Description

server_uuid

body

string

The Unique UUID of the server.

server_name

body

string

The Name of the server.

server_vcpus

body

integer

The Vcpu of the server.

server_memory

body

integer

The Memory of server.

server_disk

body

integer

The Disk of the server.

server_state

body

string

The State of the server.

node_uuid

body

string

The Unique UUID of the node.

node_hostname

body

string

The Host Name of the node.

node_vcpus

body

integer

The Vcpu of the node.

node_vcpu_ratio

body

float

The Vcpu ratio of the node.

node_memory

body

integer

The Memory of the node(in MiB).

node_memory_ratio

body

float

The Memory Ratio of the node.

node_disk

body

integer

The Disk of the node(in GiB).

node_disk_ratio

body

float

The Disk Ratio of the node.

node_state

body

string

The State of the node. The value is up or down.

Example JSON representation of a Data Model:

{
    "context": [
        {
            "server_uuid": "1bf91464-9b41-428d-a11e-af691e5563bb",
            "server_name": "chenke-test1",
            "server_vcpus": "1",
            "server_memory": "512",
            "server_disk": "1",
            "server_state": "active",
            "node_uuid": "253e5dd0-9384-41ab-af13-4f2c2ce26112",
            "node_hostname": "localhost.localdomain",
            "node_vcpus": "4",
            "node_vcpu_ratio": "16.0",
            "node_memory": "16383",
            "node_memory_ratio": "1.5",
            "node_disk": "37"
            "node_disk_ratio": "1.0",
            "node_state": "up",
        },
        {
            "server_uuid": "e2cb5f6f-fa1d-4ba2-be1e-0bf02fa86ba4",
            "server_name": "chenke-test2",
            "server_vcpus": "1",
            "server_memory": "512",
            "server_disk": "1",
            "server_state": "active",
            "node_uuid": "253e5dd0-9384-41ab-af13-4f2c2ce26112",
            "node_hostname": "localhost.localdomain",
            "node_vcpus": "4",
            "node_vcpu_ratio": "16.0",
            "node_memory": "16383",
            "node_memory_ratio": "1.5",
            "node_disk": "37"
            "node_disk_ratio": "1.0",
            "node_state": "up",
        }
    ]
}

Webhooks

New in version 1.4.

Triggers an event based Audit.

POST
/v1/webhooks/{audit_ident}

Trigger EVENT Audit

Normal response codes: 202

Error codes: 400,404

Request

Name

In

Type

Description

audit_ident

path

string

The UUID or name of the Audit.