Masakari API

This is a reference for the OpenStack Masakari API which is provided by the Masakari project.

API Versions

In order to bring new features to users over time, the Masakari API supports versioning.

  • ‘’major versions’’, which have dedicated urls

The Version APIs work differently from other APIs as they do not require authentication.

GET
/

List All Major 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 API version.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Response

Name

In

Type

Description

versions

body

array

A list of version objects that describe the API versions available.

id

body

string

A common name for the version in question. Informative only, it has no real semantic meaning.

status

body

string

The status of this API version. This can be one of:

  • CURRENT: this is the preferred version of the API to use

  • SUPPORTED: this is an older, but still supported version of the API

  • DEPRECATED: a deprecated version of the API that is slated for removal

links

body

array

Links to the resources in question.

version

body

string

The maximum version supported by API.

min_version

body

string

The minimum version supported by API.

Note

The updated parameter in the response is vestigial and provides no useful information.

Response Example

This demonstrates the expected response from a bleeding edge server that supports up to the current version.

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

Show Details of Specific API Version

This gets the details of a specific API at its root. Nearly all this information exists at the API root, so this is mostly a redundant operation.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Request

Name

In

Type

Description

api_version

path

string

The API version as returned in the links from the GET / call.

Response

Name

In

Type

Description

version

body

string

The version.

id

body

string

A common name for the version in question. Informative only, it has no real semantic meaning.

status

body

string

The status of this API version. This can be one of:

  • CURRENT: this is the preferred version of the API to use

  • SUPPORTED: this is an older, but still supported version of the API

  • DEPRECATED: a deprecated version of the API that is slated for removal

links

body

array

Links to the resources in question.

version

body

string

The maximum version supported by API.

min_version

body

string

The minimum version supported by API.

Note

The updated and media-types parameters in the response are vestigial and provide no useful information. They will probably be deprecated and removed in the future.

Response Example

This is an example of a GET /v1/ on a relatively current server.

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

FailoverSegments (segments)

Segments

System can be zoned from top to down levels, into Regions, Availability Zones and Host Aggregates (or Cells). Within those zones, one or more pacemaker/pacemaker-remote clusters may exist. In addition to those boundaries, shared storage boundary is also important to decide the optimal host for fail-over. Openstack zoned boundaries (such as Regions, AZ, Host Aggregates, etc..) can be managed by the nova scheduler. However, shared storage boundaries are difficult to manage. Moreover, the operator may want to use other types of boundary such as rack layout and powering. Therefore, operator may want to define the segment of hypervisor hosts and assign the failover host/hosts for each of them. Those segment can be define based on the shared storage boundaries or any other limitations may critical for selection of the failover host.

Lists, creates, shows details for, updates, and deletes segments.

GET
/segments

List FailoverSegments

Lists IDs, names, description, recovery_method, service_type for all segments.

Segments contains service_type and recovery_method attributes. service_type attribute indicates for which service (e.g. compute, cinder etc) this segment belongs to. recovery_method attribute indicates the recovery action to be followed when any host in a segment goes down. The possible recovery_method values are:

  • AUTO. Auto recovery action.

  • RESERVED_HOST. Reserved host recovery action.

  • AUTO_PRIORITY. First executes auto and if auto fails then retried with reserved host recover action.

  • RH_PRIORITY. First executes reserved host and if it fails then retried with reserved host recover action.

You can filter on the service_type and recovery_method when you complete a list segments request.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

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.

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.

recovery_method (Optional)

query

string

Filter the segment list result by recovery_method.

service_type (Optional)

query

string

Filter the segment list result by service_type.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the segment sort_key attribute.

sort_key (Optional)

query

string

Sorts by a segment attribute. Default attribute is created. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the segment sort_key attribute. The sort keys are limited to:

  • created_at

  • description

  • name

  • updated_at

  • uuid

  • recovery_method

  • service_type

Response

Name

In

Type

Description

segments

body

array

A list of segment objects.

name

body

string

The segment name.

uuid

body

string

The UUID of the segment.

Example List Segments

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

Create Segment

Creates a segment.

Creates a FailoverSegment with name, description, service_type and recovery_method. For service_type user can mention the name of service for which this segment is created. As of now user can mention COMPUTE as service_type. For recovery_method user can mention either AUTO, RESERVED_HOST, AUTO_PRIORITY or RH_PRIORITY. Segment name should be unique.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

