Baremetal Compute API V1 (CURRENT)

Baremetal Compute API V1 (CURRENT)

Service URLs

All API calls through the rest of this document require authentication with the OpenStack Identity service. They also required a base service url that is extracted from the Identity token of type baremetal-compute. This will be the root url that every call below will be added to build a full path.

For instance, if the service url is http://mycompute.pvt/mogan/v1 then the full API call for /servers is http://mycompute.pvt/mogan/v1/servers.

Depending on the deployment the baremetal compute service url might be http or https, a custom port, a custom path, and include your tenant id. The only way to know the urls for your deployment is by using the service catalog. The baremetal compute servic URL should never be hard coded in applications, even if they are only expected to work at a single site. It should always be discovered from the Identity token.

As such, for the rest of this document we will be using short hand where GET /servers really means GET {your_service_url}/servers.

Servers

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

POST
/servers

Create Server

Creates a server.

The progress of this operation depends on the location of the requested image, network I/O, selected type, and other factors.

The Location header returns the full URL to the newly created server and is available as a self and bookmark link in the server representation.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
server body object The dictionary of data represent a server creation request.
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
flavor_uuid body string The flavor reference, as a UUID for the flavor for your server server.
image_uuid body string The UUID of the image to use for your server.
availability_zone (Optional) body string The availability zone from which to launch the server. When you provision resources, you specify from which availability zone you want your server to be built. Typically, you use availability zones to arrange bare metal nodes into logical groups. An availability zone provides a form of physical isolation and redundancy from other availability zones. For server, if some racks in your data center are on a separate power source, you can put servers in those racks in their own availability zone. Availability zones can also help separate different classes of hardware. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure.
networks body array A list of networks of the tenant. Optionally, you can create one or more NICs on the server. To provision the server with a NIC for a network, specify the UUID of the network with the net_id key in a dict in networks list. To provision the server with a specified type of NIC, specify the port-type key in a dict in a networks list. To provision the server with a NIC for an already existing port, specify the port_id in a networks list. Now net_id and port_id are exclusive, so you should use only one of them at one time.
networks.net_id (Optional) body string To provision the server with a NIC for a network, specify the UUID of the network with the net_id key in a dict in networks list.
networks.port_id (Optional) body string To provision the server with a NIC for an already existing port, specify the port_id in a networks list.
metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
user_data (Optional) body string Configuration information or scripts to use upon launch. Must be Base64 encoded.
personality (Optional) body string The file path and contents, text only, to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit is the number of allowed bytes in the decoded, rather than encoded, data.
key_name (Optional) body string Key pair name.
partitions (Optional) body object The partitions info for root disk, this is only allowed when using partition images with root_gb(required), ephemeral_gb, and swap_mb.
scheduler_hints (Optional) body object The dictionary of data send to the scheduler, it represents scheduling options will be passed to scheduler.

Example Create Server: JSON request

