Clustering API

API Versions

Concepts

The Senlin API supports a ‘’major versions’’ expressed in request URLs and ‘’microversions’’ which can be sent in HTTP header OpenStack-API-Version.

When the specified OpenStack-API-Version is not supported by the API service, a 406 (NotAcceptable) exception will be raised. Note that this applies to all API requests documented in this guide.

GET
/

List Major Versions

Lists information for all Clustering API major versions.

Response Codes

Success

Code

Reason

300 - Multiple Choices

There is more than one API version for choice. The client has to be more specific to request a service endpoint.

Error

Code

Reason

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

versions

body

array

A list of supported major API versions.

id

body

string

The string representation of an API version number, e.g. 1.0.

links

body

array

A list of relative URLs to different version objects.

max_version

body

string

The string representation of the maximum microversion supported.

media-types

body

array

A list of content-type based media type request supported.

min_version

body

string

The string representation of the minimum microversion supported.

status

body

string

A string indicating the supporting status of the version.

updated

body

string

The date and time when the version was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

Response Example

{
    "versions": [
        {
            "id": "1.0",
            "links": [
                {
                    "href": "/v1/",
                    "rel": "self"
                },
                {
                    "href": "https://docs.openstack.org/api-ref/clustering",
                    "rel": "help"
                }
            ],
            "max_version": "1.7",
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.clustering-v1+json"
                }
            ],
            "min_version": "1.0",
            "status": "CURRENT",
            "updated": "2016-01-18T00:00:00Z"
        }
    ]
}
GET
/{version}/

Show Details of an API Version

Show details about an API major version.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

404 - Not Found

The requested resource could not be found.

406 - Not Acceptable

The requested API version is not supported by the API.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

version

path

string

A string indicating the major version of Clustering API.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

version

body

object

The details about a major API version.

id

body

string

The string representation of an API version number, e.g. 1.0.

links

body

array

A list of relative URLs to different version objects.

max_version

body

string

The string representation of the maximum microversion supported.

media-types

body

array

A list of content-type based media type request supported.

min_version

body

string

The string representation of the minimum microversion supported.

status

body

string

A string indicating the supporting status of the version.

updated

body

string

The date and time when the version was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

Response Example

{
    "version": {
        "id": "1.0",
        "links": [
            {
                "href": "/v1/",
                "rel": "self"
            },
            {
                "href": "https://docs.openstack.org/api-ref/clustering",
                "rel": "help"
            }
        ],
        "max_version": "1.7",
        "media-types": [
            {
                "base": "application/json",
                "type": "application/vnd.openstack.clustering-v1+json"
            }
        ],
        "min_version": "1.0",
        "status": "CURRENT",
        "updated": "2016-01-18T00:00:00Z"
    }
}

Build information (build-info)

Shows build information for a Senlin deployment.

GET
/v1/build-info

Show build information

Shows build information for a Senlin deployment.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

build_info

body

object

Build information for a Senlin deployment.

api

body

object

Revision information of Senlin API service.

engine

body

object

Revision information of Senlin engine service.

Response Example

{
    "build_info": {
        "api": {
            "revision": "1.0"
        },
        "engine": {
            "revision": "2.0"
        }
    }
}

This operation does not accept a request body.

Profile Types (profile-types)

Lists all profile types and shows details for a profile type.

GET
/v1/profile-types

List profile types

Lists supported profile types.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

profile_types

body

array

A list of profile_type objects. Since API micro-version 1.5, each record in the list will have a “support_status” property which contains a list of support status changes.

Response Example

For API microversion lower than 1.5, the response only contains the name for each profile type:

{
    "profile_types": [
        {
            "name": "container.dockerinc.docker-1.0"
        },
        {
            "name": "os.heat.stack-1.0"
        },
        {
            "name": "os.nova.server-1.0"
        }
    ]
}

Since API microversion 1.5, the response contains the support status of each profile type and the version is provided using a separate key:

{
    "profile_types": [
        {
            "name": "container.dockerinc.docker",
            "version": "1.0",
            "support_status": {
                "1.0": [
                    {
                        "status": "EXPERIMENTAL",
                        "since": "2017.02"
                    }
                ]
            }
        },
        {
            "name": "os.heat.stack",
            "version": "1.0",
            "support_status": {
                "1.0": [
                    {
                        "status": "SUPPORTED",
                        "since": "2016.04"
                    }
                ]
            }
        },
        {
            "name": "os.nova.server",
            "version": "1.0",
            "support_status": {
                "1.0": [
                    {
                        "status": "SUPPORTED",
                        "since": "2016.04"
                    }
                ]
            }
        }
    ]
}
GET
/v1/profile-types/{profile_type}

Show profile type details

Shows details for a profile type.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

profile_type

path

string

The name of a profile type.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

profile_type

body

object

A structured description of a profile type. Since API micro-version 1.5, a “support_status” property is returned which contains a list of support status changes.

name

body

string

The name of the profile type.

schema

body

object

The schema of a profile type. The schema of a profile type varies a lot based on the specific type implementation. All profile types share the context property which is a dictionary for customizing the request context to authenticate with a backend service. A common usage of this property is to set the region_name in the dictionary so that a node can be created in the specified region. All other properties are defined by a particular profile type implementation.

Response Example

For API microversion lower than 1.5, the response only contains the name and schema of the specified profile type:

{
    "profile_type": {
        "name": "os.heat.stack-1.0",
        "schema": {
            "context": {
                "default": {},
                "description": "A dictionary for specifying the customized context for stack operations",
                "required": false,
                "type": "Map",
                "updatable": false
            },
            "disable_rollback": {
                "default": true,
                "description": "A boolean specifying whether a stack operation can be rolled back.",
                "required": false,
                "type": "Boolean",
                "updatable": true
            },
            "environment": {
                "default": {},
                "description": "A map that specifies the environment used for stack operations.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "files": {
                "default": {},
                "description": "Contents of files referenced by the template, if any.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "parameters": {
                "default": {},
                "description": "Parameters to be passed to Heat for stack operations.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "template": {
                "default": {},
                "description": "Heat stack template.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "template_url": {
                "default": "",
                "description": "Heat stack template url.",
                "required": false,
                "type": "String",
                "updatable": true
            },
            "timeout": {
                "description": "A integer that specifies the number of minutes that a stack operation times out.",
                "required": false,
                "type": "Integer",
                "updatable": true
            }
        }
    }
}

Since API microversion 1.5, the response contains the support status of the specified profile type:

{
    "profile_type": {
        "name": "os.heat.stack-1.0",
        "schema": {
            "context": {
                "default": {},
                "description": "A dictionary for specifying the customized context for stack operations",
                "required": false,
                "type": "Map",
                "updatable": false
            },
            "disable_rollback": {
                "default": true,
                "description": "A boolean specifying whether a stack operation can be rolled back.",
                "required": false,
                "type": "Boolean",
                "updatable": true
            },
            "environment": {
                "default": {},
                "description": "A map that specifies the environment used for stack operations.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "files": {
                "default": {},
                "description": "Contents of files referenced by the template, if any.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "parameters": {
                "default": {},
                "description": "Parameters to be passed to Heat for stack operations.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "template": {
                "default": {},
                "description": "Heat stack template.",
                "required": false,
                "type": "Map",
                "updatable": true
            },
            "template_url": {
                "default": "",
                "description": "Heat stack template url.",
                "required": false,
                "type": "String",
                "updatable": true
            },
            "timeout": {
                "description": "A integer that specifies the number of minutes that a stack operation times out.",
                "required": false,
                "type": "Integer",
                "updatable": true
            }
        },
        "support_status": {
            "1.0": [
                {
                    "status": "SUPPORTED",
                     "since": "2016.04"
                }
            ]
        }
    }
}
GET
/v1/profile-types/{profile_type}/ops

List profile type operations

List operations and parameters supported by a profile type.

This API is only available since API microversion 1.4.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

profile_type

path

string

The name of a profile type.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

operations

body

object

A dictionary containing the description of operations (and parameters) supported by a profile type.

Response Example

{
    "operations": {
        "reboot": {
            "description": "Reboot the nova server.",
            "parameters": {
                "type": {
                    "constraints": [
                        {
                            "constraint": [
                                "SOFT",
                                "HARD"
                            ],
                            "type": "AllowedValues"
                        }
                    ],
                    "default": "SOFT",
                    "description": "Type of reboot which can be 'SOFT' or 'HARD'.",
                    "required": false,
                    "type": "String"
                }
            }
        }
    }
}

Profiles (profiles)

Lists all profiles and creates, shows information for, updates, and deletes a profile.

GET
/v1/profiles

List profiles

Lists all profiles.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

global_project (Optional)

query

boolean

Indicates whether to include resources for all projects or resources for the current project in the response.

If you are an administrative user and you set this value to true, the call returns all resources from all projects. Default is false, which returns only resources in the current project.

limit (Optional)

query

integer

Requests a page size of resources. Returns a number of resources up to the limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

UUID

The ID of the last-seen resource. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

name (Optional)

query

string

Filters the response by the specified name property of the object, such as policy_name or name property of cluster.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

type (Optional)

query

string

Filters the response by the specified type property of the object, such as policy_type property of cluster-policy binding object or type property of policy object.

The sorting keys include name, type, created_at and updated_at.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

profiles

body

array

A list for profile objects.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the profile.

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of the profile.

type

body

string

The name of the profile type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "profiles": [
        {
            "created_at": "2016-01-03T16:22:23Z",
            "domain": null,
            "id": "9e1c6f42-acf5-4688-be2c-8ce954ef0f23",
            "metadata": {},
            "name": "pserver",
            "project": "42d9e9663331431f97b75e25136307ff",
            "spec": {
                "properties": {
                    "flavor": 1,
                    "image": "cirros-0.3.4-x86_64-uec",
                    "key_name": "oskey",
                    "name": "cirros_server",
                    "networks": [
                        {
                            "network": "private"
                        }
                    ]
                },
                "type": "os.nova.server",
                "version": 1.0
            },
            "type": "os.nova.server-1.0",
            "updated_at": null,
            "user": "5e5bf8027826429c96af157f68dc9072"
        }
    ]
}
POST
/v1/profiles

Create profile

Creates a profile.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

profile

body

object

A structured description of a profile object.

name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

metadata (Optional)

body

object

A collection of key-value pairs associated with an object.

spec

body

object

The detailed specification of the profile.

Request Example