409 - Conflict

This operation conflicted with another operation on this resource.

A conflict(409) is returned if segment with same name is already present.

Request

Name

In

Type

Description

sgement

body

object

A segment object.

description (Optional)

body

string

A free form description of the segment. Limited to 255 characters in length.

name

body

string

The segment name.

recovery_method

body

string

Type of recovery if any host in this segment goes down. User can mention either ‘AUTO’, ‘RESERVED_HOST’, ‘AUTO_PRIORITY’ or ‘RH_PRIORITY’.

service_type

body

string

The name of service which will be deployed in this segment. As of now user can mention ‘COMPUTE’ as service_type.

Example Create Segment

{
    "segment" : {
        "service_type": "COMPUTE",
        "recovery_method": "AUTO",
        "name": "new_segment"
    }
}

Response

Name

In

Type

Description

segment

body

object

A segment object.

created

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

description (Optional)

body

string

A free form description of the segment. Limited to 255 characters in length.

id

body

string

The Id of the segment.

name

body

string

The segment name.

recovery_method

body

string

Type of recovery if any host in this segment goes down. User can mention either ‘AUTO’, ‘RESERVED_HOST’, ‘AUTO_PRIORITY’ or ‘RH_PRIORITY’.

service_type

body

string

The name of service which will be deployed in this segment. As of now user can mention ‘COMPUTE’ as service_type.

updated

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

uuid

body

string

The UUID of the segment.

Example Create Segment

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

Show Segment Details

Shows details for a segment.

Preconditions

The segment must exist.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

Response

Name

In

Type

Description

segment

body

object

A segment object.

created

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

description (Optional)

body

string

A free form description of the segment. Limited to 255 characters in length.

id

body

string

The Id of the segment.

name

body

string

The segment name.

recovery_method

body

string

Type of recovery if any host in this segment goes down. User can mention either ‘AUTO’, ‘RESERVED_HOST’, ‘AUTO_PRIORITY’ or ‘RH_PRIORITY’.

service_type

body

string

The name of service which will be deployed in this segment. As of now user can mention ‘COMPUTE’ as service_type.

updated

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

uuid

body

string

The UUID of the segment.

Example Show Segment Details

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

Update Segment

Updates the editable attributes of an existing host.

Preconditions

  • The segment must exist.

  • User can not update segment if any host from the segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

A conflict(409) is returned if user tries to update segment name which is already assigned to segment or if any host from the segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

description (Optional)

body

string

A free form description of the segment. Limited to 255 characters in length.

name

body

string

The segment name.

recovery_method

body

string

Type of recovery if any host in this segment goes down. User can mention either ‘AUTO’, ‘RESERVED_HOST’, ‘AUTO_PRIORITY’ or ‘RH_PRIORITY’.

service_type

body

string

The name of service which will be deployed in this segment. As of now user can mention ‘COMPUTE’ as service_type.

Example Update segment name

{
    "segment": {
        "name": "new_segment"
    }
}

Response

Name

In

Type

Description

segment

body

object

A segment object.

created

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

description (Optional)

body

string

A free form description of the segment. Limited to 255 characters in length.

id

body

string

The Id of the segment.

name

body

string

The segment name.

recovery_method

body

string

Type of recovery if any host in this segment goes down. User can mention either ‘AUTO’, ‘RESERVED_HOST’, ‘AUTO_PRIORITY’ or ‘RH_PRIORITY’.

service_type

body

string

The name of service which will be deployed in this segment. As of now user can mention ‘COMPUTE’ as service_type.

updated

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

uuid

body

string

The UUID of the segment.

Example Update Segment name

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

Delete Segment

Deletes a segment.

Preconditions

  • The segment must exist.

  • User can not delete segment if any host from the segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

Response Codes

Success

Code

Reason

204 - No Content

The server has fulfilled the request by deleting the resource.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

A conflict(409) is returned if user tries to delete the segment if any host from the segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

Response

There is no body content for the response of a successful DELETE query.

Hosts (hosts)

Hosts

A host belongs to segment. Host can be any kind of virtual machine which can have compute service running on it.

Lists, creates, shows details for, updates, and deletes hosts.

GET
/segments/{segment_id}/hosts