{
    "server": {
        "name": "test_server",
        "description": "this is a test server",
        "flavor_uuid": "0607b5f3-6111-424d-ba46-f5de39a6fa69",
        "image_uuid": "efe0a06f-ca95-4808-b41e-9f55b9c5eb98",
        "availability_zone": "mogan",
        "networks": [
            {
                "net_id": "c1940655-8b8e-4370-b8f9-03ba1daeca31"
            },
            {
                "net_id": "8e8ceb07-4641-4188-9b22-840755e92ee2"
            }
        ],
        "metadata": {
            "My Server Name": "Apache1"
        },
        "partitions": {
            "root_gb": 100,
            "ephemeral_gb": 400,
            "swap_mb": 40960
        },
        "personality": [
            {
                "path": "/etc/banner.txt",
                "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ],
        "user_data": "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
        "key_name": "test_key"
    },
    "scheduler_hints": {
        "group": "group1"
    }
}

Response

Name In Type Description
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
flavor_uuid body string The flavor reference, as a UUID for the flavor for your server server.
image_uuid body string The UUID of the image to use for your server.
availability_zone (Optional) body string The availability zone from which to launch the server. When you provision resources, you specify from which availability zone you want your server to be built. Typically, you use availability zones to arrange bare metal nodes into logical groups. An availability zone provides a form of physical isolation and redundancy from other availability zones. For server, if some racks in your data center are on a separate power source, you can put servers in those racks in their own availability zone. Availability zones can also help separate different classes of hardware. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure.
addresses body object The addresses for the server.
node (Optional) body string The node which our server associated with. Only visible for admin users.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server
status body string The status of this server. Usually, “building”, “active”, “error”, or “None”.
power_state body string The current power state of this server. Usually, “power on” or “power off”, but may be “None” if Mogan is unable to determine the power state (eg, due to hardware failure)
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
updated_at body string

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

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

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

created_at body string

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

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

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

metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
affinity_zone (Optional) body string The affinity zone which the server belongs to.
key_name (Optional) body string Key pair name.
partitions (Optional) body object The partitions info for root disk, this is only allowed when using partition images with root_gb(required), ephemeral_gb, and swap_mb.
locked body boolean The lock state of a server.

Example Create Server: JSON response

{
    "name": "test_server",
    "description": "this is a test server",
    "flavor_uuid": "0607b5f3-6111-424d-ba46-f5de39a6fa69",
    "image_uuid": "efe0a06f-ca95-4808-b41e-9f55b9c5eb98",
    "availability_zone": "Beijing-01",
    "status": "active",
    "power_state": "on",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "locked": false,
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "launched_at": "2016-09-27T02:39:21.966342+00:00",
    "updated_at": null,
    "affinity_zone": null,
    "project_id": "2f15c3524826465a9afbd150478b3b76",
    "user_id": "a6205fcab03d4a289251f420456b1289",
    "addresses": {},
    "partitions": {
        "root_gb": 100,
        "ephemeral_gb": 400,
        "swap_mb": 40960
    },
    "metadata": {
        "My Server Name": "Apache1"
    }
}
POST
/servers

Create Multiple Servers

Create Multiple Servers.

There is a second kind of create call which can create multiple servers at once. This supports all the same parameters as create with a few additional attributes specific to multiple create.

Error handling for multiple create is not as consistent as for single server create, and there is no guarantee that all the servers will be created successfully.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request (Additional Parameters)

These are the parameters beyond single create that are supported.

Name In Type Description
name body string A base name for creating unique names during multiple create. A unique string will be appended to the end of this base name for every instacne created.
min_count (Optional) body integer The min number of servers to be created. Defaults to 1.
max_count (Optional) body integer The max number of servers to be created. Defaults to the value of min_count.

Example Create Multiple Server: JSON request

{
    "name": "test_server",
    "description": "this is a test server",
    "flavor_uuid": "0607b5f3-6111-424d-ba46-f5de39a6fa69",
    "image_uuid": "efe0a06f-ca95-4808-b41e-9f55b9c5eb98",
    "networks": [
        {
            "net_id": "c1940655-8b8e-4370-b8f9-03ba1daeca31"
        },
        {
            "net_id": "8e8ceb07-4641-4188-9b22-840755e92ee2"
        }
    ],
    "min_count": 2,
    "max_count": 3
}

Response

The first server will be returned. The returned parameters is same to creating a single server’s.

Example Create Multiple Server: JSON response

{
    "name": "test_server",
    "description": "this is a test server",
    "flavor_uuid": "0607b5f3-6111-424d-ba46-f5de39a6fa69",
    "image_uuid": "efe0a06f-ca95-4808-b41e-9f55b9c5eb98",
    "availability_zone": "Beijing-01",
    "status": "active",
    "power_state": "on",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "locked": false,
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "launched_at": "2016-09-27T02:39:21.966342+00:00",
    "updated_at": null,
    "affinity_zone": null,
    "project_id": "2f15c3524826465a9afbd150478b3b76",
    "user_id": "a6205fcab03d4a289251f420456b1289",
    "addresses": {},
    "partitions": {
        "root_gb": 100,
        "ephemeral_gb": 400,
        "swap_mb": 40960
    },
    "metadata": {
        "My Server Name": "Apache1"
    }
}
GET
/servers

List Servers

Return a list of bare metal Servers, with some useful information about each Server.

By default, this query will return the name, server uuid, server status and description for each Server.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
name (Optional) query string Filters the server list by name. Users can filter by prefix of server’s name.
status (Optional) query string Filters the server list by the server’s status.
flavor_uuid (Optional) query string Filters the server list by flavor’s UUID.
flavor_name (Optional) query string Filters the server list by flavor’s name.
image_uuid (Optional) query string Filters the server list by image’s UUID.
ip (Optional) query string Filters the server list result by fixed ip. Users can filter by prefix of ip address.
all_tenants (Optional) query integer Specify the all_tenants=1 query parameter to list all servers for all projects. By default this is only allowed by admin users.
fields (Optional) query array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each server:

GET /v1/servers?fields=uuid,name

Response

Name In Type Description
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
uuid body string The UUID of the server
status body string The status of this server. Usually, “building”, “active”, “error”, or “None”.
power_state body string The current power state of this server. Usually, “power on” or “power off”, but may be “None” if Mogan is unable to determine the power state (eg, due to hardware failure)
links body array A list of relative links. Includes the self and bookmark links.

Example List of Servers: JSON response

{
    "servers": [
        {
            "description": "this is a test server",
            "links": [
                {
                    "href": "http://localhost:6688/v1/servers/f978ef48-d4af-4dad-beec-e6174309bc71",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:6688/servers/f978ef48-d4af-4dad-beec-e6174309bc71",
                    "rel": "bookmark"
                }
            ],
            "name": "test_server",
            "status": "building",
            "power_state": "power on",
            "uuid": "f978ef48-d4af-4dad-beec-e6174309bc71"
        }
    ]
}
GET
/servers/detail

List Servers Detailed

Return a list of bare metal Servers with complete details. We can also apply filters to show more precisely the servers.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
name (Optional) query string Filters the server list by name. Users can filter by prefix of server’s name.
status (Optional) query string Filters the server list by the server’s status.
flavor_uuid (Optional) query string Filters the server list by flavor’s UUID.
flavor_name (Optional) query string Filters the server list by flavor’s name.
image_uuid (Optional) query string Filters the server list by image’s UUID.
ip (Optional) query string Filters the server list result by fixed ip. Users can filter by prefix of ip address.
all_tenants (Optional) query integer Specify the all_tenants=1 query parameter to list all servers for all projects. By default this is only allowed by admin users.

Response

Name In Type Description
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
flavor_uuid body string The flavor reference, as a UUID for the flavor for your server server.
image_uuid body string The UUID of the image to use for your server.
availability_zone (Optional) body string The availability zone from which to launch the server. When you provision resources, you specify from which availability zone you want your server to be built. Typically, you use availability zones to arrange bare metal nodes into logical groups. An availability zone provides a form of physical isolation and redundancy from other availability zones. For server, if some racks in your data center are on a separate power source, you can put servers in those racks in their own availability zone. Availability zones can also help separate different classes of hardware. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure.
addresses body object The addresses for the server.
node (Optional) body string The node which our server associated with. Only visible for admin users.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server
status body string The status of this server. Usually, “building”, “active”, “error”, or “None”.
power_state body string The current power state of this server. Usually, “power on” or “power off”, but may be “None” if Mogan is unable to determine the power state (eg, due to hardware failure)
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
updated_at body string

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

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

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

created_at body string

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

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

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

launched_at body string

The date and time when the server was launched. The date and time stamp format is ISO 8601

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

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

metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
affinity_zone (Optional) body string The affinity zone which the server belongs to.
key_name (Optional) body string Key pair name.
partitions (Optional) body object The partitions info for root disk, this is only allowed when using partition images with root_gb(required), ephemeral_gb, and swap_mb.
locked body boolean The lock state of a server.

Example Detailed list of Servers: JSON response

{
    "servers": [
        {
            "availability_zone": null,
            "created_at": "2016-10-17T04:12:41+00:00",
            "description": "this is a test server",
            "image_uuid": "ac3b2291-b9ef-45f6-8eeb-21ac568a64a5",
            "flavor_uuid": "28708dff-283c-449e-9bfa-a48c93480c86",
            "links": [
                {
                    "href": "http://localhost:6688/v1/servers/f978ef48-d4af-4dad-beec-e6174309bc71",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:6688/servers/f978ef48-d4af-4dad-beec-e6174309bc71",
                    "rel": "bookmark"
                }
            ],
            "name": "test_server",
            "addresses": {
                "bcaebdc4-da29-46c2-8f85-ac22ecacec3c": [
                    {
                        "type": "fixed",
                        "addr": "192.168.0.3"
                    }
                ]
            },
            "partitions": {
                "root_gb": 100,
                "ephemeral_gb": 400,
                "swap_mb": 40960
            },
            "power_state": "power on",
            "locked": false,
            "project_id": "c18e8a1a870d4c08a0b51ced6e0b6459",
            "status": "building",
            "updated_at": "2016-10-17T04:12:44+00:00",
            "launched_at": null,
            "affinity_zone": null,
            "user_id": "cdbf77d47f1d4d04ad9b7ff62b672467",
            "uuid": "f978ef48-d4af-4dad-beec-e6174309bc71",
            "metadata": {
                "My Server Name": "Apache1"
            }
        }
    ]
}
GET
/servers/{server_uuid}

Show Server Details

Shows details of a server. By default, this will return the full representation of the resource; an optional fields parameter can be supplied to return only the specified set.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
server_uuid path string The UUID of the server.
fields (Optional) query array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each server:

GET /v1/servers?fields=uuid,name

Response

Name In Type Description
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
flavor_uuid body string The flavor reference, as a UUID for the flavor for your server server.
image_uuid body string The UUID of the image to use for your server.
availability_zone (Optional) body string The availability zone from which to launch the server. When you provision resources, you specify from which availability zone you want your server to be built. Typically, you use availability zones to arrange bare metal nodes into logical groups. An availability zone provides a form of physical isolation and redundancy from other availability zones. For server, if some racks in your data center are on a separate power source, you can put servers in those racks in their own availability zone. Availability zones can also help separate different classes of hardware. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure.
addresses body object The addresses for the server.
node (Optional) body string The node which our server associated with. Only visible for admin users.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server
status body string The status of this server. Usually, “building”, “active”, “error”, or “None”.
power_state body string The current power state of this server. Usually, “power on” or “power off”, but may be “None” if Mogan is unable to determine the power state (eg, due to hardware failure)
fault (Optional) body object A fault object. Only displayed in the failed response. Default keys are code, message, and detail (response code, message, and detail respectively).
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
updated_at body string

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

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

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

created_at body string

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

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

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

launched_at body string

The date and time when the server was launched. The date and time stamp format is ISO 8601

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

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

metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
affinity_zone (Optional) body string The affinity zone which the server belongs to.
key_name (Optional) body string Key pair name.
partitions (Optional) body object The partitions info for root disk, this is only allowed when using partition images with root_gb(required), ephemeral_gb, and swap_mb.
locked body boolean The lock state of a server.

Example Server Details: JSON response

{
    "availability_zone": null,
    "created_at": "2016-10-17T04:12:41+00:00",
    "description": "this is a test server",
    "image_uuid": "ac3b2291-b9ef-45f6-8eeb-21ac568a64a5",
    "flavor_uuid": "28708dff-283c-449e-9bfa-a48c93480c86",
    "links": [
        {
            "href": "http://localhost:6688/v1/servers/f978ef48-d4af-4dad-beec-e6174309bc71",
            "rel": "self"
        },
        {
            "href": "http://localhost:6688/servers/f978ef48-d4af-4dad-beec-e6174309bc71",
            "rel": "bookmark"
        }
    ],
    "name": "test_server",
    "addresses": {
        "bcaebdc4-da29-46c2-8f85-ac22ecacec3c": [
            {
                "type": "fixed",
                "addr": "192.168.0.3"
            }
        ]
    },
    "partitions": {
        "root_gb": 100,
        "ephemeral_gb": 400,
        "swap_mb": 40960
    },
    "power_state": "power on",
    "locked": false,
    "project_id": "c18e8a1a870d4c08a0b51ced6e0b6459",
    "status": "building",
    "launched_at": null,
    "affinity_zone": null,
    "updated_at": "2016-10-17T04:12:44+00:00",
    "user_id": "cdbf77d47f1d4d04ad9b7ff62b672467",
    "uuid": "f978ef48-d4af-4dad-beec-e6174309bc71",
    "metadata": {
        "My Server Name": "Apache1"
    }
}

Example Server Details With Fault: JSON response

{
    "availability_zone": null,
    "created_at": "2016-10-17T04:12:41+00:00",
    "description": "this is a test server",
    "image_uuid": "ac3b2291-b9ef-45f6-8eeb-21ac568a64a5",
    "server_type_uuid": "28708dff-283c-449e-9bfa-a48c93480c86",
    "name": "test_server",
    "addresses": {},
    "partitions": {
        "root_gb": 100,
        "ephemeral_gb": 400,
        "swap_mb": 40960
    },
    "power_state": "power on",
    "project_id": "c18e8a1a870d4c08a0b51ced6e0b6459",
    "status": "error",
    "locked": false,
    "fault": {
        "code": 500,
        "message": "fault message",
        "detail": "fault detail"
    },
    "launched_at": null,
    "affinity_zone": null,
    "updated_at": "2016-10-17T04:12:44+00:00",
    "user_id": "cdbf77d47f1d4d04ad9b7ff62b672467",
    "uuid": "f978ef48-d4af-4dad-beec-e6174309bc71",
    "metadata": {
        "My Server Name": "Apache1"
    }
}
PATCH
/servers/{server_uuid}

Update Server

Updates the information stored about a server.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name In Type Description
server_uuid path string The UUID of the server.

Example Update Server: JSON request

[
    {
        "op": "replace",
        "path": "/metadata/k1",
        "value": "v1"
    },
    {
        "op": "add",
        "path": "/metadata/k2",
        "value": "v2"
    }
]

Response

Name In Type Description
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
flavor_uuid body string The flavor reference, as a UUID for the flavor for your server server.
image_uuid body string The UUID of the image to use for your server.
availability_zone (Optional) body string The availability zone from which to launch the server. When you provision resources, you specify from which availability zone you want your server to be built. Typically, you use availability zones to arrange bare metal nodes into logical groups. An availability zone provides a form of physical isolation and redundancy from other availability zones. For server, if some racks in your data center are on a separate power source, you can put servers in those racks in their own availability zone. Availability zones can also help separate different classes of hardware. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure.
addresses body object The addresses for the server.
node (Optional) body string The node which our server associated with. Only visible for admin users.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server
status body string The status of this server. Usually, “building”, “active”, “error”, or “None”.
power_state body string The current power state of this server. Usually, “power on” or “power off”, but may be “None” if Mogan is unable to determine the power state (eg, due to hardware failure)
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
updated_at body string

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

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

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

created_at body string

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

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

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

metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
affinity_zone (Optional) body string The affinity zone which the server belongs to.
key_name (Optional) body string Key pair name.
partitions (Optional) body object The partitions info for root disk, this is only allowed when using partition images with root_gb(required), ephemeral_gb, and swap_mb.
locked body boolean The lock state of a server.

Example Update Server: JSON response

{
    "name": "test_server",
    "description": "this is a test server",
    "flavor_uuid": "0607b5f3-6111-424d-ba46-f5de39a6fa69",
    "image_uuid": "efe0a06f-ca95-4808-b41e-9f55b9c5eb98",
    "availability_zone": "Beijing-01",
    "status": "active",
    "power_state": "on",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "locked": false,
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "launched_at": "2016-09-27T02:39:21.966342+00:00",
    "updated_at": null,
    "affinity_zone": null,
    "project_id": "2f15c3524826465a9afbd150478b3b76",
    "user_id": "a6205fcab03d4a289251f420456b1289",
    "addresses": {
        "bcaebdc4-da29-46c2-8f85-ac22ecacec3c": [
            {
                "type": "fixed",
                "addr": "192.168.0.3"
            }
        ]
    },
    "partitions": {
        "root_gb": 100,
        "ephemeral_gb": 400,
        "swap_mb": 40960
    },
    "metadata": {
        "k1": "v1",
        "k2": "v2"
    }
}
DELETE
/servers/{server_uuid}

Delete Server

Deletes a server.

Preconditions

  • The server must exist.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
server_uuid path string The UUID of the server.

Response

No body content is returned on a successful DELETE.

Server States

Servers States can be managed through states sub-resource.

A Server can be rebooted, turned on, or turned off by requesting a change to its power state.

PUT
/v1/servers/{server_uuid}/states/power

Change Server Power State

Request a change to the Server’s power state.

Normal response code: 202

Error codes:
  • 409 (ClientError)
  • 400 (InvalidState)
  • 406 (NotAcceptable)

Request

Name In Type Description
server_uuid path string The UUID of the server.
target body string This field represents the requested state either “on”, “off”, “soft_off”, “reboot”, or “soft_reboot”.

Example request to power off a Server:

{
    "target": "off"
}

Response

If successful, this method does not return content in the response body.

PUT
/v1/servers/{server_uuid}/states/lock

Change Server Lock State

Request a change to the Server’s lockstate.

Normal response code: 202

Error codes:
  • 409 (ClientError)
  • 400 (BadRequest)
  • 403 (Forbidden)

Request

Name In Type Description
server_uuid path string The UUID of the server.
target body boolean The lock state of a server.

Example request to lock a Server:

{
    "target": true
}

Example request to unlock a Server:

{
    "target": false
}

Response

If successful, this method does not return content in the response body.

PUT
/v1/servers/{server_uuid}/states/provision

Change Server Provision State

Request a change to the Server’s provision state.

Normal response code: 202

Error codes:
  • 409 (ClientError)
  • 400 (BadRequest)
  • 403 (Forbidden)

Request

Name In Type Description
server_uuid path string The UUID of the server.
target body string One of the provisioning verbs, currently only support rebuild.
image_uuid (Optional) body string The UUID of the image to apply to rebuild your server.
preserve_ephemeral (Optional) body boolean Indicates whether the server is rebuilt with the preservation of the ephemeral partition (true).

Example request to rebuild a Server:

{
    "target": "rebuild",
    "image_uuid": "9145be5b-38d0-4a05-8dd6-837a8ec15281",
    "preserve_ephemeral": true
}

Response

If successful, this method does not return content in the response body.

Server Networks

Servers Networks can be managed through networks sub-resource.

A Server can be associated or dissociated with a floating IP by requesting the floatingip sub-resource.

GET
/v1/servers/{server_uuid}/networks

Server Network Summary

Get a summary of the Server’s networks.

Normal response code: 200

Request

Name In Type Description
server_uuid path string The UUID of the server.

Response

Name In Type Description
nics body object The port info in the requested network for the server, with fixed_ip, mac_address, and network uuid

Example server network:

{
    "nics": [
        {
            "network_id": "f31af5a2-f14d-4007-b2e5-abeb82429b87",
            "port_id": "99845c22-6268-46c1-b068-1dbcb8adaf68",
            "floating_ip": null,
            "mac_address": "52:54:00:cc:ed:87",
            "fixed_ips": [
                {
                    "subnet_id": "5a324b29-9aca-43d8-a6c3-31986dda95b5",
                    "ip_address": "11.0.0.6"
                },
                {
                    "subnet_id": "9baceab1-40ec-4c53-ad83-530a625bddb1",
                    "ip_address": "fdaa:67c7:e09e:0:5054:ff:fecc:ed87"
                }
            ]
        }
    ]
}
POST
/v1/servers/{server_uuid}/networks/floatingips

Add (Associate) Floating IP

Adds a floating IP address to a server, which associates that address with the server.

If a server is connected to multiple networks, you can associate a floating IP address with a specific fixed IP address by using the optional fixed_address parameter.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name In Type Description
server_uuid path string The UUID of the server.
address body string The floating IP address.
fixed_address (Optional) body string The fixed IP address with which you want to associate the floating IP address.

Example request to Add (Associate) Floating IP to a server:

{
    "address": "172.24.4.10",
    "fixed_address": "11.0.0.5"
}

Response

If successful, this method does not return content in the response body.

DELETE
/v1/servers/{server_uuid}/networks/floatingips/{fip_address}

Remove (Disassociate) Floating IP

Removes, or disassociates, a floating IP address from a server.

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
server_uuid path string The UUID of the server.
fip_address path string The floating IP address.

Response

If successful, this method does not return content in the response body.

POST
/v1/servers/{server_uuid}/networks/interfaces

Add (Associate) Interface

Adds an interface to a server.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name In Type Description
server_uuid path string The UUID of the server.
net_id (Optional) body string To provision the server with a NIC for a network, specify the UUID of the network with the net_id key in a dict in networks list.
port_id (Optional) body string To provision the server with a NIC for an already existing port, specify the port_id in a networks list.

Example request to Add (Associate) Interface to a server:

{
    "port_id": "6cefb080-77bb-4bf9-8695-c10401e86c05"
}

Response

If successful, this method does not return content in the response body.

DELETE
/v1/servers/{server_uuid}/networks/interfaces/{port_id}

Detach a network interface.

Detach a network interface from a server.

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
server_uuid path string The UUID of the server.
port_id path string The UUID of a network port.

Response

If successful, this method does not return content in the response body.

Server Remote Consoles

Create server remote console.

POST
/v1/servers/{server_uuid}/remote_consoles

Create Remote Console

The API provides a unified request for creating a remote console. The user can get a URL to connect the console from this API. The URL includes the token which is used to get permission to access the console. Servers may support different console protocols. To return a remote console using a specific protocol, such as serial, set the protocol parameter to serial. For the same protocol, there may be different connection types such as serial protocol and socat type or serial protocol and shellinabox type.

Normal response code: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409), notImplemented(501)

Request

Name In Type Description
server_uuid path string The UUID of the server.
protocol body string The protocol of remote console. The valid value is serial now.
type body string The type of remote console. The valid values are socat, and shellinabox.

Example Create Remote Socat Console: JSON request

{
    "protocol": "serial",
    "type": "shellinabox"
}

Response

Name In Type Description
protocol body string The protocol of remote console. The valid value is serial now.
type body string The type of remote console. The valid values are socat, and shellinabox.
url body string The URL is used to connect the console.

Example Create Remote Socat Console: JSON response

{
    "protocol": "serial",
    "type": "shellinabox",
    "url": "http://127.0.0.1:8866/?token=b4f5cb4a-8b01-40ea-ae46-67f0db4969b3"
}

Flavors

Show and manage server flavors.

Flavors are a way to describe the basic dimensions of a server to be created including how much cpu, ram, and disk space are allocated to a server built with this flavor.

GET
/flavors

List Flavors

Lists all flavors accessible to your project.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name In Type Description
flavors body array An array of flavor objects.
name body string The name of the flavor.
links body array A list of relative links. Includes the self and bookmark links.
description body string The description of the flavor.
resources body object A dict of key and value pairs associate with the flavor including the resource name and the quantity.
resource_aggregates body object A dict of key and value pairs associate with the flavor including the resources aggregate metadata.
uuid body string The UUID of the flavor.
created_at body string

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

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

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

updated_at body string

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

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

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

is_public body boolean Whether the flavor is public (available to all projects) or scoped to a set of projects. Default is True if not specified.
disabled (Optional) body boolean Whether or not the flavor has been administratively disabled.

Example List flavors

{
    "flavors": [
        {
            "description": "this is a test flavor1",
            "links": [
                {
                    "href": "http://10.3.150.17:6688/v1/flavors/2ce3df6b-f571-42e8-b6a8-8f7fa1c019ce",
                    "rel": "self"
                },
                {
                    "href": "http://10.3.150.17:6688/flavors/2ce3df6b-f571-42e8-b6a8-8f7fa1c019ce",
                    "rel": "bookmark"
                }
            ],
            "resources": {
                "CUSTOM_BAREMETAL_GOLD": 1
            },
            "resource_aggregates": {
                "high_mem": "true"
            },
            "created_at": "2016-09-22T03:21:57+00:00",
            "uuid": "2ce3df6b-f571-42e8-b6a8-8f7fa1c019ce",
            "updated_at": null,
            "is_public": true,
            "disabled": false,
            "name": "new_test1"
        },
        {
            "description": "this is a test flavor2",
            "links": [
                {
                    "href": "http://10.3.150.17:6688/v1/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
                    "rel": "self"
                },
                {
                    "href": "http://10.3.150.17:6688/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
                    "rel": "bookmark"
                }
            ],
            "resources": {
                "CUSTOM_BAREMETAL_GOLD": 1
            },
            "resource_aggregates": {
                "high_mem": "true"
            },
            "created_at": "2016-09-27T02:37:21+00:00",
            "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "updated_at": null,
            "is_public": true,
            "disabled": false,
            "name": "new_test2"
        }
    ]
}
POST
/flavors

Create Flavor

Creates a flavor.

Creating a flavor is typically only available to administrators of a cloud because this has implications for scheduling efficiently in the cloud.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
name body string The name of the flavor.
description body string The description of the flavor.
resources body object A dict of key and value pairs associate with the flavor including the resource name and the quantity.
resource_aggregates body object A dict of key and value pairs associate with the flavor including the resources aggregate metadata.
is_public (Optional) body boolean Whether the flavor is public (available to all projects) or scoped to a set of projects. Default is True if not specified.
disabled (Optional) body boolean Whether or not the flavor has been administratively disabled.

Example Create Flavor

{
    "name": "test_flavor",
    "description": "this is a test flavor",
    "resources": {
        "CUSTOM_BAREMETAL_GOLD": 1
    },
    "resource_aggregates": {
        "high_mem": "true"
    },
    "is_public": true,
    "disabled": true
}

Response

Name In Type Description
name body string The name of the flavor.
links body array A list of relative links. Includes the self and bookmark links.
description body string The description of the flavor.
resources body object A dict of key and value pairs associate with the flavor including the resource name and the quantity.
resource_aggregates body object A dict of key and value pairs associate with the flavor including the resources aggregate metadata.
uuid body string The UUID of the flavor.
created_at body string

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

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

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

updated_at body string

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

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

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

is_public body boolean Whether the flavor is public (available to all projects) or scoped to a set of projects. Default is True if not specified.
disabled (Optional) body boolean Whether or not the flavor has been administratively disabled.

Example Create flavor

{
    "description": "this is a test flavor",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "resources": {
        "CUSTOM_BAREMETAL_GOLD": 1
    },
    "resource_aggregates": {
        "high_mem": "true"
    },
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "updated_at": null,
    "is_public": true,
    "disabled": true,
    "name": "test_flavor"
}
PATCH
/flavors/{flavor_uuid}

Update Flavor

Updates a flavor.

Updating a flavor is typically only available to administrators of a cloud because this has implications for scheduling efficiently in the cloud.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name In Type Description
flavor_uuid path string The UUID of the flavor.

Example Update Flavor: JSON request

[
    {
        "op": "replace",
        "path": "/name",
        "value": "updated_flavor"
    },
    {
        "op": "replace",
        "path": "/is_public",
        "value": false
    }
]

Response

Name In Type Description
name body string The name of the flavor.
links body array A list of relative links. Includes the self and bookmark links.
description body string The description of the flavor.
resources body object A dict of key and value pairs associate with the flavor including the resource name and the quantity.
resource_aggregates body object A dict of key and value pairs associate with the flavor including the resources aggregate metadata.
uuid body string The UUID of the flavor.
created_at body string

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

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

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

updated_at body string

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

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

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

is_public body boolean Whether the flavor is public (available to all projects) or scoped to a set of projects. Default is True if not specified.
disabled (Optional) body boolean Whether or not the flavor has been administratively disabled.

Example Update flavor

{
    "description": "this is a flavor to be updated",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "resources": {
        "CUSTOM_BAREMETAL_GOLD": 1
    },
    "resource_aggregates": {
        "high_mem": "true"
    },
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "updated_at": null,
    "is_public": false,
    "disabled": false,
    "name": "updated_flavor"
}
GET
/flavors/{flavor_uuid}

Show Server Flavor Details

Shows details for a flavor.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
flavor_uuid path string The UUID of the flavor.

Response

Name In Type Description
name body string The name of the flavor.
links body array A list of relative links. Includes the self and bookmark links.
description body string The description of the flavor.
resources body object A dict of key and value pairs associate with the flavor including the resource name and the quantity.
resource_aggregates body object A dict of key and value pairs associate with the flavor including the resources aggregate metadata.
uuid body string The UUID of the flavor.
created_at body string

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

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

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

updated_at body string

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

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

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

is_public body boolean Whether the flavor is public (available to all projects) or scoped to a set of projects. Default is True if not specified.
disabled (Optional) body boolean Whether or not the flavor has been administratively disabled.

Example Show Flavor Details

{
    "description": "this is a test flavor",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/flavors/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "resources": {
        "CUSTOM_BAREMETAL_GOLD": 1
    },
    "resource_aggregates": {
        "high_mem": "true"
    },
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "updated_at": null,
    "is_public": true,
    "disabled": false,
    "name": "test_flavor"
}
DELETE
/flavors/{flavor_uuid}

Delete Flavor

Deletes a flavor.

This is typically an admin only action. Deleting a flavor that is in use by existing servers is not recommended as it can cause incorrect data to be returned to the user under some operations.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
flavor_uuid path string The UUID of the flavor.

Response

No body content is returned on a successful DELETE.

Flavors access

Lists tenants who have access to a private flavor and adds private flavor access to and removes private flavor access from tenants. By default, only administrators can manage private flavor access. A private flavor has is_public set to false while a public flavor has is_public set to true.

GET
/flavors/{flavor_uuid}/access

List Flavor Access Information For Given Flavor

Lists flavor access information.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name In Type Description
flavor_uuid path string The UUID of the flavor.

Response

Name In Type Description
flavor_access body array A list of tenants.

Example List Flavor Access Information For Given Flavor: JSON response

{
    "flavor_access": [
        "tenant1",
        "tenant2",
        "tenant3"
    ]
}
POST
/flavors/{flavor_uuid}/access

Add Flavor Access To Tenant

Adds flavor access to a tenant and flavor.

Specify the tenant_id in the request body.

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
flavor_uuid path string The UUID of the flavor.
tenant_id body string The UUID of the tenant in a multi-tenancy cloud.

Example Add Flavor Access To Tenant: JSON response

{
    "tenant_id": "fake_tenant"
}

Response

If successful, this method does not return content in the response body.

DELETE
/flavors/{flavor_uuid}/access/{tenant_id}

Remove Flavor Access From Tenant

Removes flavor access from a tenant and flavor.

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)