{
    "profile": {
        "metadata": {},
        "name": "test-profile",
        "spec": {
            "properties": {
                "flavor": "m1.small",
                "image": "F20",
                "key_name": "oskey",
                "name": "F20_server",
                "networks": [
                    {
                        "network": "private"
                    }
                ],
                "security_groups": [
                    "default"
                ]
            },
            "type": "os.nova.server",
            "version": 1.0
        }
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

profile

body

object

A structured description of a profile object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the profile.

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of the profile.

type

body

string

The name of the profile type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "profile": {
        "created_at": "2016-05-05T10:15:22Z",
        "domain": null,
        "id": "1d85fc39-7d9a-4f64-9751-b127ef554923",
        "metadata": {},
        "name": "test-profile",
        "project": "42d9e9663331431f97b75e25136307ff",
        "spec": {
            "properties": {
                "flavor": "m1.small",
                "image": "F20",
                "key_name": "oskey",
                "name": "F20_server",
                "networks": [
                    {
                        "network": "private"
                    }
                ],
                "security_groups": [
                    "default"
                ]
            },
            "type": "os.nova.server",
            "version": 1.0
        },
        "type": "os.nova.server-1.0",
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
GET
/v1/profiles/{profile_id}

Show profile details

Shows details for a profile.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

profile_id

path

string

The name, UUID or short-UUID of a profile.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

profile

body

object

A structured description of a profile object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the profile.

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of the profile.

type

body

string

The name of the profile type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "profile": {
        "created_at": "2016-03-10T06:34:56Z",
        "domain": null,
        "id": "17151d8a-f46f-4541-bde0-db3b207c20d2",
        "metadata": {},
        "name": "PF20",
        "project": "42d9e9663331431f97b75e25136307ff",
        "spec": {
            "properties": {
                "flavor": "m1.small",
                "image": "F20",
                "key_name": "oskey",
                "name": "F20_server",
                "networks": [
                    {
                        "network": "private"
                    }
                ]
            },
            "type": "os.nova.server",
            "version": 1.0
        },
        "type": "os.nova.server-1.0",
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
PATCH
/v1/profiles/{profile_id}

Update profile

Updates a profile.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

profile_id

path

string

The name, UUID or short-UUID of a profile.

profile

body

object

A structured description of a profile object.

metadata (Optional)

body

object

A collection of key-value pairs associated with an object.

name (Optional)

body

string

The new name of the object in question.

Request Example

{
    "profile": {
        "metadata": {"key": "value"},
        "name": "new-name"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

profile

body

object

A structured description of a profile object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

id

body

UUID

The UUID of the profile.

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of the profile.

type

body

string

The name of the profile type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "profile": {
        "created_at": "2016-03-10T06:34:56Z",
        "domain": null,
        "id": "17151d8a-f46f-4541-bde0-db3b207c20d2",
        "metadata": {
            "key": "value"
        },
        "name": "new-name",
        "project": "42d9e9663331431f97b75e25136307ff",
        "spec": {
            "properties": {
                "flavor": "m1.small",
                "image": "F20",
                "key_name": "oskey",
                "name": "F20_server",
                "networks": [
                    {
                        "network": "private"
                    }
                ]
            },
            "type": "os.nova.server",
            "version": 1.0
        },
        "type": "os.nova.server-1.0",
        "updated_at": "2016-03-11T05:10:11Z",
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
DELETE
/v1/profiles/{profile_id}

Delete profile

Deletes a profile.

Response Codes

A profile cannot be deleted if it is still used by node or cluster. In that case, a 409 error will be returned.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

profile_id

path

string

The name, UUID or short-UUID of a profile.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/profiles/validate

Validate profile

Validates a profile.

This API is only available since API microversion 1.2.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

profile

body

object

A structured description of a profile object.

spec

body

object

The detailed specification of the profile.

Request Example

{
    "profile": {
        "spec": {
            "properties": {
                "flavor": "m1.small",
                "image": "F20",
                "key_name": "oskey",
                "name": "F20_server",
                "networks": [
                    {
                        "network": "private"
                    }
                ],
                "security_groups": [
                    "default"
                ]
            },
            "type": "os.nova.server",
            "version": 1.0
        }
    }
}

Response Parameters

The response contains properties as if the profile is created.

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

profile

body

object

A structured description of a profile object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the profile.

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of the profile.

type

body

string

The name of the profile type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "profile": {
        "created_at": null,
        "domain": null,
        "id": null,
        "metadata": null,
        "name": "validated_profile",
        "project": "1d567ed4ef51453a85545f018b68c26d",
        "spec": {
            "properties": {
                "flavor": "m1.small",
                "image": "F20",
                "key_name": "oskey",
                "name": "F20_server",
                "networks": [
                    {
                        "network": "private"
                    }
                ],
                "security_groups": [
                    "default"
                ]
            },
            "type": "os.nova.server",
            "version": 1.0
        },
        "type": "os.nova.server-1.0",
        "updated_at": null,
        "user": "990e4c1f4a414f74990b17d16f2540b5"
    }
}

Policy Types (policy-types)

Lists all policy types and shows details for a policy type.

GET
/v1/policy-types

List policy types

Lists all supported policy types.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

policy_types

body

array

A list of policy_type objects. Since API micro-version 1.5, each record in the list will have a “support_status” property which contains a list of support status changes.

Response Example

For API microversion lower than 1.5, the response only contains the name for each policy type:

{
    "policy_types": [
        {
            "name": "senlin.policy.affinity-1.0"
        },
        {
            "name": "senlin.policy.batch-1.0"
        },
        {
            "name": "senlin.policy.health-1.0"
        },
        {
            "name": "senlin.policy.scaling-1.0"
        },
        {
            "name": "senlin.policy.region_placement-1.0"
        },
        {
            "name": "senlin.policy.deletion-1.0"
        },
        {
            "name": "senlin.policy.loadbalance-1.1"
        },
        {
            "name": "senlin.policy.zone_placement-1.0"
        }
    ]
}

Since API microversion 1.5, the response contains the support status of each policy type and the version is provided using a separate key:

{
    "policy_types": [
        {
            "name": "senlin.policy.affinity",
            "version": "1.0",
            "support_status": {
                "1.0": [
                    {
                        "status": "SUPPORTED",
                        "since": "2016.10"
                    }
                ]
            }
        },
        {
            "name": "senlin.policy.health",
            "version": "1.0",
            "support_status": {
                "1.0": [
                    {
                        "status": "EXPERIMENTAL",
                        "since": "2016.10"
                    }
                ]
            }
        },
        {
            "name": "senlin.policy.scaling",
            "version": "1.0",
            "support_status": {
                "1.0": [
                    {
                        "status": "SUPPORTED",
                        "since": "2016.04"
                    }
                ]
            }
        },
        {
            "name": "senlin.policy.region_placement",
            "version": "1.0",
            "support_status": {
                "1.0": [
                    {
                        "status": "EXPERIMENTAL",
                        "since": "2016.04"
                    },
                    {
                        "status": "SUPPORTED",
                        "since": "2016.10"
                    }
                ]
            }
        }
    ]
}
GET
/v1/policy-types/{policy_type}

Show policy type details

Shows details for a policy type.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

policy_type

path

string

The name of a policy type.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

policy_type

body

object

A structured description of a policy type. Since API micro-version 1.5, a “support_status” property is returned which contains a list of support status changes.

name

body

string

The name of the policy type.

schema

body

object

The schema of a policy type. The schema of a policy type varies a lot based on the specific type implementation.

Response Example

For API microversion lower than 1.5, the response only contains the name and schema of the specified policy type:

{
    "policy_type": {
        "name": "senlin.policy.affinity-1.0",
        "schema": {
            "availability_zone": {
                "description": "Name of the availability zone to place the nodes.",
                "required": false,
                "type": "String",
                "updatable": false
            },
            "enable_drs_extension": {
                "default": false,
                "description": "Enable vSphere DRS extension.",
                "required": false,
                "type": "Boolean",
                "updatable": false
            },
            "servergroup": {
                "description": "Properties of the VM server group",
                "required": false,
                "schema": {
                    "name": {
                        "description": "The name of the server group",
                        "required": false,
                        "type": "String",
                        "updatable": false
                    },
                    "policies": {
                        "constraints": [
                            {
                                "constraint": [
                                    "affinity",
                                    "anti-affinity"
                                ],
                                "type": "AllowedValues"
                            }
                        ],
                        "default": "anti-affinity",
                        "description": "The server group policies.",
                        "required": false,
                        "type": "String",
                        "updatable": false
                    }
                },
                "type": "Map",
                "updatable": false
            }
        }
    }
}

Since API microversion 1.5, the response contains the support status of the specified policy type:

{
    "policy_type": {
        "name": "senlin.policy.affinity-1.0",
        "schema": {
            "availability_zone": {
                "description": "Name of the availability zone to place the nodes.",
                "required": false,
                "type": "String",
                "updatable": false
            },
            "enable_drs_extension": {
                "default": false,
                "description": "Enable vSphere DRS extension.",
                "required": false,
                "type": "Boolean",
                "updatable": false
            },
            "servergroup": {
                "description": "Properties of the VM server group",
                "required": false,
                "schema": {
                    "name": {
                        "description": "The name of the server group",
                        "required": false,
                        "type": "String",
                        "updatable": false
                    },
                    "policies": {
                        "constraints": [
                            {
                                "constraint": [
                                    "affinity",
                                    "anti-affinity"
                                ],
                                "type": "AllowedValues"
                            }
                        ],
                        "default": "anti-affinity",
                        "description": "The server group policies.",
                        "required": false,
                        "type": "String",
                        "updatable": false
                    }
                },
                "type": "Map",
                "updatable": false
            }
        },
        "support_status": {
            "1.0": [
                {
                    "status": "SUPPORTED",
                    "since": "2016.10"
                }
            ]
        }
    }
}

Policies (policies)

Lists all policies and creates, shows information for, updates, and deletes a policy.

GET
/v1/policies

List policies

Lists all policies.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

limit (Optional)

query

integer

Requests a page size of resources. Returns a number of resources up to the limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

UUID

The ID of the last-seen resource. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

global_project (Optional)

query

boolean

Indicates whether to include resources for all projects or resources for the current project in the response.

If you are an administrative user and you set this value to true, the call returns all resources from all projects. Default is false, which returns only resources in the current project.

name (Optional)

query

string

Filters the response by the specified name property of the object, such as policy_name or name property of cluster.

type (Optional)

query

string

Filters the response by the specified type property of the object, such as policy_type property of cluster-policy binding object or type property of policy object.

The sorting keys include name, type, created_at and udpated_at.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

policies

body

array

A list of policy objects.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A structured representation of data associated with a policy object.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of a policy object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of a policy object.

type

body

string

The name of the policy type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "policies": [
        {
            "created_at": "2015-02-15T08:33:13.000000",
            "data": {},
            "domain": null,
            "id": "7192d8df-73be-4e98-ab99-1cf6d5066729",
            "name": "test_policy_1",
            "project": "42d9e9663331431f97b75e25136307ff",
            "spec": {
                "description": "A test policy",
                "properties": {
                    "criteria": "OLDEST_FIRST",
                    "destroy_after_deletion": true,
                    "grace_period": 60,
                    "reduce_desired_capacity": false
                },
                "type": "senlin.policy.deletion",
                "version": "1.0"
            },
            "type": "senlin.policy.deletion-1.0",
            "updated_at": null,
            "user": "5e5bf8027826429c96af157f68dc9072"
        }
    ]
}
POST
/v1/policies

Create policy

Creates a policy.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

policy

body

object

A structured description of a policy object.

name

body

string

The name of a policy object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

spec

body

object

The detailed specification of a policy object.

Request Example

{
    "policy": {
        "name": "sp001",
        "spec": {
            "properties": {
                "adjustment": {
                    "min_step": 1,
                    "number": 1,
                    "type": "CHANGE_IN_CAPACITY"
                },
                "event": "CLUSTER_SCALE_IN"
            },
            "type": "senlin.policy.scaling",
            "version": "1.0"
        }
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

policy

body

object

A structured description of a policy object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A structured representation of data associated with a policy object.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of a policy object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of a policy object.

type

body

string

The name of the policy type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "policy": {
        "created_at": "2015-03-02T07:40:31",
        "data": {},
        "domain": null,
        "id": "02f62195-2198-4797-b0a9-877632208527",
        "name": "sp001",
        "project": "42d9e9663331431f97b75e25136307ff",
        "spec": {
            "properties": {
                "adjustment": {
                    "best_effort": true,
                    "min_step": 1,
                    "number": 1,
                    "type": "CHANGE_IN_CAPACITY"
                },
                "event": "CLUSTER_SCALE_IN"
            },
            "type": "senlin.policy.scaling",
            "version": "1.0"
        },
        "type": "senlin.policy.scaling-1.0",
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
GET
/v1/policies/{policy_id}

Show policy details

Shows details for a policy.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

policy_id

path

string

The name, UUID or short-UUID of a policy object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

policy

body

object

A structured description of a policy object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A structured representation of data associated with a policy object.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of a policy object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of a policy object.

type

body

string

The name of the policy type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "policy": {
        "created_at": "2015-03-02T07:40:31",
        "data": {},
        "domain": null,
        "id": "02f62195-2198-4797-b0a9-877632208527",
        "name": "sp001",
        "project": "42d9e9663331431f97b75e25136307ff",
        "spec": {
            "properties": {
                "adjustment": {
                    "best_effort": true,
                    "min_step": 1,
                    "number": 1,
                    "type": "CHANGE_IN_CAPACITY"
                },
                "event": "CLUSTER_SCALE_IN"
            },
            "type": "senlin.policy.scaling",
            "version": "1.0"
        },
        "type": "senlin.policy.scaling-1.0",
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
PATCH
/v1/policies/{policy_id}

Update policy

Updates a policy.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

policy_id

path

string

The name, UUID or short-UUID of a policy object.

policy

body

object

A structured description of a policy object.

name

body

string

The name of the object in question.

Note that the only property that can be updated on a policy object after creation is name.

Request Example

{
    "policy": {
        "name": "new_name"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

policy

body

object

A structured description of a policy object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A structured representation of data associated with a policy object.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of a policy object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of a policy object.

type

body

string

The name of the policy type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "policy": {
        "created_at": "2015-10-14T09:14:53",
        "data": {},
        "domain": null,
        "id": "ac5415bd-f522-4160-8be0-f8853e4bc332",
        "name": "dp01",
        "project": "42d9e9663331431f97b75e25136307ff",
        "spec": {
            "description": "A policy for node deletion.",
            "properties": {
                "criteria": "OLDEST_FIRST",
                "destroy_after_deletion": true,
                "grace_period": 60,
                "reduce_desired_capacity": false
            },
            "type": "senlin.policy.deletion",
            "version": "1.0"
        },
        "type": "senlin.policy.deletion-1.0",
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
DELETE
/v1/policies/{policy_id}

Delete policy

Deletes a policy.

Response Codes

A policy cannot be deleted if it is still attached to cluster(s). In that case, a 409 error will be returned.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

policy_id

path

string

The name, UUID or short-UUID of a policy object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/policies/validate

Validate policy

Validates a policy.

This API is only available since API microversion 1.2.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

policy

body

object

A structured description of a policy object.

spec

body

object

The detailed specification of a policy object.

Request Example

{
    "policy": {
        "spec": {
            "properties": {
                "adjustment": {
                    "min_step": 1,
                    "number": 1,
                    "type": "CHANGE_IN_CAPACITY"
                },
                "event": "CLUSTER_SCALE_IN"
            },
            "type": "senlin.policy.scaling",
            "version": "1.0"
        }
    }
}

Response Parameters

The response contains properties as if the policy has been created.

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

policy

body

object

A structured description of a policy object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A structured representation of data associated with a policy object.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of a policy object.

name

body

string

The name of the object in question.

project

body

UUID

The ID of the project a resource is created in.

spec

body

object

The detailed specification of a policy object.

type

body

string

The name of the policy type.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "policy": {
        "created_at": null,
        "data": {},
        "domain": null,
        "id": null,
        "name": "validated_policy",
        "project": "1d567ed4ef51453a85545f018b68c26d",
        "spec": {
            "properties": {
                "adjustment": {
                    "min_step": 1,
                    "number": 1,
                    "type": "CHANGE_IN_CAPACITY"
                },
                "event": "CLUSTER_SCALE_IN"
            },
            "type": "senlin.policy.scaling",
            "version": "1.0"
        },
        "type": "senlin.policy.scaling-1.0",
        "updated_at": null,
        "user": "990e4c1f4a414f74990b17d16f2540b5"
    }
}

Clusters

Lists all clusters and creates, shows information for, updates, deletes, and triggers an action on a cluster.

GET
/v1/clusters

List clusters

Lists clusters.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

limit (Optional)

query

integer

Requests a page size of resources. Returns a number of resources up to the limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

UUID

The ID of the last-seen resource. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

global_project (Optional)

query

boolean

Indicates whether to include resources for all projects or resources for the current project in the response.

If you are an administrative user and you set this value to true, the call returns all resources from all projects. Default is false, which returns only resources in the current project.

name (Optional)

query

string

Filters the response by the specified name property of the object, such as policy_name or name property of cluster.

status (Optional)

query

string

Filters the resource collection by the status property.

The sorting keys include name, status, init_at, created_at and updated_at.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

clusters

body

array

A list of cluster objects.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

config

body

object

The structured config associated with the cluster.

data

body

object

The structured data associated with the cluster.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

desired_capacity

body

integer

The desired capacity of a cluster. When creating a cluster, this value is set to 0 by default.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the cluster object.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

max_size

body

integer

The maximum size of a cluster, i.e. the maximum number of nodes that can be members of the cluster. A value of -1 means that the cluster doesn’t have an upper bound regarding the number of member nodes.

metadata

body

object

A collection of key-value pairs associated with an object.

min_size

body

integer

The minimum size of a cluster, i.e. the minimum number of nodes that can be members of the cluster.

name

body

string

The name of the object in question.

nodes

body

array

A list of the UUIDs of node objects which are members of the current cluster.

policies

body

array

A list of UUIDs of the policies attached to current cluster.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

The string representation of the current status of the cluster.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

timeout

body

integer

The default timeout value (in seconds) of cluster operations.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "clusters": [
        {
            "config": {},
            "created_at": "2015-02-10T14:26:14Z",
            "data": {},
            "dependents": {},
            "desired_capacity": 4,
            "domain": null,
            "id": "7d85f602-a948-4a30-afd4-e84f47471c15",
            "init_at": "2015-02-10T14:26:11",
            "max_size": -1,
            "metadata": {},
            "min_size": 0,
            "name": "cluster1",
            "nodes": [
                "b07c57c8-7ab2-47bf-bdf8-e894c0c601b9",
                "ecc23d3e-bb68-48f8-8260-c9cf6bcb6e61",
                "da1e9c87-e584-4626-a120-022da5062dac"
            ],
            "policies": [],
            "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
            "profile_name": "mystack",
            "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
            "status": "ACTIVE",
            "status_reason": "Cluster scale-in succeeded",
            "timeout": 3600,
            "updated_at": null,
            "user": "5e5bf8027826429c96af157f68dc9072"
        }
    ]
}
POST
/v1/clusters

Create cluster

Creates a cluster.

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.

500 - Internal Server Error

Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

config (Optional)

body

object

The structured config associated with the cluster.

cluster

body

object

The structured definition of a cluster object.

name

body

string

The name of a cluster object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

desired_capacity

body

integer

The desired capacity of a cluster. When creating a cluster, this value is set to 0 by default.

profile_id

body

string

The name, short-ID, or UUID of a profile.

min_size (Optional)

body

integer

The minimum size of a cluster, i.e. the minimum number of nodes that can be members of the cluster.

timeout (Optional)

body

integer

The new timeout value (in seconds) of cluster operations.

max_size (Optional)

body

integer

The maximum size of a cluster, i.e. the maximum number of nodes that can be members of the cluster. A value of -1 means that the cluster doesn’t have an upper bound regarding the number of member nodes.

metadata (Optional)

body

object

A collection of key-value pairs associated with an object.

Request Example

{
    "cluster": {
        "config": {},
        "desired_capacity": 0,
        "max_size": -1,
        "metadata": {},
        "min_size": 0,
        "name": "test_cluster",
        "profile_id": "mystack",
        "timeout": null
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

cluster

body

object

The structured definition of a cluster object.

config

body

object

The structured config associated with the cluster.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

The structured data associated with the cluster.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

desired_capacity

body

integer

The desired capacity of a cluster. When creating a cluster, this value is set to 0 by default.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the cluster object.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

max_size

body

integer

The maximum size of a cluster, i.e. the maximum number of nodes that can be members of the cluster. A value of -1 means that the cluster doesn’t have an upper bound regarding the number of member nodes.

metadata

body

object

A collection of key-value pairs associated with an object.

min_size

body

integer

The minimum size of a cluster, i.e. the minimum number of nodes that can be members of the cluster.

name

body

string

The name of the object in question.

nodes

body

array

A list of the UUIDs of node objects which are members of the current cluster.

policies

body

array

A list of UUIDs of the policies attached to current cluster.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

The string representation of the current status of the cluster.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

timeout

body

integer

The default timeout value (in seconds) of cluster operations.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "cluster": {
        "config": {},
        "created_at": null,
        "data": {},
        "dependents": {},
        "desired_capacity": 4,
        "domain": null,
        "id": "45edadcb-c73b-4920-87e1-518b2f29f54b",
        "init_at": "2015-02-10T14:16:10",
        "max_size": -1,
        "metadata": {},
        "min_size": 0,
        "name": "test_cluster",
        "nodes": [],
        "policies": [],
        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
        "profile_name": "mystack",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "status": "INIT",
        "status_reason": "Initializing",
        "timeout": 3600,
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
GET
/v1/clusters/{cluster_id}

Show cluster details

Shows details for a cluster.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

cluster

body

object

The structured definition of a cluster object.

config

body

object

The structured config associated with the cluster.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

The structured data associated with the cluster.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

desired_capacity

body

integer

The desired capacity of a cluster. When creating a cluster, this value is set to 0 by default.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the cluster object.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

max_size

body

integer

The maximum size of a cluster, i.e. the maximum number of nodes that can be members of the cluster. A value of -1 means that the cluster doesn’t have an upper bound regarding the number of member nodes.

metadata

body

object

A collection of key-value pairs associated with an object.

min_size

body

integer

The minimum size of a cluster, i.e. the minimum number of nodes that can be members of the cluster.

name

body

string

The name of the object in question.

nodes

body

array

A list of the UUIDs of node objects which are members of the current cluster.

policies

body

array

A list of UUIDs of the policies attached to current cluster.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

The string representation of the current status of the cluster.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

timeout

body

integer

The default timeout value (in seconds) of cluster operations.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "cluster": {
        "config": {},
        "created_at": "2015-02-11T15:13:20Z",
        "data": {},
        "dependents": {},
        "desired_capacity": 0,
        "domain": null,
        "id": "45edadcb-c73b-4920-87e1-518b2f29f54b",
        "init_at": "2015-02-10T14:26:10",
        "max_size": -1,
        "metadata": {},
        "min_size": 0,
        "name": "test_cluster",
        "nodes": [],
        "policies": [],
        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
        "profile_name": "mystack",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "status": "ACTIVE",
        "status_reason": "Creation succeeded",
        "timeout": 3600,
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
PATCH
/v1/clusters/{cluster_id}

Update cluster

Updates a cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

cluster

body

object

The structured definition of a cluster object.

config (Optional)

body

object

The structured config associated with the cluster.

name (Optional)

body

string

The new name of the object in question.

profile_id (Optional)

body

string

The name, short-ID, or UUID of a profile.

timeout (Optional)

body

integer

The new timeout value (in seconds) of cluster operations.

metadata (Optional)

body

object

A collection of key-value pairs associated with an object.

profile_only (Optional)

body

boolean

Whether the update of profile is limited to the target cluster. All nodes in the cluster will be updated with the specified new profile if this parameter is set to False. The default value is False.

New in version 1.6

Request Example

{
    "cluster": {
        "metadata": null,
        "name": null,
        "profile_id": null,
        "timeout": 30,
        "profile_only": true
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

cluster

body

object

The structured definition of a cluster object.

config

body

object

The structured config associated with the cluster.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

The structured data associated with the cluster.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

desired_capacity

body

integer

The desired capacity of a cluster. When creating a cluster, this value is set to 0 by default.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the cluster object.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

max_size

body

integer

The maximum size of a cluster, i.e. the maximum number of nodes that can be members of the cluster. A value of -1 means that the cluster doesn’t have an upper bound regarding the number of member nodes.

metadata

body

object

A collection of key-value pairs associated with an object.

min_size

body

integer

The minimum size of a cluster, i.e. the minimum number of nodes that can be members of the cluster.

name

body

string

The name of the object in question.

nodes

body

array

A list of the UUIDs of node objects which are members of the current cluster.

policies

body

array

A list of UUIDs of the policies attached to current cluster.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

The string representation of the current status of the cluster.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

timeout

body

integer

The default timeout value (in seconds) of cluster operations.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "cluster": {
        "config": {},
        "created_at": "2015-02-11T15:13:20Z",
        "data": {},
        "dependents": {},
        "desired_capacity": 0,
        "domain": null,
        "id": "45edadcb-c73b-4920-87e1-518b2f29f54b",
        "init_at": "2015-02-10T14:26:10",
        "max_size": -1,
        "metadata": {},
        "min_size": 0,
        "name": "test_cluster",
        "nodes": [],
        "policies": [],
        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
        "profile_name": "mystack",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "status": "UPDATING",
        "status_reason": "Updating",
        "timeout": 3600,
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
DELETE
/v1/clusters/{cluster_id}

Delete cluster

Deletes a cluster.

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

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

POST
/v1/clusters/{cluster_id}/actions

Resize a Cluster

Resize a cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

adjustment_type (Optional)

body

string

The type of size adjustment. The valid values are:

  • EXACT_CAPACITY: The adjustment number specified is to be interpreted as the targeted desired_capacity. This value has to be a non-negative integer.

  • CHANGE_IN_CAPACITY: The adjustment number specified is to be treated as the number of nodes to add or remove. The value has to be a non-zero integer. A positive number can be used to specify the number of nodes to add while a negative number can be specified to indicate the number of nodes to remove.

  • CHANGE_IN_PERCENTAGE: The adjustment number will be interpreted as a percentile relative to a cluster’s current desired_capacity. The adjustment number can be a positive or negative float value.

This parameter is optional when a resize request is only about changing the min_size and/or max_size of the cluster. Otherwise, it is required. When this parameter is specified, the number parameter has to be provided as well.

number (Optional)

body

number

The number of adjustment. The interpretation of the value depends on the value of the adjustment_type parameter. This parameter is mandatory when adjustment_type is specified. Otherwise, it is optional.

When adjustment_type is specified as CHANGE_IN_PERCENTAGE, the value of this parameter can be a float number, otherwise it has to be an integer.

min_size (Optional)

body

integer

The value to be set as the new min_size of the cluster.

max_size (Optional)

body

integer

The value to be set as the new max_size of the cluster.

min_step (Optional)

body

integer

When adjustment_type is set to CHANGE_IN_PERCENTAGE, often times the computed value is a float which could be less than 1.0. The min_step can be used to specify that at least this number of nodes will be added or removed.

strict (Optional)

body

boolean

There are cases where the computed number of nodes to adjust will break the size constraints of a cluster, i.e. its min_size or max_size property. If this is the case, the strict parameter can further instructs the senlin engine whether the resize should be done on a best effort basis. If the value is set to True, senlin engine will perform the resize operation while respecting the cluster’s size constraints. Otherwise, if the computed adjustment will break the size constraints, the resize request will be directly rejected.

The action_name in the request body has to be resize.

Request Example

{
    "resize": {
        "adjustment_type": "CHANGE_IN_CAPACITY",
        "max_size": 5,
        "min_size": 1,
        "number": -2,
        "strict": true 
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Scale-in a Cluster

Shrink the size of a cluster by a given number.

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.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

count (Optional)

body

integer

The number of new nodes to add to or remove from the specified cluster. The interpretation is depending on the action requested. Default value is 1.

The action_name in the request body has to be scale_in.

Request Example

{
    "scale_in": {
        "count": 2
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Scale-out a Cluster

Expand the size of a cluster by a given number.

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.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

count (Optional)

body

integer

The number of new nodes to add to or remove from the specified cluster. The interpretation is depending on the action requested. Default value is 1.

The action_name in the request body has to be scale_out.

Request Example

{
    "scale_out": {
        "count": 2
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Add nodes to a Cluster

Add the specified list of nodes to the cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

nodes

body

array

The candidate nodes to be added to or removed from a cluster. The meaning of the parameter is depended on the action requested.

Each item in the list can be the name, the short-ID or the UUID of a node.

The action_name in the request body has to be add_nodes.

Request Example

{
    "add_nodes": {
        "nodes": [
            "node-1234",
            "node-5678"
	]
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Remove nodes from a Cluster

Remove the specified list of nodes from the cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

nodes

body

array

The candidate nodes to be added to or removed from a cluster. The meaning of the parameter is depended on the action requested.

Each item in the list can be the name, the short-ID or the UUID of a node.

destroy_after_deletion (Optional)

body

boolean

Whether deleted nodes to be destroyed right away.

New in version 1.4

The action_name in the request body has to be del_nodes.

Request Example

{
    "del_nodes": {
        "nodes": [
            "aff0135",
            "e28a207"
        ],
        "destroy_after_deletion": false
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Replace nodes in a Cluster

Replace the specified nodes in a cluster.

This API is only available since API microversion 1.3.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

nodes

body

object

A collection of key-value pairs. Each key is the node to be replaced of a cluster, each value is the node used to replace the original one.

Each item in of the key-value pairs can be the name, the short-ID or the UUID of a node.

The action_name in the request body has to be replace_nodes.

Request Example

{
    "replace_nodes": {
        "nodes": {
            "node-1234": "node-5678"
        }
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Attach a Policy to a Cluster

Attach the specified policy to the cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

policy_id

body

string

The name, UUID or short-UUID of a policy object.

enabled

body

boolean

Whether the policy is enabled on the attached cluster.

The action_name in the request body has to be policy_attach.

Request Example

{
    "policy_attach": {
        "policy_id": "dp01",
        "enabled": false
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Detach a Policy from a Cluster

Detach the specified policy from the cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

policy_id

body

string

The name, UUID or short-UUID of a policy object.

The action_name in the request body has to be policy_detach.

Request Example

{
    "policy_detach": {
        "policy_id": "5630fb31"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Update a Policy on a Cluster

Update the specified policy on the cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

policy_id

body

string

The name, UUID or short-UUID of a policy object.

enabled

body

boolean

Whether the policy is enabled on the attached cluster.

The action_name in the request body has to be update_policy.

Request Example

{
    "update_policy": {
        "policy_id": "dp01",
        "enabled": false
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
GET
/v1/clusters/{cluster_id}/attrs/{path}

Collect Attributes Across a Cluster

Aggregate an attribute value across all nodes in a cluster.

This API is only available since API microversion 1.2.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

path

path

string

A Json path format string for node attribute.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

cluster_attributes

body

array

A list of dictionaries each containing the node ID and the corresponding attribute value.

id

body

UUID

A UUID string that uniquely identifies a node object.

value (Optional)

body

object

The attribute value on a specific node. The value could be of any data type that is valid for the attribute.

POST
/v1/clusters/{cluster_id}/actions

Check a Cluster’s Health Status

Check the health status of all nodes in a cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

params (Optional)

body

object

The optional parameters provided to a cluster check operation. The detailed keys and values are not checked at the moment.

The action_name in the request body has to be check.

Request Example

{
    "check": {}
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Recover a Cluster to a Healthy Status

Recover the health status for all nodes in a cluster.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

params (Optional)

body

object

The optional parameters provided to a cluster recover operation. The detailed keys and values are not checked at the moment.

The action_name in the body must be recover. The valid parameters include:

  • operation: A string specifying the action to be performed for node recovery.

  • operation_params: An optional dictionary specifying the key-value arguments for the specific node recovery action.

  • check: A boolean specifying whether the engine should check the actual statuses of cluster nodes before performing the recovery action. This parameter is added since microversion 1.6 and it defaults to False.

  • check_capacity: A boolean specifying whether check the current number of nodes and the desired_capacity field. Will delete nodes if the number of nodes is larger than desired_capacity, otherwise, create nodes. This parameter is added since microversion 1.7 and it defaults to False.

Request Example

{
    "recover": {
        "operation": "reboot",
        "operation_params": {
            "type": "soft"
        },
        "check": false
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/ops

Perform an Operation on a Cluster

Perform an operation on the specified cluster. The specified operation and its associated parameters must validate against the profile type of the cluster.

This API is only available since API microversion 1.4.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

operation

body

object

A structured definition of an operation to be performed. The object is usually expressed as:

<operation_name>: {
  filters: {
    <cond_1>: <var_1>,
    <cond_2>: <var_2>
  }
  params: {
    <param_1>: <value_1>,
    <param_2>: <value_2>
    ...
  }
}

The <operation_name> specifies the operation to be performed, in which the filters object contains a collection of filtering rules, and the params object provide the parameters (if any) to the operation. Each individual operation has its own set of parameters, as supported by the profile type of the target cluster.

Request Example

{
    "reboot": {
        "filters": {
            "role": "slave"
        },
        "params": {
            "type": "soft"
        }
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}
POST
/v1/clusters/{cluster_id}/actions

Complete Lifecycle on a Cluster action

Complete lifecycle action and trigger deletion of nodes.

This API is only available since API microversion 1.9.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

lifecycle_action_token

body

UUID

The UUID of the lifecycle action to be completed.

The action_name in the body must be complete_lifecycle.

Request Example

{
    "complete_lifecycle": {
        "lifecycle_action_token": "ffbb9175-d510-4bc1-b676-c6aba2a4ca81"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "2a0ff107-e789-4660-a122-3816c43af703"
}

Cluster Policies (cluster-policies)

Lists all cluster policies and shows information for a cluster policy.

GET
/v1/clusters/{cluster_id}/policies

List all cluster policies

Lists all policies attached to specific cluster

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

enabled (Optional)

query

string

Filters the response by a policy enabled status on the cluster.

policy_name (Optional)

query

string

Filters the response by the specified name property of the object, such as policy_name or name property of cluster.

policy_type (Optional)

query

string

Filters the response by the specified type property of the object, such as policy_type property of cluster-policy binding object or type property of policy object.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

cluster_policies

body

array

A list of cluster_policy objects.

cluster_id

body

UUID

The UUID of the cluster object.

cluster_name

body

string

The name of a cluster object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

enabled

body

boolean

Whether the policy is enabled on the attached cluster.

id

body

UUID

The UUID of a cluster_policy object.

policy_id

body

UUID

The UUID of a policy object.

policy_name

body

string

The name of a policy object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

policy_type

body

string

The name of the policy type.

Response Example

{
    "cluster_policies": [
        {
            "cluster_id": "7d85f602-a948-4a30-afd4-e84f47471c15",
            "cluster_name": "cluster4",
            "enabled": true,
            "id": "06be3a1f-b238-4a96-a737-ceec5714087e",
            "policy_id": "714fe676-a08f-4196-b7af-61d52eeded15",
            "policy_name": "dp01",
            "policy_type": "senlin.policy.deletion-1.0"
        },
        {
            "cluster_id": "7d85f602-a948-4a30-afd4-e84f47471c15",
            "cluster_name": "cluster4",
            "enabled": true,
            "id": "abddc45e-ac31-4f90-93cc-db55a7d8dd6d",
            "policy_id": "e026e09f-a3e9-4dad-a1b9-d7ba316026a1",
            "policy_name": "sp1",
            "policy_type": "senlin.policy.scaling-1.0"
        }
    ]
}
GET
/v1/clusters/{cluster_id}/policies/{policy_id}

Show cluster_policy details

Shows details for a cluster policy.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

cluster_id

path

string

The name, UUID or short-UUID of a cluster object.

policy_id

path

string

The name, UUID or short-UUID of a policy object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

cluster_policy

body

object

The structured description of a cluster_policy object.

cluster_id

body

UUID

The UUID of the cluster object.

cluster_name

body

string

The name of a cluster object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

enabled

body

boolean

Whether the policy is enabled on the attached cluster.

id

body

UUID

The UUID of a cluster_policy object.

policy_id

body

UUID

The UUID of a policy object.

policy_name

body

string

The name of a policy object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

policy_type

body

string

The name of the policy type.

Response Example

{
    "cluster_policy": {
        "cluster_id": "7d85f602-a948-4a30-afd4-e84f47471c15",
        "cluster_name": "cluster4",
        "enabled": true,
        "id": "06be3a1f-b238-4a96-a737-ceec5714087e",
        "policy_id": "714fe676-a08f-4196-b7af-61d52eeded15",
        "policy_name": "dp01",
        "policy_type": "senlin.policy.deletion-1.0"
    }
}

Nodes

Lists all nodes, and creates, shows information for, updates, deletes a node.

GET
/v1/nodes

List nodes

Lists all nodes.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

limit (Optional)

query

integer

Requests a page size of resources. Returns a number of resources up to the limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

UUID

The ID of the last-seen resource. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

global_project (Optional)

query

boolean

Indicates whether to include resources for all projects or resources for the current project in the response.

If you are an administrative user and you set this value to true, the call returns all resources from all projects. Default is false, which returns only resources in the current project.

cluster_id (Optional)

query

string

The name, short-ID or UUID of the cluster object.

name (Optional)

query

string

Filters the response by the specified name property of the object, such as policy_name or name property of cluster.

status (Optional)

query

string

Filters the resource collection by the status property.

The sorting keys include name, index, status, init_at, created_at and updated_at.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

nodes

body

array

A list of node objects.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A map containing key-value pairs associated with a node object.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

A UUID string that uniquely identifies a node object.

index

body

integer

An integer that uniquely identifies a node within its owning cluster.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

physical_id

body

UUID

The UUID of the physical resource represented by the node object.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

role

body

string

A string describing the role played by a node inside a cluster.

status

body

string

The string representation of the current status of the node object.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

tainted

body

bool

A boolean indicating whether a node is considered tainted. Tainted nodes are selected first during scale-in operations. This field is only returned starting with API microversion 1.13 or greater.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "nodes": [
        {
            "cluster_id": "e395be1e-8d8e-43bb-bd6c-943eccf76a6d",
            "created_at": "2016-05-13T07:02:20Z",
            "data": {},
            "dependents": {},
            "domain": null,
            "id": "82fe28e0-9fcb-42ca-a2fa-6eb7dddd75a1",
            "index": 2,
            "init_at": "2016-05-13T07:02:04Z",
            "metadata": {},
            "name": "node-e395be1e-002",
            "physical_id": "66a81d68-bf48-4af5-897b-a3bfef7279a8",
            "profile_id": "d8a48377-f6a3-4af4-bbbb-6e8bcaa0cbc0",
            "profile_name": "pcirros",
            "project_id": "eee0b7c083e84501bdd50fb269d2a10e",
            "role": "",
            "status": "ACTIVE",
            "status_reason": "Creation succeeded",
            "updated_at": null,
            "user": "ab79b9647d074e46ac223a8fa297b846"
        }
    ]
}
POST
/v1/nodes

Create node

Creates a node.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

node

body

object

A structured description of a node object.

role (Optional)

body

string

A string describing the new role played by a node inside a cluster.

profile_id

body

string

The name, short-ID, or UUID of a profile.

cluster_id (Optional)

body

string

The name, short-ID or UUID of the cluster object a node belongs to.

name

body

string

The name of a node object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

metadata (Optional)

body

object

A collection of key-value pairs associated with an object.

Request Example

{
    "node": {
        "cluster_id": null,
        "metadata": {},
        "name": "node009",
        "profile_id": "mystack",
        "role": "master"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

node

body

object

A structured description of a node object.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A map containing key-value pairs associated with a node object.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

A UUID string that uniquely identifies a node object.

index

body

integer

An integer that uniquely identifies a node within its owning cluster.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

physical_id

body

UUID

The UUID of the physical resource represented by the node object.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

role

body

string

A string describing the role played by a node inside a cluster.

status

body

string

The string representation of the current status of the node object.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

tainted

body

bool

A boolean indicating whether a node is considered tainted. Tainted nodes are selected first during scale-in operations. This field is only returned starting with API microversion 1.13 or greater.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "node": {
        "cluster_id": null,
        "created_at": null,
        "data": {},
        "dependents": {},
        "domain": null,
        "id": "0df0931b-e251-4f2e-8719-4ebfda3627ba",
        "index": -1,
        "init_at": "2015-03-05T08:53:15Z",
        "metadata": {},
        "name": "node009",
        "physical_id": "",
        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
        "profile_name": "mystack",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "role": "master",
        "status": "INIT",
        "status_reason": "Initializing",
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
POST
/v1/nodes/adopt

Adopt node

Adopts a node.

This API is only available since API microversion 1.7.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

identity

body

string

The ID or name of the physical resource to be adopted.

metadata (Optional)

body

object

A collection of key-value pairs associated with an object.

name (Optional)

body

string

The name of a node object. If specified, the name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

overrides (Optional)

body

object

If specified, provides a collection of key-value pairs that will override the property name and values extracted from the spec extracted from the existing physical node.

role (Optional)

body

string

A string describing the new role played by a node inside a cluster.

snapshot (Optional)

body

bool

A flat indicating whether a shapshot of the existing physical object should be created before the object is adopted as a node.

type

body

string

The name of the profile type.

Request Example

{
    "identity": "65e27958-d6dc-4b0e-87bf-78e8f5536cbc",
    "metadata": {},
    "name": "node009",
    "overrides": null,
    "role": "master",
    "snapshot": true,
    "type": "os.nova.server-1.0"
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

node

body

object

A structured description of a node object.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A map containing key-value pairs associated with a node object.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

A UUID string that uniquely identifies a node object.

index

body

integer

An integer that uniquely identifies a node within its owning cluster.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

physical_id

body

UUID

The UUID of the physical resource represented by the node object.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

role

body

string

A string describing the role played by a node inside a cluster.

status

body

string

The string representation of the current status of the node object.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

tainted

body

bool

A boolean indicating whether a node is considered tainted. Tainted nodes are selected first during scale-in operations. This field is only returned starting with API microversion 1.13 or greater.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "node": {
        "cluster_id": null,
        "created_at": null,
        "data": {},
        "domain": null,
        "id": "0df0931b-e251-4f2e-8719-4ebfda3627ba",
        "index": -1,
        "init_at": "2015-03-05T08:53:15Z",
        "metadata": {},
        "name": "node009",
        "physical_id": "65e27958-d6dc-4b0e-87bf-78e8f5536cbc",
        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
        "profile_name": "prof-node009",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "role": "master",
        "status": "ACTIVE",
        "status_reason": "Node adopted successfully",
        "updated_at": null,
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
POST
/v1/nodes/adopt-preview

Adopt node (preview)

Preview a node adoption.

This API is only available since API microversion 1.7.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

identity

body

string

The ID or name of the physical resource to be adopted.

overrides (Optional)

body

object

If specified, provides a collection of key-value pairs that will override the property name and values extracted from the spec extracted from the existing physical node.

snapshot (Optional)

body

bool

A flat indicating whether a shapshot of the existing physical object should be created before the object is adopted as a node.

type

body

string

The name of the profile type.

Request Example

{
    "identity": "65e27958-d6dc-4b0e-87bf-78e8f5536cbc",
    "overrides": null,
    "snapshot": true,
    "type": "os.nova.server-1.0"
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

node_preview

body

object

A structured representation of the node to be adopted. Note this is a preview version which only contains the spec of the profile to be created.

cluster_id

body

UUID

The UUID of the cluster object.

type

body

string

The name of the profile type.

version

body

string

The version of the profile type.

properties

body

object

The detailed specification of the profile.

Response Example

{
    "node_preview": {
        "properties": {
            "flavor": "m1.small",
            "image": "F20",
            "key_name": "oskey",
            "name": "F20_server",
            "networks": [
                {
                    "network": "private"
                }
            ],
            "security_groups": [
                "default"
            ]
        },
        "type": "os.nova.server",
        "version": 1.0
    }
}
GET
/v1/nodes/{node_id}

Show node details

Shows details about a node.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

node_id

path

string

The name, short-ID or UUID of a node object.

show_details (Optional)

query

boolean

A boolean indicating whether the detailed information about the physical resource associated with the node object will be returned.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

node

body

object

A structured description of a node object.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A map containing key-value pairs associated with a node object.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

A UUID string that uniquely identifies a node object.

index

body

integer

An integer that uniquely identifies a node within its owning cluster.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

physical_id

body

UUID

The UUID of the physical resource represented by the node object.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

role

body

string

A string describing the role played by a node inside a cluster.

status

body

string

The string representation of the current status of the node object.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

tainted

body

bool

A boolean indicating whether a node is considered tainted. Tainted nodes are selected first during scale-in operations. This field is only returned starting with API microversion 1.13 or greater.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "node": {
        "cluster_id": null,
        "created_at": "2015-02-10T12:03:16Z",
        "data": {},
        "dependents": {},
        "domain": null,
        "id": "d5779bb0-f0a0-49c9-88cc-6f078adb5a0b",
        "index": -1,
        "init_at": "2015-02-10T12:03:13",
        "metadata": {},
        "name": "node1",
        "physical_id": "f41537fa-22ab-4bea-94c0-c874e19d0c80",
        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
        "profile_name": "mystack",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "role": null,
        "status": "ACTIVE",
        "status_reason": "Creation succeeded",
        "updated_at": "2015-03-04T04:58:27Z",
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
PATCH
/v1/nodes/{node_id}

Update node

Updates a node.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

node_id

path

string

The name, short-ID or UUID of a node object.

node

body

object

A structured description of a node object.

name (Optional)

body

string

The new name of the object in question.

profile_id (Optional)

body

string

The name, short-ID, or UUID of a profile.

role (Optional)

body

string

A string describing the new role played by a node inside a cluster.

metadata (Optional)

body

object

A collection of key-value pairs associated with an object.

tainted (Optional)

body

bool

A boolean indicating whether a node is considered tainted. Tainted nodes are selected first during scale-in operations. This parameter is only accepted starting with API microversion 1.13 or greater.

Request Example

{
    "node": {
        "name": "new_node_name"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

node

body

object

A structured description of a node object.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A map containing key-value pairs associated with a node object.

dependents

body

object

A dict contains dependency information between nova server, heat stack cluster and container cluster.

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

A UUID string that uniquely identifies a node object.

index

body

integer

An integer that uniquely identifies a node within its owning cluster.

init_at

body

string

The date and time when the object was initialized. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

metadata

body

object

A collection of key-value pairs associated with an object.

name

body

string

The name of the object in question.

physical_id

body

UUID

The UUID of the physical resource represented by the node object.

profile_id

body

UUID

The UUID of the profile.

profile_name

body

string

The name of a profile object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

project

body

UUID

The ID of the project a resource is created in.

role

body

string

A string describing the role played by a node inside a cluster.

status

body

string

The string representation of the current status of the node object.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

tainted

body

bool

A boolean indicating whether a node is considered tainted. Tainted nodes are selected first during scale-in operations. This field is only returned starting with API microversion 1.13 or greater.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "node": {
        "cluster_id": null,
        "created_at": "2015-02-10T12:03:16Z",
        "data": {},
        "dependents": {},
        "domain": null,
        "id": "d5779bb0-f0a0-49c9-88cc-6f078adb5a0b",
        "index": -1,
        "init_at": "2015-02-10T12:03:13",
        "metadata": {},
        "name": "node1",
        "physical_id": "f41537fa-22ab-4bea-94c0-c874e19d0c80",
        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
        "profile_name": "mystack",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "role": null,
        "status": "ACTIVE",
        "status_reason": "Creation succeeded",
        "updated_at": "2015-03-04T04:58:27Z",
        "user": "5e5bf8027826429c96af157f68dc9072"
    }
}
DELETE
/v1/nodes/{node_id}

Delete node

Deletes a node.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

node_id

path

string

The name, short-ID or UUID of a node object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

POST
/v1/nodes/{node_id}/actions

Check a Node’s Health

Check the health status of the specified node.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

node_id

path

string

The name, short-ID or UUID of a node object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

The action_name in the body must be check.

Request Example

{
    "check": {}
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "7f760b61-7b15-4a50-af05-319922fa3229"
}
POST
/v1/nodes/{node_id}/actions

Recover a Node to Healthy Status

Recover the specified node to its healthy status.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

node_id

path

string

The name, short-ID or UUID of a node object.

action

body

object

A structured definition of an action to be executed. The object is usually expressed as:

<action_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <action_name> indicates the requested action while the <param> keys provide the associated parameters to the action. Each individual action has its own set of parameters.

The action_name in the body must be recover. The valid parameters include:

  • operation: A string specifying the action to be performed for node recovery.

  • operation_params: An optional dictionary specifying the key-value arguments for the specific node recovery action.

  • check: A boolean specifying whether the engine should check the node’s actual status before performing the recovery action. This parameter is added since microversion 1.6.

Request Example

{
    "recover": {
        "operation": "reboot",
        "operation_params": {
            "type": "soft"
        },
        "check": false
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "7f760b61-7b15-4a50-af05-319922fa3229"
}
POST
/v1/nodes/{node_id}/ops

Perform an Operation on a Node

Perform the specified operation on the specified node.

This API is only available since API microversion 1.4.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

node_id

path

string

The name, short-ID or UUID of a node object.

operation

body

object

A structured definition of an operation to be performed. The object is usually expressed as:

<operation_name>: {
  <param_1>: <value_1>
  <param_2>: <value_2>
  ...
}

The <operation_name> specifies the operation to be performed while the <param_n> keys provide the parameters (if any) to the operation. Each individual operation has its own set of parameters, as supported by the profile type of the target cluster or node.

Request Example

{
    "reboot": {
        "type": "SOFT"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
  "action": "7f760b61-7b15-4a50-af05-319922fa3229"
}

Receivers (receivers)

Lists all receivers and creates, shows information for, and deletes a receiver.

GET
/v1/receivers

List receivers

Lists all receivers.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

limit (Optional)

query

integer

Requests a page size of resources. Returns a number of resources up to the limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

UUID

The ID of the last-seen resource. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

global_project (Optional)

query

boolean

Indicates whether to include resources for all projects or resources for the current project in the response.

If you are an administrative user and you set this value to true, the call returns all resources from all projects. Default is false, which returns only resources in the current project.

name (Optional)

query

string

Filters the response by the specified name property of the object, such as policy_name or name property of cluster.

type (Optional)

query

string

Filters the response by the type property of the receiver.

cluster_id (Optional)

query

string

The name, short-ID or UUID of the cluster object.

action (Optional)

query

string

Filters the response by the action targeted by the receiver.

user (Optional)

query

string

Filters the response by the user property of the receiver.

New in version 1.4

The sorting keys include name, type, action, cluster_id, created_at and user.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

receivers

body

array

A list for receiver objects.

action (Optional)

body

string

The action to initiate when the receiver is triggered. A valid value should be the name of an action that can be applied on a cluster.

actor (Optional)

body

object

A map of key and value pairs to use for authentication.

channel

body

object

The target to be used by user to trigger a receiver. For webhook type of receiver, channel is a webhook URL.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the receiver object.

name

body

string

The name of the object in question.

params

body

object

A map of key and value pairs to use for action creation.

project

body

UUID

The ID of the project a resource is created in.

type

body

string

The type of the receiver.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "receivers": [
        {
            "action": "CLUSTER_SCALE_OUT",
            "actor": {
                "trust_id": [
                    "6dc6d336e3fc4c0a951b5698cd1236d9"
                ]
            },
            "channel": {
                "alarm_url": "http://node1:8777/v1/webhooks/e03dd2e5-8f2e-4ec1-8c6a-74ba891e5422/trigger?V=2&count=1"
            },
            "cluster_id": "ae63a10b-4a90-452c-aef1-113a0b255ee3",
            "created_at": "2015-06-27T05:09:43",
            "domain": "Default",
            "id": "573aa1ba-bf45-49fd-907d-6b5d6e6adfd3",
            "name": "cluster_inflate",
            "params": {
                "count": "1"
            },
            "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
            "type": "webhook",
            "updated_at": null,
            "user": "b4ad2d6e18cc2b9c48049f6dbe8a5b3c"
        }
    ]
}
POST
/v1/receivers

Create receiver

Creates a receiver.

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.

500 - Internal Server Error

Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

receiver

body

object

The structured definition of a receiver object.

name

body

string

The name of a receiver object. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens and its length must be less than 255.

cluster_id (Optional)

body

string

The name, short-ID or UUID of the cluster object a node belongs to.

type

body

string

The type of the receiver. The valid values include webhook and message.

action (Optional)

body

string

The action to initiate when the receiver is triggered. A valid value should be the name of an action that can be applied on a cluster.

actor (Optional)

body

object

A map of key and value pairs to use for authentication.

params (Optional)

body

object

A map of key and value pairs to use for action creation. Some actions might require certain input parameters.

Request Example

{
    "receiver": {
        "action": "CLUSTER_SCALE_OUT",
        "cluster_id": "cf99d754-3cdc-47f4-8a29-cd14f02f5436",
        "name": "cluster_inflate",
        "params": {
            "count": "1"
        },
        "type": "webhook"
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

receiver

body

object

The structured definition of a receiver object.

action (Optional)

body

string

The action to initiate when the receiver is triggered. A valid value should be the name of an action that can be applied on a cluster.

actor (Optional)

body

object

A map of key and value pairs to use for authentication.

channel

body

object

The target to be used by user to trigger a receiver. For webhook type of receiver, channel is a webhook URL.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the receiver object.

name

body

string

The name of the object in question.

params

body

object

A map of key and value pairs to use for action creation.

project

body

UUID

The ID of the project a resource is created in.

type

body

string

The type of the receiver.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "receiver": {
        "action": "CLUSTER_SCALE_OUT",
        "actor": {
            "trust_id": [
                "6dc6d336e3fc4c0a951b5698cd1236d9"
            ]
        },
        "channel": {
            "alarm_url": "http://node1:8777/v1/webhooks/e03dd2e5-8f2e-4ec1-8c6a-74ba891e5422/trigger?V=2&count=1"
        },
        "cluster_id": "ae63a10b-4a90-452c-aef1-113a0b255ee3",
        "created_at": "2015-06-27T05:09:43",
        "domain": "Default",
        "id": "573aa1ba-bf45-49fd-907d-6b5d6e6adfd3",
        "name": "cluster_inflate",
        "params": {
            "count": "1"
        },
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "type": "webhook",
        "updated_at": null,
        "user": "b4ad2d6e18cc2b9c48049f6dbe8a5b3c"
    }
}
GET
/v1/receivers/{receiver_id}

Show receiver details

Shows details for a receiver.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

receiver_id

path

string

The name, UUID or short-UUID of a receiver object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

receiver

body

object

The structured definition of a receiver object.

action (Optional)

body

string

The action to initiate when the receiver is triggered. A valid value should be the name of an action that can be applied on a cluster.

actor (Optional)

body

object

A map of key and value pairs to use for authentication.

channel

body

object

The target to be used by user to trigger a receiver. For webhook type of receiver, channel is a webhook URL.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the receiver object.

name

body

string

The name of the object in question.

params

body

object

A map of key and value pairs to use for action creation.

project

body

UUID

The ID of the project a resource is created in.

type

body

string

The type of the receiver.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "receiver": {
        "action": "CLUSTER_SCALE_OUT",
        "actor": {
            "trust_id": [
                "6dc6d336e3fc4c0a951b5698cd1236d9"
            ]
        },
        "channel": {
            "alarm_url": "http://node1:8777/v1/webhooks/e03dd2e5-8f2e-4ec1-8c6a-74ba891e5422/trigger?V=2&count=1"
        },
        "cluster_id": "ae63a10b-4a90-452c-aef1-113a0b255ee3",
        "created_at": "2015-06-27T05:09:43",
        "domain": "Default",
        "id": "573aa1ba-bf45-49fd-907d-6b5d6e6adfd3",
        "name": "cluster_inflate",
        "params": {
            "count": "1"
        },
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "type": "webhook",
        "updated_at": null,
        "user": "b4ad2d6e18cc2b9c48049f6dbe8a5b3c"
    }
}
PATCH
/v1/receivers/{receiver_id}

Update receiver

Updates a receiver.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

receiver_id

path

string

The name, UUID or short-UUID of a receiver object.

receiver

body

object

The structured definition of a receiver object.

name (Optional)

body

string

The new name of the object in question.

action (Optional)

body

string

The action to initiate when the receiver is triggered. A valid value should be the name of an action that can be applied on a cluster.

params (Optional)

body

object

A map of key and value pairs to use for action creation. Some actions might require certain input parameters.

Request Example

{
    "receiver": {
        "name": "new-name",
        "action": "CLUSTER_SCALE_OUT",
        "params": {
            "count": "2"
        }
    }
}

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

receiver

body

object

The structured definition of a receiver object.

action (Optional)

body

string

The action to initiate when the receiver is triggered. A valid value should be the name of an action that can be applied on a cluster.

actor (Optional)

body

object

A map of key and value pairs to use for authentication.

channel

body

object

The target to be used by user to trigger a receiver. For webhook type of receiver, channel is a webhook URL.

cluster_id

body

UUID

The UUID of the cluster object.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

domain

body

UUID

The ID of the domain a resource is created in.

id

body

UUID

The UUID of the receiver object.

name

body

string

The name of the object in question.

params

body

object

A map of key and value pairs to use for action creation.

project

body

UUID

The ID of the project a resource is created in.

type

body

string

The type of the receiver.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "receiver": {
        "action": "CLUSTER_SCALE_OUT",
        "actor": {
            "trust_id": [
                "6dc6d336e3fc4c0a951b5698cd1236d9"
            ]
        },
        "channel": {
            "alarm_url": "http://node1:8777/v1/webhooks/e03dd2e5-8f2e-4ec1-8c6a-74ba891e5422/trigger?V=2&count=2"
        },
        "cluster_id": "ae63a10b-4a90-452c-aef1-113a0b255ee3",
        "created_at": "2015-06-27T05:09:43",
        "domain": "Default",
        "id": "573aa1ba-bf45-49fd-907d-6b5d6e6adfd3",
        "name": "new-name",
        "params": {
            "count": "2"
        },
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "type": "webhook",
        "updated_at": "2016-03-11T05:10:11",
        "user": "b4ad2d6e18cc2b9c48049f6dbe8a5b3c"
    }
}
DELETE
/v1/receivers/{receiver_id}

Delete receiver

Deletes a receiver.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

This operation does not accept a request body.

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

receiver_id

path

string

The name, UUID or short-UUID of a receiver object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

This operation does not return a response body.

POST
/v1/receivers/{receiver_id}/notify

Notify receiver

Notifies message type receiver.

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.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

This operation does not accept a request body.

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

receiver_id

path

string

The name, UUID or short-UUID of a receiver object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

This operation does not return a response body.

Events (events)

Lists all events and shows information for an event.

GET
/v1/events

List events

Lists all events.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

limit (Optional)

query

integer

Requests a page size of resources. Returns a number of resources up to the limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

level (Optional)

body

string

The level of an event object.

marker (Optional)

query

UUID

The ID of the last-seen resource. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

global_project (Optional)

query

boolean

Indicates whether to include resources for all projects or resources for the current project in the response.

If you are an administrative user and you set this value to true, the call returns all resources from all projects. Default is false, which returns only resources in the current project.

oid (Optional)

query

string

Filters the response by the ID of object associated with an event. Use this filter multiple times to filter by multiple objects.

otype (Optional)

query

string

Filters the response by the type of object associated with an event. Use this filter multiple times to filter by multiple objects. A valid value is CLUSTER or NODE.

oname (Optional)

query

string

Filters the response by the name of object associated with an event. Use this filter multiple times to filter by multiple objects.

cluster_id (Optional)

query

string

The name, short-ID or UUID of the cluster object.

action (Optional)

query

string

Filters the response by the action name associated with an event. Use this filter multiple times to filter by multiple actions.

The sorting keys include timestamp, level, otype, oname, action, status, oid and cluster_id.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

events

body

array

A list of event objects.

action

body

string

The name of an action object.

cluster_id

body

UUID

The UUID of the cluster object.

id

body

UUID

The UUID of an event object.

level

body

string

The level of an event object.

oid

body

UUID

The UUID of an object associated with the event.

oname

body

string

The name of an object associated with the event.

otype

body

string

The type of an object associated with the event.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

The current status of the object associated with the event.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

timestamp

body

string

The date and time when the event was generated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ.

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "events": [
        {
            "action": "create",
            "cluster": null,
            "cluster_id": null,
            "id": "2d255b9c-8f36-41a2-a137-c0175ccc29c3",
            "level": "20",
            "meta_data": {},
            "oid": "0df0931b-e251-4f2e-8719-4ebfda3627ba",
            "oname": "node009",
            "otype": "NODE",
            "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
            "status": "CREATING",
            "status_reason": "Initializing",
            "timestamp": "2015-03-05T08:53:15Z",
            "user": "a21ded6060534d99840658a777c2af5a"
        }
    ]
}
GET
/v1/events/{event_id}

Shows event details

Shows details for an event.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

event_id

path

string

The name, UUID or short-UUID of an event object.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

event

body

object

The structured description of an event object.

action

body

string

The name of an action object.

cluster_id

body

UUID

The UUID of the cluster object.

id

body

UUID

The UUID of an event object.

level

body

string

The level of an event object.

oid

body

UUID

The UUID of an object associated with the event.

oname

body

string

The name of an object associated with the event.

otype

body

string

The type of an object associated with the event.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

The current status of the object associated with the event.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

timestamp

body

string

The date and time when the event was generated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ.

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "event": {
        "action": "create",
        "cluster": null,
        "cluster_id": null,
        "id": "2d255b9c-8f36-41a2-a137-c0175ccc29c3",
        "level": "20",
        "meta_data": {},
        "oid": "0df0931b-e251-4f2e-8719-4ebfda3627ba",
        "oname": "node009",
        "otype": "NODE",
        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
        "status": "CREATING",
        "status_reason": "Initializing",
        "timestamp": "2015-03-05T08:53:15Z",
        "user": "a21ded6060534d99840658a777c2af5a"
    }
}

Webhooks (webhooks)

Triggers an action represented by a webhook. For API microversion less than 1.10, optional params in the query are sent as inputs to be used by the targeted action. For API microversion equal or greater than 1.10, any key-value pairs in the request body are sent as inputs to be used by the targeted action.

POST
/v1/webhooks/{webhook_id}/trigger

Trigger webhook action

Triggers a webhook receiver.

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.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

webhook_id

path

UUID

The UUID of a webhook object.

V

query

string

The webhook implementation version requested.

params (Optional)

query

object

The query string that forms the inputs to use for the targeted action for API microversion less than 1.10.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-Id (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Location

header

string

For asynchronous object operations, the location header contains a string that can be interpreted as a relative URI from where users can track the progress of the action triggered.

action

body

string

A string representation of the action for execution.

Response Example

{
    "action": "290c44fa-c60f-4d75-a0eb-87433ba982a3"
}

Actions

Lists all actions and shows details for an action.

GET
/v1/actions

List actions

Lists all actions.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

limit (Optional)

query

integer

Requests a page size of resources. Returns a number of resources up to the limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

marker (Optional)

query

UUID

The ID of the last-seen resource. Use the limit parameter to make an initial limited request and use the ID of the last-seen resource from the response as the marker parameter value in a subsequent limited request.

sort (Optional)

query

string

Sorts the response by one or more attribute and optional sort direction combinations. A valid direction is asc (ascending) or desc (descending). Default direction is asc (ascending).

Specify the list as <key>[:<direction>].

For example, the following query parameters in the URI sort the resources in the response by name in ascending order and then by status in descending order:

GET /v1/clusters?sort=name:asc,status:desc

global_project (Optional)

query

boolean

Indicates whether to include resources for all projects or resources for the current project in the response.

If you are an administrative user and you set this value to true, the call returns all resources from all projects. Default is false, which returns only resources in the current project.

name (Optional)

query

string

Filters the response by the specified name property of the object, such as policy_name or name property of cluster.

target (Optional)

query

string

Filters the results by the UUID of the targeted object which is usually a cluster.

action (Optional)

query

string

Filters the resulted list using the action field of the object.

status (Optional)

query

string

Filters the results by the status property of an action object.

The sorting keys include name, target, action, created_at and status.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

actions

body

array

A list of action objects.

action

body

string

A string representation of the action for execution.

cause

body

string

An explanation why an action was started.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A structured representation of data associated with an action object.

depended_by

body

array

A list of UUIDs of the actions that depend on the current action.

depends_on

body

array

A list of UUIDs of the actions that the current action depends on.

start_time

body

float

A floating point number that represents the time when an action started execution.

end_time

body

float

A floating point number that represents when an action’s execution has completed.

id

body

UUID

A UUID that uniquely identifies an action object.

inputs

body

object

A collection of key-value pairs that are fed to the action as input parameters.

interval

body

integer

An integer that indicates the interval in seconds between two consecutive executions of a repeatable action.

name

body

string

The name of the object in question.

outputs

body

object

A collection of key-value pairs that were produced during the execution of an action as its outputs.

owner

body

string

The UUID of the owning engine that is currently locking the action for execution.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

A string representation of the current status of the action.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

target

body

string

The UUID of the targeted object (which is usually a cluster).

timeout

body

integer

The number of seconds after which an unfinished action execution will be treated as timeout.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "actions": [
        {
            "action": "NODE_CREATE",
            "cause": "RPC Request",
            "created_at": "2015-12-04T04:54:41Z",
            "data": {},
            "depended_by": [],
            "depends_on": [],
            "end_time": 1425550000.0,
            "id": "2366d440-c73e-4961-9254-6d1c3af7c167",
            "inputs": {},
            "interval": -1,
            "name": "node_create_0df0931b",
            "outputs": {},
            "owner": null,
            "project": "f1fe61dcda2f4618a14c10dc7abc214d",
            "start_time": 1425550000.0,
            "status": "SUCCEEDED",
            "status_reason": "Action completed successfully.",
            "target": "0df0931b-e251-4f2e-8719-4ebfda3627ba",
            "timeout": 3600,
            "updated_at": null,
            "user": "8bcd2cdca7684c02afc9e4f2fc0f0c79"
        },
        {
            "action": "NODE_DELETE",
            "cause": "RPC Request",
            "created_at": "2015-11-04T05:21:41Z",
            "data": {},
            "depended_by": [],
            "depends_on": [],
            "end_time": 1425550000.0,
            "id": "edce3528-864f-41fb-8759-f4707925cc09",
            "inputs": {},
            "interval": -1,
            "name": "node_delete_f0de9b9c",
            "outputs": {},
            "owner": null,
            "project": "f1fe61dcda2f4618a14c10dc7abc214d",
            "start_time": 1425550000.0,
            "status": "SUCCEEDED",
            "status_reason": "Action completed successfully.",
            "target": "f0de9b9c-6d48-4a46-af21-2ca8607777fe",
            "timeout": 3600,
            "updated_at": null,
            "user": "8bcd2cdca7684c02afc9e4f2fc0f0c79"
        }
    ]
}
GET
/v1/actions/{action_id}

Show action details

Shows details for an action.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

action_id

path

string

The name or short-ID or UUID that identifies an action object.

Response Parameters:

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

action

body

string

A string representation of the action for execution.

cause

body

string

An explanation why an action was started.

created_at

body

string

The date and time when the object was created. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

data

body

object

A structured representation of data associated with an action object.

depended_by

body

array

A list of UUIDs of the actions that depend on the current action.

depends_on

body

array

A list of UUIDs of the actions that the current action depends on.

start_time

body

float

A floating point number that represents the time when an action started execution.

end_time

body

float

A floating point number that represents when an action’s execution has completed.

id

body

UUID

A UUID that uniquely identifies an action object.

inputs

body

object

A collection of key-value pairs that are fed to the action as input parameters.

interval

body

integer

An integer that indicates the interval in seconds between two consecutive executions of a repeatable action.

name

body

string

The name of the object in question.

outputs

body

object

A collection of key-value pairs that were produced during the execution of an action as its outputs.

owner

body

string

The UUID of the owning engine that is currently locking the action for execution.

project

body

UUID

The ID of the project a resource is created in.

status

body

string

A string representation of the current status of the action.

status_reason

body

string

The string representation of the reason why the object has transited to its current status.

target

body

string

The UUID of the targeted object (which is usually a cluster).

timeout

body

integer

The number of seconds after which an unfinished action execution will be treated as timeout.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

user

body

UUID

The ID of the user an object is created by.

Response Example

{
    "action": {
        "action": "CLUSTER_DELETE",
        "cause": "RPC Request",
        "created_at": "2015-06-27T05:09:43Z",
        "data": {},
        "depended_by": [],
        "depends_on": [],
        "end_time": 1423570000.0,
        "id": "ffbb9175-d510-4bc1-b676-c6aba2a4ca81",
        "inputs": {},
        "interval": -1,
        "name": "cluster_delete_fcc9b635",
        "outputs": {},
        "owner": null,
        "project": "f1fe61dcda2f4618a14c10dc7abc214d",
        "start_time": 1423570000.0,
        "status": "FAILED",
        "status_reason": "Cluster action FAILED",
        "target": "fcc9b635-52e3-490b-99f2-87b1640e4e89",
        "timeout": 3600,
        "updated_at": null,
        "user": "8bcd2cdca7684c02afc9e4f2fc0f0c79"
    }
}
PATCH
/v1/actions/{action_id}

Update action

Update status of an action.

This API is only available since API microversion 1.12.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

action_id

path

string

The name or short-ID or UUID that identifies an action object.

action

body

object

A structured definition of an action object.

status

body

string

A string representation of the action status to update. CANCELLED is the only valid status at this time.

force (Optional)

query

boolean

A boolean indicating if the action update request should be forced.

Request Example

{
  "action": {
    "status": "CANCELLED",
  }
}

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.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Services (services)

Lists all services for senlin engine.

GET
/v1/services

List services

This API is only available since API microversion 1.7.

Lists all services.

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.

503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Request Parameters

Name

In

Type

Description

OpenStack-API-Version (Optional)

header

string

API microversion request. It takes the form of OpenStack-API-Version: clustering 1.0, where 1.0 is the requested API version.

Response Parameters

Name

In

Type

Description

X-OpenStack-Request-ID (Optional)

header

string

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

services

body

array

A list of service.

binary

body

string

The binary name of the service.

disabled_reason (Optional)

body

string

The reason for disabling a service.

host

body

string

The name of the host.

id

body

UUID

A UUID that uniquely identifies an service object.

state

body

string

The state of the service. One of up or down.

status

body

string

The status of the service. One of enabled or disabled.

topic

body

string

The topic name of the service.

updated_at

body

string

The date and time when the object was last updated. The date and time stamp format is ISO8601: CCYY-MM-DDThh:mm:ssZ. For example: 2016-01-18T00:00:00Z

Response Example

{
    "services": [
        {
            "binary": "senlin-engine",
            "disabled_reason": null,
            "host": "host1",
            "id": "f93f83f6-762b-41b6-b757-80507834d394",
            "state": "up",
            "status": "enabled",
            "topic": "senlin-engine",
            "updated_at": "2017-04-24T07:43:12"
        }
    ]
}