List Hosts

Lists IDs, names, type, reserved, on_maintenance for all hosts.

You can filter on the type, on_maintenance and reserved when you complete a list hosts request.

Preconditions

The segment must exist.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

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.

on_maintenance (Optional)

query

boolean

Filter the host list result by on_maintenance.

reserved (Optional)

query

boolean

Filter the host list result by reserved flag.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the segment sort_key attribute.

sort_key (Optional)

query

string

Sorts by a hosts attribute. Default attribute is created. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the segment sort_key attribute. The sort keys are limited to:

  • created_at

  • type

  • name

  • updated_at

  • uuid

  • reserved

  • on_maintenance

type (Optional)

query

boolean

Filter the host list result by type of host.

Response

Name

In

Type

Description

hosts

body

array

A list of host objects.

name

body

string

The host name.

uuid

body

string

The UUID of the host.

failover_segment_id

body

string

The UUID of the segment.

deleted

body

boolean

A boolean indicates whether this resource is deleted or not, if it has not been deleted, false will appear.

on_maintenance (Optional)

body

boolean

A boolean indicates whether this host is on maintenance or not, if it is not on maintenance mode, false will appear.

reserved (Optional)

body

boolean

A boolean indicates whether this host is reserved or not, if it is not reserved, false will appear.

created_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

control_attributes

body

string

Attributes to control host.

updated_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

failover_segment

body

object

A segment object.

type

body

string

Type of host.

id

body

string

ID of host.

Example List hosts

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

Create Host

Creates a host under given segment.

Creates a Host under given segment with name, type, control_attributes. User can set sepcific hosts as reserved by setting reserved attribute to True. By default on_maintenance mode which indicates whether host is under maintenance or not is False when host is created.

Preconditions

The segment must exist.

Response Codes

Success

Code

Reason

201 - Created

Resource was created and is ready to use.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

A conflict(409) is returned if host with same name is already present under given segment.

BadRequest (400) is returned if host doesn’t exists in nova.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

host

body

object

A host object.

type

body

string

Type of host.

name

body

string

The host name.

reserved (Optional)

body

boolean

A boolean indicates whether this host is reserved or not, if it is not reserved, false will appear.

on_maintenance (Optional)

body

boolean

A boolean indicates whether this host is on maintenance or not, if it is not on maintenance mode, false will appear.

Example Create Host

{
    "host": {
        "control_attributes": "SSH",
        "type": "COMPUTE",
        "name": "openstack-VirtualBox"
    }
}

Response

Name

In

Type

Description

host

body

object

A host object.

name

body

string

The host name.

uuid

body

string

The UUID of the host.

failover_segment_id

body

string

The UUID of the segment.

deleted

body

boolean

A boolean indicates whether this resource is deleted or not, if it has not been deleted, false will appear.

on_maintenance (Optional)

body

boolean

A boolean indicates whether this host is on maintenance or not, if it is not on maintenance mode, false will appear.

reserved (Optional)

body

boolean

A boolean indicates whether this host is reserved or not, if it is not reserved, false will appear.

created_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

control_attributes

body

string

Attributes to control host.

updated_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

failover_segment

body

object

A segment object.

type

body

string

Type of host.

id

body

string

ID of host.

Example Create Host

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

Show Host Details

Shows details for a host.

Preconditions

The segment must exist. The host must exist.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

host_id

path

string

The UUID of the host.

Response

Name

In

Type

Description

host

body

object

A host object.

name

body

string

The host name.

uuid

body

string

The UUID of the host.

failover_segment_id

body

string

The UUID of the segment.

deleted

body

boolean

A boolean indicates whether this resource is deleted or not, if it has not been deleted, false will appear.

on_maintenance (Optional)

body

boolean

A boolean indicates whether this host is on maintenance or not, if it is not on maintenance mode, false will appear.

reserved (Optional)

body

boolean

A boolean indicates whether this host is reserved or not, if it is not reserved, false will appear.

created_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

control_attributes

body

string

Attributes to control host.

updated_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

failover_segment

body

object

A segment object.

type

body

string

Type of host.

id

body

string

ID of host.

Example Show Host Details

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

Update Host

Updates the editable attributes of an existing host.

Preconditions

  • The segment must exist.

  • The host must exist.

  • User can not update host if that host or any host from the failover segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