Request

Name In Type Description
flavor_uuid path string The UUID of the flavor.
tenant_id path string The UUID of the tenant in a multi-tenancy cloud.

Response

If successful, this method does not return content in the response body.

Availability Zones

Lists availability zones.

GET
/availability_zones

List Availability Zone information

Lists availability zone information.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name In Type Description
availability_zones body array An array of availability zone name.

Example List availability zone information

{
    "availability_zones": [
        "az1",
        "az2",
        "az3"
    ]
}

Aggregates

Creates and manages node aggregates. An aggregate assigns metadata to groups of compute nodes. Aggregates are only visible to the cloud provider.

GET
/aggregates

List Aggregates

Lists all aggregates.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name In Type Description
aggregates body array The list of existing aggregates.
name body string The name of the node aggregate.
links body array A list of relative links. Includes the self and bookmark links.
metadata body object Metadata key and value pairs associate with the aggregate.
uuid body string The UUID of the node aggregate.
created_at body string

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

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

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

updated_at body string

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

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

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

Example List aggregates: JSON response

{
    "aggregates": [
        {
            "name": "test_aggregate1",
            "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "links": [
                {
                    "href": "http://10.3.150.17:6688/v1/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
                    "rel": "self"
                },
                {
                    "href": "http://10.3.150.17:6688/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
                    "rel": "bookmark"
                }
            ],
            "metadata": {
                "k1": "v1"
            },
            "created_at": "2016-09-27T02:37:21.966342+00:00",
            "updated_at": null
        },
        {
            "name": "test_aggregate2",
            "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "links": [
                {
                    "href": "http://10.3.150.17:6688/v1/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
                    "rel": "self"
                },
                {
                    "href": "http://10.3.150.17:6688/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
                    "rel": "bookmark"
                }
            ],
            "metadata": {
                "k2": "v2"
            },
            "created_at": "2016-09-27T02:37:21.966342+00:00",
            "updated_at": null
        }
    ]
}
POST
/aggregates

