Masakari API

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
    }
}
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.