A conflict(409) is returned if user tries to update host name which is already assigned to host under given segment or user tries to update the host or any other host from the failover segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

BadRequest (400) is returned if host doesn’t exists in nova.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

host_id

path

string

The UUID of the host.

type

body

string

Type of host.

name

body

string

The segment name.

on_maintenance (Optional)

body

boolean

A boolean indicates whether this host is on maintenance or not, if it is not on maintenance mode, false will appear.

reserved (Optional)

body

boolean

A boolean indicates whether this host is reserved or not, if it is not reserved, false will appear.

Example Update host reserved flag

{
    "host": {
        "reserved": "True"
    }
}

Response

Name

In

Type

Description

host

body

object

A host object.

name

body

string

The host name.

uuid

body

string

The UUID of the host.

failover_segment_id

body

string

The UUID of the segment.

deleted

body

boolean

A boolean indicates whether this resource is deleted or not, if it has not been deleted, false will appear.

on_maintenance (Optional)

body

boolean

A boolean indicates whether this host is on maintenance or not, if it is not on maintenance mode, false will appear.

reserved (Optional)

body

boolean

A boolean indicates whether this host is reserved or not, if it is not reserved, false will appear.

created_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

control_attributes

body

string

Attributes to control host.

updated_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

failover_segment

body

object

A segment object.

type

body

string

Type of host.

id

body

string

ID of host.

Example Update host reserved flag

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

Delete Host

Deletes a host from given segment.

Preconditions

  • The segment must exist.

  • The host must exist.

  • User can not delete host if that host or any host from the failover segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

Response Codes

Success

Code

Reason

204 - No Content

The server has fulfilled the request by deleting the resource.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

A conflict(409) is returned if user tries to delete the host or any other host from the failover segment has any usage in the notification table i.e. any host from the failover segment has notification status as new/error/running.

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

host_id

path

string

The UUID of the host.

Response

There is no body content for the response of a successful DELETE query.

Notifications (notifications)

Notifications

A notification is a kind of alert provided by monitoring services (masakari-monitors) for failure of either host, process or instance.

Lists, creates and shows details for notifications.

GET
/notifications

List Notifications

Lists IDs, notification types, host_name, generated_time, payload and status for all notifications.

Notifications contain a status attribute that indicates the current notification state. You can filter on the notification status when you complete a list notifications request. The notification status is returned in the response body. The possible notification status values are:

  • NEW. The notification is in new state and yet to be processed.

  • RUNNING. The notification is in progress.

  • FINISHED. The notification is completed successfully.

  • ERROR. The notification is ended up in error.

  • FAILED. The notification is not processed successfully after failed once.

  • IGNORED. The notification is ignored by masakari engine.

You can also filter on the basis of source_host_uuid, generated_since and type when you complete a list notifications request.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

generated_since (Optional)

query

string

Filter the notifications list result by notification generated time.

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

Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the segment sort_key attribute.

sort_key (Optional)

query

string

Sorts by a notification attribute. Default attribute is created. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the segment sort_key attribute. The sort keys are limited to:

  • created_at

  • type

  • generated_time

  • updated_at

  • uuid

  • payload

  • status

  • source_host_uuid

source_host_uuid (Optional)

query

string

Filter the notifications list result by source_host_uuid.

type (Optional)

query

string

Filter the notifications list result by notification type.

Response

Name

In

Type

Description

notifications

body

array

A list of notification objects.

notification_uuid

body

string

The UUID of the notification.

deleted

body

boolean

A boolean indicates whether this resource is deleted or not, if it has not been deleted, false will appear.

created_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

updated_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

status

body

string

The notification status.

uuid

body

string

The UUID of the notification.

source_host_uuid

body

string

The UUID of host for which notification is generated.

generated_time

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

type

body

string

Type of notification, can be either PROCESS, COMPUTE_HOST or VM.

payload

body

string

Payload for notification.

Note

This is a JSON string.

id

body

string

ID of notification.

Example List Notifications

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

Create Notification

Creates a notiification.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

409 - Conflict

This operation conflicted with another operation on this resource.

A conflict(409) is returned if notification with same payload is exists or host for which notification is generated is under maintenance.

BadRequest (400) is returned if notification payload is incorrect.

Request

Name

In

Type

Description

notification

body

object

A notification object.