Create Aggregate

Creates an aggregate.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
name body string The name of the node aggregate.
metadata body object Metadata key and value pairs associate with the aggregate.

Example Create Aggregatei: JSON request

{
    "name": "test_aggregate",
    "metadata": {
        "k1": "v1"
    }
}

Response

Name In Type Description
name body string The name of the node aggregate.
links body array A list of relative links. Includes the self and bookmark links.
metadata body object Metadata key and value pairs associate with the aggregate.
uuid body string The UUID of the node aggregate.
created_at body string

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

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

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

updated_at body string

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

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

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

Example Create Aggregate: JSON response

{
    "name": "test_aggregate",
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "metadata": {
        "k1": "v1"
    },
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "updated_at": null
}
PATCH
/aggregates/{aggregate_uuid}

Update Aggregate

Updates an aggregate.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name In Type Description
aggregate_uuid path string The UUID of the aggregate.

Example Update Aggregate: JSON request

[
    {
        "op": "replace",
        "path": "/metadata/k1",
        "value": "v2"
    },
    {
        "op": "add",
        "path": "/metadata/k2",
        "value": "v2"
    }
]

Response

Name In Type Description
name body string The name of the node aggregate.
links body array A list of relative links. Includes the self and bookmark links.
metadata body object Metadata key and value pairs associate with the aggregate.
uuid body string The UUID of the node aggregate.
created_at body string

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

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

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

