Watcher API

Watcher API

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.

Warning

Only ``audit_template_uuid`` can be used to create audit so far. It should be fixed during the Rocky cycle.

Normal response codes: 201

Error codes: 400,404

Request

Name In Type Description
audit_template_uuid body string The name of the Audit template.
audit_type body string Type of this audit. Can 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.
scope (Optional) body JSON Audit Scope.
auto_trigger (Optional) body boolean Autoexecute action plan once audit is succeeded.

Example ONESHOT Audit creation request:

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

Example CONTINUOUS Audit creation request with a specified strategy:

{
    "auto_trigger": false,
    "audit_template_uuid": "76fddfee-a9c4-40b0-8da0-c19ad6904f09",
    "name": "test_audit",
    "parameters": {
        "metrics": [
            "cpu_util"
        ]
    },
    "audit_type": "CONTINUOUS",
    "interval": "*/2 * * * *"
}

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 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 Autoexecute 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

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,
    "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
}
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 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 Autoexecute 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 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 Autoexecute 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

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,
            "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"
        }
    ]
}
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 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 Autoexecute 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

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,
    "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"
}
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 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 Autoexecute 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

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,
    "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"
}
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 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 Autoexecute 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

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,
    "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"
}
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 ID of service.
name body string Name of service like watcher-applier.
host body string Name of host where service is placed on.
status body string 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 ID of service.
name body string Name of service like watcher-applier.
host body string Name of host where service is placed on.
status body string State of service. It can be either in ACTIVE or FAILED state.
last_seen_up body string 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 ID of service.
name body string Name of service like watcher-applier.
host body string Name of host where service is placed on.
status body string State of service. It can be either in ACTIVE or FAILED state.
last_seen_up body string 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": ""
}
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.