type

body

string

Type of notification, can be either PROCESS, COMPUTE_HOST or VM.

generated_time

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

payload

body

string

Payload for notification.

Note

This is a JSON string.

host_name

body

object

A name of host for which notification is created.

Example create Process failure notification

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

Example create VM failure notification

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

Example create COMPUTE_HOST failure notification

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

Response

Name

In

Type

Description

notification

body

object

A notification object.

type

body

string

Type of notification, can be either PROCESS, COMPUTE_HOST or VM.

generated_time

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

payload

body

string

Payload for notification.

Note

This is a JSON string.

source_host_uuid

body

string

The UUID of host for which notification is generated.

uuid

body

string

The UUID of the notification.

deleted

body

boolean

A boolean indicates whether this resource is deleted or not, if it has not been deleted, false will appear.

created_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

status

body

string

The notification status.

updated_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

id

body

string

ID of notification.

Example create Process failure notification

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

Example create VM failure notification

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

Example create COMPUTE_HOST failure notification

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

Show Notification Details

Shows details for a notification.

Preconditions

The notification must exist.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

notification_id

path

string

The UUID of the notification.

Response

Name

In

Type

Description

notification

body

object

A notification object.

type

body

string

Type of notification, can be either PROCESS, COMPUTE_HOST or VM.

generated_time

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

payload

body

string

Payload for notification.

Note

This is a JSON string.

source_host_uuid

body

string

The UUID of host for which notification is generated.

uuid

body

string

The UUID of the notification.

deleted

body

boolean

A boolean indicates whether this resource is deleted or not, if it has not been deleted, false will appear.

created_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

status

body

string

The notification status.

updated_at

body

string

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

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2017-04-21T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

recovery_workflow_details

body

array

Recovery workflow details of the notification. This is a list of dictionary.

New in version 1.1

id

body

string

ID of notification.

Example Show Notification Details

{
    "notification": {
        "notification_uuid": "07a331b8-df15-4582-b121-73ed3541a408",
        "status": "finished",
        "source_host_uuid": "b5bc49be-ea6f-472d-9240-968f75d7a16a",
        "deleted": false,
        "created_at": "2019-02-28T07:19:49.000000",
        "updated_at": "2019-02-28T07:19:59.000000",
        "payload": {
            "instance_uuid": "b9837317-a5b8-44f4-93b4-45500c562bb8",
            "vir_domain_event": "STOPPED_FAILED",
            "event": "LIFECYCLE"
        },
        "recovery_workflow_details": [
            {
                "progress": 1.0,
                "state": "SUCCESS",
                "name": "StopInstanceTask",
                "progress_details": [
                    {"timestamp": "2019-03-07 13:54:28.842031", "message": "Stopping instance: df528f02-2415-4a40-bad8-453ad6a519f7", "progress": "0.0"},
                    {"timestamp": "2019-03-07 13:54:34.442617", "message": "Stopped instance: 'df528f02-2415-4a40-bad8-453ad6a519f7'", "progress": "1.0"}
                ]
            },
            {
                "progress": 1.0,
                "state": "SUCCESS",
                "name": "StartInstanceTask",
                "progress_details": [
                    {"timestamp": "2019-03-07 13:54:34.531755", "message": "Starting instance: 'df528f02-2415-4a40-bad8-453ad6a519f7'", "progress": "0.0"},
                    {"timestamp": "2019-03-07 13:54:35.930430", "message": "Instance started: 'df528f02-2415-4a40-bad8-453ad6a519f7'", "progress": "1.0"}
                ]
            },
            {
                "progress": 1.0,
                "state": "SUCCESS",
                "name": "ConfirmInstanceActiveTask",
                "progress_details": [
                    {"timestamp": "2019-03-07 13:54:36.019208", "message": "Confirming instance 'df528f02-2415-4a40-bad8-453ad6a519f7' vm_state is ACTIVE", "progress": "0.0"},
                    {"timestamp": "2019-03-07 13:54:38.569373", "message": "Confirmed instance 'df528f02-2415-4a40-bad8-453ad6a519f7' vm_state is ACTIVE", "progress": "1.0"}
                ]
            }
        ],
        "generated_time": "2017-06-13T15:34:55.000000",
        "deleted_at": null,
        "type": "VM",
        "id": 13
    }
}