updated_at body string

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

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

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

Example Update Aggregate: JSON response

{
    "name": "test_aggregate",
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "metadata": {
        "k1": "v2",
        "k2": "v2"
    },
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "updated_at": null
}
GET
/aggregates/{aggregate_uuid}

Show Aggregate Details

Shows details for an aggregate.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
aggregate_uuid path string The UUID of the aggregate.

Response

Name In Type Description
name body string The name of the node aggregate.
links body array A list of relative links. Includes the self and bookmark links.
metadata body object Metadata key and value pairs associate with the aggregate.
uuid body string The UUID of the node aggregate.
created_at body string

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

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

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

updated_at body string

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

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

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

Example Show Aggregate Details

{
    "name": "test_aggregate",
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/aggregates/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "metadata": {
        "k1": "v1"
    },
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "updated_at": null
}
DELETE
/aggregates/{aggregate_uuid}

Delete Aggregate

Deletes an aggregate.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
aggregate_uuid path string The UUID of the aggregate.

Response

No body content is returned on a successful DELETE.

GET
/aggregates/{aggregate_uuid}/nodes

List Aggregate Nodes

Lists nodes for the specified aggregate.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name In Type Description
aggregate_uuid path string The UUID of the aggregate.

Response

Name In Type Description
nodes body array An array of node information.

Example List aggregates: JSON response

{
    "nodes": [
        "node1",
        "node2",
        "node3"
    ]
}
POST
/aggregates/{aggregate_uuid}/nodes

Add Aggregate Node

Adds a node to an aggregate.

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
aggregate_uuid path string The UUID of the aggregate.
node body string The name of the node.

Example Add Aggregate Node: JSON request

{
    "node": "fake_node"
}

Response

If successful, this method does not return content in the response body.

DELETE
/aggregates/{aggregate_uuid}/nodes/{node}

Remove Aggregate Node

Removes a node to an aggregate.

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
aggregate_uuid path string The UUID of the aggregate.
node path string The name of the node.

Response

If successful, this method does not return content in the response body.

ServerGroups

Lists, creates, shows and deletes server groups.

GET
/server_groups

List ServerGroups

Lists server groups.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name In Type Description
all_tenants (Optional) query integer Specify the all_tenants=1 query parameter to list server groups for all projects. By default this is only allowed by admin users.

Response

Name In Type Description
server_groups body array The list of existing server groups.
name body string The server group name.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server group.
policies body array

A list of exactly one policy name to associate with the server group. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different affinity-zones.
  • affinity - servers in this group must be scheduled to the same affinity-zone.
members (Optional) body array A list of uuids of servers which belong to this server group.
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
created_at body string

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

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

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

updated_at body string

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

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

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

Example List server groups: JSON response

{
    "server_groups": [
        {
            "user_id": "9851baf53c75452dad7951bca7b3dbac",
            "uuid": "73f9f8be-2e4e-4de8-b3f9-e1bf6618c1b1",
            "links": [
                {
                    "href": "http://10.229.40.107/v1/server_groups/73f9f8be-2e4e-4de8-b3f9-e1bf6618c1b1",
                    "rel": "self"
                },
                {
                    "href": "http://10.229.40.107/server_groups/73f9f8be-2e4e-4de8-b3f9-e1bf6618c1b1",
                    "rel": "bookmark"
                }
            ],
            "created_at": "2017-08-02T09:18:24+00:00",
            "updated_at": null,
            "members": [],
            "project_id": "b5f8b7e5429449a8a1366088abede8d1",
            "policies": [
                "anti-affinity"
            ],
            "name": "test"
        },
        {
            "user_id": "9851baf53c75452dad7951bca7b3dbac",
            "uuid": "fd2dab04-ab3e-4893-9ee4-837cc0ea2d9c",
            "links": [
                {
                    "href": "http://10.229.40.107/v1/server_groups/fd2dab04-ab3e-4893-9ee4-837cc0ea2d9c",
                    "rel": "self"
                },
                {
                    "href": "http://10.229.40.107/server_groups/fd2dab04-ab3e-4893-9ee4-837cc0ea2d9c",
                    "rel": "bookmark"
                }
            ],
            "created_at": "2017-08-02T09:20:24+00:00",
            "updated_at": null,
            "members": [],
            "project_id": "b5f8b7e5429449a8a1366088abede8d1",
            "policies": [
                "affinity"
            ],
            "name": "test2"
        }
    ]
}
POST
/server_groups

Create ServerGroup

Creates a server group.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
name body string The server group name.
policies body array

A list of exactly one policy name to associate with the server group. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different affinity-zones.
  • affinity - servers in this group must be scheduled to the same affinity-zone.

Example Create a ServerGroup: JSON request

{
    "name": "test",
    "policies": [
        "anti-affinity"
    ]
}

Response

Name In Type Description
name body string The server group name.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server group.
policies body array

A list of exactly one policy name to associate with the server group. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different affinity-zones.
  • affinity - servers in this group must be scheduled to the same affinity-zone.
members (Optional) body array A list of uuids of servers which belong to this server group.
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
created_at body string

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

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

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

updated_at body string

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

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

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

Example Create ServerGroup: JSON response

{
    "user_id": "9851baf53c75452dad7951bca7b3dbac",
    "uuid": "159628a2-2f07-42cf-aebf-83bb5eb0ff3c",
    "links": [
        {
            "href": "http://10.229.40.107/v1/server_groups/159628a2-2f07-42cf-aebf-83bb5eb0ff3c",
            "rel": "self"
        },
        {
            "href": "http://10.229.40.107/server_groups/159628a2-2f07-42cf-aebf-83bb5eb0ff3c",
            "rel": "bookmark"
        }
    ],
    "created_at": "2017-08-02T09:15:36+00:00",
    "updated_at": null,
    "members": [],
    "project_id": "b5f8b7e5429449a8a1366088abede8d1",
    "policies": [
        "anti-affinity"
    ],
    "name": "test"
}
GET
/server_groups/{server_group_uuid}

Show ServerGroup Details

Shows details for a server group.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
server_group_uuid path string The UUID of the server group.

Response

Name In Type Description
name body string The server group name.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server group.
policies body array

A list of exactly one policy name to associate with the server group. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different affinity-zones.
  • affinity - servers in this group must be scheduled to the same affinity-zone.
members (Optional) body array A list of uuids of servers which belong to this server group.
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
created_at body string

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

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

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

updated_at body string

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

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

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

Example Show ServerGroup Details

{
    "user_id": "9851baf53c75452dad7951bca7b3dbac",
    "uuid": "73f9f8be-2e4e-4de8-b3f9-e1bf6618c1b1",
    "links": [
        {
            "href": "http://10.229.40.107/v1/server_groups/73f9f8be-2e4e-4de8-b3f9-e1bf6618c1b1",
            "rel": "self"
        },
        {
            "href": "http://10.229.40.107/server_groups/73f9f8be-2e4e-4de8-b3f9-e1bf6618c1b1",
            "rel": "bookmark"
        }
    ],
    "created_at": "2017-08-02T09:18:24+00:00",
    "updated_at": null,
    "members": [],
    "project_id": "b5f8b7e5429449a8a1366088abede8d1",
    "policies": [
        "anti-affinity"
    ],
    "name": "test"
}
DELETE
/server_groups/{server_group_uuid}

Delete a ServerGroup

Deletes a server group.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name In Type Description
server_group_uuid path string The UUID of the server group.

Response

No body content is returned on a successful DELETE.

Manageable Servers

Lists, manages manageable servers.

GET
/manageable_servers

List manageable servers information

Lists manageable servers information.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name In Type Description
manageable_servers body array An array of manageable servers information.
uuid body string UUID of manageable server.
name body string Name of manageable server.
resource_class body string Resource class of manageable server.
power_state body string The power state of manageable server.
provision_state body string The provision state of manageable server.
ports body array The ports of manageable server.
portgroups body array The portgroups of manageable server.
image_source body string Image source uuid of manageable server.

Example List manageable servers information

{
    "manageable_servers": [
        {
            "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "name": "test_node",
            "resource_class": "gold",
            "power_state": "power on",
            "provision_state": "active",
            "ports": [
                {
                    "address": "a4:dc:be:0e:82:a5",
                    "uuid": "1ec01153-685a-49b5-a6d3-45a4e7dddf53",
                    "neutron_port_id": "a9b94592-1d8e-46bb-836b-c7ba935b0136"
                }
            ],
            "portgroups": [
                {
                    "address": "a4:dc:be:0e:82:a6",
                    "uuid": "1ec01153-685a-49b5-a6d3-45a4e7dddf54",
                    "neutron_port_id": "a9b94592-1d8e-46bb-836b-c7ba935b0137"
                }
            ],
            "image_source": "03239419-e588-42b6-a70f-94f23ed0c9e2"
        }
    ]
}
POST
/manageable_servers

Manage an existing server

Manage a server.

Manage nodes in active which migrated by operators.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name In Type Description
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
node_uuid body string UUID of manageable server.
metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.

Example Manage Server: JSON request

{
    "name": "test_manageable_server",
    "description": "This is a manageable server",
    "metadata": {
        "My Server Name": "Apache1"
    },
    "node_uuid": "aacdbd78-d670-409e-95aa-ecfcfb94fee2"
}

Response

Name In Type Description
name body string The server name.
description (Optional) body string A free form description of the server. Limited to 255 characters in length.
flavor_uuid body string The flavor reference, as a UUID for the flavor for your server server.
image_uuid body string The UUID of the image to use for your server.
availability_zone (Optional) body string The availability zone from which to launch the server. When you provision resources, you specify from which availability zone you want your server to be built. Typically, you use availability zones to arrange bare metal nodes into logical groups. An availability zone provides a form of physical isolation and redundancy from other availability zones. For server, if some racks in your data center are on a separate power source, you can put servers in those racks in their own availability zone. Availability zones can also help separate different classes of hardware. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure.
addresses body object The addresses for the server.
links body array A list of relative links. Includes the self and bookmark links.
uuid body string The UUID of the server
status body string The status of this server. Usually, “building”, “active”, “error”, or “None”.
power_state body string The current power state of this server. Usually, “power on” or “power off”, but may be “None” if Mogan is unable to determine the power state (eg, due to hardware failure)
project_id body string The UUID of the project in a multi-tenancy cloud.
user_id body string The user ID of the user who owns the server.
updated_at body string

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

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

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

created_at body string

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

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

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

launched_at body string

The date and time when the server was launched. The date and time stamp format is ISO 8601

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

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

metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
affinity_zone (Optional) body string The affinity zone which the server belongs to.
key_name (Optional) body string Key pair name.
node_uuid body string UUID of manageable server.
partitions (Optional) body object The partitions info for root disk, this is only allowed when using partition images with root_gb(required), ephemeral_gb, and swap_mb.

Example Manage Server: JSON response

{
    "name": "test_manageable_server",
    "description": "This is a manageable server",
    "flavor_uuid": null,
    "image_uuid": "efe0a06f-ca95-4808-b41e-9f55b9c5eb98",
    "availability_zone": null,
    "status": "active",
    "power_state": "on",
    "links": [
        {
            "href": "http://10.3.150.17:6688/v1/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "self"
        },
        {
            "href": "http://10.3.150.17:6688/servers/7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
            "rel": "bookmark"
        }
    ],
    "uuid": "7de2859d-ec6d-42c7-bb86-9d630ba5ac94",
    "created_at": "2016-09-27T02:37:21.966342+00:00",
    "launched_at": "2016-09-27T02:39:21.966342+00:00",
    "updated_at": null,
    "affinity_zone": null,
    "project_id": "2f15c3524826465a9afbd150478b3b76",
    "user_id": "a6205fcab03d4a289251f420456b1289",
    "addresses": [],
    "metadata": {
        "My Server Name": "Apache1"
    },
    "key_name": null,
    "node_uuid": "aacdbd78-d670-409e-95aa-ecfcfb94fee2",
    "partitions": null
}
Creative Commons Attribution 3.0 License

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