Compute API

This is a reference for the OpenStack Compute API which is provided by the Nova project. To learn more about the OpenStack Compute API concepts, please refer to the API guide.

API Versions

In order to bring new features to users over time, the Nova API supports versioning. There are two kinds of versions in Nova.

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

  • ‘’microversions’’, which can be requested through the use of the X-OpenStack-Nova-API-Version header, or since microversion 2.27 the OpenStack-API-Version header may also be used.

For more details about Microversions, please reference: Microversions

Note

The maximum microversion supported by each release varies. Please reference: API Microversion History for API microversion history details.

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

GET
/

List All Major Versions

This fetches all the information about all known major API versions in the deployment. Links to more specific information will be provided for each API version, as well as information about supported min and max microversions.

Normal Response Codes: 200

Response

Name

In

Type

Description

versions

body

array

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

id

body

string

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

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

min_version

body

string

If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.

status

body

string

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

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

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

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

updated

body

string

This is a fixed string. It is 2011-01-21T11:33:21Z in version 2.0, 2013-07-23T11:33:21Z in version 2.1.

Note

It is vestigial and provides no useful information. It will be deprecated and removed in the future.

version

body

string

If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.

Response Example

This demonstrates the expected response from a bleeding edge server that supports up to the current microversion. When querying OpenStack environments you will typically find the current microversion on the v2.1 API is lower than listed below.

{
    "versions": [
        {
            "id": "v2.0",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/",
                    "rel": "self"
                }
            ],
            "status": "SUPPORTED",
            "version": "",
            "min_version": "",
            "updated": "2011-01-21T11:33:21Z"
        },
        {
            "id": "v2.1",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/",
                    "rel": "self"
                }
            ],
            "status": "CURRENT",
            "version": "2.96",
            "min_version": "2.1",
            "updated": "2013-07-23T11:33:21Z"
        }
    ]
}
GET
/{api_version}/

Show Details of Specific API Version

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

Normal Response Codes: 200

Request

Name

In

Type

Description

api_version

path

string

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

Response

Name

In

Type

Description

version

body

string

The version.

id

body

string

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

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

media-types

body

array

The media types. It is an array of a fixed dict.

Note

It is vestigial and provide no useful information. It will be deprecated and removed in the future.

min_version

body

string

If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.

status

body

string

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

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

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

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

updated

body

string

This is a fixed string. It is 2011-01-21T11:33:21Z in version 2.0, 2013-07-23T11:33:21Z in version 2.1.

Note

It is vestigial and provides no useful information. It will be deprecated and removed in the future.

version

body

string

If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.

Response Example

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

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

Service URLs

All API calls described throughout the rest of this document require authentication with the OpenStack Identity service. After authentication, a base service url can be extracted from the Identity token of type compute. This service url will be the root url that every API call uses to build a full path.

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

Depending on the deployment, the 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 Compute 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_compute_service_url}/servers.

Request IDs

Users can specify the global request ID in the request header. Users can receive the local request ID in the response header.

For more details about Request IDs, please reference: Faults

Request

Name

In

Type

Description

X-Openstack-Request-Id (Optional)

header

string

The global request ID, which is a unique common ID for tracking each request in OpenStack components. The format of the global request ID must be req- + UUID (UUID4). If not in accordance with the format, it is ignored. It is associated with the request and appears in the log lines for that request. By default, the middleware configuration ensures that the global request ID appears in the log files.

New in version 2.46

Response

Name

In

Type

Description

X-Compute-Request-Id

header

string

The local request ID, which is a unique ID generated automatically for tracking each request to nova. It is associated with the request and appears in the log lines for that request. By default, the middleware configuration ensures that the local request ID appears in the log files.

Note

This header exists for backward compatibility.

X-Openstack-Request-Id

header

string

The local request ID, which is a unique ID generated automatically for tracking each request to nova. It is associated with the request and appears in the log lines for that request. By default, the middleware configuration ensures that the local request ID appears in the log files.

New in version 2.46

Servers (servers)

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

Passwords

When you create a server, you can specify a password through the optional adminPass attribute. The password must meet the complexity requirements set by your OpenStack Compute provider. The server might enter an ERROR state if the complexity requirements are not met. In this case, a client might issue a change password action to reset the server password.

If you do not specify a password, the API generates and assigns a random password that it returns in the response object. This password meets the security requirements set by the compute provider. For security reasons, subsequent GET calls do not require this password.

Server metadata

You can specify custom server metadata at server launch time. The maximum size for each metadata key-value pair is 255 bytes. The compute provider determines the maximum number of key-value pairs for each server. You can query this value through the maxServerMeta absolute limit.

Server networks

You can specify one or more networks to which the server connects at launch time. Users can also specify a specific port on the network or the fixed IP address to assign to the server interface.

Note

You can use both IPv4 and IPv6 addresses as access addresses, and you can assign both addresses simultaneously. You can update access addresses after you create a server.

Server personality

Note

The use of personality files is deprecated starting with the 2.57 microversion. Use metadata and user_data to customize a server instance.

To customize the personality of a server instance, you can inject data into its file system. For example, you might insert ssh keys, set configuration files, or store data that you want to retrieve from inside the instance. This customization method provides minimal launch-time personalization. If you require significant customization, create a custom image.

Follow these guidelines when you inject files:

  • The maximum size of the file path data is 255 bytes.

  • Encode the file contents as a Base64 string. The compute provider determines the maximum size of the file contents. The image that you use to create the server determines this value.

    Note

    The maximum limit refers to the number of bytes in the decoded data and not to the number of characters in the encoded data.

  • The maxPersonality absolute limit defines the maximum number of file path and content pairs that you can supply. The compute provider determines this value.

  • The maxPersonalitySize absolute limit is a byte limit that applies to all images in the deployment. Providers can set additional per-image personality limits.

The file injection might not occur until after the server builds and boots.

After file injection, only system administrators can access personality files. For example, on Linux, all files have root as the owner and the root group as the group owner, and allow only user and group read access (chmod 440).

Server access addresses

In a hybrid environment, the underlying implementation might not control the IP address of a server. Instead, the access IP address might be part of the dedicated hardware; for example, a router/NAT device. In this case, you cannot use the addresses that the implementation provides to access the server from outside the local LAN. Instead, the API might assign a separate access address at creation time to provide access to the server. This address might not be directly bound to a network interface on the server and might not necessarily appear when you query the server addresses. However, clients should use an access address to access the server directly.

GET
/servers

List Servers

Lists IDs, names, and links for servers.

By default the servers are filtered using the project ID associated with the authenticated request.

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

  • ACTIVE. The server is active.

  • BUILD. The server has not finished the original build process.

  • DELETED. The server is permanently deleted.

  • ERROR. The server is in error.

  • HARD_REBOOT. The server is hard rebooting. This is equivalent to pulling the power plug on a physical server, plugging it back in, and rebooting it.

  • MIGRATING. The server is being migrated to a new host.

  • PASSWORD. The password is being reset on the server.

  • PAUSED. In a paused state, the state of the server is stored in RAM. A paused server continues to run in frozen state.

  • REBOOT. The server is in a soft reboot state. A reboot command was passed to the operating system.

  • REBUILD. The server is currently being rebuilt from an image.

  • RESCUE. The server is in rescue mode. A rescue image is running with the original server image attached.

  • RESIZE. Server is performing the differential copy of data that changed during its initial copy. Server is down for this stage.

  • REVERT_RESIZE. The resize or migration of a server failed for some reason. The destination server is being cleaned up and the original source server is restarting.

  • SHELVED: The server is in shelved state. Depending on the shelve offload time, the server will be automatically shelved offloaded.

  • SHELVED_OFFLOADED: The shelved server is offloaded (removed from the compute host) and it needs unshelved action to be used again.

  • SHUTOFF. The server is powered off and the disk image still persists.

  • SOFT_DELETED. The server is marked as deleted but the disk images are still available to restore.

  • SUSPENDED. The server is suspended, either by request or necessity. When you suspend a server, its state is stored on disk, all memory is written to disk, and the server is stopped. Suspending a server is similar to placing a device in hibernation and its occupied resource will not be freed but rather kept for when the server is resumed. If a server is infrequently used and the occupied resource needs to be freed to create other servers, it should be shelved.

  • UNKNOWN. The state of the server is unknown. Contact your cloud provider.

  • VERIFY_RESIZE. System is awaiting confirmation that the server is operational after a move or resize.

There is whitelist for valid filter keys. Any filter key other than from whitelist will be silently ignored.

  • For non-admin users, whitelist is different from admin users whitelist. The valid whitelist can be configured using the os_compute_api:servers:allow_all_filters policy rule. By default, the valid whitelist for non-admin users includes

    • changes-since

    • flavor

    • image

    • ip

    • ip6 (New in version 2.5)

    • name

    • not-tags (New in version 2.26)

    • not-tags-any (New in version 2.26)

    • reservation_id

    • status

    • tags (New in version 2.26)

    • tags-any (New in version 2.26)

    • changes-before (New in version 2.66)

    • locked (New in version 2.73)

    • availability_zone (New in version 2.83)

    • config_drive (New in version 2.83)

    • key_name (New in version 2.83)

    • created_at (New in version 2.83)

    • launched_at (New in version 2.83)

    • terminated_at (New in version 2.83)

    • power_state (New in version 2.83)

    • task_state (New in version 2.83)

    • vm_state (New in version 2.83)

    • progress (New in version 2.83)

    • user_id (New in version 2.83)

  • For admin user, whitelist includes all filter keys mentioned in Request Section.

Note

Starting with microversion 2.69 if server details cannot be loaded due to a transient condition in the deployment like infrastructure failure, the response body for those unavailable servers will be missing keys. See handling down cells section of the Compute API guide for more information on the keys that would be returned in the partial constructs.

Normal response codes: 200

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

Request

Name

In

Type

Description

access_ip_v4 (Optional)

query

string

Filter server list result by IPv4 address that should be used to access the server.

access_ip_v6 (Optional)

query

string

Filter server list result by IPv6 address that should be used to access the server.

all_tenants (Optional)

query

boolean

Specify the all_tenants query parameter to list all instances for all projects. By default this is only allowed by administrators. If this parameter is specified without a value, the value defaults to True. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False. (They are case-insensitive.)

auto_disk_config (Optional)

query

string

Filter the server list result by the disk_config setting of the server, Valid values are:

  • AUTO

  • MANUAL

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

availability_zone (Optional)

query

string

Filter the server list result by server availability zone.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

changes-since (Optional)

query

string

Filters the response by a date and time stamp when the server last changed status. To help keep track of changes this may also return recently deleted servers.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-since must be earlier than or equal to the value of the changes-before otherwise API will return 400.

config_drive (Optional)

query

string

Filter the server list result by the config drive setting of the server.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

created_at (Optional)

query

string

Filter the server list result by a date and time stamp when server was created.

The date and time stamp format is ISO 8601:

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

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

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

deleted (Optional)

query

boolean

Show deleted items only. In some circumstances deleted items will still be accessible via the backend database, however there is no contract on how long, so this parameter should be used with caution. 1, t, true, on, y and yes are treated as True (case-insensitive). Other than them are treated as False.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

description (Optional)

query

string

Filter the server list result by description.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

Note

display_description can also be requested which is alias of description but that is not recommended to use as that will be removed in future.

flavor (Optional)

query

string

Filters the response by a flavor, as a UUID. A flavor is a combination of memory, disk size, and CPUs.

host (Optional)

query

string

Filter the server list result by the host name of compute node.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

hostname (Optional)

query

string

Filter the server list result by the host name of server.

This parameter is only valid when specified by administrators until microversion 2.90, after which it can be specified by all users. If non-admin users specify this parameter before microversion 2.90, it is ignored.

image (Optional)

query

string

Filters the response by an image, as a UUID.

Note

‘image_ref’ can also be requested which is alias of ‘image’ but that is not recommended to use as that will be removed in future.

ip (Optional)

query

string

An IPv4 address to filter results by.

ip6 (Optional)

query

string

An IPv6 address to filter results by.

Up to microversion 2.4, this parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored. Starting from microversion 2.5, this parameter is valid for no-admin users as well as administrators.

kernel_id (Optional)

query

string

Filter the server list result by the UUID of the kernel image when using an AMI.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

key_name (Optional)

query

string

Filter the server list result by keypair name.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

launch_index (Optional)

query

integer

Filter the server list result by the sequence in which the servers were launched.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

launched_at (Optional)

query

string

Filter the server list result by a date and time stamp when the instance was launched. The date and time stamp format is ISO 8601:

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

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

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

limit (Optional)

query

integer

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

locked_by (Optional)

query

string

Filter the server list result by who locked the server, possible value could be admin or owner.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

marker (Optional)

query

string

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

name (Optional)

query

string

Filters the response by a server name, as a string. You can use regular expressions in the query. For example, the ?name=bob regular expression returns both bob and bobb. If you must match on only bob, you can use a regular expression that matches the syntax of the underlying database server that is implemented for Compute, such as MySQL or PostgreSQL.

Note

‘display_name’ can also be requested which is alias of ‘name’ but that is not recommended to use as that will be removed in future.

node (Optional)

query

string

Filter the server list result by the node.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

power_state (Optional)

query

integer

Filter the server list result by server power state.

Possible values are integer values that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

progress (Optional)

query

integer

Filter the server list result by the progress of the server. The value could be from 0 to 100 as integer.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

project_id (Optional)

query

string

Filter the list of servers by the given project ID.

This filter only works when the all_tenants filter is also specified.

Note

‘tenant_id’ can also be requested which is alias of ‘project_id’ but that is not recommended to use as that will be removed in future.

ramdisk_id (Optional)

query

string

Filter the server list result by the UUID of the ramdisk image when using an AMI.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

reservation_id (Optional)

query

string

A reservation id as returned by a servers multiple create call.

root_device_name (Optional)

query

string

Filter the server list result by the root device name of the server.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

soft_deleted (Optional)

query

boolean

Filter the server list by SOFT_DELETED status. This parameter is only valid when the deleted=True filter parameter is specified.

sort_dir (Optional)

query

string

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

sort_key (Optional)

query

string

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

  • access_ip_v4

  • access_ip_v6

  • auto_disk_config

  • availability_zone

  • config_drive

  • created_at

  • display_description

  • display_name

  • host

  • hostname

  • image_ref

  • instance_type_id

  • kernel_id

  • key_name

  • launch_index

  • launched_at

  • locked (New in version 2.73)

  • locked_by

  • node

  • power_state

  • progress

  • project_id

  • ramdisk_id

  • root_device_name

  • task_state

  • terminated_at

  • updated_at

  • user_id

  • uuid

  • vm_state

host and node are only allowed for admin. If non-admin users specify them, a 403 error is returned.

status (Optional)

query

string

Filters the response by a server status, as a string. For example, ACTIVE.

Up to microversion 2.37, an empty list is returned if an invalid status is specified. Starting from microversion 2.38, a 400 error is returned in that case.

task_state (Optional)

query

string

Filter the server list result by task state.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

terminated_at (Optional)

query

string

Filter the server list result by a date and time stamp when instance was terminated. The date and time stamp format is ISO 8601:

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

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

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

user_id (Optional)

query

string

Filter the list of servers by the given user ID.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

uuid (Optional)

query

string

Filter the server list result by the UUID of the server.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

vm_state (Optional)

query

string

Filter the server list result by vm state.

The value could be:

  • ACTIVE

  • BUILDING

  • DELETED

  • ERROR

  • PAUSED

  • RESCUED

  • RESIZED

  • SHELVED

  • SHELVED_OFFLOADED

  • SOFT_DELETED

  • STOPPED

  • SUSPENDED

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

not-tags (Optional)

query

string

A list of tags to filter the server list by. Servers that don’t match all tags in this list will be returned. Boolean expression in this case is ‘NOT (t1 AND t2)’. Tags in query must be separated by comma.

New in version 2.26

not-tags-any (Optional)

query

string

A list of tags to filter the server list by. Servers that don’t match any tags in this list will be returned. Boolean expression in this case is ‘NOT (t1 OR t2)’. Tags in query must be separated by comma.

New in version 2.26

tags (Optional)

query

string

A list of tags to filter the server list by. Servers that match all tags in this list will be returned. Boolean expression in this case is ‘t1 AND t2’. Tags in query must be separated by comma.

New in version 2.26

tags-any (Optional)

query

string

A list of tags to filter the server list by. Servers that match any tag in this list will be returned. Boolean expression in this case is ‘t1 OR t2’. Tags in query must be separated by comma.

New in version 2.26

changes-before (Optional)

query

string

Filters the response by a date and time stamp when the server last changed. Those servers that changed before or equal to the specified date and time stamp are returned. To help keep track of changes this may also return recently deleted servers.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-before must be later than or equal to the value of the changes-since otherwise API will return 400.

New in version 2.66

locked (Optional)

query

boolean

Specify the locked query parameter to list all locked or unlocked instances. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False. (They are case-insensitive.) Any other value provided will be considered invalid.

New in version 2.73

Response

Name

In

Type

Description

servers

body

array

A list of server objects.

id

body

string

The UUID of the server.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

name

body

string

The server name.

servers_links (Optional)

body

array

Links to the next server. It is available when the number of servers exceeds limit parameter or [api]/max_limit in the configuration file. See Paginated collections for more info.

Example List Servers

{
    "servers": [
        {
            "id": "22c91117-08de-4894-9aa9-6ef382400985",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/servers/22c91117-08de-4894-9aa9-6ef382400985",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/22c91117-08de-4894-9aa9-6ef382400985",
                    "rel": "bookmark"
                }
            ],
            "name": "new-server-test"
        }
    ],
    "servers_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers?limit=1&marker=22c91117-08de-4894-9aa9-6ef382400985",
            "rel": "next"
        }
    ]
}

Example List Servers (2.69)

This is a sample response for the servers from the non-responsive part of the deployment. The responses for the available server records will be normal without any missing keys.

{
    "servers": [
        {
            "id": "2e136db7-b4a4-4815-8a00-25d9bfe59617",
            "status": "UNKNOWN",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/2e136db7-b4a4-4815-8a00-25d9bfe59617",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/2e136db7-b4a4-4815-8a00-25d9bfe59617",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}
POST
/servers

Create Server

Creates a server.

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

To check the progress of the request, make a GET /servers/{id} request. This call returns a progress attribute, which is a percentage value from 0 to 100.

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.

When you create a server, the response shows only the server ID, its links, and the admin password. You can get additional attributes through subsequent GET requests on the server.

Include the block_device_mapping_v2 parameter in the create request body to boot a server from a volume.

Include the key_name parameter in the create request body to add a keypair to the server when you create it. To create a keypair, make a create keypair request.

Note

Starting with microversion 2.37 the networks field is required.

Preconditions

  • The user must have sufficient server quota to create the number of servers requested.

  • The connection to the Image service is valid.

Asynchronous postconditions

  • With correct permissions, you can see the server status as ACTIVE through API calls.

  • With correct access, you can see the created server in the compute node that OpenStack Compute manages.

Troubleshooting

  • If the server status remains BUILDING or shows another error status, the request failed. Ensure you meet the preconditions then investigate the compute node.

  • The server is not created in the compute node that OpenStack Compute manages.

  • The compute node needs enough free resource to match the resource of the server creation request.

  • Ensure that the scheduler selection filter can fulfill the request with the available compute nodes that match the selection criteria of the filter.

Normal response codes: 202

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

Request

Name

In

Type

Description

server

body

object

A server object.

flavorRef

body

string

The flavor reference, as an ID (including a UUID) or full URL, for the flavor for your server instance.

name

body

string

The server name.

networks

body

array

A list of network object. Required parameter when there are multiple networks defined for the tenant. When you do not specify the networks parameter, the server attaches to the only network created for the current tenant. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a network, specify the UUID of the network in the uuid attribute in a networks object. To provision the server instance with a NIC for an already existing port, specify the port-id in the port attribute in a networks object.

If multiple networks are defined, the order in which they appear in the guest operating system will not necessarily reflect the order in which they are given in the server boot request. Guests should therefore not depend on device order to deduce any information about their network devices. Instead, device role tags should be used: introduced in 2.32, broken in 2.37, and re-introduced and fixed in 2.42, the tag is an optional, string attribute that can be used to assign a tag to a virtual network interface. This tag is then exposed to the guest in the metadata API and the config drive and is associated to hardware metadata for that network interface, such as bus (ex: PCI), bus address (ex: 0000:00:02.0), and MAC address.

A bug has caused the tag attribute to no longer be accepted starting with version 2.37. Therefore, network interfaces could only be tagged in versions 2.32 to 2.36 inclusively. Version 2.42 has restored the tag attribute.

Starting with microversion 2.37, this field is required and the special string values auto and none can be specified for networks. auto tells the Compute service to use a network that is available to the project, if one exists. If one does not exist, the Compute service will attempt to automatically allocate a network for the project (if possible). none tells the Compute service to not allocate a network for the instance. The auto and none values cannot be used with any other network values, including other network uuids, ports, fixed IPs or device tags. These are requested as strings for the networks value, not in a list. See the associated example.

networks.uuid (Optional)

body

string

To provision the server instance with a NIC for a network, specify the UUID of the network in the uuid attribute in a networks object. Required if you omit the port attribute.

Starting with microversion 2.37, this value is strictly enforced to be in UUID format.

networks.port (Optional)

body

string

To provision the server instance with a NIC for an already existing port, specify the port-id in the port attribute in a networks object. The port status must be DOWN. Required if you omit the uuid attribute. Requested security groups are not applied to pre-existing ports.

networks.fixed_ip (Optional)

body

string

A fixed IPv4 address for the NIC. Valid with a neutron or nova-networks network.

networks.tag (Optional)

body

string

A device role tag that can be applied to a network interface. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled.

Note

Due to a bug, network interface tags are accepted between 2.32 and 2.36 inclusively, and subsequently starting with version 2.42.

New in version 2.32

accessIPv4 (Optional)

body

string

IPv4 address that should be used to access this server.

accessIPv6 (Optional)

body

string

IPv6 address that should be used to access this server.

adminPass (Optional)

body

string

The administrative password of the server. If you omit this parameter, the operation generates a new password.

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 instance to be built. Typically, an admin user will use availability zones to arrange OpenStack compute hosts into logical groups.

An availability zone provides a form of physical isolation and redundancy from other availability zones. For instance, 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. See Availability Zones (AZs) for more information.

You can list the available availability zones by calling the Availability zones (os-availability-zone) API, but you should avoid using the default availability zone when creating the server. The default availability zone is named nova. This AZ is only shown when listing the availability zones as an admin.

block_device_mapping_v2 (Optional)

body

array

Enables fine grained control of the block device mapping for an instance. This is typically used for booting servers from volumes. An example format would look as follows:

"block_device_mapping_v2": [{
    "boot_index": "0",
    "uuid": "ac408821-c95a-448f-9292-73986c790911",
    "source_type": "image",
    "volume_size": "25",
    "destination_type": "volume",
    "delete_on_termination": true,
    "tag": "disk1",
    "disk_bus": "scsi"}]

In microversion 2.32, tag is an optional string attribute that can be used to assign a tag to the block device. This tag is then exposed to the guest in the metadata API and the config drive and is associated to hardware metadata for that block device, such as bus (ex: SCSI), bus address (ex: 1:0:2:0), and serial.

A bug has caused the tag attribute to no longer be accepted starting with version 2.33. It has been restored in version 2.42.

block_device_mapping_v2.boot_index

body

integer

Defines the order in which a hypervisor tries devices when it attempts to boot the guest from storage. Give each device a unique boot index starting from 0. To disable a device from booting, set the boot index to a negative value or use the default boot index value, which is None. The simplest usage is, set the boot index of the boot device to 0 and use the default boot index value, None, for any other devices. Some hypervisors might not support booting from multiple devices; these hypervisors consider only the device with a boot index of 0. Some hypervisors support booting from multiple devices but only if the devices are of different types. For example, a disk and CD-ROM.

block_device_mapping_v2.delete_on_termination (Optional)

body

boolean

To delete the boot volume when the server is destroyed, specify true. Otherwise, specify false. Default: false

block_device_mapping_v2.destination_type (Optional)

body

string

Defines where the block device mapping will reside. Valid values are:

  • local: The ephemeral disk resides local to the compute host on which the server runs

  • volume: The persistent volume is stored in the block storage service

block_device_mapping_v2.device_name (Optional)

body

string

A path to the device for the volume that you want to use to boot the server. Note that as of the 12.0.0 Liberty release, the Nova libvirt driver no longer honors a user-supplied device name. This is the same behavior as if the device name parameter is not supplied on the request.

block_device_mapping_v2.device_type (Optional)

body

string

The device type. For example, disk, cdrom.

block_device_mapping_v2.disk_bus (Optional)

body

string

Disk bus type, some hypervisors (currently only libvirt) support specify this parameter. Some example disk_bus values can be: fdc, ide, sata, scsi, usb, virtio, xen, lxc and uml. Support for each bus type depends on the virtualization driver and underlying hypervisor.

block_device_mapping_v2.guest_format (Optional)

body

string

Specifies the guest server disk file system format, such as ext2, ext3, ext4, xfs or swap.

Swap block device mappings have the following restrictions:

  • The source_type must be blank

  • The destination_type must be local

  • There can only be one swap disk per server

  • The size of the swap disk must be less than or equal to the swap size of the flavor

block_device_mapping_v2.no_device (Optional)

body

boolean

It is no device if True.

block_device_mapping_v2.source_type (Optional)

body

string

The source type of the block device. Valid values are:

  • blank: Depending on the destination_type and guest_format, this will either be a blank persistent volume or an ephemeral (or swap) disk local to the compute host on which the server resides

  • image: This is only valid with destination_type=volume; creates an image-backed volume in the block storage service and attaches it to the server

  • snapshot: This is only valid with destination_type=volume; creates a volume backed by the given volume snapshot referenced via the block_device_mapping_v2.uuid parameter and attaches it to the server

  • volume: This is only valid with destination_type=volume; uses the existing persistent volume referenced via the block_device_mapping_v2.uuid parameter and attaches it to the server

This parameter is required unless block_device_mapping_v2.no_device is specified.

See Block Device Mapping in Nova for more details on valid source and destination types.

block_device_mapping_v2.uuid (Optional)

body

string

This is the uuid of source resource. The uuid points to different resources based on the source_type. For example, if source_type is image, the block device is created based on the specified image which is retrieved from the image service. Similarly, if source_type is snapshot then the uuid refers to a volume snapshot in the block storage service. If source_type is volume then the uuid refers to a volume in the block storage service.

block_device_mapping_v2.volume_size (Optional)

body

integer

The size of the volume (in GiB). This is integer value from range 1 to 2147483647 which can be requested as integer and string. This parameter must be specified in the following cases:

  • An image to volume case

    • block_device_mapping_v2.source_type is image

    • block_device_mapping_v2.destination_type is volume

  • A blank to volume case

    • block_device_mapping_v2.source_type is blank

    • block_device_mapping_v2.destination_type is volume

block_device_mapping_v2.tag (Optional)

body

string

A device role tag that can be applied to a block device. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled.

Note

Due to a bug, block device tags are accepted in version 2.32 and subsequently starting with version 2.42.

New in version 2.32

block_device_mapping_v2.volume_type (Optional)

body

string

The device volume_type. This can be used to specify the type of volume which the compute service will create and attach to the server. If not specified, the block storage service will provide a default volume type. See the block storage volume types API for more details. There are some restrictions on volume_type:

  • It can be a volume type ID or name.

  • It is only supported with source_type of blank, image or snapshot.

  • It is only supported with destination_type of volume.

New in version 2.67

config_drive (Optional)

body

boolean

Indicates whether a config drive enables metadata injection. The config_drive setting provides information about a drive that the instance can mount at boot time. The instance reads files from the drive to get information that is normally available through the metadata service. This metadata is different from the user data. Not all cloud providers enable the config_drive. Read more in the OpenStack End User Guide.

imageRef (Optional)

body

string

The UUID of the image to use for your server instance. This is not required in case of boot from volume. In all other cases it is required and must be a valid UUID otherwise API will return 400.

key_name (Optional)

body

string

Key pair name.

Note

The null value was allowed in the Nova legacy v2 API, but due to strict input validation, it is not allowed in the Nova v2.1 API.

metadata (Optional)

body

object

Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.

OS-DCF:diskConfig (Optional)

body

string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

personality (Optional)

body

array

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.

Available until version 2.56

security_groups (Optional)

body

array

One or more security groups. Specify the name of the security group in the name attribute. If you omit this attribute, the API creates the server in the default security group. Requested security groups are not applied to pre-existing ports.

user_data (Optional)

body

string

Configuration information or scripts to use upon launch. Must be Base64 encoded. Restricted to 65535 bytes.

Note

The null value allowed in Nova legacy v2 API, but due to the strict input validation, it isn’t allowed in Nova v2.1 API.

description (Optional)

body

string

A free form description of the server. Limited to 255 characters in length. Before microversion 2.19 this was set to the server name.

New in version 2.19

hostname (Optional)

body

string

The hostname to configure for the instance in the metadata service.

Starting with microversion 2.94, this can be a Fully Qualified Domain Name (FQDN) of up to 255 characters in length.

Note

This information is published via the metadata service and requires application such as cloud-init to propagate it through to the instance.

New in version 2.90

tags (Optional)

body

array

A list of tags. Tags have the following restrictions:

  • Tag is a Unicode bytestring no longer than 60 characters.

  • Tag is a non-empty string.

  • ‘/’ is not allowed to be in a tag name

  • Comma is not allowed to be in a tag name in order to simplify requests that specify lists of tags

  • All other characters are allowed to be in a tag name

  • Each server can have up to 50 tags.

New in version 2.52

trusted_image_certificates (Optional)

body

array

A list of trusted certificate IDs, which are used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. This parameter is optional in server create requests if allowed by policy, and is not supported for volume-backed instances.

New in version 2.63

host (Optional)

body

string

The name of the compute service host on which the server is to be created. The API will return 400 if no compute services are found with the given host name. By default, it can be specified by administrators only.

New in version 2.74

hypervisor_hostname (Optional)

body

string

The hostname of the hypervisor on which the server is to be created. The API will return 400 if no hypervisors are found with the given hostname. By default, it can be specified by administrators only.

New in version 2.74

os:scheduler_hints (Optional)

body

object

The dictionary of data to send to the scheduler. Alternatively, you can specify OS-SCH-HNT:scheduler_hints as the key in the request body.

Note

This is a top-level key in the request body, not part of the server portion of the request body.

There are a few caveats with scheduler hints:

  • The request validation schema is per hint. For example, some require a single string value, and some accept a list of values.

  • Hints are only used based on the cloud scheduler configuration, which varies per deployment.

  • Hints are pluggable per deployment, meaning that a cloud can have custom hints which may not be available in another cloud.

For these reasons, it is important to consult each cloud’s user documentation to know what is available for scheduler hints.

os:scheduler_hints.build_near_host_ip (Optional)

body

string

Schedule the server on a host in the network specified with this parameter and a cidr (os:scheduler_hints.cidr). It is available when SimpleCIDRAffinityFilter is available on cloud side.

os:scheduler_hints.cidr (Optional)

body

string

Schedule the server on a host in the network specified with an IP address (os:scheduler_hints:build_near_host_ip) and this parameter. If os:scheduler_hints:build_near_host_ip is specified and this parameter is omitted, /24 is used. It is available when SimpleCIDRAffinityFilter is available on cloud side.

os:scheduler_hints.different_cell (Optional)

body

array

A list of cell routes or a cell route (string). Schedule the server in a cell that is not specified. It is available when DifferentCellFilter is available on cloud side that is cell v1 environment.

os:scheduler_hints.different_host (Optional)

body

array

A list of server UUIDs or a server UUID. Schedule the server on a different host from a set of servers. It is available when DifferentHostFilter is available on cloud side.

os:scheduler_hints.group (Optional)

body

string

The server group UUID. Schedule the server according to a policy of the server group (anti-affinity, affinity, soft-anti-affinity or soft-affinity). It is available when ServerGroupAffinityFilter, ServerGroupAntiAffinityFilter, ServerGroupSoftAntiAffinityWeigher, ServerGroupSoftAffinityWeigher are available on cloud side.

os:scheduler_hints.query (Optional)

body

string

Schedule the server by using a custom filter in JSON format. For example:

"query": "[\">=\",\"$free_ram_mb\",1024]"

It is available when JsonFilter is available on cloud side.

os:scheduler_hints.same_host (Optional)

body

array

A list of server UUIDs or a server UUID. Schedule the server on the same host as another server in a set of servers. It is available when SameHostFilter is available on cloud side.

os:scheduler_hints.target_cell (Optional)

body

string

A target cell name. Schedule the server in a host in the cell specified. It is available when TargetCellFilter is available on cloud side that is cell v1 environment.

Example Create Server

{
    "server" : {
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "name" : "new-server-test",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef" : "1",
        "availability_zone": "us-west",
        "OS-DCF:diskConfig": "AUTO",
        "metadata" : {
            "My Server Name" : "Apache1"
        },
        "personality": [
            {
                "path": "/etc/banner.txt",
                "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ],
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg=="
    },
    "OS-SCH-HNT:scheduler_hints": {
        "same_host": "48e6a9f6-30af-47e0-bc04-acaed113bb4e"
    }
}

Example Create Server With Networks(array) and Block Device Mapping V2 (v2.32)

{
    "server" : {
        "name" : "device-tagging-server",
        "flavorRef" : "http://openstack.example.com/flavors/1",
        "networks" : [{
            "uuid" : "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
            "tag": "nic1"
        }],
        "block_device_mapping_v2": [{
            "uuid": "70a599e0-31e7-49b7-b260-868f441e862b",
            "source_type": "image",
            "destination_type": "volume",
            "boot_index": 0,
            "volume_size": "1",
            "tag": "disk1"
        }]
    }
}

Example Create Server With Automatic Networking (v2.37)

{
    "server": {
        "name": "auto-allocate-network",
        "imageRef": "70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef": "http://openstack.example.com/flavors/1",
        "networks": "auto"
    }
}

Example Create Server With Trusted Image Certificates (v2.63)

{
    "server" : {
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "name" : "new-server-test",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef" : "6",
        "availability_zone": "%(availability_zone)s",
        "OS-DCF:diskConfig": "AUTO",
        "metadata" : {
            "My Server Name" : "Apache1"
        },
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
        "networks": "auto",
        "trusted_image_certificates": [
            "0b5d2c72-12cc-4ba6-a8d7-3ff5cc1d8cb8",
            "674736e3-f25c-405c-8362-bbf991e0ce0a"
        ]
    },
    "OS-SCH-HNT:scheduler_hints": {
        "same_host": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
    }
}

Example Create Server With Host and Hypervisor Hostname (v2.74)

{
    "server" : {
        "adminPass": "MySecretPass",
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "name" : "new-server-test",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef" : "6",
        "OS-DCF:diskConfig": "AUTO",
        "metadata" : {
            "My Server Name" : "Apache1"
        },
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
        "networks": "auto",
        "host": "openstack-node-01",
        "hypervisor_hostname": "openstack-node-01"
    }
}

Example Create Server With Hostname (v2.90)

{
    "server" : {
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "name" : "new-server-test",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef" : "1",
        "availability_zone": "us-west",
        "OS-DCF:diskConfig": "AUTO",
        "hostname": "custom-hostname",
        "metadata" : {
            "My Server Name" : "Apache1"
        },
        "personality": [
            {
                "path": "/etc/banner.txt",
                "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ],
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg=="
    },
    "OS-SCH-HNT:scheduler_hints": {
        "same_host": "48e6a9f6-30af-47e0-bc04-acaed113bb4e"
    }
}

Example Create Server With FQDN in Hostname (v2.94)

{
    "server" : {
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "name" : "new-server-test",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef" : "1",
        "availability_zone": "us-west",
        "OS-DCF:diskConfig": "AUTO",
        "hostname": "custom-hostname.example.com",
        "metadata" : {
            "My Server Name" : "Apache1"
        },
        "personality": [
            {
                "path": "/etc/banner.txt",
                "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ],
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg=="
    },
    "OS-SCH-HNT:scheduler_hints": {
        "same_host": "48e6a9f6-30af-47e0-bc04-acaed113bb4e"
    }
}

Response

Name

In

Type

Description

Location

header

string

The location URL of the server, HTTP header “Location: <server location URL>” will be returned.

server

body

object

A server object.

id

body

string

The UUID of the server.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

OS-DCF:diskConfig

body

string

Disk configuration. The value is either:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.

security_groups

body

array

One or more security groups objects.

security_groups.name

body

string

The security group name.

adminPass (Optional)

body

string

The administrative password for the server. If you set enable_instance_password configuration option to False, the API wouldn’t return the adminPass field in response.

Example Create Server

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "adminPass": "6NpUwoz2QDRN",
        "id": "f5dc173b-6804-445a-a6d8-c705dad5b5eb",
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/servers/f5dc173b-6804-445a-a6d8-c705dad5b5eb",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/f5dc173b-6804-445a-a6d8-c705dad5b5eb",
                "rel": "bookmark"
            }
        ],
        "security_groups": [
            {
                "name": "default"
            }
        ]
    }
}
POST
/servers

Create Multiple Servers

There is a second kind of create call which can build 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 built. This call should generally be avoided in favor of clients doing direct individual server creates.

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.

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.

return_reservation_id (Optional)

body

boolean

Set to True to request that the response return a reservation ID instead of instance information. Default is False.

Example Multiple Create with reservation ID

{
    "server": {
        "name": "new-server-test",
        "imageRef": "70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef": "1",
        "metadata": {
            "My Server Name": "Apache1"
        },
        "return_reservation_id": "True",
        "min_count": "2",
        "max_count": "3"
    }
}

Response

Name

In

Type

Description

reservation_id

body

string

The reservation id for the server. This is an id that can be useful in tracking groups of servers created with multiple create, that will all have the same reservation_id.

If return_reservation_id is set to true only the reservation_id will be returned. This can be used as a filter with list servers detailed to see the status of all the servers being built.

Example Create multiple servers with reservation ID

{
    "reservation_id": "r-3fhpjulh"
}

If return_reservation_id is set to false a representation of the first server will be returned.

Example Create multiple servers without reservation ID

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "adminPass": "wfksH3GTTseP",
        "id": "440cf918-3ee0-4143-b289-f63e1d2000e6",
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/servers/440cf918-3ee0-4143-b289-f63e1d2000e6",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/440cf918-3ee0-4143-b289-f63e1d2000e6",
                "rel": "bookmark"
            }
        ],
        "security_groups": [
            {
                "name": "default"
            }
        ]
    }
}
GET
/servers/detail

List Servers Detailed

For each server, shows server details including config drive, extended status, and server usage information.

The extended status information appears in the OS-EXT-STS:vm_state, OS-EXT-STS:power_state, and OS-EXT-STS:task_state attributes.

The server usage information appears in the OS-SRV-USG:launched_at and OS-SRV-USG:terminated_at attributes.

HostId is unique per account and is not globally unique.

Note

Starting with microversion 2.69 if server details cannot be loaded due to a transient condition in the deployment like infrastructure failure, the response body for those unavailable servers will be missing keys. See handling down cells section of the Compute API guide for more information on the keys that would be returned in the partial constructs.

Normal response codes: 200

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

Request

Name

In

Type

Description

access_ip_v4 (Optional)

query

string

Filter server list result by IPv4 address that should be used to access the server.

access_ip_v6 (Optional)

query

string

Filter server list result by IPv6 address that should be used to access the server.

all_tenants (Optional)

query

boolean

Specify the all_tenants query parameter to list all instances for all projects. By default this is only allowed by administrators. If this parameter is specified without a value, the value defaults to True. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False. (They are case-insensitive.)

auto_disk_config (Optional)

query

string

Filter the server list result by the disk_config setting of the server, Valid values are:

  • AUTO

  • MANUAL

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

availability_zone (Optional)

query

string

Filter the server list result by server availability zone.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

changes-since (Optional)

query

string

Filters the response by a date and time stamp when the server last changed status. To help keep track of changes this may also return recently deleted servers.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-since must be earlier than or equal to the value of the changes-before otherwise API will return 400.

config_drive (Optional)

query

string

Filter the server list result by the config drive setting of the server.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

created_at (Optional)

query

string

Filter the server list result by a date and time stamp when server was created.

The date and time stamp format is ISO 8601:

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

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

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

deleted (Optional)

query

boolean

Show deleted items only. In some circumstances deleted items will still be accessible via the backend database, however there is no contract on how long, so this parameter should be used with caution. 1, t, true, on, y and yes are treated as True (case-insensitive). Other than them are treated as False.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

description (Optional)

query

string

Filter the server list result by description.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

Note

display_description can also be requested which is alias of description but that is not recommended to use as that will be removed in future.

flavor (Optional)

query

string

Filters the response by a flavor, as a UUID. A flavor is a combination of memory, disk size, and CPUs.

host (Optional)

query

string

Filter the server list result by the host name of compute node.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

hostname (Optional)

query

string

Filter the server list result by the host name of server.

This parameter is only valid when specified by administrators until microversion 2.90, after which it can be specified by all users. If non-admin users specify this parameter before microversion 2.90, it is ignored.

image (Optional)

query

string

Filters the response by an image, as a UUID.

Note

‘image_ref’ can also be requested which is alias of ‘image’ but that is not recommended to use as that will be removed in future.

ip (Optional)

query

string

An IPv4 address to filter results by.

ip6 (Optional)

query

string

An IPv6 address to filter results by.

Up to microversion 2.4, this parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored. Starting from microversion 2.5, this parameter is valid for no-admin users as well as administrators.

kernel_id (Optional)

query

string

Filter the server list result by the UUID of the kernel image when using an AMI.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

key_name (Optional)

query

string

Filter the server list result by keypair name.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

launch_index (Optional)

query

integer

Filter the server list result by the sequence in which the servers were launched.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

launched_at (Optional)

query

string

Filter the server list result by a date and time stamp when the instance was launched. The date and time stamp format is ISO 8601:

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

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

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

limit (Optional)

query

integer

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

locked_by (Optional)

query

string

Filter the server list result by who locked the server, possible value could be admin or owner.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

marker (Optional)

query

string

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

name (Optional)

query

string

Filters the response by a server name, as a string. You can use regular expressions in the query. For example, the ?name=bob regular expression returns both bob and bobb. If you must match on only bob, you can use a regular expression that matches the syntax of the underlying database server that is implemented for Compute, such as MySQL or PostgreSQL.

Note

‘display_name’ can also be requested which is alias of ‘name’ but that is not recommended to use as that will be removed in future.

node (Optional)

query

string

Filter the server list result by the node.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

power_state (Optional)

query

integer

Filter the server list result by server power state.

Possible values are integer values that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

progress (Optional)

query

integer

Filter the server list result by the progress of the server. The value could be from 0 to 100 as integer.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

project_id (Optional)

query

string

Filter the list of servers by the given project ID.

This filter only works when the all_tenants filter is also specified.

Note

‘tenant_id’ can also be requested which is alias of ‘project_id’ but that is not recommended to use as that will be removed in future.

ramdisk_id (Optional)

query

string

Filter the server list result by the UUID of the ramdisk image when using an AMI.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

reservation_id (Optional)

query

string

A reservation id as returned by a servers multiple create call.

root_device_name (Optional)

query

string

Filter the server list result by the root device name of the server.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

soft_deleted (Optional)

query

boolean

Filter the server list by SOFT_DELETED status. This parameter is only valid when the deleted=True filter parameter is specified.

sort_dir (Optional)

query

string

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

sort_key (Optional)

query

string

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

  • access_ip_v4

  • access_ip_v6

  • auto_disk_config

  • availability_zone

  • config_drive

  • created_at

  • display_description

  • display_name

  • host

  • hostname

  • image_ref

  • instance_type_id

  • kernel_id

  • key_name

  • launch_index

  • launched_at

  • locked (New in version 2.73)

  • locked_by

  • node

  • power_state

  • progress

  • project_id

  • ramdisk_id

  • root_device_name

  • task_state

  • terminated_at

  • updated_at

  • user_id

  • uuid

  • vm_state

host and node are only allowed for admin. If non-admin users specify them, a 403 error is returned.

status (Optional)

query

string

Filters the response by a server status, as a string. For example, ACTIVE.

Up to microversion 2.37, an empty list is returned if an invalid status is specified. Starting from microversion 2.38, a 400 error is returned in that case.

task_state (Optional)

query

string

Filter the server list result by task state.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

terminated_at (Optional)

query

string

Filter the server list result by a date and time stamp when instance was terminated. The date and time stamp format is ISO 8601:

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

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

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

user_id (Optional)

query

string

Filter the list of servers by the given user ID.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

uuid (Optional)

query

string

Filter the server list result by the UUID of the server.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

vm_state (Optional)

query

string

Filter the server list result by vm state.

The value could be:

  • ACTIVE

  • BUILDING

  • DELETED

  • ERROR

  • PAUSED

  • RESCUED

  • RESIZED

  • SHELVED

  • SHELVED_OFFLOADED

  • SOFT_DELETED

  • STOPPED

  • SUSPENDED

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter on a microversion less than 2.83, it will be ignored.

not-tags (Optional)

query

string

A list of tags to filter the server list by. Servers that don’t match all tags in this list will be returned. Boolean expression in this case is ‘NOT (t1 AND t2)’. Tags in query must be separated by comma.

New in version 2.26

not-tags-any (Optional)

query

string

A list of tags to filter the server list by. Servers that don’t match any tags in this list will be returned. Boolean expression in this case is ‘NOT (t1 OR t2)’. Tags in query must be separated by comma.

New in version 2.26

tags (Optional)

query

string

A list of tags to filter the server list by. Servers that match all tags in this list will be returned. Boolean expression in this case is ‘t1 AND t2’. Tags in query must be separated by comma.

New in version 2.26

tags-any (Optional)

query

string

A list of tags to filter the server list by. Servers that match any tag in this list will be returned. Boolean expression in this case is ‘t1 OR t2’. Tags in query must be separated by comma.

New in version 2.26

changes-before (Optional)

query

string

Filters the response by a date and time stamp when the server last changed. Those servers that changed before or equal to the specified date and time stamp are returned. To help keep track of changes this may also return recently deleted servers.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-before must be later than or equal to the value of the changes-since otherwise API will return 400.

New in version 2.66

locked (Optional)

query

boolean

Specify the locked query parameter to list all locked or unlocked instances. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False. (They are case-insensitive.) Any other value provided will be considered invalid.

New in version 2.73

Response

Name

In

Type

Description

servers

body

array

A list of server objects.

accessIPv4

body

string

IPv4 address that should be used to access this server. May be automatically set by the provider.

accessIPv6

body

string

IPv6 address that should be used to access this server. May be automatically set by the provider.

addresses

body

object

The addresses for the server. Servers with status BUILD hide their addresses information.

config_drive

body

string

Indicates whether or not a config drive was used for this server. The value is True or an empty string. An empty string stands for False.

created

body

string

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

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

For example, 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.

flavor

body

object

Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system.

As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.

flavor.id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

Available until version 2.46

flavor.links

body

array

Links to the flavor resource. See API Guide / Links and References for more info.

Available until version 2.46

flavor.vcpus

body

integer

The number of virtual CPUs that were allocated to the server.

New in version 2.47

flavor.ram

body

integer

The amount of RAM a flavor has, in MiB.

New in version 2.47

flavor.disk

body

integer

The size of the root disk that was created in GiB.

New in version 2.47

flavor.ephemeral

body

integer

The size of the ephemeral disk that was created, in GiB.

New in version 2.47

flavor.swap

body

integer

The size of a dedicated swap disk that was allocated, in MiB.

New in version 2.47

flavor.original_name

body

string

The display name of a flavor.

New in version 2.47

flavor.extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.47

flavor.extra_specs.key

body

string

The extra spec key of a flavor.

New in version 2.47

flavor.extra_specs.value

body

string

The extra spec value of a flavor.

New in version 2.47

hostId

body

string

An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.

id

body

string

The UUID of the server.

image

body

object

The UUID and links for the image for your server instance. The image object will be an empty string when you boot the server from a volume.

key_name

body

string

The name of associated key pair, if any.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

metadata

body

object

A dictionary of metadata key-and-value pairs, which is maintained for backward compatibility.

name

body

string

The server name.

OS-DCF:diskConfig

body

string

Disk configuration. The value is either:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.

OS-EXT-AZ:availability_zone

body

string

The availability zone name.

OS-EXT-SRV-ATTR:host

body

string

The name of the compute host on which this instance is running. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:hostname (Optional)

body

string

The hostname of the instance reported in the metadata service. This parameter only appears in responses for administrators until microversion 2.90, after which it is shown for all users.

Note

This information is published via the metadata service and requires application such as cloud-init to propagate it through to the instance.

New in version 2.3

OS-EXT-SRV-ATTR:hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:instance_name

body

string

The instance name. The Compute API generates the instance name from the instance name template. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:kernel_id (Optional)

body

string

The UUID of the kernel image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:launch_index (Optional)

body

integer

When servers are launched via multiple create, this is the sequence in which the servers were launched. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:ramdisk_id (Optional)

body

string

The UUID of the ramdisk image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:reservation_id (Optional)

body

string

The reservation id for the server. This is an id that can be useful in tracking groups of servers created with multiple create, that will all have the same reservation_id. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:root_device_name (Optional)

body

string

The root device name for the instance By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:user_data (Optional)

body

string

The user_data the instance was created with. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-STS:power_state

body

integer

The power state of the instance. This is an enum value that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED

OS-EXT-STS:task_state

body

string

The task state of the instance.

OS-EXT-STS:vm_state

body

string

The VM state.

os-extended-volumes:volumes_attached

body

array

The attached volumes, if any.

os-extended-volumes:volumes_attached.id

body

string

The attached volume ID.

os-extended-volumes:volumes_attached.delete_on_termination

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted. By default this is False.

New in version 2.3

OS-SRV-USG: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. If the deleted_at date and time stamp is not set, its value is null.

OS-SRV-USG:terminated_at

body

string

The date and time when the server was deleted.

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. If the deleted_at date and time stamp is not set, its value is null.

status

body

string

The server status.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

updated

body

string

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

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

For example, 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.

user_id

body

string

The user ID of the user who owns the server.

fault (Optional)

body

object

A fault object. Only displayed when the server status is ERROR or DELETED and a fault occurred.

fault.code

body

integer

The error response code.

fault.created

body

string

The date and time when the exception was raised. 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.

fault.message

body

string

The error message.

fault.details (Optional)

body

string

The stack trace. It is available if the response code is not 500 or you have the administrator privilege

pinned_availability_zone (Optional)

body

string

This is the availability zone requested during server creation. Also when cross_az_attach option is false and booting an instance from volume, the instance can be pinned to AZ and in that case, instance will be scheduled on host belonging to pinned AZ. Also when default_schedule_zone config option set to specific AZ, in that case, instance would be pinned to that specific AZ, and instance will be scheduled on host belonging to pinned AZ.

New in version 2.96

progress (Optional)

body

integer

A percentage value of the operation progress. This parameter only appears when the server status is ACTIVE, BUILD, REBUILD, RESIZE, VERIFY_RESIZE or MIGRATING.

security_groups (Optional)

body

array

One or more security groups objects.

security_group.name

body

string

The security group name.

servers_links (Optional)

body

array

Links to the next server. It is available when the number of servers exceeds limit parameter or [api]/max_limit in the configuration file. See Paginated collections for more info.

locked

body

boolean

True if the instance is locked otherwise False.

New in version 2.9

host_status (Optional)

body

string

The host status. Values where next value in list can override the previous:

  • UP if nova-compute up.

  • UNKNOWN if nova-compute not reported by servicegroup driver.

  • DOWN if nova-compute forced down.

  • MAINTENANCE if nova-compute is disabled.

  • Empty string indicates there is no host for server.

This attribute appears in the response only if the policy permits. By default, only administrators can get this parameter.

New in version 2.16

description

body

string

The description of the server. Before microversion 2.19 this was set to the server name.

New in version 2.19

tags

body

array

A list of tags. The maximum count of tags in this list is 50.

New in version 2.26

trusted_image_certificates

body

array

A list of trusted certificate IDs, that were used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. The value is null if trusted certificate IDs are not set.

New in version 2.63

locked_reason

body

string

The reason behind locking a server.

New in version 2.73

Example List Servers Detailed (2.96)

{
    "servers": [
        {
            "accessIPv4": "1.2.3.4",
            "accessIPv6": "80fe::",
            "addresses": {
                "private": [
                    {
                        "addr": "192.168.1.30",
                        "OS-EXT-IPS-MAC:mac_addr": "00:0c:29:0d:11:74",
                        "OS-EXT-IPS:type": "fixed",
                        "version": 4
                    }
                ]
            },
            "created": "2013-09-03T04:01:32Z",
            "description": "",
            "flavor": {
                "disk": 1,
                "ephemeral": 0,
                "extra_specs": {},
                "original_name": "m1.tiny",
                "ram": 512,
                "swap": 0,
                "vcpus": 1
            },
            "hostId": "bcf92836fc9ed4203a75cb0337afc7f917d2be504164b995c2334b25",
            "id": "f5dc173b-6804-445a-a6d8-c705dad5b5eb",
            "image": {
                "id": "70a599e0-31e7-49b7-b260-868f441e862b",
                "links": [
                    {
                        "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                        "rel": "bookmark"
                    }
                ]
            },
            "key_name": null,
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/servers/f5dc173b-6804-445a-a6d8-c705dad5b5eb",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/f5dc173b-6804-445a-a6d8-c705dad5b5eb",
                    "rel": "bookmark"
                }
            ],
            "metadata": {
                "My Server Name": "Apache1"
            },
            "name": "new-server-test",
            "config_drive": "",
            "locked": false,
            "locked_reason": "",
            "OS-DCF:diskConfig": "AUTO",
            "OS-EXT-AZ:availability_zone": "us-west",
            "OS-EXT-SRV-ATTR:hostname": "new-server-test",
            "OS-EXT-STS:power_state": 1,
            "OS-EXT-STS:task_state": null,
            "OS-EXT-STS:vm_state": "active",
            "os-extended-volumes:volumes_attached": [
                {"id": "volume_id1", "delete_on_termination": false},
                {"id": "volume_id2", "delete_on_termination": false}
            ],
            "OS-SRV-USG:launched_at": "2013-09-23T13:53:12.774549",
            "OS-SRV-USG:terminated_at": null,
            "pinned_availability_zone": "us-west",
            "progress": 0,
            "security_groups": [
                {
                    "name": "default"
                }
            ],
            "status": "ACTIVE",
            "tags": [],
            "tenant_id": "6f70656e737461636b20342065766572",
            "trusted_image_certificates": null,
            "updated": "2013-09-03T04:01:32Z",
            "user_id": "fake"
        }
    ],
    "servers_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/detail?limit=1&marker=f5dc173b-6804-445a-a6d8-c705dad5b5eb",
            "rel": "next"
        }
    ]
}

Example List Servers Detailed (2.73)

{
    "servers": [
        {
            "OS-DCF:diskConfig": "AUTO",
            "OS-EXT-AZ:availability_zone": "nova",
            "OS-EXT-SRV-ATTR:host": "compute",
            "OS-EXT-SRV-ATTR:hostname": "new-server-test",
            "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
            "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
            "OS-EXT-SRV-ATTR:kernel_id": "",
            "OS-EXT-SRV-ATTR:launch_index": 0,
            "OS-EXT-SRV-ATTR:ramdisk_id": "",
            "OS-EXT-SRV-ATTR:reservation_id": "r-l0i0clt2",
            "OS-EXT-SRV-ATTR:root_device_name": "/dev/sda",
            "OS-EXT-SRV-ATTR:user_data": "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
            "OS-EXT-STS:power_state": 1,
            "OS-EXT-STS:task_state": null,
            "OS-EXT-STS:vm_state": "active",
            "OS-SRV-USG:launched_at": "2019-04-23T15:19:15.317839",
            "OS-SRV-USG:terminated_at": null,
            "accessIPv4": "1.2.3.4",
            "accessIPv6": "80fe::",
            "addresses": {
                "private": [
                    {
                        "OS-EXT-IPS-MAC:mac_addr": "00:0c:29:0d:11:74",
                        "OS-EXT-IPS:type": "fixed",
                        "addr": "192.168.1.30",
                        "version": 4
                    }
                ]
            },
            "config_drive": "",
            "created": "2019-04-23T15:19:14Z",
            "description": null,
            "flavor": {
                "disk": 1,
                "ephemeral": 0,
                "extra_specs": {},
                "original_name": "m1.tiny",
                "ram": 512,
                "swap": 0,
                "vcpus": 1
            },
            "hostId": "2091634baaccdc4c5a1d57069c833e402921df696b7f970791b12ec6",
            "host_status": "UP",
            "id": "2ce4c5b3-2866-4972-93ce-77a2ea46a7f9",
            "image": {
                "id": "70a599e0-31e7-49b7-b260-868f441e862b",
                "links": [
                    {
                        "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                        "rel": "bookmark"
                    }
                ]
            },
            "key_name": null,
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/2ce4c5b3-2866-4972-93ce-77a2ea46a7f9",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/2ce4c5b3-2866-4972-93ce-77a2ea46a7f9",
                    "rel": "bookmark"
                }
            ],
            "locked": true,
            "locked_reason": "I don't want to work",
            "metadata": {
                "My Server Name": "Apache1"
            },
            "name": "new-server-test",
            "os-extended-volumes:volumes_attached": [],
            "progress": 0,
            "security_groups": [
                {
                    "name": "default"
                }
            ],
            "status": "ACTIVE",
            "tags": [],
            "tenant_id": "6f70656e737461636b20342065766572",
            "trusted_image_certificates": null,
            "updated": "2019-04-23T15:19:15Z",
            "user_id": "admin"
        }
    ]
}

Example List Servers Detailed (2.69)

This is a sample response for the servers from the non-responsive part of the deployment. The responses for the available server records will be normal without any missing keys.

{
    "servers": [
        {
            "created": "2018-12-03T21:06:18Z",
            "id": "b6b0410f-b65f-4473-855e-5d82a71759e0",
            "status": "UNKNOWN",
            "tenant_id": "6f70656e737461636b20342065766572",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/b6b0410f-b65f-4473-855e-5d82a71759e0",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/b6b0410f-b65f-4473-855e-5d82a71759e0",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}
GET
/servers/{server_id}

Show Server Details

Shows details for a server.

Includes server details including configuration drive, extended status, and server usage information.

The extended status information appears in the OS-EXT-STS:vm_state, OS-EXT-STS:power_state, and OS-EXT-STS:task_state attributes.

The server usage information appears in the OS-SRV-USG:launched_at and OS-SRV-USG:terminated_at attributes.

HostId is unique per account and is not globally unique.

Preconditions

The server must exist.

Note

Starting with microversion 2.69 if the server detail cannot be loaded due to a transient condition in the deployment like infrastructure failure, the response body for the unavailable server will be missing keys. See handling down cells section of the Compute API guide for more information on the keys that would be returned in the partial constructs.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

server

body

object

A server object.

accessIPv4

body

string

IPv4 address that should be used to access this server. May be automatically set by the provider.

accessIPv6

body

string

IPv6 address that should be used to access this server. May be automatically set by the provider.

addresses

body

object

The addresses for the server. Servers with status BUILD hide their addresses information.

config_drive

body

string

Indicates whether or not a config drive was used for this server. The value is True or an empty string. An empty string stands for False.

created

body

string

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

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

For example, 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.

flavor

body

object

Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system.

As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.

flavor.id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

Available until version 2.46

flavor.links

body

array

Links to the flavor resource. See API Guide / Links and References for more info.

Available until version 2.46

flavor.vcpus

body

integer

The number of virtual CPUs that were allocated to the server.

New in version 2.47

flavor.ram

body

integer

The amount of RAM a flavor has, in MiB.

New in version 2.47

flavor.disk

body

integer

The size of the root disk that was created in GiB.

New in version 2.47

flavor.ephemeral

body

integer

The size of the ephemeral disk that was created, in GiB.

New in version 2.47

flavor.swap

body

integer

The size of a dedicated swap disk that was allocated, in MiB.

New in version 2.47

flavor.original_name

body

string

The display name of a flavor.

New in version 2.47

flavor.extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.47

flavor.extra_specs.key

body

string

The extra spec key of a flavor.

New in version 2.47

flavor.extra_specs.value

body

string

The extra spec value of a flavor.

New in version 2.47

hostId

body

string

An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.

id

body

string

The UUID of the server.

image

body

object

The UUID and links for the image for your server instance. The image object will be an empty string when you boot the server from a volume.

key_name

body

string

The name of associated key pair, if any.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

metadata

body

object

A dictionary of metadata key-and-value pairs, which is maintained for backward compatibility.

name

body

string

The server name.

OS-DCF:diskConfig

body

string

Disk configuration. The value is either:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.

OS-EXT-AZ:availability_zone

body

string

The availability zone name.

OS-EXT-SRV-ATTR:host

body

string

The name of the compute host on which this instance is running. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:hostname (Optional)

body

string

The hostname of the instance reported in the metadata service. This parameter only appears in responses for administrators until microversion 2.90, after which it is shown for all users.

Note

This information is published via the metadata service and requires application such as cloud-init to propagate it through to the instance.

New in version 2.3

OS-EXT-SRV-ATTR:hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:instance_name

body

string

The instance name. The Compute API generates the instance name from the instance name template. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:kernel_id (Optional)

body

string

The UUID of the kernel image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:launch_index (Optional)

body

integer

When servers are launched via multiple create, this is the sequence in which the servers were launched. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:ramdisk_id (Optional)

body

string

The UUID of the ramdisk image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:reservation_id (Optional)

body

string

The reservation id for the server. This is an id that can be useful in tracking groups of servers created with multiple create, that will all have the same reservation_id. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:root_device_name (Optional)

body

string

The root device name for the instance By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-SRV-ATTR:user_data (Optional)

body

string

The user_data the instance was created with. By default, it appears in the response for administrative users only.

New in version 2.3

OS-EXT-STS:power_state

body

integer

The power state of the instance. This is an enum value that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED

OS-EXT-STS:task_state

body

string

The task state of the instance.

OS-EXT-STS:vm_state

body

string

The VM state.

os-extended-volumes:volumes_attached

body

array

The attached volumes, if any.

os-extended-volumes:volumes_attached.id

body

string

The attached volume ID.

os-extended-volumes:volumes_attached.delete_on_termination

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted. By default this is False.

New in version 2.3

OS-SRV-USG: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. If the deleted_at date and time stamp is not set, its value is null.

OS-SRV-USG:terminated_at

body

string

The date and time when the server was deleted.

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. If the deleted_at date and time stamp is not set, its value is null.

status

body

string

The server status.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

updated

body

string

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

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

For example, 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.

user_id

body

string

The user ID of the user who owns the server.

fault (Optional)

body

object

A fault object. Only displayed when the server status is ERROR or DELETED and a fault occurred.

fault.code

body

integer

The error response code.

fault.created

body

string

The date and time when the exception was raised. 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.

fault.message

body

string

The error message.

fault.details (Optional)

body

string

The stack trace. It is available if the response code is not 500 or you have the administrator privilege

pinned_availability_zone (Optional)

body

string

This is the availability zone requested during server creation. Also when cross_az_attach option is false and booting an instance from volume, the instance can be pinned to AZ and in that case, instance will be scheduled on host belonging to pinned AZ. Also when default_schedule_zone config option set to specific AZ, in that case, instance would be pinned to that specific AZ, and instance will be scheduled on host belonging to pinned AZ.

New in version 2.96

progress (Optional)

body

integer

A percentage value of the operation progress. This parameter only appears when the server status is ACTIVE, BUILD, REBUILD, RESIZE, VERIFY_RESIZE or MIGRATING.

security_groups (Optional)

body

array

One or more security groups objects.

security_group.name

body

string

The security group name.

locked

body

boolean

True if the instance is locked otherwise False.

New in version 2.9

host_status (Optional)

body

string

The host status. Values where next value in list can override the previous:

  • UP if nova-compute up.

  • UNKNOWN if nova-compute not reported by servicegroup driver.

  • DOWN if nova-compute forced down.

  • MAINTENANCE if nova-compute is disabled.

  • Empty string indicates there is no host for server.

This attribute appears in the response only if the policy permits. By default, only administrators can get this parameter.

New in version 2.16

description

body

string

The description of the server. Before microversion 2.19 this was set to the server name.

New in version 2.19

tags

body

array

A list of tags. The maximum count of tags in this list is 50.

New in version 2.26

trusted_image_certificates

body

array

A list of trusted certificate IDs, that were used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. The value is null if trusted certificate IDs are not set.

New in version 2.63

server_groups

body

array

The UUIDs of the server groups to which the server belongs. Currently this can contain at most one entry.

New in version 2.71

locked_reason

body

string

The reason behind locking a server.

New in version 2.73

Example Show Server Details (2.96)

{
    "server": {
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "addresses": {
            "private": [
                {
                    "addr": "192.168.1.30",
                    "OS-EXT-IPS-MAC:mac_addr": "00:0c:29:0d:11:74",
                    "OS-EXT-IPS:type": "fixed",
                    "version": 4
                }
            ]
        },
        "created": "2013-09-03T04:01:32Z",
        "description": null,
        "locked": false,
        "locked_reason": null,
        "flavor": {
            "disk": 1,
            "ephemeral": 0,
            "extra_specs": {},
            "original_name": "m1.tiny",
            "ram": 512,
            "swap": 0,
            "vcpus": 1
        },
        "hostId": "92154fab69d5883ba2c8622b7e65f745dd33257221c07af363c51b29",
        "id": "0e44cc9c-e052-415d-afbf-469b0d384170",
        "image": {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                }
            ]
        },
        "key_name": null,
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/servers/0e44cc9c-e052-415d-afbf-469b0d384170",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/0e44cc9c-e052-415d-afbf-469b0d384170",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "My Server Name": "Apache1"
        },
        "name": "new-server-test",
        "config_drive": "",
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-AZ:availability_zone": "us-west",
        "OS-EXT-SRV-ATTR:hostname": "new-server-test",
        "OS-EXT-STS:power_state": 1,
        "OS-EXT-STS:task_state": null,
        "OS-EXT-STS:vm_state": "active",
        "os-extended-volumes:volumes_attached": [
            {"id": "volume_id1", "delete_on_termination": false},
            {"id": "volume_id2", "delete_on_termination": false}
        ],
        "OS-SRV-USG:launched_at": "2013-09-23T13:37:00.880302",
        "OS-SRV-USG:terminated_at": null,
        "pinned_availability_zone": "us-west",
        "progress": 0,
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "server_groups": [],
        "status": "ACTIVE",
        "tags": [],
        "tenant_id": "6f70656e737461636b20342065766572",
        "trusted_image_certificates": null,
        "updated": "2013-09-03T04:01:33Z",
        "user_id": "fake"
    }
}

Example Show Server Details (2.73)

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-AZ:availability_zone": "nova",
        "OS-EXT-SRV-ATTR:host": "compute",
        "OS-EXT-SRV-ATTR:hostname": "new-server-test",
        "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
        "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
        "OS-EXT-SRV-ATTR:kernel_id": "",
        "OS-EXT-SRV-ATTR:launch_index": 0,
        "OS-EXT-SRV-ATTR:ramdisk_id": "",
        "OS-EXT-SRV-ATTR:reservation_id": "r-t61j9da6",
        "OS-EXT-SRV-ATTR:root_device_name": "/dev/sda",
        "OS-EXT-SRV-ATTR:user_data": "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
        "OS-EXT-STS:power_state": 1,
        "OS-EXT-STS:task_state": null,
        "OS-EXT-STS:vm_state": "active",
        "OS-SRV-USG:launched_at": "2019-04-23T15:19:10.855016",
        "OS-SRV-USG:terminated_at": null,
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "addresses": {
            "private": [
                {
                    "OS-EXT-IPS-MAC:mac_addr": "00:0c:29:0d:11:74",
                    "OS-EXT-IPS:type": "fixed",
                    "addr": "192.168.1.30",
                    "version": 4
                }
            ]
        },
        "config_drive": "",
        "created": "2019-04-23T15:19:09Z",
        "description": null,
        "flavor": {
            "disk": 1,
            "ephemeral": 0,
            "extra_specs": {},
            "original_name": "m1.tiny",
            "ram": 512,
            "swap": 0,
            "vcpus": 1
        },
        "hostId": "2091634baaccdc4c5a1d57069c833e402921df696b7f970791b12ec6",
        "host_status": "UP",
        "id": "0e12087a-7c87-476a-8f84-7398e991cecc",
        "image": {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                }
            ]
        },
        "key_name": null,
        "links": [
            {
                "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/0e12087a-7c87-476a-8f84-7398e991cecc",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/0e12087a-7c87-476a-8f84-7398e991cecc",
                "rel": "bookmark"
            }
        ],
        "locked": true,
        "locked_reason": "I don't want to work",
        "metadata": {
            "My Server Name": "Apache1"
        },
        "name": "new-server-test",
        "os-extended-volumes:volumes_attached": [],
        "progress": 0,
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "server_groups": [],
        "status": "ACTIVE",
        "tags": [],
        "tenant_id": "6f70656e737461636b20342065766572",
        "trusted_image_certificates": null,
        "updated": "2019-04-23T15:19:11Z",
        "user_id": "admin"
    }
}

Example Show Server Details (2.69)

This is a sample response for a server from the non-responsive part of the deployment. The responses for available server records will be normal without any missing keys.

{
    "server": {
        "OS-EXT-AZ:availability_zone": "UNKNOWN",
        "OS-EXT-STS:power_state": 0,
        "created": "2018-12-03T21:06:18Z",
        "flavor": {
            "disk": 1,
            "ephemeral": 0,
            "extra_specs": {},
            "original_name": "m1.tiny",
            "ram": 512,
            "swap": 0,
            "vcpus": 1
        },
        "id": "33748c23-38dd-4f70-b774-522fc69e7b67",
        "image": {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                }
            ]
        },
        "status": "UNKNOWN",
        "tenant_id": "6f70656e737461636b20342065766572",
        "user_id": "admin",
        "links": [
            {
                "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/33748c23-38dd-4f70-b774-522fc69e7b67",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/33748c23-38dd-4f70-b774-522fc69e7b67",
                "rel": "bookmark"
            }
        ]
    }
}
PUT
/servers/{server_id}

Update Server

Updates the editable attributes of an existing server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

server

body

object

A server object.

accessIPv4 (Optional)

body

string

IPv4 address that should be used to access this server.

accessIPv6 (Optional)

body

string

IPv6 address that should be used to access this server.

name (Optional)

body

string

The server name.

hostname (Optional)

body

string

The hostname to configure for the instance in the metadata service.

Starting with microversion 2.94, this can be a Fully Qualified Domain Name (FQDN) of up to 255 characters in length.

Note

This information is published via the metadata service and requires application such as cloud-init to propagate it through to the instance.

New in version 2.90

OS-DCF:diskConfig (Optional)

body

string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

description (Optional)

body

string

A free form description of the server. Limited to 255 characters in length. Before microversion 2.19 this was set to the server name.

New in version 2.19

Note

You can specify parameters to update independently. e.g. name only, description only, name and description, etc.

Example Update Server (2.63)

{
    "server": {
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "OS-DCF:diskConfig": "AUTO",
        "name": "new-server-test",
        "description": "Sample description"
    }
}

Response

Name

In

Type

Description

server

body

object

A server object.

accessIPv4

body

string

IPv4 address that should be used to access this server. May be automatically set by the provider.

accessIPv6

body

string

IPv6 address that should be used to access this server. May be automatically set by the provider.

addresses

body

object

The addresses for the server. Servers with status BUILD hide their addresses information.

created

body

string

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

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

For example, 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.

flavor

body

object

Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system.

As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.

flavor.id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

Available until version 2.46

flavor.links

body

array

Links to the flavor resource. See API Guide / Links and References for more info.

Available until version 2.46

flavor.vcpus

body

integer

The number of virtual CPUs that were allocated to the server.

New in version 2.47

flavor.ram

body

integer

The amount of RAM a flavor has, in MiB.

New in version 2.47

flavor.disk

body

integer

The size of the root disk that was created in GiB.

New in version 2.47

flavor.ephemeral

body

integer

The size of the ephemeral disk that was created, in GiB.

New in version 2.47

flavor.swap

body

integer

The size of a dedicated swap disk that was allocated, in MiB.

New in version 2.47

flavor.original_name

body

string

The display name of a flavor.

New in version 2.47

flavor.extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.47

flavor.extra_specs.key

body

string

The extra spec key of a flavor.

New in version 2.47

flavor.extra_specs.value

body

string

The extra spec value of a flavor.

New in version 2.47

hostId

body

string

An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.

id

body

string

The UUID of the server.

image

body

object

The UUID and links for the image for your server instance. The image object will be an empty string when you boot the server from a volume.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

metadata

body

object

A dictionary of metadata key-and-value pairs, which is maintained for backward compatibility.

name

body

string

The server name.

OS-DCF:diskConfig

body

string

Disk configuration. The value is either:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.

status

body

string

The server status.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

updated

body

string

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

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

For example, 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.

user_id

body

string

The user ID of the user who owns the server.

fault (Optional)

body

object

A fault object. Only displayed when the server status is ERROR or DELETED and a fault occurred.

fault.code

body

integer

The error response code.

fault.created

body

string

The date and time when the exception was raised. 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.

fault.message

body

string

The error message.

fault.details (Optional)

body

string

The stack trace. It is available if the response code is not 500 or you have the administrator privilege

progress (Optional)

body

integer

A percentage value of the operation progress. This parameter only appears when the server status is ACTIVE, BUILD, REBUILD, RESIZE, VERIFY_RESIZE or MIGRATING.

locked

body

boolean

True if the instance is locked otherwise False.

New in version 2.9

description

body

string

The description of the server. Before microversion 2.19 this was set to the server name.

New in version 2.19

tags

body

array

A list of tags. The maximum count of tags in this list is 50.

New in version 2.26

trusted_image_certificates

body

array

A list of trusted certificate IDs, that were used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. The value is null if trusted certificate IDs are not set.

New in version 2.63

server_groups

body

array

The UUIDs of the server groups to which the server belongs. Currently this can contain at most one entry.

New in version 2.71

locked_reason

body

string

The reason behind locking a server.

New in version 2.73

config_drive

body

string

Indicates whether or not a config drive was used for this server. The value is True or an empty string. An empty string stands for False.

New in version 2.75

OS-EXT-AZ:availability_zone

body

string

The availability zone name.

New in version 2.75

OS-EXT-SRV-ATTR:host

body

string

The name of the compute host on which this instance is running. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:hostname (Optional)

body

string

The hostname of the instance reported in the metadata service. This parameter only appears in responses for administrators until microversion 2.90, after which it is shown for all users.

Note

This information is published via the metadata service and requires application such as cloud-init to propagate it through to the instance.

New in version 2.75

OS-EXT-SRV-ATTR:hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:instance_name

body

string

The instance name. The Compute API generates the instance name from the instance name template. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:kernel_id (Optional)

body

string

The UUID of the kernel image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:launch_index (Optional)

body

integer

When servers are launched via multiple create, this is the sequence in which the servers were launched. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:ramdisk_id (Optional)

body

string

The UUID of the ramdisk image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:reservation_id (Optional)

body

string

The reservation id for the server. This is an id that can be useful in tracking groups of servers created with multiple create, that will all have the same reservation_id. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:root_device_name (Optional)

body

string

The root device name for the instance By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:user_data (Optional)

body

string

The user_data the instance was created with. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-STS:power_state

body

integer

The power state of the instance. This is an enum value that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED

New in version 2.75

OS-EXT-STS:task_state

body

string

The task state of the instance.

New in version 2.75

OS-EXT-STS:vm_state

body

string

The VM state.

New in version 2.75

os-extended-volumes:volumes_attached

body

array

The attached volumes, if any.

New in version 2.75

os-extended-volumes:volumes_attached.id

body

string

The attached volume ID.

New in version 2.75

os-extended-volumes:volumes_attached.delete_on_termination

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted. By default this is False.

New in version 2.75

OS-SRV-USG: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. If the deleted_at date and time stamp is not set, its value is null.

New in version 2.75

OS-SRV-USG:terminated_at

body

string

The date and time when the server was deleted.

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. If the deleted_at date and time stamp is not set, its value is null.

New in version 2.75

security_groups (Optional)

body

array

One or more security groups objects.

New in version 2.75

security_group.name

body

string

The security group name.

New in version 2.75

host_status (Optional)

body

string

The host status. Values where next value in list can override the previous:

  • UP if nova-compute up.

  • UNKNOWN if nova-compute not reported by servicegroup driver.

  • DOWN if nova-compute forced down.

  • MAINTENANCE if nova-compute is disabled.

  • Empty string indicates there is no host for server.

This attribute appears in the response only if the policy permits. By default, only administrators can get this parameter.

New in version 2.75

key_name

body

string

The name of associated key pair, if any.

New in version 2.75

Example Update Server (2.75)

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-AZ:availability_zone": "us-west",
        "OS-EXT-SRV-ATTR:host": "compute",
        "OS-EXT-SRV-ATTR:hostname": "new-server-test",
        "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
        "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
        "OS-EXT-SRV-ATTR:kernel_id": "",
        "OS-EXT-SRV-ATTR:launch_index": 0,
        "OS-EXT-SRV-ATTR:ramdisk_id": "",
        "OS-EXT-SRV-ATTR:reservation_id": "r-t61j9da6",
        "OS-EXT-SRV-ATTR:root_device_name": "/dev/sda",
        "OS-EXT-SRV-ATTR:user_data": "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
        "OS-EXT-STS:power_state": 1,
        "OS-EXT-STS:task_state": null,
        "OS-EXT-STS:vm_state": "active",
        "OS-SRV-USG:launched_at": "2019-04-23T15:19:10.855016",
        "OS-SRV-USG:terminated_at": null,
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "addresses": {
            "private": [
                {
                    "OS-EXT-IPS-MAC:mac_addr": "00:0c:29:0d:11:74",
                    "OS-EXT-IPS:type": "fixed",
                    "addr": "192.168.1.30",
                    "version": 4
                }
            ]
        },
        "config_drive": "",
        "created": "2012-12-02T02:11:57Z",
        "description": "Sample description",
        "flavor": {
            "disk": 1,
            "ephemeral": 0,
            "extra_specs": {},
            "original_name": "m1.tiny",
            "ram": 512,
            "swap": 0,
            "vcpus": 1
        },
        "hostId": "6e84af987b4e7ec1c039b16d21f508f4a505672bd94fb0218b668d07",
        "host_status": "UP",
        "id": "324dfb7d-f4a9-419a-9a19-237df04b443b",
        "image": {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                }
            ]
        },
        "key_name": null,
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/servers/324dfb7d-f4a9-419a-9a19-237df04b443b",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/324dfb7d-f4a9-419a-9a19-237df04b443b",
                "rel": "bookmark"
            }
        ],
        "locked": false,
        "locked_reason": null,
        "metadata": {
            "My Server Name": "Apache1"
        },
        "name": "new-server-test",
        "os-extended-volumes:volumes_attached": [],
        "progress": 0,
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "server_groups": [],
        "status": "ACTIVE",
        "tags": [],
        "tenant_id": "6f70656e737461636b20342065766572",
        "trusted_image_certificates": null,
        "updated": "2012-12-02T02:11:58Z",
        "user_id": "admin"
    }
}
DELETE
/servers/{server_id}

Delete Server

Deletes a server.

By default, the instance is going to be (hard) deleted immediately from the system, but you can set reclaim_instance_interval > 0 to make the API soft delete the instance, so that the instance won’t be deleted until the reclaim_instance_interval has expired since the instance was soft deleted. The instance marked as SOFT_DELETED can be recovered via restore action before it’s really deleted from the system.

Preconditions

  • The server must exist.

  • Anyone can delete a server when the status of the server is not locked and when the policy allows.

  • If the server is locked, you must have administrator privileges to delete the server.

Asynchronous postconditions

  • With correct permissions, you can see the server status as deleting.

  • The ports attached to the server, which Nova created during the server create process or when attaching interfaces later, are deleted.

  • The server does not appear in the list servers response.

  • If hard delete, the server managed by OpenStack Compute is deleted on the compute node.

Troubleshooting

  • If server status remains in deleting status or another error status, the request failed. Ensure that you meet the preconditions. Then, investigate the compute back end.

  • The request returns the HTTP 409 response code when the server is locked even if you have correct permissions. Ensure that you meet the preconditions then investigate the server status.

  • The server managed by OpenStack Compute is not deleted from the compute node.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

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

Servers - run an action (servers, action)

Enables all users to perform an action on a server. Specify the action in the request body.

You can associate a fixed or floating IP address with a server, or disassociate a fixed or floating IP address from a server.

You can create an image from a server, create a backup of a server, and force-delete a server before deferred cleanup. You can lock, pause, reboot, rebuild, rescue, resize, resume, confirm the resize of, revert a pending resize for, shelve, shelf-offload, unshelve, start, stop, unlock, unpause, and unrescue a server. You can also change the password of the server and add a security group to or remove a security group from a server. You can also trigger a crash dump into a server since Mitaka release.

You can get an serial, SPICE, or VNC console for a server.

POST
/servers/{server_id}/action

Add (Associate) Floating Ip (addFloatingIp Action) (DEPRECATED)

Warning

This API is deprecated and will fail with a 404 starting from microversion 2.44. This is replaced with using the Neutron networking service API.

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

A pool of floating IP addresses, configured by the cloud administrator, is available in OpenStack Compute. The project quota defines the maximum number of floating IP addresses that you can allocate to the project. After you create (allocate) a floating IPaddress for a project, you can associate that address with the server. Specify the addFloatingIp action in the request body.

If an instance 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.

Preconditions

The server must exist.

You can only add a floating IP address to the server when its status is ACTIVE or STOPPED

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

addFloatingIp

body

object

The action. Contains required floating IP address and optional fixed_address.

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 Add (Associate) Floating Ip (addFloatingIp Action)

{
    "addFloatingIp" : {
        "address": "10.10.10.10",
        "fixed_address": "192.168.1.30"
    }
}

Response

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

POST
/servers/{server_id}/action

Add Security Group To A Server (addSecurityGroup Action)

Adds a security group to a server.

Specify the addSecurityGroup action in the request body.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

addSecurityGroup

body

object

The action to add a security group to a server.

name

body

string

The security group name.

Example Add Security Group To A Server (addSecurityGroup Action)

{
    "addSecurityGroup": {
        "name": "test"
    }
}

Response

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

POST
/servers/{server_id}/action

Change Administrative Password (changePassword Action)

Changes the administrative password for a server.

Specify the changePassword action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

changePassword

body

object

The action to change an administrative password of the server.

adminPass

body

string

The administrative password for the server.

Example Change Administrative Password (changePassword Action)

{
    "changePassword" : {
        "adminPass" : "foo"
    }
}

Response

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

POST
/servers/{server_id}/action

Confirm Resized Server (confirmResize Action)

Confirms a pending resize action for a server.

Specify the confirmResize action in the request body.

After you make this request, you typically must keep polling the server status to determine whether the request succeeded. A successfully confirming resize operation shows a status of ACTIVE or SHUTOFF and a migration status of confirmed. You can also see the resized server in the compute node that OpenStack Compute manages.

Preconditions

You can only confirm the resized server where the status is VERIFY_RESIZE.

If the server is locked, you must have administrator privileges to confirm the server.

Troubleshooting

If the server status remains VERIFY_RESIZE, the request failed. Ensure you meet the preconditions and run the request again. If the request fails again, the server status should be ERROR and a migration status of error. Investigate the compute back end or ask your cloud provider. There are some options for trying to correct the server status:

Note that the cloud provider may still need to cleanup any orphaned resources on the source hypervisor.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

confirmResize

body

none

The action to confirm a resize operation.

Example Confirm Resized Server (confirmResize Action)

{
    "confirmResize" : null
}

Response

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

POST
/servers/{server_id}/action

Create Server Back Up (createBackup Action)

Creates a back up of a server.

Note

This API is not supported for volume-backed instances.

Specify the createBackup action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Note

Starting from version 2.39 the image quota enforcement with Nova metadata is removed and quota checks should be performed using Glance API directly.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

createBackup

body

object

The action.

name

body

string

The name of the image to be backed up.

backup_type

body

string

The type of the backup, for example, daily.

rotation

body

integer

The rotation of the back up image, the oldest image will be removed when image count exceed the rotation count.

metadata (Optional)

body

object

Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.

Example Create Server Back Up (createBackup Action)

{
    "createBackup": {
        "name": "Backup 1",
        "backup_type": "daily",
        "rotation": 1
    }
}

Response

Name

In

Type

Description

Location

header

string

The image location URL of the image or backup created, HTTP header “Location: <image location URL>” will be returned.

Note

The URL returned may not be accessible to users and should not be relied upon. Use microversion 2.45 or simply parse the image ID out of the URL in the Location response header.

Available until version 2.44

image_id

body

string

The UUID for the resulting image snapshot.

New in version 2.45

Example Create Server Back Up (v2.45)

{
    "image_id": "0e7761dd-ee98-41f0-ba35-05994e446431"
}
POST
/servers/{server_id}/action

Create Image (createImage Action)

Creates an image from a server.

Specify the createImage action in the request body.

After you make this request, you typically must keep polling the status of the created image to determine whether the request succeeded.

If the operation succeeds, the created image has a status of active and the server status returns to the original status. You can also see the new image in the image back end that OpenStack Image service manages.

Note

Starting from version 2.39 the image quota enforcement with Nova metadata is removed and quota checks should be performed using Glance API directly.

Preconditions

The server must exist.

You can only create a new image from the server when its status is ACTIVE, SHUTOFF, SUSPENDED or PAUSED (PAUSED is only supported for image-backed servers).

The project must have sufficient volume snapshot quota in the block storage service when the server has attached volumes. If the project does not have sufficient volume snapshot quota, the API returns a 403 error.

Asynchronous Postconditions

A snapshot image will be created in the Image service.

In the image-backed server case, volume snapshots of attached volumes will not be created. In the volume-backed server case, volume snapshots will be created for all volumes attached to the server and then those will be represented with a block_device_mapping image property in the resulting snapshot image in the Image service. If that snapshot image is used later to create a new server, it will result in a volume-backed server where the root volume is created from the snapshot of the original root volume. The volumes created from the snapshots of the original other volumes will be attached to the server.

Troubleshooting

If the image status remains uploading or shows another error status, the request failed. Ensure you meet the preconditions and run the request again. If the request fails again, investigate the image back end.

If the server status does not go back to an original server’s status, the request failed. Ensure you meet the preconditions, or check if there is another operation that causes race conditions for the server, then run the request again. If the request fails again, investigate the compute back end or ask your cloud provider.

If the request fails due to an error on OpenStack Compute service, the image is purged from the image store that OpenStack Image service manages. Ensure you meet the preconditions and run the request again. If the request fails again, investigate OpenStack Compute service or ask your cloud provider.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

createImage

body

object

The action to create a snapshot of the image or the volume(s) of the server.

name

body

string

The display name of an Image.

metadata (Optional)

body

object

Metadata key and value pairs for the image. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Image (createImage Action)

{
    "createImage" : {
        "name" : "foo-image",
        "metadata": {
            "meta_var": "meta_val"
        }
    }
}

Response

Name

In

Type

Description

Location

header

string

The image location URL of the image or backup created, HTTP header “Location: <image location URL>” will be returned.

Note

The URL returned may not be accessible to users and should not be relied upon. Use microversion 2.45 or simply parse the image ID out of the URL in the Location response header.

Available until version 2.44

image_id

body

string

The UUID for the resulting image snapshot.

New in version 2.45

Example Create Image (v2.45)

{
    "image_id": "0e7761dd-ee98-41f0-ba35-05994e446431"
}
POST
/servers/{server_id}/action

Lock Server (lock Action)

Locks a server.

Specify the lock action in the request body.

Most actions by non-admin users are not allowed to the server after this operation is successful and the server is locked. See the “Lock, Unlock” item in Server actions for the restricted actions. But administrators can perform actions on the server even though the server is locked. Note that from microversion 2.73 it is possible to specify a reason when locking the server.

The unlock action will unlock a server in locked state so additional actions can be performed on the server by non-admin users.

You can know whether a server is locked or not and the locked_reason (if specified, from the 2.73 microversion) by the List Servers Detailed API or the Show Server Details API.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file. Administrators can overwrite owner’s lock.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

lock

body

object

The action to lock a server. This parameter can be null. Up to microversion 2.73, this parameter should be null.

locked_reason (Optional)

body

string

The reason behind locking a server. Limited to 255 characters in length.

New in version 2.73

Example Lock Server (lock Action)

{
    "lock": null
}

Example Lock Server (lock Action) (v2.73)

{
    "lock": {"locked_reason": "I don't want to work"}
}

Response

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

POST
/servers/{server_id}/action

Pause Server (pause Action)

Pauses a server. Changes its status to PAUSED.

Specify the pause action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

pause

body

none

The action to pause a server.

Example Pause Server (pause Action)

{
    "pause": null
}

Response

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

POST
/servers/{server_id}/action

Reboot Server (reboot Action)

Reboots a server.

Specify the reboot action in the request body.

Preconditions

The preconditions for rebooting a server depend on the type of reboot.

You can only SOFT reboot a server when its status is ACTIVE.

You can only HARD reboot a server when its status is one of:

  • ACTIVE

  • ERROR

  • HARD_REBOOT

  • PAUSED

  • REBOOT

  • SHUTOFF

  • SUSPENDED

If the server is locked, you must have administrator privileges to reboot the server.

Asynchronous Postconditions

After you successfully reboot a server, its status changes to ACTIVE.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

reboot

body

object

The action to reboot a server.

type

body

string

The type of the reboot action. The valid values are HARD and SOFT. A SOFT reboot attempts a graceful shutdown and restart of the server. A HARD reboot attempts a forced shutdown and restart of the server. The HARD reboot corresponds to the power cycles of the server.

Example Reboot Server (reboot Action)

{
    "reboot" : {
        "type" : "HARD"
    }
}

Response

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

POST
/servers/{server_id}/action

Rebuild Server (rebuild Action)

Rebuilds a server.

Specify the rebuild action in the request body.

This operation recreates the root disk of the server.

With microversion 2.93, we support rebuilding volume backed instances which will reimage the volume with the provided image. For microversion < 2.93, this operation keeps the contents of the volume given the image provided is same as the image with which the volume was created else the operation will error out.

Preconditions

The server status must be ACTIVE, SHUTOFF or ERROR.

Asynchronous Postconditions

If the server was in status SHUTOFF before the rebuild, it will be stopped and in status SHUTOFF after the rebuild, otherwise it will be ACTIVE if the rebuild was successful or ERROR if the rebuild failed.

Note

With microversion 2.93, we support rebuilding volume backed instances. If any microversion < 2.93 is specified, there is a known limitation where the root disk is not replaced for volume-backed instances during a rebuild.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

rebuild

body

object

The action to rebuild a server.

imageRef

body

string

The UUID of the image to rebuild for your server instance. It must be a valid UUID otherwise API will return 400. To rebuild a volume-backed server with a new image, at least microversion 2.93 needs to be provided in the request else the request will fall back to old behaviour i.e. the API will return 400 (for an image different from the image used when creating the volume). For non-volume-backed servers, specifying a new image will result in validating that the image is acceptable for the current compute host on which the server exists. If the new image is not valid, the server will go into ERROR status.

accessIPv4 (Optional)

body

string

IPv4 address that should be used to access this server.

accessIPv6 (Optional)

body

string

IPv6 address that should be used to access this server.

adminPass (Optional)

body

string

The administrative password of the server. If you omit this parameter, the operation generates a new password.

metadata (Optional)

body

object

Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.

name (Optional)

body

string

The server name.

OS-DCF:diskConfig (Optional)

body

string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

personality (Optional)

body

array

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.

Available until version 2.56

personality.path

body

string

The path field in the personality object.

Available until version 2.56

personality.contents

body

string

The file contents field in the personality object.

Available until version 2.56

preserve_ephemeral (Optional)

body

boolean

Indicates whether the server is rebuilt with the preservation of the ephemeral partition (true).

Note

This only works with baremetal servers provided by Ironic. Passing it to any other server instance results in a fault and will prevent the rebuild from happening.

description (Optional)

body

string

A free form description of the server. Limited to 255 characters in length. Before microversion 2.19 this was set to the server name.

New in version 2.19

key_name (Optional)

body

string

Key pair name for rebuild API. If null is specified, the existing keypair is unset.

Note

Users within the same project are able to rebuild other user’s instances in that project with a new keypair. Keys are owned by users (which is the only resource that’s true of). Servers are owned by projects. Because of this a rebuild with a key_name is looking up the keypair by the user calling rebuild.

New in version 2.54

user_data (Optional)

body

string

Configuration information or scripts to use upon rebuild. Must be Base64 encoded. Restricted to 65535 bytes. If null is specified, the existing user_data is unset.

New in version 2.57

trusted_image_certificates (Optional)

body

array

A list of trusted certificate IDs, which are used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. This parameter is optional in server rebuild requests if allowed by policy, and is not supported for volume-backed instances.

If null is specified, the existing trusted certificate IDs are either unset or reset to the configured defaults.

New in version 2.63

hostname (Optional)

body

string

The hostname to configure for the instance in the metadata service.

Starting with microversion 2.94, this can be a Fully Qualified Domain Name (FQDN) of up to 255 characters in length.

Note

This information is published via the metadata service and requires application such as cloud-init to propagate it through to the instance.

New in version 2.90

Example Rebuild Server (rebuild Action) (v2.63)

{
    "rebuild" : {
        "accessIPv4" : "1.2.3.4",
        "accessIPv6" : "80fe::",
        "OS-DCF:diskConfig": "AUTO",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "name" : "foobar",
        "key_name": "new-key",
        "description" : "description of foobar",
        "adminPass" : "seekr3t",
        "metadata" : {
            "meta_var" : "meta_val"
        },
        "user_data": "ZWNobyAiaGVsbG8gd29ybGQi",
        "trusted_image_certificates": [
            "0b5d2c72-12cc-4ba6-a8d7-3ff5cc1d8cb8",
            "674736e3-f25c-405c-8362-bbf991e0ce0a"
        ]
    }
}

Example Rebuild Server (rebuild Action) (v2.90)

{
    "rebuild" : {
        "accessIPv4" : "1.2.3.4",
        "accessIPv6" : "80fe::",
        "OS-DCF:diskConfig": "AUTO",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "name" : "foobar",
        "adminPass" : "seekr3t",
        "hostname": "custom-hostname",
        "metadata" : {
            "meta_var" : "meta_val"
        },
        "user_data": "ZWNobyAiaGVsbG8gd29ybGQi"
    }
}

Example Rebuild Server (rebuild Action) (v2.94)

{
    "rebuild" : {
        "accessIPv4" : "1.2.3.4",
        "accessIPv6" : "80fe::",
        "OS-DCF:diskConfig": "AUTO",
        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
        "name" : "foobar",
        "adminPass" : "seekr3t",
        "hostname": "custom-hostname.example.com",
        "metadata" : {
            "meta_var" : "meta_val"
        },
        "user_data": "ZWNobyAiaGVsbG8gd29ybGQi"
    }
}

Response

Name

In

Type

Description

Location

header

string

The location URL of the server, HTTP header “Location: <server location URL>” will be returned.

server

body

object

A server object.

accessIPv4

body

string

IPv4 address that should be used to access this server. May be automatically set by the provider.

accessIPv6

body

string

IPv6 address that should be used to access this server. May be automatically set by the provider.

addresses

body

object

The addresses information for the server.

created

body

string

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

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

For example, 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.

flavor

body

object

Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system.

As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.

flavor.id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

Available until version 2.46

flavor.links

body

array

Links to the flavor resource. See API Guide / Links and References for more info.

Available until version 2.46

flavor.vcpus

body

integer

The number of virtual CPUs that were allocated to the server.

New in version 2.47

flavor.ram

body

integer

The amount of RAM a flavor has, in MiB.

New in version 2.47

flavor.disk

body

integer

The size of the root disk that was created in GiB.

New in version 2.47

flavor.ephemeral

body

integer

The size of the ephemeral disk that was created, in GiB.

New in version 2.47

flavor.swap

body

integer

The size of a dedicated swap disk that was allocated, in MiB.

New in version 2.47

flavor.original_name

body

string

The display name of a flavor.

New in version 2.47

flavor.extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.47

flavor.extra_specs.key

body

string

The extra spec key of a flavor.

New in version 2.47

flavor.extra_specs.value

body

string

The extra spec value of a flavor.

New in version 2.47

hostId

body

string

An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.

id

body

string

The UUID of the server.

image

body

object

The UUID and links for the image for your server instance. The image object will be an empty string when you boot the server from a volume.

image.id

body

string

The ID of the Image.

image.links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

links

body

array

Links pertaining to the server. See API Guide / Links and References for more info.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

name

body

string

The server name.

OS-DCF:diskConfig

body

string

Disk configuration. The value is either:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.

status

body

string

The server status.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

updated

body

string

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

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

For example, 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.

user_id

body

string

The user ID of the user who owns the server.

adminPass (Optional)

body

string

The administrative password for the server. If you set enable_instance_password configuration option to False, the API wouldn’t return the adminPass field in response.

progress (Optional)

body

integer

A percentage value of the operation progress. This parameter only appears when the server status is ACTIVE, BUILD, REBUILD, RESIZE, VERIFY_RESIZE or MIGRATING.

locked

body

boolean

True if the instance is locked otherwise False.

New in version 2.9

description

body

string

The description of the server. Before microversion 2.19 this was set to the server name.

New in version 2.19

tags

body

array

A list of tags. The maximum count of tags in this list is 50.

New in version 2.26

key_name

body

string

The name of associated key pair, if any.

New in version 2.54

user_data

body

string

The current user_data for the instance.

New in version 2.57

trusted_image_certificates

body

array

A list of trusted certificate IDs, that were used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. The value is null if trusted certificate IDs are not set.

New in version 2.63

server_groups

body

array

The UUIDs of the server groups to which the server belongs. Currently this can contain at most one entry.

New in version 2.71

locked_reason

body

string

The reason behind locking a server.

New in version 2.73

config_drive

body

string

Indicates whether or not a config drive was used for this server. The value is True or an empty string. An empty string stands for False.

New in version 2.75

OS-EXT-AZ:availability_zone

body

string

The availability zone name.

New in version 2.75

OS-EXT-SRV-ATTR:host

body

string

The name of the compute host on which this instance is running. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:instance_name

body

string

The instance name. The Compute API generates the instance name from the instance name template. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-STS:power_state

body

integer

The power state of the instance. This is an enum value that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED

New in version 2.75

OS-EXT-STS:task_state

body

string

The task state of the instance.

New in version 2.75

OS-EXT-STS:vm_state

body

string

The VM state.

New in version 2.75

OS-EXT-SRV-ATTR:hostname (Optional)

body

string

The hostname of the instance reported in the metadata service. This parameter only appears in responses for administrators until microversion 2.90, after which it is shown for all users.

Note

This information is published via the metadata service and requires application such as cloud-init to propagate it through to the instance.

New in version 2.75

OS-EXT-SRV-ATTR:reservation_id (Optional)

body

string

The reservation id for the server. This is an id that can be useful in tracking groups of servers created with multiple create, that will all have the same reservation_id. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:launch_index (Optional)

body

integer

When servers are launched via multiple create, this is the sequence in which the servers were launched. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:kernel_id (Optional)

body

string

The UUID of the kernel image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:ramdisk_id (Optional)

body

string

The UUID of the ramdisk image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:root_device_name (Optional)

body

string

The root device name for the instance By default, it appears in the response for administrative users only.

New in version 2.75

os-extended-volumes:volumes_attached

body

array

The attached volumes, if any.

New in version 2.75

os-extended-volumes:volumes_attached.id

body

string

The attached volume ID.

New in version 2.75

os-extended-volumes:volumes_attached.delete_on_termination

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted. By default this is False.

New in version 2.75

OS-SRV-USG: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. If the deleted_at date and time stamp is not set, its value is null.

New in version 2.75

OS-SRV-USG:terminated_at

body

string

The date and time when the server was deleted.

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. If the deleted_at date and time stamp is not set, its value is null.

New in version 2.75

security_groups (Optional)

body

array

One or more security groups objects.

New in version 2.75

security_group.name

body

string

The security group name.

New in version 2.75

host_status (Optional)

body

string

The host status. Values where next value in list can override the previous:

  • UP if nova-compute up.

  • UNKNOWN if nova-compute not reported by servicegroup driver.

  • DOWN if nova-compute forced down.

  • MAINTENANCE if nova-compute is disabled.

  • Empty string indicates there is no host for server.

This attribute appears in the response only if the policy permits. By default, only administrators can get this parameter.

New in version 2.75

Example Rebuild Server (rebuild Action) (v2.75)

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-AZ:availability_zone": "us-west",
        "OS-EXT-SRV-ATTR:host": "compute",
        "OS-EXT-SRV-ATTR:hostname": "new-server-test",
        "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
        "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
        "OS-EXT-SRV-ATTR:kernel_id": "",
        "OS-EXT-SRV-ATTR:launch_index": 0,
        "OS-EXT-SRV-ATTR:ramdisk_id": "",
        "OS-EXT-SRV-ATTR:reservation_id": "r-t61j9da6",
        "OS-EXT-SRV-ATTR:root_device_name": "/dev/sda",
        "OS-EXT-STS:power_state": 1,
        "OS-EXT-STS:task_state": null,
        "OS-EXT-STS:vm_state": "active",
        "OS-SRV-USG:launched_at": "2019-04-23T15:19:10.855016",
        "OS-SRV-USG:terminated_at": null,
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "addresses": {
            "private": [
                {
                    "OS-EXT-IPS-MAC:mac_addr": "00:0c:29:0d:11:74",
                    "OS-EXT-IPS:type": "fixed",
                    "addr": "192.168.1.30",
                    "version": 4
                }
            ]
        },
        "adminPass": "seekr3t",
        "config_drive": "",
        "created": "2019-04-23T17:10:22Z",
        "description": null,
        "flavor": {
            "disk": 1,
            "ephemeral": 0,
            "extra_specs": {},
            "original_name": "m1.tiny",
            "ram": 512,
            "swap": 0,
            "vcpus": 1
        },
        "hostId": "2091634baaccdc4c5a1d57069c833e402921df696b7f970791b12ec6",
        "host_status": "UP",
        "id": "0c37a84a-c757-4f22-8c7f-0bf8b6970886",
        "image": {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                }
            ]
        },
        "key_name": null,
        "links": [
            {
                "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/0c37a84a-c757-4f22-8c7f-0bf8b6970886",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/0c37a84a-c757-4f22-8c7f-0bf8b6970886",
                "rel": "bookmark"
            }
        ],
        "locked": false,
        "locked_reason": null,
        "metadata": {
            "meta_var": "meta_val"
        },
        "name": "foobar",
        "os-extended-volumes:volumes_attached": [],
        "progress": 0,
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "server_groups": [],
        "status": "ACTIVE",
        "tags": [],
        "tenant_id": "6f70656e737461636b20342065766572",
        "trusted_image_certificates": null,
        "updated": "2019-04-23T17:10:24Z",
        "user_data": "ZWNobyAiaGVsbG8gd29ybGQi",
        "user_id": "admin"
    }
}
POST
/servers/{server_id}/action

Remove (Disassociate) Floating Ip (removeFloatingIp Action) (DEPRECATED)

Warning

This API is deprecated and will fail with a 404 starting from microversion 2.44. This is replaced with using the Neutron networking service API.

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

The IP address is returned to the pool of IP addresses that is available for all projects. When you remove a floating IP address and that IP address is still associated with a running instance, it is automatically disassociated from that instance.

Specify the removeFloatingIp action in the request body.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

removeFloatingIp

body

object

The action to remove or disassociate a floating IP address from the server.

address

body

string

The floating IP address.

Example Remove (Disassociate) Floating Ip (removeFloatingIp Action)

{
    "removeFloatingIp": {
        "address": "172.16.10.7"
    }
}

Response

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

POST
/servers/{server_id}/action

Remove Security Group From A Server (removeSecurityGroup Action)

Removes a security group from a server.

Specify the removeSecurityGroup action in the request body.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

removeSecurityGroup

body

object

The action to remove a security group from the server.

name

body

string

The security group name.

Example Remove Security Group From A Server (removeSecurityGroup Action)

{
    "removeSecurityGroup": {
        "name": "test"
    }
}

Response

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

POST
/servers/{server_id}/action

Rescue Server (rescue Action)

Puts a server in rescue mode and changes its status to RESCUE.

Note

Until microversion 2.87, this API is not supported for volume-backed instances.

Specify the rescue action in the request body.

If you specify the rescue_image_ref extended attribute, the image is used to rescue the instance. If you omit an image reference, the base image reference is used by default.

Asynchronous Postconditions

After you successfully rescue a server and make a GET /servers/​{server_id}​ request, its status changes to RESCUE.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

rescue

body

object

The action to rescue a server.

adminPass (Optional)

body

string

The password for the rescued instance. If you omit this parameter, the operation generates a new password.

rescue_image_ref (Optional)

body

string

The image reference to use to rescue your server instance. Specify the image reference by ID or full URL. If you omit an image reference, default is the base image reference.

Example Rescue server (rescue Action)

{
    "rescue": {
        "adminPass": "MySecretPass",
        "rescue_image_ref": "70a599e0-31e7-49b7-b260-868f441e862b"
    }
}

Response

Name

In

Type

Description

adminPass (Optional)

body

string

The administrative password for the server. If you set enable_instance_password configuration option to False, the API wouldn’t return the adminPass field in response.

Example Rescue server (rescue Action)

{
    "adminPass": "MySecretPass"
}
POST
/servers/{server_id}/action

Resize Server (resize Action)

Resizes a server.

Specify the resize action in the request body.

Preconditions

You can only resize a server when its status is ACTIVE or SHUTOFF.

If the server is locked, you must have administrator privileges to resize the server.

Asynchronous Postconditions

A successfully resized server shows a VERIFY_RESIZE status and finished migration status. If the cloud has configured the resize_confirm_window option of the Compute service to a positive value, the Compute service automatically confirms the resize operation after the configured interval.

Note

There is a known limitation that ephemeral disks are not resized.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

resize

body

object

The action to resize a server.

flavorRef

body

string

The flavor ID for resizing the server. The size of the disk in the flavor being resized to must be greater than or equal to the size of the disk in the current flavor.

If a specified flavor ID is the same as the current one of the server, the request returns a Bad Request (400) response code.

OS-DCF:diskConfig (Optional)

body

string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

Example Resize Server (Resize Action)

{
    "resize" : {
        "flavorRef" : "2",
        "OS-DCF:diskConfig": "AUTO"
    }
}

Response

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

POST
/servers/{server_id}/action

Resume Suspended Server (resume Action)

Resumes a suspended server and changes its status to ACTIVE.

Specify the resume action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

resume

body

none

The action to resume a suspended server.

Example Resume Suspended Server (Resume Action)

{
    "resume": null
}

Response

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

POST
/servers/{server_id}/action

Revert Resized Server (revertResize Action)

Cancels and reverts a pending resize action for a server.

Specify the revertResize action in the request body.

Preconditions

You can only revert the resized server where the status is VERIFY_RESIZE and the OS-EXT-STS:vm_state is resized.

If the server is locked, you must have administrator privileges to revert the resizing.

Asynchronous Postconditions

After you make this request, you typically must keep polling the server status to determine whether the request succeeded. A reverting resize operation shows a status of REVERT_RESIZE and a task_state of resize_reverting. If successful, the status will return to ACTIVE or SHUTOFF. You can also see the reverted server in the compute node that OpenStack Compute manages.

Troubleshooting

If the server status remains VERIFY_RESIZE, the request failed. Ensure you meet the preconditions and run the request again. If the request fails again, investigate the compute back end.

The server is not reverted in the compute node that OpenStack Compute manages.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

revertResize

body

none

The action to revert a resize operation.

Example Revert Resized Server (revertResize Action)

{
    "revertResize" : null
}

Response

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

POST
/servers/{server_id}/action

Start Server (os-start Action)

Starts a stopped server and changes its status to ACTIVE.

Specify the os-start action in the request body.

Preconditions

The server status must be SHUTOFF.

If the server is locked, you must have administrator privileges to start the server.

Asynchronous Postconditions

After you successfully start a server, its status changes to ACTIVE.

Troubleshooting

If the server status does not change to ACTIVE, the start operation failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate whether another operation is running that causes a race condition.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-start

body

none

The action to start a stopped server.

Example Start server

{
    "os-start" : null
}

Response

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

POST
/servers/{server_id}/action

Stop Server (os-stop Action)

Stops a running server and changes its status to SHUTOFF.

Specify the os-stop action in the request body.

Preconditions

The server status must be ACTIVE or ERROR.

If the server is locked, you must have administrator privileges to stop the server.

Asynchronous Postconditions

After you successfully stop a server, its status changes to SHUTOFF. This API operation does not delete the server instance data and the data will be available again after os-start action.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-stop

body

none

The action to stop a running server.

Example Stop server

{
    "os-stop" : null
}

Response

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

POST
/servers/{server_id}/action

Suspend Server (suspend Action)

Suspends a server and changes its status to SUSPENDED.

Specify the suspend action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

suspend

body

none

The action to suspend a server.

Example Suspend Server (suspend Action)

{
    "suspend": null
}

Response

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

POST
/servers/{server_id}/action

Unlock Server (unlock Action)

Unlocks a locked server.

Specify the unlock action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

unlock

body

none

The action to unlock a locked server.

Example Unlock Server (unlock Action)

{
    "unlock": null
}

Response

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

POST
/servers/{server_id}/action

Unpause Server (unpause Action)

Unpauses a paused server and changes its status to ACTIVE.

Specify the unpause action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

unpause

body

none

The action to unpause a paused server.

Example Unpause Server (unpause Action)

{
    "unpause": null
}

Response

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

POST
/servers/{server_id}/action

Unrescue Server (unrescue Action)

Unrescues a server. Changes status to ACTIVE.

Specify the unrescue action in the request body.

Preconditions

The server must exist.

You can only unrescue a server when its status is RESCUE.

Asynchronous Postconditions

After you successfully unrescue a server and make a GET /servers/​{server_id}​ request, its status changes to ACTIVE.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

unrescue

body

none

The action to unrescue a server in rescue mode.

Example Unrescue server

{
    "unrescue": null
}

Response

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

POST
/servers/{server_id}/action

Add (Associate) Fixed Ip (addFixedIp Action) (DEPRECATED)

Warning

This API is deprecated and will fail with a 404 starting from microversion 2.44. This is replaced with using the Neutron networking service API.

Adds a fixed IP address to a server instance, which associates that address with the server. The fixed IP address is retrieved from the network that you specify in the request.

Specify the addFixedIp action and the network ID in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

addFixedIp

body

object

The action to add a fixed ip address to a server.

networkId

body

string

The network ID.

Example Add (Associate) Fixed Ip (addFixedIp Action)

{
    "addFixedIp": {
        "networkId": "e1882e38-38c2-4239-ade7-35d644cb963a"
    }
}

Response

No response body is returned after a successful addFixedIp action.

POST
/servers/{server_id}/action

Remove (Disassociate) Fixed Ip (removeFixedIp Action) (DEPRECATED)

Warning

This API is deprecated and will fail with a 404 starting from microversion 2.44. This is replaced with using the Neutron networking service API.

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

Specify the removeFixedIp action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

removeFixedIp

body

object

The action to remove a fixed ip address from a server.

address

body

string

The IP address.

Example Remove (Disassociate) Fixed Ip (removeFixedIp Action)

{
    "removeFixedIp": {
        "address": "10.0.0.4"
    }
}

Response

No response body is returned after a successful removeFixedIp action.

POST
/servers/{server_id}/action

Force-Delete Server (forceDelete Action)

Force-deletes a server before deferred cleanup.

Specify the forceDelete action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

forceDelete

body

none

The action.

Example Force-Delete Server (forceDelete Action): JSON request

{
    "forceDelete": null
}

Response

No body is returned on a successful submission.

POST
/servers/{server_id}/action

Restore Soft-Deleted Instance (restore Action)

Restores a previously soft-deleted server instance. You cannot use this method to restore deleted instances.

Specify the restore action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

restore

body

none

The action.

Example Restore Soft-Deleted Instance (restore Action): JSON request

{
    "restore": null
}

Response

No body is returned on a successful submission.

POST
/servers/{server_id}/action

Show Console Output (os-getConsoleOutput Action)

Shows console output for a server.

This API returns the text of the console since boot. The content returned may be large. Limit the lines of console text, beginning at the tail of the content, by setting the optional length parameter in the request body.

The server to get console log from should set export LC_ALL=en_US.UTF-8 in order to avoid incorrect unicode error.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), notFound(404), conflict(409), methodNotImplemented(501)

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-getConsoleOutput

body

object

The action to get console output of the server.

length (Optional)

body

integer

The number of lines to fetch from the end of console log. All lines will be returned if this is not specified.

Note

This parameter can be specified as not only ‘integer’ but also ‘string’.

Example Show Console Output (os-getConsoleOutput Action)

This example requests the last 50 lines of console content from the specified server.

{
    "os-getConsoleOutput": {
        "length": 50
    }
}

Response

Name

In

Type

Description

output

body

string

The console output as a string. Control characters will be escaped to create a valid JSON string.

Example Show Console Output (os-getConsoleOutput Action)

{
    "output": "FAKE CONSOLE OUTPUT\nANOTHER\nLAST LINE"
}
POST
/servers/{server_id}/action

Shelve Server (shelve Action)

Shelves a server.

Specify the shelve action in the request body.

All associated data and resources are kept but anything still in memory is not retained. To restore a shelved instance, use the unshelve action. To remove a shelved instance, use the shelveOffload action.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Preconditions

The server status must be ACTIVE, SHUTOFF, PAUSED, or SUSPENDED.

If the server is locked, you must have administrator privileges to shelve the server.

Asynchronous Postconditions

After you successfully shelve a server, its status changes to SHELVED and the image status is ACTIVE. The server instance data appears on the compute node that the Compute service manages.

If you boot the server from volumes or set the shelved_offload_time option to 0, the Compute service automatically deletes the instance on compute nodes and changes the server status to SHELVED_OFFLOADED.

Troubleshooting

If the server status does not change to SHELVED or SHELVED_OFFLOADED, the shelve operation failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate whether another operation is running that causes a race condition.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

shelve

body

none

The action.


Example Shelve server (shelve Action)

{
    "shelve": null
}

Response

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

POST
/servers/{server_id}/action

Shelf-Offload (Remove) Server (shelveOffload Action)

Shelf-offloads, or removes, a shelved server.

Specify the shelveOffload action in the request body.

Data and resource associations are deleted. If an instance is no longer needed, you can remove that instance from the hypervisor to minimize resource usage.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Preconditions

The server status must be SHELVED.

If the server is locked, you must have administrator privileges to shelve-offload the server.

Asynchronous Postconditions

After you successfully shelve-offload a server, its status changes to SHELVED_OFFLOADED. The server instance data appears on the compute node.

Troubleshooting

If the server status does not change to SHELVED_OFFLOADED, the shelve-offload operation failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate whether another operation is running that causes a race condition.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

shelveOffload

body

none

The action.


Example Shelf-Offload server (shelveOffload Action)

{
    "shelveOffload": null
}

Response

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

POST
/servers/{server_id}/action

Unshelve (Restore) Shelved Server (unshelve Action)

Unshelves, or restores, a shelved server.

Specify the unshelve action in the request body.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Preconditions

Unshelving a server without parameters requires its status to be SHELVED or SHELVED_OFFLOADED.

Unshelving a server with availability_zone and/or host parameters requires its status to be only SHELVED_OFFLOADED otherwise HTTP 409 conflict response is returned.

If a server is locked, you must have administrator privileges to unshelve the server.

As of microversion 2.91, you can unshelve to a specific compute node if you have PROJECT_ADMIN privileges. This microversion also gives the ability to pin a server to an availability_zone and to unpin a server from any availability_zone.

When a server is pinned to an availability_zone, the server move operations will keep the server in that availability_zone. However, when the server is not pinned to any availability_zone, the move operations can move the server to nodes in different availability_zones.

The behavior according to unshelve parameters will follow the below table.

Boot

AZ (1)

Host (1)

Result

No AZ

No AZ or AZ=null

No

Free scheduling (2)

No AZ

No AZ or AZ=null

Host1

Schedule to Host1. Server remains unpinned.

No AZ

AZ=”AZ1”

No

Schedule to any host in “AZ1”. Server is pined to “AZ1”.

No AZ

AZ=”AZ1”

Host1

Verify Host1 is in “AZ1”, then schedule to Host1, otherwise reject the request. Server is pined to “AZ1”.

AZ1

No AZ

No

Schedule to any host in “AZ1”. Server remains pined to “AZ1”.

AZ1

AZ=null

No

Free scheduling (2). Server is unpinned.

AZ1

No AZ

Host1

Verify Host1 is in “AZ1”, then schedule to Host1, otherwise reject the request. Server remains pined to “AZ1”.

AZ1

AZ=null

Host1

Schedule to Host1. Server is unpinned.

AZ1

AZ=”AZ2”

No

Schedule to any host in “AZ2”. Server is pined to “AZ2”.

AZ1

AZ=”AZ2”

Host1

Verify Host1 is in “AZ2” then schedule to Host1, otherwise reject the request. Server is pined to “AZ2”.

  1. Unshelve body parameters

  2. Schedule to any host available.

Asynchronous Postconditions

After you successfully unshelve a server, its status changes to ACTIVE. The server appears on the compute node.

The shelved image is deleted from the list of images returned by an API call.

Troubleshooting

If the server status does not change to ACTIVE, the unshelve operation failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate whether another operation is running that causes a race condition.

Normal response codes: 202

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

Request

Note

Since microversion 2.77, allowed request body schema are {“unshelve”: null} or {“unshelve”: {“availability_zone”: <string>}}. A request body of {“unshelve”: {}} is not allowed.

Note

Since microversion 2.91, allowed request body schema are

  • {“unshelve”: null} (Keep compatibility with previous microversions)

or

  • {“unshelve”: {“availability_zone”: <string>}} (Unshelve and pin server to availability_zone)

  • {“unshelve”: {“availability_zone”: null}} (Unshelve and unpin server from any availability zone)

  • {“unshelve”: {“host”: <fqdn>}}

  • {“unshelve”: {“availability_zone”: <string>, “host”: <fqdn>}}

  • {“unshelve”: {“availability_zone”: null, “host”: <fqdn>}}

Everything else is not allowed, examples:

  • {“unshelve”: {}}

  • {“unshelve”: {“host”: <fqdn>, “host”: <fqdn>}}

  • {“unshelve”: {“foo”: <string>}}

Name

In

Type

Description

server_id

path

string

The UUID of the server.

unshelve

body

none

The action.

availability_zone (Optional)

body

string

The availability zone name. Specifying an availability zone is only allowed when the server status is SHELVED_OFFLOADED otherwise HTTP 409 conflict response is returned.

Since microversion 2.91 "availability_zone":null allows unpinning the instance from any availability_zone it is pinned to.

New in version 2.77

host (Optional)

body

string

The destination host name. Specifying a destination host is by default only allowed to project_admin, if it not the case HTTP 403 forbidden response is returned.

New in version 2.91


Example Unshelve server (unshelve Action)

{
    "unshelve": null
}

Example Unshelve server (unshelve Action) (v2.77)

{
    "unshelve": {
        "availability_zone": "us-west"
    }
}

Examples Unshelve server (unshelve Action) (v2.91)

{
    "unshelve": {
        "host": "host01"
    }
}
{
    "unshelve": {
        "availability_zone": "nova",
        "host": "host01"
    }
}
{
    "unshelve": {
        "availability_zone": null,
        "host": "host01"
    }
}
{
    "unshelve": {
        "availability_zone": null
    }
}

Response

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

POST
/servers/{server_id}/action

Trigger Crash Dump In Server

New in version 2.17.

Trigger a crash dump in a server.

When a server starts behaving oddly at a fundamental level, it maybe be useful to get a kernel level crash dump to debug further. The crash dump action forces a crash dump followed by a system reboot of the server. Once the server comes back online, you can find a Kernel Crash Dump file in a certain location of the filesystem. For example, for Ubuntu you can find it in the /var/crash directory.

Warning

This action can cause data loss. Also, network connectivity can be lost both during and after this operation.

Normal response codes: 202

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

  • 400 is returned if the server does not support a crash dump (either by configuration or because the backend does not support it)

  • 409 is returned if the server is not in a state where a crash dump action is allowed.

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

trigger_crash_dump

body

none

Specifies the trigger crash dump action should be run

Example Trigger crash dump: JSON request

{
    "trigger_crash_dump": null
}

Response

No body is returned on a successful submission.

POST
/servers/{server_id}/action

Get Serial Console (os-getSerialConsole Action) (DEPRECATED)

Gets a serial console for a server.

Warning

This action is deprecated in microversion 2.5 and superseded by the API Server Consoles in microversion 2.6. The new API offers a unified API for different console types.

Specify the os-getSerialConsole action in the request body.

The only supported connection type is serial. The type parameter should be set as serial.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-getSerialConsole

body

object

The action.

type

body

string

The type of serial console. The only valid value is serial.

Example Get Serial Console (os-getSerialConsole Action)

{
    "os-getSerialConsole": {
        "type": "serial"
    }
}

Response

Name

In

Type

Description

console

body

object

The remote console object.

type

body

string

The type of serial console. The only valid value is serial.

url

body

string

The URL used to connect to the Serial console.

Example Get Serial Console (os-getSerialConsole Action)

{
    "console": {
        "type": "serial",
        "url":"ws://127.0.0.1:6083/?token=f9906a48-b71e-4f18-baca-c987da3ebdb3"
    }
}
POST
/servers/{server_id}/action

Get SPICE Console (os-getSPICEConsole Action) (DEPRECATED)

Gets a SPICE console for a server.

Warning

This action is deprecated in microversion 2.5 and superseded by the API Server Consoles in microversion 2.6. The new API offers a unified API for different console types.

Specify the os-getSPICEConsole action in the request body.

The only supported connection type is spice-html5. The type parameter should be set to spice-html5.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-getSPICEConsole

body

object

The action.

type

body

string

The type of SPICE console. The only valid value is spice-html5.

Example Get Spice Console (os-getSPICEConsole Action)

{
    "os-getSPICEConsole": {
        "type": "spice-html5"
    }
}

Response

Name

In

Type

Description

console

body

object

The remote console object.

type

body

string

The type of SPICE console. The only valid value is spice-html5.

url

body

string

The URL used to connect to the SPICE console.

Example Get SPICE Console (os-getSPICEConsole Action)

{
    "console": {
        "type": "spice-html5",
        "url": "http://127.0.0.1:6082/spice_auto.html?token=a30e5d08-6a20-4043-958f-0852440c6af4"
    }
}
POST
/servers/{server_id}/action

Get VNC Console (os-getVNCConsole Action) (DEPRECATED)

Gets a VNC console for a server.

Warning

This action is deprecated in microversion 2.5 and superseded by the API Server Consoles in microversion 2.6. The new API offers a unified API for different console types.

Specify the os-getVNCConsole action in the request body.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-getVNCConsole

body

object

The action.

type

body

string

The type of VNC console. The only valid value is novnc.

Example Get Vnc Console (os-getVNCConsole Action)

{
    "os-getVNCConsole": {
        "type": "novnc"
    }
}

Response

Name

In

Type

Description

console

body

object

The remote console object.

type

body

string

The type of VNC console. The only valid value is novnc.

url

body

string

The URL used to connect to the VNC console.

Example Get VNC Console (os-getVNCConsole Action)

{
    "console": {
        "type": "novnc",
        "url": "http://127.0.0.1:6080/vnc_auto.html?path=%3Ftoken%3Ddaae261f-474d-4cae-8f6a-1865278ed8c9"
    }
}

Servers - run an administrative action (servers, action)

Enables administrators to perform an action on a server. Specify the action in the request body.

You can inject network information into, migrate, live-migrate, reset networking on, reset the state of a server, and evacuate a server from a failed host to a new host.

POST
/servers/{server_id}/action

Inject Network Information (injectNetworkInfo Action)

Injects network information into a server.

Specify the injectNetworkInfo action in the request body.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Warning

There is very limited support on this API, For more information, see nova virt support matrix

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

injectNetworkInfo

body

none

The action.

Example Inject Network Information (injectNetworkInfo Action)

{
    "injectNetworkInfo": null
}

Response

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

POST
/servers/{server_id}/action

Migrate Server (migrate Action)

Migrates a server to a host.

Specify the migrate action in the request body.

Up to microversion 2.55, the scheduler chooses the host. Starting from microversion 2.56, the host parameter is available to specify the destination host. If you specify null or don’t specify this parameter, the scheduler chooses a host.

Asynchronous Postconditions

A successfully migrated server shows a VERIFY_RESIZE status and finished migration status. If the cloud has configured the resize_confirm_window option of the Compute service to a positive value, the Compute service automatically confirms the migrate operation after the configured interval.

There are two different policies for this action, depending on whether the host parameter is set. Both defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

migrate

body

object

The action to cold migrate a server. This parameter can be null. Up to microversion 2.55, this parameter should be null.

host (Optional)

body

string

The host to which to migrate the server. If you specify null or don’t specify this parameter, the scheduler chooses a host.

New in version 2.56

Example Migrate Server (migrate Action) (v2.1)

{
    "migrate": null
}

Example Migrate Server (migrate Action) (v2.56)

{
    "migrate": {
        "host": "host1"
    }
}

Response

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

POST
/servers/{server_id}/action

Live-Migrate Server (os-migrateLive Action)

Live-migrates a server to a new host without rebooting.

Specify the os-migrateLive action in the request body.

Use the host parameter to specify the destination host. If this param is null, the scheduler chooses a host. If a scheduled host is not suitable to do migration, the scheduler tries up to migrate_max_retries rescheduling attempts.

Starting from API version 2.25, the block_migration parameter could be to auto so that nova can decide value of block_migration during live migration.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Starting from REST API version 2.34 pre-live-migration checks are done asynchronously, results of these checks are available in instance-actions. Nova responds immediately, and no pre-live-migration checks are returned. The instance will not immediately change state to ERROR, if a failure of the live-migration checks occurs.

Starting from API version 2.68, the force parameter is no longer accepted as this could not be meaningfully supported by servers with complex resource allocations.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-migrateLive

body

object

The action.

host

body

string

The host to which to migrate the server. If this parameter is None, the scheduler chooses a host.

Warning

Prior to microversion 2.30, specifying a host will bypass validation by the scheduler, which could result in failures to actually migrate the instance to the specified host, or over-subscription of the host. It is recommended to either not specify a host so that the scheduler will pick one, or specify a host with microversion >= 2.30 and without force=True set.

block_migration

body

boolean

Set to True to migrate local disks by using block migration. If the source or destination host uses shared storage and you set this value to True, the live migration fails.

Available until version 2.24

block_migration

body

string

Migrates local disks by using block migration. Set to auto which means nova will detect whether source and destination hosts on shared storage. if they are on shared storage, the live-migration won’t be block migration. Otherwise the block migration will be executed. Set to True, means the request will fail when the source or destination host uses shared storage. Set to False means the request will fail when the source and destination hosts are not on the shared storage.

New in version 2.25

disk_over_commit

body

boolean

Set to True to enable over commit when the destination host is checked for available disk space. Set to False to disable over commit. This setting affects only the libvirt virt driver.

Available until version 2.25

force (Optional)

body

boolean

Force a live-migration by not verifying the provided destination host by the scheduler.

Warning

This could result in failures to actually live migrate the instance to the specified host. It is recommended to either not specify a host so that the scheduler will pick one, or specify a host without force=True set.

New in version 2.30

Available until version 2.67

Example Live-Migrate Server (os-migrateLive Action)

{
    "os-migrateLive": {
        "host": "01c0cadef72d47e28a672a76060d492c",
        "block_migration": "auto",
        "force": false
    }
}

Response

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

POST
/servers/{server_id}/action

Reset Networking On A Server (resetNetwork Action) (DEPRECATED)

Resets networking on a server.

Warning

This action was only supported by the XenAPI virt driver, which was deprecated in the 20.0.0 (Train) release and removed in the 22.0.0 (Victoria) release. This action should be avoided in new applications. It was removed in the 23.0.0 (Wallaby) release.

Specify the resetNetwork action in the request body.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409), gone(410)

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

resetNetwork

body

none

The action.

Example Reset Networking On A Server (resetNetwork Action)

{
    "resetNetwork": null
}

Response

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

POST
/servers/{server_id}/action

Reset Server State (os-resetState Action)

Resets the state of a server.

Specify the os-resetState action and the state in the request body.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-resetState

body

object

The action.

os-resetState.state

body

string

The state of the server to be set, active or error are valid.

Example Reset Server State (os-resetState Action)

{
    "os-resetState": {
        "state": "active"
    }
}

Response

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

POST
/servers/{server_id}/action

Evacuate Server (evacuate Action)

Evacuates a server from a failed host to a new host.

  • Specify the evacuate action in the request body.

  • In the request body, if onSharedStorage is set, then do not set adminPass.

  • The target host should not be the same as the instance host.

Preconditions

  • The failed host must be fenced and no longer running the original server.

  • The failed host must be reported as down or marked as forced down using Update Forced Down.

Starting from API version 2.68, the force parameter is no longer accepted as this could not be meaningfully supported by servers with complex resource allocations.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

evacuate

body

object

The action to evacuate a server to another host.

host (Optional)

body

string

The name or ID of the host to which the server is evacuated. If you omit this parameter, the scheduler chooses a host.

Warning

Prior to microversion 2.29, specifying a host will bypass validation by the scheduler, which could result in failures to actually evacuate the instance to the specified host, or over-subscription of the host. It is recommended to either not specify a host so that the scheduler will pick one, or specify a host with microversion >= 2.29 and without force=True set.

adminPass (Optional)

body

string

An administrative password to access the evacuated server. If you omit this parameter, the operation generates a new password. Up to API version 2.13, if onSharedStorage is set to True and this parameter is specified, an error is raised.

onSharedStorage

body

boolean

Server on shared storage.

Note

Starting since version 2.14, Nova automatically detects whether the server is on shared storage or not. Therefore this parameter was removed.

Available until version 2.13

force (Optional)

body

boolean

Force an evacuation by not verifying the provided destination host by the scheduler.

Warning

This could result in failures to actually evacuate the instance to the specified host. It is recommended to either not specify a host so that the scheduler will pick one, or specify a host without force=True set.

Furthermore, this should not be specified when evacuating instances managed by a clustered hypervisor driver like ironic since you cannot specify a node, so the compute service will pick a node randomly which may not be able to accommodate the instance.

New in version 2.29

Available until version 2.67


Example Evacuate Server (evacuate Action)

{
    "evacuate": {
        "host": "b419863b7d814906a68fb31703c0dbd6",
        "adminPass": "MySecretPass",
        "onSharedStorage": "False"
    }
}

Response

Name

In

Type

Description

adminPass (Optional)

body

string

An administrative password to access the evacuated instance. If you set enable_instance_password configuration option to False, the API wouldn’t return the adminPass field in response.

Available until version 2.13

Note

API does not return any Response for Microversion 2.14 or greater.

Example Evacuate Server (evacuate Action)

{
    "adminPass": "MySecretPass"
}

Server Consoles

Manage server consoles.

POST
/servers/{server_id}/remote-consoles

Create Console

Note

Microversion 2.6 or greater is required for this API.

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 VNC, set the protocol parameter to vnc.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

remote_console

body

object

The remote console object.

protocol

body

string

The protocol of remote console. The valid values are vnc, spice, serial and mks. The protocol mks is added since Microversion 2.8.

type

body

string

The type of remote console. The valid values are novnc, spice-html5, serial, and webmks. The type webmks is added since Microversion 2.8.

Example Get Remote VNC Console

{
    "remote_console": {
        "protocol": "vnc",
        "type": "novnc"
    }
}

Response

Name

In

Type

Description

remote_console

body

object

The remote console object.

protocol

body

string

The protocol of remote console. The valid values are vnc, spice, serial and mks. The protocol mks is added since Microversion 2.8.

type

body

string

The type of remote console. The valid values are novnc, spice-html5, serial, and webmks. The type webmks is added since Microversion 2.8.

url

body

string

The URL is used to connect the console.

Example Get Remote VNC Console

{
    "remote_console": {
        "protocol": "vnc",
        "type": "novnc",
        "url": "http://example.com:6080/vnc_auto.html?path=%3Ftoken%3Db60bcfc3-5fd4-4d21-986c-e83379107819"
    }
}
GET
/os-console-auth-tokens/{console_token}

Show Console Connection Information

Given the console authentication token for a server, shows the related connection information.

Nova HyperV driver has been removed therefore requests for RDP console connection information will always return an http 400 error. Starting from microversion 2.31 it’s available for all other console types.

Normal response codes: 200

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

Request

Name

In

Type

Description

console_token

path

string

Console authentication token.

Response

Name

In

Type

Description

console

body

object

The console object.

instance_uuid

body

string

The UUID of the server.

host (Optional)

body

string

The name or ID of the host.

port

body

integer

The port number.

internal_access_path (Optional)

body

string

The id representing the internal access path.

Example Show Console Authentication Token

{
    "console": {
        "instance_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
        "host": "localhost",
        "port": 5900,
        "internal_access_path": "51af38c3-555e-4884-a314-6c8cdde37444"
    }
}

Servers Security Groups (servers, os-security-groups)

Lists Security Groups for a server.

GET
/servers/{server_id}/os-security-groups

List Security Groups By Server

Lists security groups for a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

security_groups

body

array

One or more security groups objects.

description

body

string

Security group description.

id

body

string

The ID of the security group.

name

body

string

The security group name.

rules

body

array

The list of security group rules.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

Example List security groups by server

{
    "security_groups": [
        {
            "description": "default",
            "id": 1,
            "name": "default",
            "rules": [],
            "tenant_id": "6f70656e737461636b20342065766572"
        }
    ]
}

Servers diagnostics (servers, diagnostics)

Shows the usage data for a server.

GET
/servers/{server_id}/diagnostics

Show Server Diagnostics

Shows basic usage data for a server.

Policy defaults enable only users with the administrative role. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), notfound(404), conflict(409), notimplemented(501)

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Starting from microversion 2.48 diagnostics response is standardized across all virt drivers. The response should be considered a debug interface only and not relied upon by programmatic tools. All response fields are listed below. If the virt driver is unable to provide a specific field then this field will be reported as None in the response.

Name

In

Type

Description

config_drive

body

boolean

Indicates whether or not a config drive was used for this server.

New in version 2.48

state

body

string

A string enum denoting the current state of the VM. Possible values are:

  • pending

  • running

  • paused

  • shutdown

  • crashed

  • suspended

New in version 2.48

driver

body

string

The driver on which the VM is running. Possible values are:

  • libvirt

  • xenapi

  • vmwareapi

  • ironic

New in version 2.48

hypervisor

body

string

The hypervisor on which the VM is running. Examples for libvirt driver may be: qemu, kvm or xen.

New in version 2.48

hypervisor_os

body

string

The hypervisor OS.

New in version 2.48

uptime

body

integer

The amount of time in seconds that the VM has been running.

New in version 2.48

num_cpus

body

integer

The number of vCPUs.

New in version 2.48

num_disks

body

integer

The number of disks.

New in version 2.48

num_nics

body

integer

The number of vNICs.

New in version 2.48

memory_details

body

array

The dictionary with information about VM memory usage. Following fields are presented in the dictionary:

  • maximum - Amount of memory provisioned for the VM in MiB (Integer)

  • used - Amount of memory that is currently used by the guest operating system and its applications in MiB (Integer)

New in version 2.48

cpu_details

body

array

The list of dictionaries with detailed information about VM CPUs. Following fields are presented in each dictionary:

  • id - the ID of CPU (Integer)

  • time - CPU Time in nano seconds (Integer)

  • utilisation - CPU utilisation in percents (Integer)

New in version 2.48

disk_details

body

array

The list of dictionaries with detailed information about VM disks. Following fields are presented in each dictionary:

  • read_bytes - Disk reads in bytes (Integer)

  • read_requests - Read requests (Integer)

  • write_bytes - Disk writes in bytes (Integer)

  • write_requests - Write requests (Integer)

  • errors_count - Disk errors (Integer)

New in version 2.48

nic_details

body

array

The list of dictionaries with detailed information about VM NICs. Following fields are presented in each dictionary:

  • mac_address - Mac address of the interface (String)

  • rx_octets - Received octets (Integer)

  • rx_errors - Received errors (Integer)

  • rx_drop - Received packets dropped (Integer)

  • rx_packets - Received packets (Integer)

  • rx_rate - Receive rate in bytes (Integer)

  • tx_octets - Transmitted Octets (Integer)

  • tx_errors - Transmit errors (Integer)

  • tx_drop - Transmit dropped packets (Integer)

  • tx_packets - Transmit packets (Integer)

  • tx_rate - Transmit rate in bytes (Integer)

New in version 2.48

Example Server diagnostics (2.48)

{
    "config_drive": true,
    "cpu_details": [
        {
            "id": 0,
            "time": 17300000000,
            "utilisation": 15
        }
    ],
    "disk_details": [
        {
            "errors_count": 1,
            "read_bytes": 262144,
            "read_requests": 112,
            "write_bytes": 5778432,
            "write_requests": 488
        }
    ],
    "driver": "libvirt",
    "hypervisor": "kvm",
    "hypervisor_os": "ubuntu",
    "memory_details": {
        "maximum": 524288,
        "used": 0
    },
    "nic_details": [
        {
            "mac_address": "01:23:45:67:89:ab",
            "rx_drop": 200,
            "rx_errors": 100,
            "rx_octets": 2070139,
            "rx_packets": 26701,
            "rx_rate": 300,
            "tx_drop": 500,
            "tx_errors": 400,
            "tx_octets": 140208,
            "tx_packets": 662,
            "tx_rate": 600
        }
    ],
    "num_cpus": 1,
    "num_disks": 1,
    "num_nics": 1,
    "state": "running",
    "uptime": 46664
}

Warning

Before microversion 2.48 the response format for diagnostics was not well defined. Each hypervisor had its own format.

Example Server diagnostics (2.1)

Below is an example of diagnostics for a libvirt based instance. The unit of the return value is hypervisor specific, but in this case the unit of vnet1_rx* and vnet1_tx* is octets.

{
    "cpu0_time": 17300000000,
    "memory": 524288,
    "vda_errors": -1,
    "vda_read": 262144,
    "vda_read_req": 112,
    "vda_write": 5778432,
    "vda_write_req": 488,
    "vnet1_rx": 2070139,
    "vnet1_rx_drop": 0,
    "vnet1_rx_errors": 0,
    "vnet1_rx_packets": 26701,
    "vnet1_tx": 140208,
    "vnet1_tx_drop": 0,
    "vnet1_tx_errors": 0,
    "vnet1_tx_packets": 662
}

Servers IPs (servers, ips)

Lists the IP addresses for an instance and shows details for an IP address.

GET
/servers/{server_id}/ips

List Ips

Lists IP addresses that are assigned to an instance.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

addresses

body

object

The addresses information for the server.

network_label

body

array

List of IP address and IP version pairs. The network_label stands for the name of a network, such as public or private.

addr

body

string

The IP address.

version

body

integer

The IP version of the address associated with server.

Example List Ips

{
    "addresses": {
        "private": [
            {
                "addr": "192.168.1.30",
                "version": 4
            }
        ]
    }
}
GET
/servers/{server_id}/ips/{network_label}

Show Ip Details

Shows IP addresses details for a network label of a server instance.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

network_label

path

string

The network label, such as public or private.

Response

Name

In

Type

Description

network_label

body

array

List of IP address and IP version pairs. The network_label stands for the name of a network, such as public or private.

addr

body

string

The IP address.

version

body

integer

The IP version of the address associated with server.

Example Show Ip Details

{
    "private": [
        {
            "addr": "192.168.1.30",
            "version": 4
        }
    ]
}

Server metadata (servers, metadata)

Lists metadata, creates or replaces one or more metadata items, and updates one or more metadata items for a server.

Shows details for, creates or replaces, and updates a metadata item, by key, for a server.

GET
/servers/{server_id}/metadata

List All Metadata

Lists all metadata for a server.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example List All Metadata

{
    "metadata": {
        "foo": "Foo Value"
    }
}
POST
/servers/{server_id}/metadata

Create or Update Metadata Items

Create or update one or more metadata items for a server.

Creates any metadata items that do not already exist in the server, replaces exists metadata items that match keys. Does not modify items that are not in the request.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}

Response

Name

In

Type

Description

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}
PUT
/servers/{server_id}/metadata

Replace Metadata Items

Replaces one or more metadata items for a server.

Creates any metadata items that do not already exist in the server. Removes and completely replaces any metadata items that already exist in the server with the metadata items in the request.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Or Replace Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}

Response

Name

In

Type

Description

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Or Replace Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}
GET
/servers/{server_id}/metadata/{key}

Show Metadata Item Details

Shows details for a metadata item, by key, for a server.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

key

path

string

The metadata item key, as a string. Maximum length is 255 characters.

Response

Name

In

Type

Description

meta

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Show Metadata Item Details

{
    "meta": {
        "foo": "Foo Value"
    }
}
PUT
/servers/{server_id}/metadata/{key}

Create Or Update Metadata Item

Creates or replaces a metadata item, by key, for a server.

Creates a metadata item that does not already exist in the server. Replaces existing metadata items that match keys with the metadata item in the request.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

key

path

string

The metadata item key, as a string. Maximum length is 255 characters.

Example Create Or Update Metadata Item

{
    "meta": {
        "foo": "Bar Value"
    }
}

Response

Name

In

Type

Description

meta

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Or Update Metadata Item

{
    "meta": {
        "foo": "Foo Value"
    }
}
DELETE
/servers/{server_id}/metadata/{key}

Delete Metadata Item

Deletes a metadata item, by key, from a server.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

key

path

string

The metadata item key, as a string. Maximum length is 255 characters.

Response

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

Servers actions (servers, os-instance-actions)

List actions and action details for a server.

GET
/servers/{server_id}/os-instance-actions

List Actions For Server

Lists actions for a server.

Action information of deleted instances can be returned for requests starting with microversion 2.21.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

limit (Optional)

query

integer

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

New in version 2.58

marker (Optional)

query

string

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

New in version 2.58

changes-since (Optional)

query

string

Filters the response by a date and time stamp when the instance action last changed.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-since must be earlier than or equal to the value of the changes-before otherwise API will return 400.

New in version 2.58

changes-before (Optional)

query

string

Filters the response by a date and time stamp when the instance actions last changed. Those instances that changed before or equal to the specified date and time stamp are returned.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-before must be later than or equal to the value of the changes-since otherwise API will return 400.

New in version 2.66

Response

Name

In

Type

Description

instanceActions

body

array

List of the actions for the given instance in descending order of creation.

action

body

string

The name of the action.

instance_uuid

body

string

The UUID of the server.

message

body

string

The related error message for when an action fails.

project_id

body

string

The ID of the project which initiated the server action.

request_id

body

string

The request id generated when execute the API of this action.

start_time

body

string

The date and time when the action was started. 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.

user_id

body

string

The ID of the user which initiated the server action.

updated_at

body

string

The date and time when the instance action or the action event of instance action 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.

New in version 2.58

links (Optional)

body

array

Links pertaining to the instance action. This parameter is returned when paging and more data is available. See Paginated collections for more info.

New in version 2.58

Example List Actions For Server: JSON response

{
    "instanceActions": [
        {
            "action": "stop",
            "instance_uuid": "fcd19ef2-b593-40b1-90a5-fc31063fa95c",
            "message": null,
            "project_id": "6f70656e737461636b20342065766572",
            "request_id": "req-f8a59f03-76dc-412f-92c2-21f8612be728",
            "start_time": "2018-04-25T01:26:29.092892",
            "user_id": "admin"
        },
        {
            "action": "create",
            "instance_uuid": "fcd19ef2-b593-40b1-90a5-fc31063fa95c",
            "message": null,
            "project_id": "6f70656e737461636b20342065766572",
            "request_id": "req-50189019-626d-47fb-b944-b8342af09679",
            "start_time": "2018-04-25T01:26:25.877278",
            "user_id": "admin"
        }
    ]
}

Example List Actions For Server With Links (v2.58):

{
    "instanceActions": [
        {
            "action": "stop",
            "instance_uuid": "ca3d3be5-1a40-427f-9515-f5e181f479d0",
            "message": null,
            "project_id": "6f70656e737461636b20342065766572",
            "request_id": "req-4dbefbb7-d743-4d42-b0a1-a79cbe256138",
            "start_time": "2018-04-25T01:26:28.909887",
            "updated_at": "2018-04-25T01:26:29.400606",
            "user_id": "admin"
        }
    ],
    "links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/ca3d3be5-1a40-427f-9515-f5e181f479d0/os-instance-actions?limit=1&marker=req-4dbefbb7-d743-4d42-b0a1-a79cbe256138",
            "rel": "next"
        }
    ]
}
GET
/servers/{server_id}/os-instance-actions/{request_id}

Show Server Action Details

Shows details for a server action.

Action details of deleted instances can be returned for requests later than microversion 2.21.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

request_id

path

string

The ID of the request.

Response

Name

In

Type

Description

instanceAction

body

object

The instance action object.

action

body

string

The name of the action.

instance_uuid

body

string

The UUID of the server.

message

body

string

The related error message for when an action fails.

project_id

body

string

The ID of the project which initiated the server action.

request_id

body

string

The request id generated when execute the API of this action.

start_time

body

string

The date and time when the action was started. 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.

user_id

body

string

The ID of the user which initiated the server action.

events (Optional)

body

array

The events which occurred in this action in descending order of creation.

Policy defaults enable only users with the administrative role to see instance action event information. Cloud providers can change these permissions through the policy.json file.

Available until version 2.50

events

body

array

The events which occurred in this action in descending order of creation.

Policy defaults enable only users with the administrative role or the owner of the server to see instance action event information. Cloud providers can change these permissions through the policy.json file.

New in version 2.51

events.event

body

string

The name of the event.

events.start_time

body

string

The date and time when the event was started. 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.

events.finish_time

body

string

The date and time when the event was finished. 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.

events.result

body

string

The result of the event.

events.traceback

body

string

The traceback stack if an error occurred in this event.

Policy defaults enable only users with the administrative role to see an instance action event traceback. Cloud providers can change these permissions through the policy.json file.

events.hostId

body

string

An obfuscated hashed host ID string, or the empty string if there is no host for the event. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids will be different. This is useful when within the same project you need to determine if two events occurred on the same or different physical hosts.

New in version 2.62

events.host (Optional)

body

string

The name of the host on which the event occurred.

Policy defaults enable only users with the administrative role to see an instance action event host. Cloud providers can change these permissions through the policy.json file.

New in version 2.62

events.details

body

string

Details of the event. May be null.

New in version 2.84

updated_at

body

string

The date and time when the instance action or the action event of instance action 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.

New in version 2.58

Example Show Server Action Details For Admin (v2.62)

{
    "instanceAction": {
        "action": "stop",
        "events": [
            {
                "event": "compute_stop_instance",
                "finish_time": "2018-04-25T01:26:36.790544",
                "host": "compute",
                "hostId": "2091634baaccdc4c5a1d57069c833e402921df696b7f970791b12ec6",
                "result": "Success",
                "start_time": "2018-04-25T01:26:36.539271",
                "traceback": null
            }
        ],
        "instance_uuid": "4bf3473b-d550-4b65-9409-292d44ab14a2",
        "message": null,
        "project_id": "6f70656e737461636b20342065766572",
        "request_id": "req-0d819d5c-1527-4669-bdf0-ffad31b5105b",
        "start_time": "2018-04-25T01:26:36.341290",
        "updated_at": "2018-04-25T01:26:36.790544",
        "user_id": "admin"
    }
}

Example Show Server Action Details For Non-Admin (v2.62)

{
    "instanceAction": {
        "action": "stop",
        "events": [
            {
                "event": "compute_stop_instance",
                "finish_time": "2018-04-25T01:26:34.784165",
                "hostId": "2091634baaccdc4c5a1d57069c833e402921df696b7f970791b12ec6",
                "result": "Success",
                "start_time": "2018-04-25T01:26:34.612020"
            }
        ],
        "instance_uuid": "79edaa44-ad4f-4af7-b994-154518c2b927",
        "message": null,
        "project_id": "6f70656e737461636b20342065766572",
        "request_id": "req-8eb28d4a-db6c-4337-bab8-ce154e9c620e",
        "start_time": "2018-04-25T01:26:34.388280",
        "updated_at": "2018-04-25T01:26:34.784165",
        "user_id": "fake"
    }
}

Example Show Server Action Details For System Reader (v2.84)

{
    "instanceAction": {
        "action": "stop",
        "events": [
            {
                "event": "compute_stop_instance",
                "finish_time": "2018-04-25T01:26:36.790544",
                "host": "compute",
                "hostId": "2091634baaccdc4c5a1d57069c833e402921df696b7f970791b12ec6",
                "result": "Success",
                "start_time": "2018-04-25T01:26:36.539271",
                "traceback": null,
                "details": null
            }
        ],
        "instance_uuid": "4bf3473b-d550-4b65-9409-292d44ab14a2",
        "message": null,
        "project_id": "6f70656e737461636b20342065766572",
        "request_id": "req-0d819d5c-1527-4669-bdf0-ffad31b5105b",
        "start_time": "2018-04-25T01:26:36.341290",
        "updated_at": "2018-04-25T01:26:36.790544",
        "user_id": "admin"
    }
}

Port interfaces (servers, os-interface)

List port interfaces, show port interface details of the given server. Create a port interface and uses it to attach a port to the given server, detach a port interface from the given server.

GET
/servers/{server_id}/os-interface

List Port Interfaces

Lists port interfaces that are attached to a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

interfaceAttachments

body

array

List of the interface attachments.

port_state

body

string

The port state.

fixed_ips

body

array

Fixed IP addresses with subnet IDs.

ip_address

body

string

The IP address.

subnet_id

body

string

The UUID of the subnet.

mac_addr

body

string

The MAC address.

net_id

body

string

The network ID.

port_id

body

string

The port ID.

tag

body

string

The device tag applied to the virtual network interface or null.

New in version 2.70

Example List Port Interfaces: JSON response

{
    "interfaceAttachments": [
        {
            "fixed_ips": [
                {
                    "ip_address": "192.168.1.3",
                    "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef"
                }
            ],
            "mac_addr": "fa:16:3e:4c:2c:30",
            "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
            "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
            "port_state": "ACTIVE"
        }
    ]
}

Example List Tagged Port Interfaces (v2.70): JSON response

{
    "interfaceAttachments": [
        {
            "fixed_ips": [
                {
                    "ip_address": "192.168.1.3",
                    "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef"
                }
            ],
            "mac_addr": "fa:16:3e:4c:2c:30",
            "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
            "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
            "port_state": "ACTIVE",
            "tag": "public"
        }
    ]
}
POST
/servers/{server_id}/os-interface

Create Interface

Creates a port interface and uses it to attach a port to a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

interfaceAttachment

body

string

Specify the interfaceAttachment action in the request body.

port_id (Optional)

body

string

The ID of the port for which you want to create an interface. The net_id and port_id parameters are mutually exclusive. If you do not specify the port_id parameter, the OpenStack Networking API v2.0 allocates a port and creates an interface for it on the network.

net_id (Optional)

body

string

The ID of the network for which you want to create a port interface. The net_id and port_id parameters are mutually exclusive. If you do not specify the net_id parameter, the OpenStack Networking API v2.0 uses the network information cache that is associated with the instance.

fixed_ips (Optional)

body

array

Fixed IP addresses. If you request a specific fixed IP address without a net_id, the request returns a Bad Request (400) response code.

ip_address

body

string

The IP address. It is required when fixed_ips is specified.

tag (Optional)

body

string

A device role tag that can be applied to a network interface when attaching it to the VM. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled.

New in version 2.49

Example Create Interface: JSON request

Create interface with net_id and fixed_ips.

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "192.168.1.3"
            }
        ],
        "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6"
    }
}

Create interface with port_id.

{
    "interfaceAttachment": {
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442"
    }
}

Example Create Tagged Interface (v2.49): JSON request

{
    "interfaceAttachment": {
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
        "tag": "foo"
    }
}

Response

Name

In

Type

Description

interfaceAttachment

body

object

The interface attachment.

fixed_ips

body

array

Fixed IP addresses with subnet IDs.

ip_address

body

string

The IP address.

subnet_id

body

string

The UUID of the subnet.

mac_addr

body

string

The MAC address.

net_id

body

string

The network ID.

port_id

body

string

The port ID.

port_state

body

string

The port state.

tag

body

string

The device tag applied to the virtual network interface or null.

New in version 2.70

Example Create Interface: JSON response

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "192.168.1.3",
                "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef"
            }
        ],
        "mac_addr": "fa:16:3e:4c:2c:30",
        "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
        "port_state": "ACTIVE"
    }
}

Example Create Tagged Interface (v2.70): JSON response

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "192.168.1.3",
                "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef"
            }
        ],
        "mac_addr": "fa:16:3e:4c:2c:30",
        "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
        "port_state": "ACTIVE",
        "tag": "public"
    }
}
GET
/servers/{server_id}/os-interface/{port_id}

Show Port Interface Details

Shows details for a port interface that is attached to a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

port_id

path

string

The UUID of the port.

Response

Name

In

Type

Description

interfaceAttachment

body

object

The interface attachment.

port_state

body

string

The port state.

fixed_ips

body

array

Fixed IP addresses with subnet IDs.

ip_address

body

string

The IP address.

subnet_id

body

string

The UUID of the subnet.

mac_addr

body

string

The MAC address.

net_id

body

string

The network ID.

port_id

body

string

The port ID.

tag

body

string

The device tag applied to the virtual network interface or null.

New in version 2.70

Example Show Port Interface Details: JSON response

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "192.168.1.3",
                "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef"
            }
        ],
        "mac_addr": "fa:16:3e:4c:2c:30",
        "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
        "port_state": "ACTIVE"
    }
}

Example Show Tagged Port Interface Details (v2.70): JSON response

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "192.168.1.3",
                "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef"
            }
        ],
        "mac_addr": "fa:16:3e:4c:2c:30",
        "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
        "port_state": "ACTIVE",
        "tag": "public"
    }
}
DELETE
/servers/{server_id}/os-interface/{port_id}

Detach Interface

Detaches a port interface from a server.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

port_id

path

string

The UUID of the port.

Response

No body is returned on successful request.

Servers password (servers, os-server-password)

Shows the encrypted administrative password. Also, clears the encrypted administrative password for a server, which removes it from the metadata server.

GET
/servers/{server_id}/os-server-password

Show Server Password

Shows the administrative password for a server.

This operation calls the metadata service to query metadata information and does not read password information from the server itself.

The password saved in the metadata service is typically encrypted using the public SSH key injected into this server, so the SSH private key is needed to read the password.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

password (Optional)

body

string

The password returned from metadata server.

Example Show Server Password

{
    "password": "xlozO3wLCBRWAa2yDjCCVx8vwNPypxnypmRYDa/zErlQ+EzPe1S/Gz6nfmC52mOlOSCRuUOmG7kqqgejPof6M7bOezS387zjq4LSvvwp28zUknzy4YzfFGhnHAdai3TxUJ26pfQCYrq8UTzmKF2Bq8ioSEtVVzM0A96pDh8W2i7BOz6MdoiVyiev/I1K2LsuipfxSJR7Wdke4zNXJjHHP2RfYsVbZ/k9ANu+Nz4iIH8/7Cacud/pphH7EjrY6a4RZNrjQskrhKYed0YERpotyjYk1eDtRe72GrSiXteqCM4biaQ5w3ruS+AcX//PXk3uJ5kC7d67fPXaVz4WaQRYMg=="
}
DELETE
/servers/{server_id}/os-server-password

Clear Admin Password

Clears the encrypted administrative password for a server, which removes it from the database.

This action does not actually change the instance server password.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

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

Servers with volume attachments (servers, os-volume_attachments)

Attaches volumes that are created through the volume API to server instances. Also, lists volume attachments for a server, shows details for a volume attachment, and detaches a volume.

GET
/servers/{server_id}/os-volume_attachments

List volume attachments for an instance

List volume attachments for an instance.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name

In

Type

Description

volumeAttachments

body

array

The list of volume attachments.

id

body

string

The volume ID of the attachment.

Available until version 2.88

serverId

body

string

The UUID of the server.

volumeId

body

string

The UUID of the attached volume.

device (Optional)

body

string

Name of the device in the attachment object, such as, /dev/vdb.

tag

body

string

The device tag applied to the volume block device or null.

New in version 2.70

delete_on_termination

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted.

New in version 2.79

attachment_id

body

string

The UUID of the associated volume attachment in Cinder.

New in version 2.89

bdm_uuid

body

string

The UUID of the block device mapping record in Nova for the attachment.

New in version 2.89

Example List volume attachments for an instance: JSON response

{
    "volumeAttachments": [
        {
            "device": "/dev/sdc",
            "id": "227cc671-f30b-4488-96fd-7d0bf13648d8",
            "serverId": "4b293d31-ebd5-4a7f-be03-874b90021e54",
            "volumeId": "227cc671-f30b-4488-96fd-7d0bf13648d8"
        },
        {
            "device": "/dev/sdb",
            "id": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
            "serverId": "4b293d31-ebd5-4a7f-be03-874b90021e54",
            "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113"
        }
    ]
}

Example List tagged volume attachments for an instance (v2.89): JSON response

{
    "volumeAttachments": [
        {
            "attachment_id": "979ce4f8-033a-409d-85e6-6b5c0f6a6302",
            "delete_on_termination": false,
            "device": "/dev/sdc",
            "serverId": "7696780b-3f53-4688-ab25-019bfcbbd806",
            "tag": null,
            "volumeId": "227cc671-f30b-4488-96fd-7d0bf13648d8",
            "bdm_uuid": "c088db45-92b8-49e8-81e2-a1b77a144b3b"
        },
        {
            "attachment_id": "c5684109-0311-4fca-9814-350e46ab7d2a",
            "delete_on_termination": true,
            "device": "/dev/sdb",
            "serverId": "7696780b-3f53-4688-ab25-019bfcbbd806",
            "tag": "foo",
            "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
            "bdm_uuid": "1aa24536-6fb5-426c-8894-d627f39aa48b"
        }
    ]
}
POST
/servers/{server_id}/os-volume_attachments

Attach a volume to an instance

Attach a volume to an instance.

Normal response codes: 200

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

Note

From v2.20 attach a volume to an instance in SHELVED or SHELVED_OFFLOADED state is allowed.

Note

From v2.60, attaching a multiattach volume to multiple instances is supported for instances that are not SHELVED_OFFLOADED. The ability to actually support a multiattach volume depends on the volume type and compute hosting the instance.

Note

This is an asynchronous API, callers should poll the status and list of attachments of the volume within the volume API to determine when the attachment has completed successfully.

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

volumeAttachment

body

object

A dictionary representation of a volume attachment containing the fields device and volumeId.

volumeId

body

string

The UUID of the volume to attach.

device (Optional)

body

string

Name of the device such as, /dev/vdb. Omit or set this parameter to null for auto-assignment, if supported. If you specify this parameter, the device must not exist in the guest operating system. Note that as of the 12.0.0 Liberty release, the Nova libvirt driver no longer honors a user-supplied device name. This is the same behavior as if the device name parameter is not supplied on the request.

tag (Optional)

body

string

A device role tag that can be applied to a volume when attaching it to the VM. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled.

Note

Tagged volume attachment is not supported for shelved-offloaded instances.

New in version 2.49

delete_on_termination (Optional)

body

boolean

To delete the attached volume when the server is destroyed, specify true. Otherwise, specify false. Default: false

New in version 2.79

Example Attach a volume to an instance: JSON request

{
    "volumeAttachment": {
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "device": "/dev/sdb"
    }
}

Example Attach a volume to an instance and tag it (v2.49): JSON request

{
    "volumeAttachment": {
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "tag": "foo"
    }
}

Example Attach a volume to an instance with “delete_on_termination” (v2.79): JSON request

{
    "volumeAttachment": {
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "tag": "foo",
        "delete_on_termination": true
    }
}

Response

Name

In

Type

Description

volumeAttachment

body

object

A dictionary representation of a volume attachment containing the fields device, id, serverId and volumeId.

device

body

string

Name of the device such as, /dev/vdb.

id (Optional)

body

string

The UUID of the attachment.

serverId

body

string

The UUID of the server.

volumeId

body

string

The UUID of the attached volume.

tag

body

string

The device tag applied to the volume block device or null.

New in version 2.70

delete_on_termination

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted.

New in version 2.79

Example Attach a volume to an instance: JSON response

{
    "volumeAttachment": {
        "device": "/dev/sdb",
        "id": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "serverId": "802db873-0373-4bdd-a433-d272a539ba18",
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113"
    }
}

Example Attach a tagged volume to an instance (v2.70): JSON response

{
    "volumeAttachment": {
        "device": "/dev/sdb",
        "id": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "serverId": "70f5c62a-972d-4a8b-abcf-e1375ca7f8c0",
        "tag": "foo",
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113"
    }
}

Example Attach a volume with “delete_on_termination” (v2.79): JSON response

{
    "volumeAttachment": {
        "delete_on_termination": true,
        "device": "/dev/sdb",
        "id": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "serverId": "09b3b9d1-b8c5-48e1-841d-62c3ef967a88",
        "tag": "foo",
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113"
    }
}
GET
/servers/{server_id}/os-volume_attachments/{volume_id}

Show a detail of a volume attachment

Show a detail of a volume attachment.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

volume_id

path

string

The UUID of the attached volume.

Response

Name

In

Type

Description

volumeAttachment

body

object

A dictionary representation of a volume attachment containing the fields device, id, serverId and volumeId.

id

body

string

The volume ID of the attachment.

Available until version 2.88

serverId

body

string

The UUID of the server.

volumeId

body

string

The UUID of the attached volume.

device (Optional)

body

string

Name of the device in the attachment object, such as, /dev/vdb.

tag

body

string

The device tag applied to the volume block device or null.

New in version 2.70

delete_on_termination

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted.

New in version 2.79

attachment_id

body

string

The UUID of the associated volume attachment in Cinder.

New in version 2.89

bdm_uuid

body

string

The UUID of the block device mapping record in Nova for the attachment.

New in version 2.89

Example Show a detail of a volume attachment: JSON response

{
    "volumeAttachment": {
        "device": "/dev/sdb",
        "id": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "serverId": "1ad6852e-6605-4510-b639-d0bff864b49a",
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113"
    }
}

Example Show a detail of a tagged volume attachment (v2.89): JSON response

{
    "volumeAttachment": {
        "attachment_id": "721a5c82-5ebc-4c6a-8339-3d33d8d027ed",
        "delete_on_termination": true,
        "device": "/dev/sdb",
        "serverId": "7ebed2ce-85b3-40b5-84ae-8cc725c37ed2",
        "tag": "foo",
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "bdm_uuid": "c088db45-92b8-49e8-81e2-a1b77a144b3b"
    }
}
PUT
/servers/{server_id}/os-volume_attachments/{volume_id}

Update a volume attachment

Update a volume attachment.

Note

This action only valid when the server is in ACTIVE, PAUSED and RESIZED state, or a conflict(409) error will be returned.

Warning

When updating volumeId, this API is typically meant to only be used as part of a larger orchestrated volume migration operation initiated in the block storage service via the os-retype or os-migrate_volume volume actions. Direct usage of this API to update volumeId is not recommended and may result in needing to hard reboot the server to update details within the guest such as block storage serial IDs. Furthermore, updating volumeId via this API is only implemented by certain compute drivers.

Policy default role is ‘rule:system_admin_or_owner’, its scope is [system, project], which allow project members or system admins to change the fields of an attached volume of a server. Policy defaults enable only users with the administrative role to change volumeId via this operation. Cloud providers can change these permissions through the policy.json file.

Updating, or what is commonly referred to as “swapping”, volume attachments with volumes that have more than one read/write attachment, is not supported.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

volume_id

path

string

The UUID of the volume being replaced.

volumeAttachment

body

object

A dictionary representation of a volume attachment containing the field volumeId which is the UUID of the replacement volume, and other fields to update in the attachment.

volumeId

body

string

The UUID of the volume to attach instead of the attached volume.

delete_on_termination (Optional)

body

boolean

A flag indicating if the attached volume will be deleted when the server is deleted.

New in version 2.85

device (Optional)

body

string

Name of the device in the attachment object, such as, /dev/vdb.

New in version 2.85

serverId (Optional)

body

string

The UUID of the server.

New in version 2.85

tag

body

string

The device tag applied to the volume block device or null.

New in version 2.85

id (Optional)

body

string

The UUID of the attachment.

New in version 2.85

Note

Other than volumeId, as of v2.85 only delete_on_termination may be changed from the current value.

Example Update a volume attachment (v2.85): JSON request

{
    "volumeAttachment": {
        "volumeId": "a07f71dc-8151-4e7d-a0cc-cd24a3f11113",
        "delete_on_termination": true
    }
}

Response

No body is returned on successful request.

DELETE
/servers/{server_id}/os-volume_attachments/{volume_id}

Detach a volume from an instance

Detach a volume from an instance.

Normal response codes: 202

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

Note

From v2.20 detach a volume from an instance in SHELVED or SHELVED_OFFLOADED state is allowed.

Note

This is an asynchronous API, callers should poll the list of volume attachments provided by GET /servers/{server_id}/os-volume_attachments to determine when the detachment of the volume has completed successfully.

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

volume_id

path

string

The UUID of the volume to detach.

Response

No body is returned on successful request.

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)

Request

Name

In

Type

Description

sort_key (Optional)

query

string

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

  • created_at

  • description

  • disabled

  • ephemeral_gb

  • flavorid

  • id

  • is_public

  • memory_mb

  • name

  • root_gb

  • rxtx_factor

  • swap

  • updated_at

  • vcpu_weight

  • vcpus

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

marker (Optional)

query

string

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

minDisk (Optional)

query

integer

Filters the response by a minimum disk space, in GiB. For example, 100.

minRam (Optional)

query

integer

Filters the response by a minimum RAM, in MiB. For example, 512.

is_public (Optional)

query

string

This parameter is only applicable to users with the administrative role. For all other non-admin users, the parameter is ignored and only public flavors will be returned. Filters the flavor list based on whether the flavor is public or private. If the value of this parameter is not specified, it is treated as True. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False (they are case-insensitive). If the value is None (case-insensitive) both public and private flavors will be listed in a single request.

Response

Name

In

Type

Description

flavors

body

array

An array of flavor objects.

id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

name

body

string

The display name of a flavor.

description

body

string

The description of the flavor.

New in version 2.55

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

Example List Flavors (v2.55)

{
    "flavors": [
        {
            "id": "1",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/1",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.tiny",
            "description": null
        },
        {
            "id": "2",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/2",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/2",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.small",
            "description": null
        },
        {
            "id": "3",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/3",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/3",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.medium",
            "description": null
        },
        {
            "id": "4",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/4",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/4",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.large",
            "description": null
        },
        {
            "id": "5",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/5",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/5",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.xlarge",
            "description": null
        },
        {
            "id": "6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/6",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.tiny.specs",
            "description": null
        },
        {
            "id": "7",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/7",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/7",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.small.description",
            "description": "test description"
        }
    ]
}
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.

Note

Flavors with special characters in the flavor ID, except the hyphen ‘-‘, underscore ‘_’, spaces and dots ‘.’, are not permitted.

Flavor IDs are meant to be UUIDs. Serialized strings separated/grouped by “-” represent the default flavor ID or UUID. eg: 01cc74d8-4816-4bef-835b-e36ff188c406.

Only for backward compatibility, an integer as a flavor ID is permitted.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor

body

object

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

name

body

string

The display name of a flavor.

description (Optional)

body

string

A free form description of the flavor. Limited to 65535 characters in length. Only printable characters are allowed.

New in version 2.55

id (Optional)

body

string

Only alphanumeric characters with hyphen ‘-’, underscore ‘_’, spaces and dots ‘.’ are permitted. If an ID is not provided, then a default UUID will be assigned.

ram

body

integer

The amount of RAM a flavor has, in MiB.

disk

body

integer

The size of the root disk that will be created in GiB. If 0 the root disk will be set to exactly the size of the image used to deploy the instance. However, in this case the scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the os_compute_api:servers:create:zero_disk_flavor policy rule.

vcpus

body

integer

The number of virtual CPUs that will be allocated to the server.

OS-FLV-EXT-DATA:ephemeral (Optional)

body

integer

The size of the ephemeral disk that will be created, in GiB. Ephemeral disks may be written over on server state changes. So should only be used as a scratch space for applications that are aware of its limitations. Defaults to 0.

swap (Optional)

body

integer

The size of a dedicated swap disk that will be allocated, in MiB. If 0 (the default), no dedicated swap disk will be created.

rxtx_factor (Optional)

body

float

The receive / transmit factor (as a float) that will be set on ports if the network backend supports the QOS extension. Otherwise it will be ignored. It defaults to 1.0.

os-flavor-access: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.

Example Create Flavor (v2.55)

{
    "flavor": {
        "name": "test_flavor",
        "ram": 1024,
        "vcpus": 2,
        "disk": 10,
        "id": "10",
        "rxtx_factor": 2.0,
        "description": "test description"
    }
}

Response

Name

In

Type

Description

flavor

body

object

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

name

body

string

The display name of a flavor.

description

body

string

The description of the flavor.

New in version 2.55

id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

ram

body

integer

The amount of RAM a flavor has, in MiB.

disk

body

integer

The size of the root disk that will be created in GiB. If 0 the root disk will be set to exactly the size of the image used to deploy the instance. However, in this case the scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the os_compute_api:servers:create:zero_disk_flavor policy rule.

vcpus

body

integer

The number of virtual CPUs that will be allocated to the server.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

OS-FLV-EXT-DATA:ephemeral

body

integer

The size of the ephemeral disk that will be created, in GiB. Ephemeral disks may be written over on server state changes. So should only be used as a scratch space for applications that are aware of its limitations. Defaults to 0.

OS-FLV-DISABLED:disabled (Optional)

body

boolean

Whether or not the flavor has been administratively disabled. This is typically only visible to administrative users.

swap

body

integer

The size of a dedicated swap disk that will be allocated, in MiB. If 0 (the default), no dedicated swap disk will be created. Currently, the empty string (‘’) is used to represent 0. As of microversion 2.75 default return value of swap is 0 instead of empty string.

rxtx_factor

body

float

The receive / transmit factor (as a float) that will be set on ports if the network backend supports the QOS extension. Otherwise it will be ignored. It defaults to 1.0.

os-flavor-access: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.

extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.61

Example Create Flavor (v2.75)

{
    "flavor": {
        "OS-FLV-DISABLED:disabled": false,
        "disk": 10,
        "OS-FLV-EXT-DATA:ephemeral": 0,
        "os-flavor-access:is_public": true,
        "id": "10",
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/10",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/10",
                "rel": "bookmark"
            }
        ],
        "name": "test_flavor",
        "ram": 1024,
        "swap": 0,
        "rxtx_factor": 2.0,
        "vcpus": 2,
        "description": "test description",
        "extra_specs": {}
    }
}
GET
/flavors/detail

List Flavors With Details

Lists flavors with details.

Normal response codes: 200

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

Request

Name

In

Type

Description

sort_key (Optional)

query

string

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

  • created_at

  • description

  • disabled

  • ephemeral_gb

  • flavorid

  • id

  • is_public

  • memory_mb

  • name

  • root_gb

  • rxtx_factor

  • swap

  • updated_at

  • vcpu_weight

  • vcpus

sort_dir (Optional)

query

string

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

limit (Optional)

query

integer

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

marker (Optional)

query

string

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

minDisk (Optional)

query

integer

Filters the response by a minimum disk space, in GiB. For example, 100.

minRam (Optional)

query

integer

Filters the response by a minimum RAM, in MiB. For example, 512.

is_public (Optional)

query

string

This parameter is only applicable to users with the administrative role. For all other non-admin users, the parameter is ignored and only public flavors will be returned. Filters the flavor list based on whether the flavor is public or private. If the value of this parameter is not specified, it is treated as True. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False (they are case-insensitive). If the value is None (case-insensitive) both public and private flavors will be listed in a single request.

Response

Name

In

Type

Description

flavors

body

array

An array of flavor objects.

name

body

string

The display name of a flavor.

description

body

string

The description of the flavor.

New in version 2.55

id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

ram

body

integer

The amount of RAM a flavor has, in MiB.

disk

body

integer

The size of the root disk that will be created in GiB. If 0 the root disk will be set to exactly the size of the image used to deploy the instance. However, in this case the scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the os_compute_api:servers:create:zero_disk_flavor policy rule.

vcpus

body

integer

The number of virtual CPUs that will be allocated to the server.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

OS-FLV-EXT-DATA:ephemeral

body

integer

The size of the ephemeral disk that will be created, in GiB. Ephemeral disks may be written over on server state changes. So should only be used as a scratch space for applications that are aware of its limitations. Defaults to 0.

OS-FLV-DISABLED:disabled (Optional)

body

boolean

Whether or not the flavor has been administratively disabled. This is typically only visible to administrative users.

swap

body

integer

The size of a dedicated swap disk that will be allocated, in MiB. If 0 (the default), no dedicated swap disk will be created. Currently, the empty string (‘’) is used to represent 0. As of microversion 2.75 default return value of swap is 0 instead of empty string.

rxtx_factor

body

float

The receive / transmit factor (as a float) that will be set on ports if the network backend supports the QOS extension. Otherwise it will be ignored. It defaults to 1.0.

os-flavor-access: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.

extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.61

Example List Flavors With Details (v2.75)

{
    "flavors": [
        {
            "OS-FLV-DISABLED:disabled": false,
            "disk": 1,
            "OS-FLV-EXT-DATA:ephemeral": 0,
            "os-flavor-access:is_public": true,
            "id": "1",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/1",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.tiny",
            "ram": 512,
            "swap": 0,
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": null,
            "extra_specs": {}
        },
        {
            "OS-FLV-DISABLED:disabled": false,
            "disk": 20,
            "OS-FLV-EXT-DATA:ephemeral": 0,
            "os-flavor-access:is_public": true,
            "id": "2",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/2",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/2",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.small",
            "ram": 2048,
            "swap": 0,
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": null,
            "extra_specs": {}
        },
        {
            "OS-FLV-DISABLED:disabled": false,
            "disk": 40,
            "OS-FLV-EXT-DATA:ephemeral": 0,
            "os-flavor-access:is_public": true,
            "id": "3",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/3",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/3",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.medium",
            "ram": 4096,
            "swap": 0,
            "vcpus": 2,
            "rxtx_factor": 1.0,
            "description": null,
            "extra_specs": {}
        },
        {
            "OS-FLV-DISABLED:disabled": false,
            "disk": 80,
            "OS-FLV-EXT-DATA:ephemeral": 0,
            "os-flavor-access:is_public": true,
            "id": "4",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/4",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/4",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.large",
            "ram": 8192,
            "swap": 0,
            "vcpus": 4,
            "rxtx_factor": 1.0,
            "description": null,
            "extra_specs": {}
        },
        {
            "OS-FLV-DISABLED:disabled": false,
            "disk": 160,
            "OS-FLV-EXT-DATA:ephemeral": 0,
            "os-flavor-access:is_public": true,
            "id": "5",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/5",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/5",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.xlarge",
            "ram": 16384,
            "swap": 0,
            "vcpus": 8,
            "rxtx_factor": 1.0,
            "description": null,
            "extra_specs": {}
        },
        {
            "OS-FLV-DISABLED:disabled": false,
            "disk": 1,
            "OS-FLV-EXT-DATA:ephemeral": 0,
            "os-flavor-access:is_public": true,
            "id": "6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/6",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.tiny.specs",
            "ram": 512,
            "swap": 0,
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": null,
            "extra_specs": {
                "hw:numa_nodes": "1"
            }
        },
        {
            "OS-FLV-DISABLED:disabled": false,
            "disk": 20,
            "OS-FLV-EXT-DATA:ephemeral": 0,
            "os-flavor-access:is_public": true,
            "id": "7",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/7",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/7",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.small.description",
            "ram": 2048,
            "swap": 0,
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": "test description",
            "extra_specs": {
                "hw:cpu_policy": "shared",
                "hw:numa_nodes": "1"
            }
        }
    ]
}
GET
/flavors/{flavor_id}

Show 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_id

path

string

The ID of the flavor.

Response

Name

In

Type

Description

flavor

body

object

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

name

body

string

The display name of a flavor.

description

body

string

The description of the flavor.

New in version 2.55

id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

ram

body

integer

The amount of RAM a flavor has, in MiB.

disk

body

integer

The size of the root disk that will be created in GiB. If 0 the root disk will be set to exactly the size of the image used to deploy the instance. However, in this case the scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the os_compute_api:servers:create:zero_disk_flavor policy rule.

vcpus

body

integer

The number of virtual CPUs that will be allocated to the server.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

OS-FLV-EXT-DATA:ephemeral

body

integer

The size of the ephemeral disk that will be created, in GiB. Ephemeral disks may be written over on server state changes. So should only be used as a scratch space for applications that are aware of its limitations. Defaults to 0.

OS-FLV-DISABLED:disabled (Optional)

body

boolean

Whether or not the flavor has been administratively disabled. This is typically only visible to administrative users.

swap

body

integer

The size of a dedicated swap disk that will be allocated, in MiB. If 0 (the default), no dedicated swap disk will be created. Currently, the empty string (‘’) is used to represent 0. As of microversion 2.75 default return value of swap is 0 instead of empty string.

rxtx_factor

body

float

The receive / transmit factor (as a float) that will be set on ports if the network backend supports the QOS extension. Otherwise it will be ignored. It defaults to 1.0.

os-flavor-access: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.

extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.61

Example Show Flavor Details (v2.75)

{
    "flavor": {
        "OS-FLV-DISABLED:disabled": false,
        "disk": 20,
        "OS-FLV-EXT-DATA:ephemeral": 0,
        "os-flavor-access:is_public": true,
        "id": "7",
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/flavors/7",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/7",
                "rel": "bookmark"
            }
        ],
        "name": "m1.small.description",
        "ram": 2048,
        "swap": 0,
        "vcpus": 1,
        "rxtx_factor": 1.0,
        "description": "test description",
        "extra_specs": {
            "hw:cpu_policy": "shared",
            "hw:numa_nodes": "1"
        }
    }
}
PUT
/flavors/{flavor_id}

Update Flavor Description

Updates a flavor description.

This API is available starting with microversion 2.55.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

flavor

body

object

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

description

body

string

A free form description of the flavor. Limited to 65535 characters in length. Only printable characters are allowed.

Example Update Flavor Description (v2.55)

{
    "flavor": {
        "description": "updated description"
    }
}

Response

Name

In

Type

Description

flavor

body

object

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

name

body

string

The display name of a flavor.

description

body

string

The description of the flavor.

id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

ram

body

integer

The amount of RAM a flavor has, in MiB.

disk

body

integer

The size of the root disk that will be created in GiB. If 0 the root disk will be set to exactly the size of the image used to deploy the instance. However, in this case the scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the os_compute_api:servers:create:zero_disk_flavor policy rule.

vcpus

body

integer

The number of virtual CPUs that will be allocated to the server.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

OS-FLV-EXT-DATA:ephemeral

body

integer

The size of the ephemeral disk that will be created, in GiB. Ephemeral disks may be written over on server state changes. So should only be used as a scratch space for applications that are aware of its limitations. Defaults to 0.

OS-FLV-DISABLED:disabled (Optional)

body

boolean

Whether or not the flavor has been administratively disabled. This is typically only visible to administrative users.

swap

body

integer

The size of a dedicated swap disk that will be allocated, in MiB. If 0 (the default), no dedicated swap disk will be created. Currently, the empty string (‘’) is used to represent 0. As of microversion 2.75 default return value of swap is 0 instead of empty string.

rxtx_factor

body

float

The receive / transmit factor (as a float) that will be set on ports if the network backend supports the QOS extension. Otherwise it will be ignored. It defaults to 1.0.

os-flavor-access: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.

extra_specs (Optional)

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.61

Example Update Flavor Description (v2.75)

{
    "flavor": {
        "OS-FLV-DISABLED:disabled": false,
        "disk": 1,
        "OS-FLV-EXT-DATA:ephemeral": 0,
        "os-flavor-access:is_public": true,
        "id": "1",
        "links": [
            {
                "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/flavors/1",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/flavors/1",
                "rel": "bookmark"
            }
        ],
        "name": "m1.tiny",
        "ram": 512,
        "swap": 0,
        "vcpus": 1,
        "rxtx_factor": 1.0,
        "description": "updated description",
        "extra_specs": {}
    }
}
DELETE
/flavors/{flavor_id}

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: 202

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

Response

No body content is returned on a successful DELETE.

Flavors access (flavors, os-flavor-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_id}/os-flavor-access

List Flavor Access Information For Given Flavor

Lists flavor access information.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

Response

Name

In

Type

Description

flavor_access

body

array

A list of objects, each with the keys flavor_id and tenant_id.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

flavor_id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

Example List Flavor Access Information For Given Flavor: JSON response

{
    "flavor_access": [
        {
            "flavor_id": "10",
            "tenant_id": "fake_tenant"
        }
    ]
}
POST
/flavors/{flavor_id}/action

Add Flavor Access To Tenant (addTenantAccess Action)

Adds flavor access to a tenant and flavor.

Specify the addTenantAccess action and the tenant in the request body.

Normal response codes: 200

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

  • 400 - BadRequest - if the tenant is not found in your OpenStack deployment, a 400 is returned to prevent typos on the API call.

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

addTenantAccess

body

string

The action.

tenant

body

string

The UUID of the tenant in a multi-tenancy cloud.

Example Add Flavor Access To Tenant: JSON request

{
    "addTenantAccess": {
        "tenant": "fake_tenant"
    }
}

Response

Name

In

Type

Description

flavor_access

body

array

A list of objects, each with the keys flavor_id and tenant_id.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

flavor_id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

Example Add Flavor Access To Tenant: JSON response

{
    "flavor_access": [
        {
            "flavor_id": "10",
            "tenant_id": "fake_tenant"
        }
    ]
}
POST
/flavors/{flavor_id}/action

Remove Flavor Access From Tenant (removeTenantAccess Action)

Removes flavor access from a tenant and flavor.

Specify the removeTenantAccess action and the tenant in the request body.

Normal response codes: 200

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

  • 400 - BadRequest - if the tenant is not found in your OpenStack deployment, a 400 is returned to prevent typos on the API call.

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

removeTenantAccess

body

string

The action.

tenant

body

string

The UUID of the tenant in a multi-tenancy cloud.

Example Remove Flavor Access From Tenant: JSON request

{
    "removeTenantAccess": {
        "tenant": "fake_tenant"
    }
}

Response

Name

In

Type

Description

flavor_access

body

array

A list of objects, each with the keys flavor_id and tenant_id.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

flavor_id

body

string

The ID of the flavor. While people often make this look like an int, this is really a string.

Example Remove Flavor Access From Tenant: JSON response

{
    "flavor_access": [
    ]
}

Flavors extra-specs (flavors, os-flavor-extra-specs)

Lists, creates, deletes, and updates the extra-specs or keys for a flavor.

Refer to Compute Flavors for available built-in extra specs.

GET
/flavors/{flavor_id}/os-extra_specs

List Extra Specs For A Flavor

Lists all extra specs for a flavor, by ID.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

Response

Name

In

Type

Description

extra_specs

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. It appears in the os-extra-specs’ “create” REQUEST body, as well as the os-extra-specs’ “create” and “list” RESPONSE body.

key

body

string

The extra spec key of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

value

body

string

The extra spec value of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

Example List Extra Specs For A Flavor: JSON response

{
    "extra_specs": {
        "hw:cpu_policy": "shared",
        "hw:numa_nodes": "1"
    }
}
POST
/flavors/{flavor_id}/os-extra_specs

Create Extra Specs For A Flavor

Creates extra specs for a flavor, by ID.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

extra_specs

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. It appears in the os-extra-specs’ “create” REQUEST body, as well as the os-extra-specs’ “create” and “list” RESPONSE body.

key

body

string

The extra spec key of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

value

body

string

The extra spec value of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

Example Create Extra Specs For A Flavor: JSON request

{
    "extra_specs": {
        "hw:cpu_policy": "shared",
        "hw:numa_nodes": "1"
    }
}

Response

Name

In

Type

Description

extra_specs

body

object

A dictionary of the flavor’s extra-specs key-and-value pairs. It appears in the os-extra-specs’ “create” REQUEST body, as well as the os-extra-specs’ “create” and “list” RESPONSE body.

key

body

string

The extra spec key of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

value

body

string

The extra spec value of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

Example Create Extra Specs For A Flavor: JSON response

{
    "extra_specs": {
        "hw:cpu_policy": "shared",
        "hw:numa_nodes": "1"
    }
}
GET
/flavors/{flavor_id}/os-extra_specs/{flavor_extra_spec_key}

Show An Extra Spec For A Flavor

Shows an extra spec, by key, for a flavor, by ID.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

flavor_extra_spec_key

path

string

The extra spec key for the flavor.

Response

Name

In

Type

Description

key

body

string

The extra spec key of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

value

body

string

The extra spec value of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

Example Show An Extra Spec For A Flavor: JSON response

{
    "hw:numa_nodes": "1"
}
PUT
/flavors/{flavor_id}/os-extra_specs/{flavor_extra_spec_key}

Update An Extra Spec For A Flavor

Updates an extra spec, by key, for a flavor, by ID.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

flavor_extra_spec_key

path

string

The extra spec key for the flavor.

key

body

string

The extra spec key of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

value

body

string

The extra spec value of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

Example Update An Extra Spec For A Flavor: JSON request

{
    "hw:numa_nodes": "2"
}

Response

Name

In

Type

Description

key

body

string

The extra spec key of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

value

body

string

The extra spec value of a flavor. It appears in the os-extra-specs’ “create” and “update” REQUEST body, as well as the os-extra-specs’ “create”, “list”, “show”, and “update” RESPONSE body.

Example Update An Extra Spec For A Flavor: JSON response

{
    "hw:numa_nodes": "2"
}
DELETE
/flavors/{flavor_id}/os-extra_specs/{flavor_extra_spec_key}

Delete An Extra Spec For A Flavor

Deletes an extra spec, by key, for a flavor, by ID.

Normal response codes: 200

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

Request

Name

In

Type

Description

flavor_id

path

string

The ID of the flavor.

flavor_extra_spec_key

path

string

The extra spec key for the flavor.

Response

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

Keypairs (keypairs)

Generates, imports, and deletes SSH keys.

GET
/os-keypairs

List Keypairs

Lists keypairs that are associated with the account.

Normal response codes: 200

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

Request

Name

In

Type

Description

user_id (Optional)

query

string

This allows administrative users to operate key-pairs of specified user ID.

New in version 2.10

limit (Optional)

query

integer

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

New in version 2.35

marker (Optional)

query

string

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

New in version 2.35

Response

Name

In

Type

Description

keypairs

body

array

Array of Keypair objects

keypair

body

object

Keypair object

name

body

string

The name for the keypair.

public_key

body

string

The keypair public key.

fingerprint

body

string

The fingerprint for the keypair.

type

body

string

The type of the keypair. Allowed values are ssh or x509.

New in version 2.2

keypairs_links (Optional)

body

array

Links pertaining to keypair. See API Guide / Links and References for more info.

New in version 2.35

Example List Keypairs (v2.35): JSON response

{
    "keypairs": [
        {
            "keypair": {
                "fingerprint": "7e:eb:ab:24:ba:d1:e1:88:ae:9a:fb:66:53:df:d3:bd",
                "name": "keypair-5d935425-31d5-48a7-a0f1-e76e9813f2c3",
                "type": "ssh",
                "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCkF3MX59OrlBs3dH5CU7lNmvpbrgZxSpyGjlnE8Flkirnc/Up22lpjznoxqeoTAwTW034k7Dz6aYIrZGmQwe2TkE084yqvlj45Dkyoj95fW/sZacm0cZNuL69EObEGHdprfGJQajrpz22NQoCD8TFB8Wv+8om9NH9Le6s+WPe98WC77KLw8qgfQsbIey+JawPWl4O67ZdL5xrypuRjfIPWjgy/VH85IXg/Z/GONZ2nxHgSShMkwqSFECAC5L3PHB+0+/12M/iikdatFSVGjpuHvkLOs3oe7m6HlOfluSJ85BzLWBbvva93qkGmLg4ZAc8rPh2O+YIsBUHNLLMM/oQp Generated-by-Nova\n"
            }
        }
    ],
    "keypairs_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-keypairs?limit=1&marker=keypair-5d935425-31d5-48a7-a0f1-e76e9813f2c3",
            "rel": "next"
        }
    ]
}
POST
/os-keypairs

Import (or create) Keypair

Imports (or generates) a keypair.

Warning

Generating a keypair is no longer possible starting from version 2.92.

Normal response codes: 200, 201

Note

The success status code was changed from 200 to 201 in version 2.2

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

Request

Name

In

Type

Description

keypair

body

object

Keypair object

name

body

string

A name for the keypair which will be used to reference it later.

Note

Since microversion 2.92, allowed characters are ASCII letters [a-zA-Z], digits [0-9] and the following special characters: [@._- ].

public_key

body

string

The public ssh key to import. Was optional before microversion 2.92 : if you were omitting this value, a keypair was generated for you.

type (Optional)

body

string

The type of the keypair. Allowed values are ssh or x509.

New in version 2.2

user_id (Optional)

body

string

The user_id for a keypair. This allows administrative users to upload keys for other users than themselves.

New in version 2.10

Example Create Or Import Keypair (v2.10): JSON request

{
    "keypair": {
        "name": "keypair-d20a3d59-9433-4b79-8726-20b431d89c78",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova",
        "user_id": "fake"
    }
}

Example Import Keypair (v2.92): JSON request

{
    "keypair": {
        "name": "me.and.myself@this.nice.domain.com mooh.",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova",
        "user_id": "fake"
    }
}

Response

Name

In

Type

Description

keypair

body

object

Keypair object

name

body

string

The name for the keypair.

public_key

body

string

The keypair public key.

fingerprint

body

string

The fingerprint for the keypair.

user_id

body

string

The user_id for a keypair.

private_key (Optional)

body

string

If you do not provide a public key on create, a new keypair will be built for you, and the private key will be returned during the initial create call. Make sure to save this, as there is no way to get this private key again in the future.

Available until version 2.91

type

body

string

The type of the keypair. Allowed values are ssh or x509.

New in version 2.2

Example Create Or Import Keypair (v2.10): JSON response

{
    "keypair": {
        "fingerprint": "1e:2c:9b:56:79:4b:45:77:f9:ca:7a:98:2c:b0:d5:3c",
        "name": "keypair-803a1926-af78-4b05-902a-1d6f7a8d9d3e",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova",
        "user_id": "fake"
    }
}

Example Import Keypair (v2.92): JSON response

{
    "keypair": {
        "fingerprint": "1e:2c:9b:56:79:4b:45:77:f9:ca:7a:98:2c:b0:d5:3c",
        "name": "me.and.myself@this.nice.domain.com mooh.",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova",
        "user_id": "fake"
    }
}
GET
/os-keypairs/{keypair_name}

Show Keypair Details

Shows details for a keypair that is associated with the account.

Normal response codes: 200

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

Request

Name

In

Type

Description

keypair_name

path

string

The keypair name.

user_id (Optional)

query

string

This allows administrative users to operate key-pairs of specified user ID.

New in version 2.10

Response

Name

In

Type

Description

keypair

body

object

Keypair object

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.

deleted

body

boolean

A boolean indicates whether this keypair is deleted or not. The value is always false (not deleted).

deleted_at

body

none

It is always null.

fingerprint

body

string

The fingerprint for the keypair.

id

body

integer

The keypair ID.

name

body

string

The name for the keypair.

public_key

body

string

The keypair public key.

updated_at

body

none

It is always null.

user_id

body

string

The user_id for a keypair.

type

body

string

The type of the keypair. Allowed values are ssh or x509.

New in version 2.2

Example Show Keypair Details (v2.10): JSON response

{
    "keypair": {
        "fingerprint": "44:fe:29:6e:23:14:b9:53:5b:65:82:58:1c:fe:5a:c3",
        "name": "keypair-6638abdb-c4e8-407c-ba88-c8dd7cc3c4f1",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1HTrHCbb9NawNLSV8N6tSa8i637+EC2dA+lsdHHfQlT54t+N0nHhJPlKWDLhc579j87vp6RDFriFJ/smsTnDnf64O12z0kBaJpJPH2zXrBkZFK6q2rmxydURzX/z0yLSCP77SFJ0fdXWH2hMsAusflGyryHGX20n+mZK6mDrxVzGxEz228dwQ5G7Az5OoZDWygH2pqPvKjkifRw0jwUKf3BbkP0QvANACOk26cv16mNFpFJfI1N3OC5lUsZQtKGR01ptJoWijYKccqhkAKuo902tg/qup58J5kflNm7I61sy1mJon6SGqNUSfoQagqtBH6vd/tU1jnlwZ03uUroAL Generated-by-Nova\n",
        "user_id": "fake",
        "deleted": false,
        "created_at": "2014-05-07T12:06:13.681238",
        "updated_at": null,
        "deleted_at": null,
        "id": 1
    }
}
DELETE
/os-keypairs/{keypair_name}

Delete Keypair

Deletes a keypair.

Normal response codes: 202, 204

Note

The normal return code is 204 in version 2.2 to match the fact that no body content is returned.

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

Request

Name

In

Type

Description

keypair_name

path

string

The keypair name.

user_id (Optional)

query

string

This allows administrative users to operate key-pairs of specified user ID.

New in version 2.10

Response

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

Limits (limits)

Shows rate and absolute limits for the project.

GET
/limits

Show Rate And Absolute Limits

Shows rate and absolute limits for the project.

Normal response codes: 200

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

Request

Name

In

Type

Description

reserved (Optional)

query

integer

Specify whether the result of resource total includes reserved resources or not.

  • 0: Not include reserved resources.

  • Other than 0: Include reserved resources.

If non integer value is specified, it is the same as 0.

tenant_id (Optional)

query

string

Specify the project ID (tenant ID) to show the rate and absolute limits. This parameter can be specified by admin only.

Response

Name

In

Type

Description

limits

body

object

Data structure that contains both absolute limits within a deployment.

absolute

body

object

Name/value pairs that set quota limits within a deployment and Name/value pairs of resource usage.

maxServerGroupMembers

body

integer

The number of allowed members for each server group.

maxServerGroups

body

integer

The number of allowed server groups for each tenant.

maxServerMeta

body

integer

The number of allowed metadata items for each server.

maxTotalCores

body

integer

The number of allowed server cores for each tenant.

maxTotalInstances

body

integer

The number of allowed servers for each tenant.

maxTotalKeypairs

body

integer

The number of allowed key pairs for each user.

maxTotalRAMSize

body

integer

The amount of allowed server RAM, in MiB, for each tenant.

totalCoresUsed

body

integer

The number of used server cores in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved server cores are also included.

totalInstancesUsed

body

integer

The number of servers in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved servers are also included.

totalRAMUsed

body

integer

The amount of used server RAM in each tenant. If reserved query parameter is specified and it is not 0, the amount of reserved server RAM is also included.

totalServerGroupsUsed

body

integer

The number of used server groups in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved server groups are also included.

maxSecurityGroupRules

body

integer

The number of allowed rules for each security group.

Available until version 2.35

maxSecurityGroups

body

integer

The number of allowed security groups for each tenant.

Available until version 2.35

maxTotalFloatingIps

body

integer

The number of allowed floating IP addresses for each tenant.

Available until version 2.35

totalFloatingIpsUsed

body

integer

The number of used floating IP addresses in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved floating IP addresses are also included.

Available until version 2.35

totalSecurityGroupsUsed

body

integer

The number of used security groups in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved security groups are also included.

Available until version 2.35

maxImageMeta

body

integer

The number of allowed metadata items for each image. Starting from version 2.39 this field is dropped from ‘os-limits’ response, because ‘image-metadata’ proxy API was deprecated.

Available until version 2.38

maxPersonality

body

integer

The number of allowed injected files for each tenant.

Available until version 2.56

maxPersonalitySize

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

rate

body

array

An empty list for backwards compatibility purposes.

Example Show Rate And Absolute Limits: JSON response

{
    "limits": {
        "absolute": {
            "maxImageMeta": 128,
            "maxPersonality": 5,
            "maxPersonalitySize": 10240,
            "maxSecurityGroupRules": -1,
            "maxSecurityGroups": -1,
            "maxServerMeta": 128,
            "maxTotalCores": 20,
            "maxTotalFloatingIps": -1,
            "maxTotalInstances": 10,
            "maxTotalKeypairs": 100,
            "maxTotalRAMSize": 51200,
            "maxServerGroups": 10,
            "maxServerGroupMembers": 10,
            "totalCoresUsed": 0,
            "totalInstancesUsed": 0,
            "totalRAMUsed": 0,
            "totalSecurityGroupsUsed": 0,
            "totalFloatingIpsUsed": 0,
            "totalServerGroupsUsed": 0
        },
        "rate": []
    }
}

Host aggregates (os-aggregates)

Creates and manages host aggregates. An aggregate assigns metadata to groups of compute nodes.

Policy defaults enable only users with the administrative role to perform operations with aggregates. Cloud providers can change these permissions through policy file configuration.

GET
/os-aggregates

List Aggregates

Lists all aggregates. Includes the ID, name, and availability zone for each aggregate.

Normal response codes: 200

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

Response

Name

In

Type

Description

aggregates

body

array

The list of existing aggregates.

availability_zone

body

string

The availability zone of the host 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.

deleted_at

body

string

The date and time when the resource was deleted. If the resource has not been deleted yet, this field will be null, 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.

deleted

body

boolean

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

hosts

body

array

A list of host ids in this aggregate.

id

body

integer

The ID of the host aggregate.

metadata

body

object

Metadata key and value pairs associated with the aggregate.

name

body

string

The name of the host aggregate.

updated_at

body

string

The date and time when the resource was updated, if the resource has not been updated, this field will show as null. 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.

uuid

body

string

The UUID of the host aggregate.

New in version 2.41

Example List Aggregates (v2.41): JSON response

{
    "aggregates": [
        {
            "availability_zone": "london",
            "created_at": "2016-12-27T23:47:32.911515",
            "deleted": false,
            "deleted_at": null,
            "hosts": [
                "compute"
            ],
            "id": 1,
            "metadata": {
                "availability_zone": "london"
            },
            "name": "name",
            "updated_at": null,
            "uuid": "6ba28ba7-f29b-45cc-a30b-6e3a40c2fb14"
        }
    ]
}
POST
/os-aggregates

Create Aggregate

Creates an aggregate. If specifying an option availability_zone, the aggregate is created as an availability zone and the availability zone is visible to normal users.

Normal response codes: 200

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

Request

Name

In

Type

Description

aggregate

body

object

The host aggregate object.

name

body

string

The name of the host aggregate.

availability_zone (Optional)

body

string

The availability zone of the host aggregate. You should use a custom availability zone rather than the default returned by the os-availability-zone API. The availability zone must not include ‘:’ in its name.

Example Create Aggregate: JSON request

{
    "aggregate":
    {
        "name": "name",
        "availability_zone": "london"
    }
}

Response

Name

In

Type

Description

aggregate

body

object

The host aggregate object.

availability_zone

body

string

The availability zone of the host 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.

deleted_at

body

string

The date and time when the resource was deleted. If the resource has not been deleted yet, this field will be null, 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.

deleted

body

boolean

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

id

body

integer

The ID of the host aggregate.

name

body

string

The name of the host aggregate.

updated_at

body

string

The date and time when the resource was updated, if the resource has not been updated, this field will show as null. 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.

uuid

body

string

The UUID of the host aggregate.

New in version 2.41

Example Create Aggregate (v2.41): JSON response

{
    "aggregate": {
        "availability_zone": "london",
        "created_at": "2016-12-27T22:51:32.877711",
        "deleted": false,
        "deleted_at": null,
        "id": 1,
        "name": "name",
        "updated_at": null,
        "uuid": "86a0da0e-9f0c-4f51-a1e0-3c25edab3783"
    }
}
GET
/os-aggregates/{aggregate_id}

Show Aggregate Details

Shows details for an aggregate. Details include hosts and metadata.

Normal response codes: 200

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

Request

Name

In

Type

Description

aggregate_id

path

integer

The aggregate ID.

Response

Name

In

Type

Description

aggregate

body

object

The host aggregate object.

availability_zone

body

string

The availability zone of the host 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.

deleted_at

body

string

The date and time when the resource was deleted. If the resource has not been deleted yet, this field will be null, 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.

deleted

body

boolean

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

hosts

body

array

An array of host information.

id

body

integer

The ID of the host aggregate.

metadata

body

object

Metadata key and value pairs associated with the aggregate.

name

body

string

The name of the host aggregate.

updated_at

body

string

The date and time when the resource was updated, if the resource has not been updated, this field will show as null. 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.

uuid

body

string

The UUID of the host aggregate.

New in version 2.41

Example Show Aggregate Details (v2.41): JSON response

{
    "aggregate": {
        "availability_zone": "london",
        "created_at": "2016-12-27T23:47:30.563527",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null,
        "uuid": "fd0a5b12-7e8d-469d-bfd5-64a6823e7407"
    }
}
PUT
/os-aggregates/{aggregate_id}

Update Aggregate

Updates either or both the name and availability zone for an aggregate. If the aggregate to be updated has host that already in the given availability zone, the request will fail with 400 error.

Normal response codes: 200

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

Request

Name

In

Type

Description

aggregate_id

path

integer

The aggregate ID.

aggregate

body

object

The host aggregate object.

name (Optional)

body

string

The name of the host aggregate.

availability_zone (Optional)

body

string

The availability zone of the host aggregate. You should use a custom availability zone rather than the default returned by the os-availability-zone API. The availability zone must not include ‘:’ in its name.

Warning

You should not change or unset the availability zone of an aggregate when that aggregate has hosts which contain servers in it since that may impact the ability for those servers to move to another host.

Example Update Aggregate: JSON request

{
    "aggregate":
    {
        "name": "newname",
        "availability_zone": "nova2"
    }
}

Response

Name

In

Type

Description

aggregate

body

object

The host aggregate object.

availability_zone

body

string

The availability zone of the host 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.

deleted_at

body

string

The date and time when the resource was deleted. If the resource has not been deleted yet, this field will be null, 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.

deleted

body

boolean

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

hosts

body

array

An array of host information.

id

body

integer

The ID of the host aggregate.

metadata

body

object

Metadata key and value pairs associated with the aggregate.

name

body

string

The name of the host aggregate.

updated_at

body

string

The date and time when the resource was updated, if the resource has not been updated, this field will show as null. 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.

uuid

body

string

The UUID of the host aggregate.

New in version 2.41

Example Update Aggregate (v2.41): JSON response

{
    "aggregate": {
        "availability_zone": "nova2",
        "created_at": "2016-12-27T23:47:32.897139",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
            "availability_zone": "nova2"
        },
        "name": "newname",
        "updated_at": "2016-12-27T23:47:33.067180",
        "uuid": "6f74e3f3-df28-48f3-98e1-ac941b1c5e43"
    }
}
DELETE
/os-aggregates/{aggregate_id}

Delete Aggregate

Deletes an aggregate.

Normal response codes: 200

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

Request

Name

In

Type

Description

aggregate_id

path

integer

The aggregate ID.

Response

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

POST
/os-aggregates/{aggregate_id}/action

Add Host

Adds a host to an aggregate.

Specify the add_host action and host name in the request body.

Normal response codes: 200

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

Request

Name

In

Type

Description

aggregate_id

path

integer

The aggregate ID.

add_host

body

object

The add_host object used to add host to aggregate.

host

body

string

The name of the host.

Example Add Host: JSON request

{
    "add_host": {
        "host": "21549b2f665945baaa7101926a00143c"
    }
}

Response

Name

In

Type

Description

aggregate

body

object

The host aggregate object.

availability_zone

body

string

The availability zone of the host 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.

deleted_at

body

string

The date and time when the resource was deleted. If the resource has not been deleted yet, this field will be null, 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.

deleted

body

boolean

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

hosts

body

array

An array of host information.

id

body

integer

The ID of the host aggregate.

metadata

body

object

Metadata key and value pairs associated with the aggregate.

name

body

string

The name of the host aggregate.

updated_at

body

string

The date and time when the resource was updated, if the resource has not been updated, this field will show as null. 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.

uuid

body

string

The UUID of the host aggregate.

New in version 2.41

Example Add Host (v2.41): JSON response

{
    "aggregate": {
        "availability_zone": "london",
        "created_at": "2016-12-27T23:47:30.594805",
        "deleted": false,
        "deleted_at": null,
        "hosts": [
            "compute"
        ],
        "id": 1,
        "metadata": {
            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null,
        "uuid": "d1842372-89c5-4fbd-ad5a-5d2e16c85456"
    }
}
POST
/os-aggregates/{aggregate_id}/action

Remove Host

Removes a host from an aggregate.

Specify the remove_host action and host name in the request body.

Normal response codes: 200

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

Request

Name

In

Type

Description

aggregate_id

path

integer

The aggregate ID.

remove_host

body

object

The add_host object used to remove host from aggregate.

host

body

string

The name of the host.

Example Remove Host: JSON request

{
    "remove_host": {
        "host": "bf1454b3d71145d49fca2101c56c728d"
    }
}

Response

Name

In

Type

Description

aggregate

body

object

The host aggregate object.

availability_zone

body

string

The availability zone of the host 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.

deleted_at

body

string

The date and time when the resource was deleted. If the resource has not been deleted yet, this field will be null, 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.

deleted

body

boolean

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

hosts

body

array

An array of host information.

id

body

integer

The ID of the host aggregate.

metadata

body

object

Metadata key and value pairs associated with the aggregate.

name

body

string

The name of the host aggregate.

updated_at

body

string

The date and time when the resource was updated, if the resource has not been updated, this field will show as null. 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.

uuid

body

string

The UUID of the host aggregate.

New in version 2.41

Example Remove Host (v2.41): JSON response

{
    "aggregate": {
        "availability_zone": "london",
        "created_at": "2016-12-27T23:47:30.594805",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null,
        "uuid": "d1842372-89c5-4fbd-ad5a-5d2e16c85456"
    }
}
POST
/os-aggregates/{aggregate_id}/action

Create Or Update Aggregate Metadata

Creates or replaces metadata for an aggregate.

Specify the set_metadata action and metadata info in the request body.

Normal response codes: 200

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

Request

Name

In

Type

Description

aggregate_id

path

integer

The aggregate ID.

set_metadata

body

object

The set_metadata object used to set metadata for host aggregate.

metadata

body

object

Metadata key and value pairs associated with the aggregate. The maximum size for each metadata key and value pair is 255 bytes.

New keys will be added to existing aggregate metadata. For existing keys, if the value is null the entry is removed, otherwise the value is updated. Note that the special availability_zone metadata entry cannot be unset to null.

Warning

You should not change the availability zone of an aggregate when that aggregate has hosts which contain servers in it since that may impact the ability for those servers to move to another host.

Example Create Or Update Aggregate Metadata: JSON request

{
    "set_metadata":
        {
            "metadata":
                {
                    "key": "value"
                }
        }
}

Response

Name

In

Type

Description

aggregate

body

object

The host aggregate object.

availability_zone

body

string

The availability zone of the host 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.

deleted_at

body

string

The date and time when the resource was deleted. If the resource has not been deleted yet, this field will be null, 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.

deleted

body

boolean

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

hosts

body

array

An array of host information.

id

body

integer

The ID of the host aggregate.

metadata

body

object

Metadata key and value pairs associated with the aggregate.

name

body

string

The name of the host aggregate.

updated_at

body

string

The date and time when the resource was updated, if the resource has not been updated, this field will show as null. 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.

uuid

body

string

The UUID of the host aggregate.

New in version 2.41

Example Create Or Update Aggregate Metadata (v2.41): JSON response

{
    "aggregate": {
        "availability_zone": "london",
        "created_at": "2016-12-27T23:59:18.623100",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
            "availability_zone": "london",
            "key": "value"
        },
        "name": "name",
        "updated_at": "2016-12-27T23:59:18.723348",
        "uuid": "26002bdb-62cc-41bd-813a-0ad22db32625"
    }
}
POST
/os-aggregates/{aggregate_id}/images

Request Image Pre-caching for Aggregate

Requests that a set of images be pre-cached on compute nodes within the referenced aggregate.

This API is available starting with microversion 2.81.

Normal response codes: 202

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

Request

Name

In

Type

Description

aggregate_id

path

integer

The aggregate ID.

cache

body

array

A list of image objects to cache.

cache.id

body

string

The ID of the Image.

Example Request Image pre-caching for Aggregate (v2.81): JSON request

{
    "cache":
    [
        {"id": "70a599e0-31e7-49b7-b260-868f441e862b"}
    ]
}

Response

The response body is always empty.

Assisted volume snapshots (os-assisted-volume-snapshots)

Creates and deletes snapshots through an emulator/hypervisor. Only qcow2 file format is supported.

This API is only implemented by the libvirt compute driver.

An internal snapshot that lacks storage such as NFS can use an emulator/hypervisor to add the snapshot feature. This is used to enable snapshot of volumes on backends such as NFS by storing data as qcow2 files on these volumes.

This API is only ever called by Cinder, where it is used to create a snapshot for drivers that extend the remotefs Cinder driver.

POST
/os-assisted-volume-snapshots

Create Assisted Volume Snapshots

Creates an assisted volume snapshot.

Normal response codes: 200

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

Request

Name

In

Type

Description

snapshot

body

object

A partial representation of a snapshot that is used to create a snapshot.

volume_id

body

string

The source volume ID.

create_info

body

object

Information for snapshot creation.

create_info.snapshot_id

body

string

The UUID for a snapshot.

create_info.type

body

string

The snapshot type. A valid value is qcow2.

create_info.new_file

body

string

The name of the qcow2 file that Block Storage creates, which becomes the active image for the VM.

create_info.id (Optional)

body

string

Its an arbitrary string that gets passed back to the user.

Example Create Assisted Volume Snapshots: JSON request

{
    "snapshot": {
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "create_info": {
            "snapshot_id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "type": "qcow2",
            "new_file": "new_file_name",
            "id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c"
        }
    }
}

Response

Name

In

Type

Description

snapshot

body

object

A partial representation of a snapshot that is used to create a snapshot.

id

body

string

Its the same arbitrary string which was sent in request body.

Note

This string is passed back to user as it is and not being used in Nova internally. So use snapshot_id instead for further operation on this snapshot.

volumeId

body

string

The source volume ID.

Example Create Assisted Volume Snapshots: JSON response

{
    "snapshot": {
        "id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "volumeId": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"
    }
}
DELETE
/os-assisted-volume-snapshots/{snapshot_id}

Delete Assisted Volume Snapshot

Deletes an assisted volume snapshot.

To make this request, add the delete_info query parameter to the URI, as follows:

DELETE /os-assisted-volume-snapshots/421752a6-acf6-4b2d-bc7a-119f9148cd8c?delete_info=’{“volume_id”: “521752a6-acf6-4b2d-bc7a-119f9148cd8c”}’

Normal response codes: 204

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

Request

Name

In

Type

Description

snapshot_id

path

string

The UUID of the snapshot.

delete_info

query

string

Information for snapshot deletion. Include the ID of the associated volume. For example:

DELETE /os-assisted-volume-snapshots/421752a6-acf6-4b2d-bc7a-119f9148cd8c?delete_info='{"volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"}'

Response

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

Availability zones (os-availability-zone)

Lists and gets detailed availability zone information.

An availability zone is created or updated by setting the availability_zone parameter in the create, update, or create or update methods of the Host Aggregates API. See Host Aggregates for more details.

GET
/os-availability-zone

Get Availability Zone Information

Lists availability zone information.

Normal response codes: 200

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

Response

Name

In

Type

Description

availabilityZoneInfo

body

array

The list of availability zone information.

hosts

body

none

It is always null.

zoneName

body

string

The availability zone name.

zoneState

body

object

The current state of the availability zone.

available

body

boolean

Returns true if the availability zone is available.


Example Get availability zone information

{
    "availabilityZoneInfo": [
        {
            "hosts": null,
            "zoneName": "nova",
            "zoneState": {
                "available": true
            }
        }
    ]
}
GET
/os-availability-zone/detail

Get Detailed Availability Zone Information

Gets detailed availability zone information. Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Response

Name

In

Type

Description

availabilityZoneInfo

body

array

The list of availability zone information.

hosts

body

object

An object containing a list of host information. The host information is comprised of host and service objects. The service object returns three parameters representing the states of the service: active, available, and updated_at.

zoneName

body

string

The availability zone name.

zoneState

body

object

The current state of the availability zone.

available

body

boolean

Returns true if the availability zone is available.


Example Get detailed availability zone information

{
    "availabilityZoneInfo": [
        {
            "hosts": {
                "conductor": {
                    "nova-conductor": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                },
                "scheduler": {
                    "nova-scheduler": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                }
            },
            "zoneName": "internal",
            "zoneState": {
                "available": true
            }
        },
        {
            "hosts": {
                "compute": {
                    "nova-compute": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                }
            },
            "zoneName": "nova",
            "zoneState": {
                "available": true
            }
        }
    ]
}

Hypervisors (os-hypervisors)

Lists all hypervisors, shows summary statistics for all hypervisors over all compute nodes, shows details for a hypervisor, shows the uptime for a hypervisor, lists all servers on hypervisors that match the given hypervisor_hostname_pattern or searches for hypervisors by the given hypervisor_hostname_pattern.

GET
/os-hypervisors

List Hypervisors

Lists hypervisors.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

limit (Optional)

query

integer

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

New in version 2.33

marker (Optional)

query

integer

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

New in version 2.33

Available until version 2.52

marker (Optional)

query

string

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

New in version 2.53

hypervisor_hostname_pattern (Optional)

query

string

The hypervisor host name or a portion of it. The hypervisor hosts are selected with the host name matching this pattern.

Note

limit and marker query parameters for paging are not supported when listing hypervisors using a hostname pattern. Also, links will not be returned in the response when using this query parameter.

New in version 2.53

with_servers (Optional)

query

boolean

Include all servers which belong to each hypervisor in the response output.

New in version 2.53

Response

Name

In

Type

Description

hypervisors

body

array

An array of hypervisor information.

hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid.

id

body

integer

The id of the hypervisor.

Available until version 2.52

id

body

string

The id of the hypervisor as a UUID.

New in version 2.53

state

body

string

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

status

body

string

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

hypervisor_links (Optional)

body

array

Links to the hypervisors resource. See API Guide / Links and References for more info.

New in version 2.33

servers

body

array

A list of server objects. This field has become mandatory in microversion 2.75. If no servers is on hypervisor then empty list is returned.

New in version 2.53

servers.uuid (Optional)

body

string

The server ID.

New in version 2.53

servers.name (Optional)

body

string

The server name.

New in version 2.53

Example List Hypervisors (v2.33): JSON response

{
    "hypervisors": [
        {
            "hypervisor_hostname": "host1",
            "id": 2,
            "state": "up",
            "status": "enabled"
        }
    ],
    "hypervisors_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-hypervisors?limit=1&marker=2",
            "rel": "next"
        }
    ]
}

Example List Hypervisors With Servers (v2.53): JSON response

{
    "hypervisors": [
        {
            "hypervisor_hostname": "fake-mini",
            "id": "b1e43b5f-eec1-44e0-9f10-7b4945c0226d",
            "state": "up",
            "status": "enabled",
            "servers": [
                {
                    "name": "test_server1",
                    "uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
                },
                {
                    "name": "test_server2",
                    "uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
                }
            ]
        }
    ]
}
GET
/os-hypervisors/detail

List Hypervisors Details

Lists hypervisors details.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

limit (Optional)

query

integer

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

New in version 2.33

marker (Optional)

query

integer

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

New in version 2.33

Available until version 2.52

marker (Optional)

query

string

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

New in version 2.53

hypervisor_hostname_pattern (Optional)

query

string

The hypervisor host name or a portion of it. The hypervisor hosts are selected with the host name matching this pattern.

Note

limit and marker query parameters for paging are not supported when listing hypervisors using a hostname pattern. Also, links will not be returned in the response when using this query parameter.

New in version 2.53

with_servers (Optional)

query

boolean

Include all servers which belong to each hypervisor in the response output.

New in version 2.53

Response

Name

In

Type

Description

hypervisors

body

array

An array of hypervisor information.

cpu_info

body

object

A dictionary that contains cpu information like arch, model, vendor, features and topology. The content of this field is hypervisor specific.

Note

Since version 2.28 cpu_info field is returned as a dictionary instead of string.

Available until version 2.87

current_workload

body

integer

The current_workload is the number of tasks the hypervisor is responsible for. This will be equal or greater than the number of active VMs on the system (it can be greater when VMs are being deleted and the hypervisor is still cleaning up).

Available until version 2.87

status

body

string

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

state

body

string

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

disk_available_least

body

integer

The actual free disk on this hypervisor(in GiB). If allocation ratios used for overcommit are configured, this may be negative. This is intentional as it provides insight into the amount by which the disk is overcommitted.

Available until version 2.87

host_ip

body

string

The IP address of the hypervisor’s host.

free_disk_gb

body

integer

The free disk remaining on this hypervisor(in GiB). This does not take allocation ratios used for overcommit into account so this value may be negative.

Available until version 2.87

free_ram_mb

body

integer

The free RAM in this hypervisor(in MiB). This does not take allocation ratios used for overcommit into account so this value may be negative.

Available until version 2.87

hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid.

hypervisor_type

body

string

The hypervisor type.

hypervisor_version

body

integer

The hypervisor version.

id

body

integer

The id of the hypervisor.

Available until version 2.52

id

body

string

The id of the hypervisor as a UUID.

New in version 2.53

local_gb

body

integer

The disk in this hypervisor (in GiB). This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

Available until version 2.87

local_gb_used

body

integer

The disk used in this hypervisor (in GiB).

Available until version 2.87

memory_mb

body

integer

The memory of this hypervisor (in MiB). This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

Available until version 2.87

memory_mb_used

body

integer

The memory used in this hypervisor (in MiB).

Available until version 2.87

running_vms

body

integer

The number of running VMs on this hypervisor.

Available until version 2.87

servers

body

array

A list of server objects. This field has become mandatory in microversion 2.75. If no servers is on hypervisor then empty list is returned.

New in version 2.53

servers.uuid (Optional)

body

string

The server ID.

New in version 2.53

servers.name (Optional)

body

string

The server name.

New in version 2.53

service

body

object

The hypervisor service object.

service.host

body

string

The name of the host.

service.id

body

integer

The id of the service.

Available until version 2.52

service.id

body

string

The id of the service as a uuid.

New in version 2.53

service.disabled_reason

body

string

The disable reason of the service, null if the service is enabled or disabled without reason provided.

uptime

body

string

The total uptime of the hypervisor and information about average load. Only reported for active hosts where the virt driver supports this feature.

New in version 2.88

vcpus

body

integer

The number of vCPU in this hypervisor. This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

Available until version 2.87

vcpus_used

body

integer

The number of vCPU used in this hypervisor.

Available until version 2.87

hypervisor_links (Optional)

body

array

Links to the hypervisors resource. See API Guide / Links and References for more info.

New in version 2.33

Example List Hypervisors Details (v2.33): JSON response

{
    "hypervisors": [
        {
            "cpu_info": {
                "arch": "x86_64",
                "model": "Nehalem",
                "vendor": "Intel",
                "features": [
                    "pge",
                    "clflush"
                ],
                "topology": {
                    "cores": 1,
                    "threads": 1,
                    "sockets": 4
                }
            },
            "current_workload": 0,
            "status": "enabled",
            "state": "up",
            "disk_available_least": 0,
            "host_ip": "1.1.1.1",
            "free_disk_gb": 1028,
            "free_ram_mb": 7680,
            "hypervisor_hostname": "host1",
            "hypervisor_type": "fake",
            "hypervisor_version": 1000,
            "id": 2,
            "local_gb": 1028,
            "local_gb_used": 0,
            "memory_mb": 8192,
            "memory_mb_used": 512,
            "running_vms": 0,
            "service": {
                "host": "host1",
                "id": 6,
                "disabled_reason": null
            },
            "vcpus": 2,
            "vcpus_used": 0
        }
    ],
    "hypervisors_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-hypervisors/detail?limit=1&marker=2",
            "rel": "next"
        }
    ]
}

Example List Hypervisors Details (v2.53): JSON response

{
    "hypervisors": [
        {
            "cpu_info": {
                "arch": "x86_64",
                "model": "Nehalem",
                "vendor": "Intel",
                "features": [
                    "pge",
                    "clflush"
                ],
                "topology": {
                    "cores": 1,
                    "threads": 1,
                    "sockets": 4
                }
            },
            "current_workload": 0,
            "status": "enabled",
            "state": "up",
            "disk_available_least": 0,
            "host_ip": "1.1.1.1",
            "free_disk_gb": 1028,
            "free_ram_mb": 7680,
            "hypervisor_hostname": "host2",
            "hypervisor_type": "fake",
            "hypervisor_version": 1000,
            "id": "1bb62a04-c576-402c-8147-9e89757a09e3",
            "local_gb": 1028,
            "local_gb_used": 0,
            "memory_mb": 8192,
            "memory_mb_used": 512,
            "running_vms": 0,
            "service": {
                "host": "host1",
                "id": "62f62f6e-a713-4cbe-87d3-3ecf8a1e0f8d",
                "disabled_reason": null
            },
            "vcpus": 2,
            "vcpus_used": 0
        }
    ],
    "hypervisors_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-hypervisors/detail?limit=1&marker=1bb62a04-c576-402c-8147-9e89757a09e3",
            "rel": "next"
        }
    ]
}

Example List Hypervisors Details (v2.88): JSON response

{
    "hypervisors": [
        {
            "host_ip": "192.168.1.135",
            "hypervisor_hostname": "host2",
            "hypervisor_type": "fake",
            "hypervisor_version": 1000,
            "id": "f6d28711-9c10-470e-8b31-c03f498b0032",
            "service": {
                "disabled_reason": null,
                "host": "host2",
                "id": "21bbb5fb-ec98-48b3-89cf-c94402c55611"
            },
            "state": "up",
            "status": "enabled",
            "uptime": null
        }
    ],
    "hypervisors_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-hypervisors/detail?limit=1&marker=f6d28711-9c10-470e-8b31-c03f498b0032",
            "rel": "next"
        }
    ]
}
GET
/os-hypervisors/statistics

Show Hypervisor Statistics (DEPRECATED)

Shows summary statistics for all enabled hypervisors over all compute nodes.

Warning

This API is deprecated and will fail with HTTP 404 starting with microversion 2.88. Use placement to get information on resource usage across hypervisors.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Note

As noted, some of the parameters in the response representing totals do not take allocation ratios into account. This can result in a disparity between the totals and the usages. A more accurate representation of state can be obtained using placement.

Normal response codes: 200

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

Response

Name

In

Type

Description

hypervisor_statistics

body

object

The hypervisors statistics summary object.

count

body

integer

The number of hypervisors.

current_workload

body

integer

The current_workload is the number of tasks the hypervisors are responsible for. This will be equal or greater than the number of active VMs on the systems (it can be greater when VMs are being deleted and a hypervisor is still cleaning up).

disk_available_least

body

integer

The actual free disk on all hypervisors(in GiB). If allocation ratios used for overcommit are configured, this may be negative. This is intentional as it provides insight into the amount by which the disk is overcommitted.

free_disk_gb

body

integer

The free disk remaining on all hypervisors(in GiB). This does not take allocation ratios used for overcommit into account so this value may be negative.

free_ram_mb

body

integer

The free RAM on all hypervisors(in MiB). This does not take allocation ratios used for overcommit into account so this value may be negative.

local_gb

body

integer

The disk on all hypervisors (in GiB). This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

local_gb_used

body

integer

The disk used on all hypervisors (in GiB).

memory_mb

body

integer

The memory of all hypervisors (in MiB). This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

memory_mb_used

body

integer

The memory used on all hypervisors(in MiB).

running_vms

body

integer

The total number of running VMs on all hypervisors.

vcpus

body

integer

The number of vCPU on all hypervisors. This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

vcpus_used

body

integer

The number of vCPU used on all hypervisors.

Example Show Hypervisor Statistics: JSON response

{
    "hypervisor_statistics": {
        "count": 1,
        "current_workload": 0,
        "disk_available_least": 0,
        "free_disk_gb": 1028,
        "free_ram_mb": 7680,
        "local_gb": 1028,
        "local_gb_used": 0,
        "memory_mb": 8192,
        "memory_mb_used": 512,
        "running_vms": 0,
        "vcpus": 2,
        "vcpus_used": 0
    }
}
GET
/os-hypervisors/{hypervisor_id}

Show Hypervisor Details

Shows details for a given hypervisor.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Note

As noted, some of the parameters in the response representing totals do not take allocation ratios into account. This can result in a disparity between the totals and the usages. A more accurate representation of state can be obtained using placement.

Normal response codes: 200

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

Request

Name

In

Type

Description

hypervisor_id

path

integer

The ID of the hypervisor.

Available until version 2.52

hypervisor_id

path

string

The ID of the hypervisor as a UUID.

New in version 2.53

with_servers (Optional)

query

boolean

Include all servers which belong to each hypervisor in the response output.

New in version 2.53

Response

Name

In

Type

Description

hypervisor

body

object

The hypervisor object.

cpu_info

body

object

A dictionary that contains cpu information like arch, model, vendor, features and topology. The content of this field is hypervisor specific.

Note

Since version 2.28 cpu_info field is returned as a dictionary instead of string.

Available until version 2.87

state

body

string

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

status

body

string

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

current_workload

body

integer

The current_workload is the number of tasks the hypervisor is responsible for. This will be equal or greater than the number of active VMs on the system (it can be greater when VMs are being deleted and the hypervisor is still cleaning up).

Available until version 2.87

disk_available_least

body

integer

The actual free disk on this hypervisor(in GiB). If allocation ratios used for overcommit are configured, this may be negative. This is intentional as it provides insight into the amount by which the disk is overcommitted.

Available until version 2.87

host_ip

body

string

The IP address of the hypervisor’s host.

free_disk_gb

body

integer

The free disk remaining on this hypervisor(in GiB). This does not take allocation ratios used for overcommit into account so this value may be negative.

Available until version 2.87

free_ram_mb

body

integer

The free RAM in this hypervisor(in MiB). This does not take allocation ratios used for overcommit into account so this value may be negative.

Available until version 2.87

hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid.

hypervisor_type

body

string

The hypervisor type.

hypervisor_version

body

integer

The hypervisor version.

id

body

integer

The id of the hypervisor.

Available until version 2.52

id

body

string

The id of the hypervisor as a UUID.

New in version 2.53

local_gb

body

integer

The disk in this hypervisor (in GiB). This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

Available until version 2.87

local_gb_used

body

integer

The disk used in this hypervisor (in GiB).

Available until version 2.87

memory_mb

body

integer

The memory of this hypervisor (in MiB). This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

Available until version 2.87

memory_mb_used

body

integer

The memory used in this hypervisor (in MiB).

Available until version 2.87

running_vms

body

integer

The number of running VMs on this hypervisor.

Available until version 2.87

servers

body

array

A list of server objects. This field has become mandatory in microversion 2.75. If no servers is on hypervisor then empty list is returned.

New in version 2.53

servers.uuid (Optional)

body

string

The server ID.

New in version 2.53

servers.name (Optional)

body

string

The server name.

New in version 2.53

service

body

object

The hypervisor service object.

service.host

body

string

The name of the host.

service.id

body

integer

The id of the service.

Available until version 2.52

service.id

body

string

The id of the service as a uuid.

New in version 2.53

service.disabled_reason

body

string

The disable reason of the service, null if the service is enabled or disabled without reason provided.

uptime

body

string

The total uptime of the hypervisor and information about average load. Only reported for active hosts where the virt driver supports this feature.

New in version 2.88

vcpus

body

integer

The number of vCPU in this hypervisor. This does not take allocation ratios used for overcommit into account so there may be disparity between this and the used count.

Available until version 2.87

vcpus_used

body

integer

The number of vCPU used in this hypervisor.

Available until version 2.87

Example Show Hypervisor Details (v2.28): JSON response

{
    "hypervisor": {
        "cpu_info": {
            "arch": "x86_64",
            "model": "Nehalem",
            "vendor": "Intel",
            "features": [
                "pge",
                "clflush"
            ],
            "topology": {
                "cores": 1,
                "threads": 1,
                "sockets": 4
            }
        },
        "state": "up",
        "status": "enabled",
        "current_workload": 0,
        "disk_available_least": 0,
        "host_ip": "1.1.1.1",
        "free_disk_gb": 1028,
        "free_ram_mb": 7680,
        "hypervisor_hostname": "fake-mini",
        "hypervisor_type": "fake",
        "hypervisor_version": 1000,
        "id": 1,
        "local_gb": 1028,
        "local_gb_used": 0,
        "memory_mb": 8192,
        "memory_mb_used": 512,
        "running_vms": 0,
        "service": {
            "host": "043b3cacf6f34c90a7245151fc8ebcda",
            "id": 2,
            "disabled_reason": null
        },
        "vcpus": 2,
        "vcpus_used": 0
    }
}

Example Show Hypervisor Details With Servers (v2.53): JSON response

{
    "hypervisor": {
        "cpu_info": {
            "arch": "x86_64",
            "model": "Nehalem",
            "vendor": "Intel",
            "features": [
                "pge",
                "clflush"
            ],
            "topology": {
                "cores": 1,
                "threads": 1,
                "sockets": 4
            }
        },
        "state": "up",
        "status": "enabled",
        "servers": [
            {
                "name": "test_server1",
                "uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
            },
            {
                "name": "test_server2",
                "uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
            }
        ],
        "current_workload": 0,
        "disk_available_least": 0,
        "host_ip": "1.1.1.1",
        "free_disk_gb": 1028,
        "free_ram_mb": 7680,
        "hypervisor_hostname": "fake-mini",
        "hypervisor_type": "fake",
        "hypervisor_version": 1000,
        "id": "b1e43b5f-eec1-44e0-9f10-7b4945c0226d",
        "local_gb": 1028,
        "local_gb_used": 0,
        "memory_mb": 8192,
        "memory_mb_used": 512,
        "running_vms": 0,
        "service": {
            "host": "043b3cacf6f34c90a7245151fc8ebcda",
            "id": "5d343e1d-938e-4284-b98b-6a2b5406ba76",
            "disabled_reason": null
        },
        "vcpus": 2,
        "vcpus_used": 0
    }
}

Example Show Hypervisors Details (v2.88): JSON response

{
    "hypervisor": {
        "host_ip": "192.168.1.135",
        "hypervisor_hostname": "fake-mini",
        "hypervisor_type": "fake",
        "hypervisor_version": 1000,
        "id": "a68a56ab-9c42-47c0-9309-879e4a6dbe86",
        "servers": [
            {
                "name": "test_server1",
                "uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
            },
            {
                "name": "test_server2",
                "uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
            }
        ],
        "service": {
            "disabled_reason": null,
            "host": "compute",
            "id": "8495059a-a079-4ab4-ad6f-cf45b81c877d"
        },
        "state": "up",
        "status": "enabled",
        "uptime": null
    }
}
GET
/os-hypervisors/{hypervisor_id}/uptime

Show Hypervisor Uptime (DEPRECATED)

Shows the uptime for a given hypervisor.

Warning

This API is deprecated and will fail with HTTP 404 starting with microversion 2.88. Use Show Hypervisor Details with microversion 2.88 and later to get this information.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

hypervisor_id

path

integer

The ID of the hypervisor.

Available until version 2.52

hypervisor_id

path

string

The ID of the hypervisor as a UUID.

New in version 2.53

Response

Name

In

Type

Description

hypervisor

body

object

The hypervisor object.

hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid.

id

body

integer

The id of the hypervisor.

Available until version 2.52

id

body

string

The id of the hypervisor as a UUID.

New in version 2.53

state

body

string

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

status

body

string

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

uptime

body

string

The total uptime of the hypervisor and information about average load.

Example Show Hypervisor Uptime: JSON response

{
    "hypervisor": {
        "hypervisor_hostname": "fake-mini",
        "id": 1,
        "state": "up",
        "status": "enabled",
        "uptime": " 08:32:11 up 93 days, 18:25, 12 users,  load average: 0.20, 0.12, 0.14"
    }
}

Example Show Hypervisor Uptime (v2.53): JSON response

{
    "hypervisor": {
        "hypervisor_hostname": "fake-mini",
        "id": "b1e43b5f-eec1-44e0-9f10-7b4945c0226d",
        "state": "up",
        "status": "enabled",
        "uptime": " 08:32:11 up 93 days, 18:25, 12 users,  load average: 0.20, 0.12, 0.14"
    }
}
GET
/os-hypervisors/{hypervisor_hostname_pattern}/search

Search Hypervisor (DEPRECATED)

Search hypervisor by a given hypervisor host name or portion of it.

Warning

This API is deprecated starting with microversion 2.53. Use List Hypervisors with the hypervisor_hostname_pattern query parameter with microversion 2.53 and later.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response code: 200

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

Request

Name

In

Type

Description

hypervisor_hostname_pattern

path

string

The hypervisor host name or a portion of it. The hypervisor hosts are selected with the host name matching this pattern.

Response

Name

In

Type

Description

hypervisors

body

array

An array of hypervisor information.

hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid.

id

body

integer

The id of the hypervisor.

state

body

string

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

status

body

string

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

Example Search Hypervisor: JSON response

{
    "hypervisors": [
        {
            "hypervisor_hostname": "fake-mini",
            "id": 1,
            "state": "up",
            "status": "enabled"
        }
    ]
}
GET
/os-hypervisors/{hypervisor_hostname_pattern}/servers

List Hypervisor Servers (DEPRECATED)

List all servers belong to each hypervisor whose host name is matching a given hypervisor host name or portion of it.

Warning

This API is deprecated starting with microversion 2.53. Use List Hypervisors with the hypervisor_hostname_pattern and with_servers query parameters with microversion 2.53 and later.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response code: 200

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

Request

Name

In

Type

Description

hypervisor_hostname_pattern

path

string

The hypervisor host name or a portion of it. The hypervisor hosts are selected with the host name matching this pattern.

Response

Name

In

Type

Description

hypervisors

body

array

An array of hypervisor information.

hypervisor_hostname

body

string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid.

id

body

integer

The id of the hypervisor.

state

body

string

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

status

body

string

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

servers

body

array

A list of server objects.

servers.uuid

body

string

The UUID of the server instance to which the API dispatches the event. You must assign this instance to a host. Otherwise, this call does not dispatch the event to the instance.

servers.name

body

string

The server name.

Example List Hypervisor Servers: JSON response

{
    "hypervisors": [
        {
            "hypervisor_hostname": "fake-mini",
            "id": 1,
            "state": "up",
            "status": "enabled",
            "servers": [
                {
                    "name": "test_server1",
                    "uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
                },
                {
                    "name": "test_server2",
                    "uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
                }
            ]
        }
    ]
}

Server usage audit log (os-instance-usage-audit-log)

Audit server usage of the cloud. This API is dependent on the instance_usage_audit configuration option being set on all compute hosts where usage auditing is required.

Policy defaults enable only users with the administrative role to perform all os-instance-usage-audit-log related operations. Cloud providers can change these permissions through the policy.json file.

GET
/os-instance_usage_audit_log

List Server Usage Audits

Lists usage audits for all servers on all compute hosts where usage auditing is configured.

Normal response codes: 200

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

Response

Name

In

Type

Description

instance_usage_audit_logs

body

object

The object of instance usage audit log information.

hosts_not_run

body

array

A list of the hosts whose instance audit tasks have not run.

log

body

object

The object of instance usage audit logs.

errors

body

integer

The number of errors.

instances

body

integer

The number of instances.

message

body

string

The log message of the instance usage audit task.

state

body

string

The state of the instance usage audit task. DONE or RUNNING.

num_hosts

body

integer

The number of the hosts.

num_hosts_done

body

integer

The number of the hosts whose instance audit tasks have been done.

num_hosts_not_run

body

integer

The number of the hosts whose instance audit tasks have not run.

num_hosts_running

body

integer

The number of the hosts whose instance audit tasks are running.

overall_status

body

string

The overall status of instance audit tasks.

M of N hosts done. K errors.

The M value is the number of hosts whose instance audit tasks have been done in the period. The N value is the number of all hosts. The K value is the number of hosts whose instance audit tasks cause errors. If instance audit tasks have been done at all hosts in the period, the overall status is as follows:

ALL hosts done. K errors.

period_beginning

body

string

The beginning time of the instance usage audit period. For example, 2016-05-01 00:00:00.

period_ending

body

string

The ending time of the instance usage audit period. For example, 2016-06-01 00:00:00.

total_errors

body

integer

The total number of instance audit task errors.

total_instances

body

integer

The total number of VM instances in the period.

Example List Usage Audits For All Servers

{
    "instance_usage_audit_logs": {
        "hosts_not_run": [
            "samplehost3"
        ],
        "log": {
            "samplehost0": {
                "errors": 1,
                "instances": 1,
                "message": "Instance usage audit ran for host samplehost0, 1 instances in 0.01 seconds.",
                "state": "DONE"
            },
            "samplehost1": {
                "errors": 1,
                "instances": 2,
                "message": "Instance usage audit ran for host samplehost1, 2 instances in 0.01 seconds.",
                "state": "DONE"
            },
            "samplehost2": {
                "errors": 1,
                "instances": 3,
                "message": "Instance usage audit ran for host samplehost2, 3 instances in 0.01 seconds.",
                "state": "DONE"
            }
        },
        "num_hosts": 4,
        "num_hosts_done": 3,
        "num_hosts_not_run": 1,
        "num_hosts_running": 0,
        "overall_status": "3 of 4 hosts done. 3 errors.",
        "period_beginning": "2012-06-01 00:00:00",
        "period_ending": "2012-07-01 00:00:00",
        "total_errors": 3,
        "total_instances": 6
    }
}
GET
/os-instance_usage_audit_log/{before_timestamp}

List Usage Audits Before Specified Time

Lists usage audits that occurred before a specified time.

Normal response codes: 200

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

Request

Name

In

Type

Description

before_timestamp

path

string

Filters the response by the date and time before which to list usage audits. The date and time stamp format is as follows:

CCYY-MM-DD hh:mm:ss.NNNNNN

For example, 2015-08-27 09:49:58 or 2015-08-27 09:49:58.123456.

Response

Name

In

Type

Description

instance_usage_audit_log

body

object

The object of instance usage audit log information.

hosts_not_run

body

array

A list of the hosts whose instance audit tasks have not run.

log

body

object

The object of instance usage audit logs.

errors

body

integer

The number of errors.

instances

body

integer

The number of instances.

message

body

string

The log message of the instance usage audit task.

state

body

string

The state of the instance usage audit task. DONE or RUNNING.

num_hosts

body

integer

The number of the hosts.

num_hosts_done

body

integer

The number of the hosts whose instance audit tasks have been done.

num_hosts_not_run

body

integer

The number of the hosts whose instance audit tasks have not run.

num_hosts_running

body

integer

The number of the hosts whose instance audit tasks are running.

overall_status

body

string

The overall status of instance audit tasks.

M of N hosts done. K errors.

The M value is the number of hosts whose instance audit tasks have been done in the period. The N value is the number of all hosts. The K value is the number of hosts whose instance audit tasks cause errors. If instance audit tasks have been done at all hosts in the period, the overall status is as follows:

ALL hosts done. K errors.

period_beginning

body

string

The beginning time of the instance usage audit period. For example, 2016-05-01 00:00:00.

period_ending

body

string

The ending time of the instance usage audit period. For example, 2016-06-01 00:00:00.

total_errors

body

integer

The total number of instance audit task errors.

total_instances

body

integer

The total number of VM instances in the period.

Example List Usage Audits Before Specified Time

{
    "instance_usage_audit_log": {
        "hosts_not_run": [
            "samplehost3"
        ],
        "log": {
            "samplehost0": {
                "errors": 1,
                "instances": 1,
                "message": "Instance usage audit ran for host samplehost0, 1 instances in 0.01 seconds.",
                "state": "DONE"
            },
            "samplehost1": {
                "errors": 1,
                "instances": 2,
                "message": "Instance usage audit ran for host samplehost1, 2 instances in 0.01 seconds.",
                "state": "DONE"
            },
            "samplehost2": {
                "errors": 1,
                "instances": 3,
                "message": "Instance usage audit ran for host samplehost2, 3 instances in 0.01 seconds.",
                "state": "DONE"
            }
        },
        "num_hosts": 4,
        "num_hosts_done": 3,
        "num_hosts_not_run": 1,
        "num_hosts_running": 0,
        "overall_status": "3 of 4 hosts done. 3 errors.",
        "period_beginning": "2012-06-01 00:00:00",
        "period_ending": "2012-07-01 00:00:00",
        "total_errors": 3,
        "total_instances": 6
    }
}

Migrations (os-migrations)

Shows data on migrations.

GET
/os-migrations

List Migrations

Lists migrations.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Starting from microversion 2.59, the response is sorted by created_at and id in descending order.

Normal response codes: 200

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

Request

Name

In

Type

Description

hidden (Optional)

query

integer

The ‘hidden’ setting of migration to filter. The ‘hidden’ flag is set if the value is 1. The ‘hidden’ flag is not set if the value is 0. But the ‘hidden’ setting of migration is always 0, so this parameter is useless to filter migrations.

host (Optional)

query

string

The source/destination compute node of migration to filter.

instance_uuid (Optional)

query

string

The uuid of the instance that migration is operated on to filter.

migration_type (Optional)

query

string

The type of migration to filter. Valid values are:

  • evacuation

  • live-migration

  • migration

  • resize

source_compute (Optional)

query

string

The source compute node of migration to filter.

status (Optional)

query

string

The status of migration to filter.

limit (Optional)

query

integer

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

New in version 2.59

marker (Optional)

query

string

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

New in version 2.59

changes-since (Optional)

query

string

Filters the response by a date and time stamp when the migration last changed. Those changed after the specified date and time stamp are returned.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-since must be earlier than or equal to the value of the changes-before otherwise API will return 400.

New in version 2.59

changes-before (Optional)

query

string

Filters the response by a date and time stamp when the migration last changed. Those migrations that changed before or equal to the specified date and time stamp are returned.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-before must be later than or equal to the value of the changes-since otherwise API will return 400.

New in version 2.66

user_id (Optional)

query

string

Filter the migrations by the given user ID.

New in version 2.80

project_id (Optional)

query

string

Filter the migrations by the given project ID.

New in version 2.80

Response

Name

In

Type

Description

migrations

body

array

The list of server migration objects.

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.

dest_compute

body

string

The target compute for a migration.

dest_host

body

string

The target host for a migration.

dest_node

body

string

The target node for a migration.

id

body

integer

The ID of the server migration.

instance_uuid

body

string

The UUID of the server.

new_instance_type_id

body

integer

In resize case, the flavor ID for resizing the server. In the other cases, this parameter is same as the flavor ID of the server when the migration was started.

Note

This is an internal ID and is not exposed in any other API. In particular, this is not the ID specified or automatically generated during flavor creation or returned via the GET /flavors API.

old_instance_type_id

body

integer

The flavor ID of the server when the migration was started.

Note

This is an internal ID and is not exposed in any other API. In particular, this is not the ID specified or automatically generated during flavor creation or returned via the GET /flavors API.

source_compute

body

string

The source compute for a migration.

source_node

body

string

The source node for a migration.

status

body

string

The current status of the migration.

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.

migration_type

body

string

The type of the server migration. This is one of live-migration, migration, resize and evacuation.

New in version 2.23

links (Optional)

body

array

Links to the migration. This parameter is returned if the migration type is live-migration and the migration status is one of queued, preparing, running and post-migrating. See Paginated collections for more info.

New in version 2.23

uuid

body

string

The UUID of the migration.

New in version 2.59

migrations_links (Optional)

body

array

Links pertaining to the migration. This parameter is returned when paging and more data is available. See Paginated collections for more info.

New in version 2.59

user_id

body

string

The ID of the user which initiated the server migration. The value may be null for older migration records.

New in version 2.80

project_id

body

string

The ID of the project which initiated the server migration. The value may be null for older migration records.

New in version 2.80

Example List Migrations: JSON response

{
    "migrations": [
        {
            "created_at": "2012-10-29T13:42:02.000000",
            "dest_compute": "compute2",
            "dest_host": "1.2.3.4",
            "dest_node": "node2",
            "id": 1234,
            "instance_uuid": "8600d31b-d1a1-4632-b2ff-45c2be1a70ff",
            "new_instance_type_id": 2,
            "old_instance_type_id": 1,
            "source_compute": "compute1",
            "source_node": "node1",
            "status": "done",
            "updated_at": "2012-10-29T13:42:02.000000"
        },
        {
            "created_at": "2013-10-22T13:42:02.000000",
            "dest_compute": "compute20",
            "dest_host": "5.6.7.8",
            "dest_node": "node20",
            "id": 5678,
            "instance_uuid": "9128d044-7b61-403e-b766-7547076ff6c1",
            "new_instance_type_id": 6,
            "old_instance_type_id": 5,
            "source_compute": "compute10",
            "source_node": "node10",
            "status": "done",
            "updated_at": "2013-10-22T13:42:02.000000"
        }
    ]
}

Example List Migrations (v2.80):

{
    "migrations": [
        {
            "created_at": "2016-06-23T14:42:02.000000",
            "dest_compute": "compute20",
            "dest_host": "5.6.7.8",
            "dest_node": "node20",
            "id": 4,
            "instance_uuid": "9128d044-7b61-403e-b766-7547076ff6c1",
            "new_instance_type_id": 6,
            "old_instance_type_id": 5,
            "source_compute": "compute10",
            "source_node": "node10",
            "status": "migrating",
            "migration_type": "resize",
            "updated_at": "2016-06-23T14:42:02.000000",
            "uuid": "42341d4b-346a-40d0-83c6-5f4f6892b650",
            "user_id": "78348f0e-97ee-4d70-ad34-189692673ea2",
            "project_id": "9842f0f7-1229-4355-afe7-15ebdbb8c3d8"
        },
        {
            "created_at": "2016-06-23T13:42:02.000000",
            "dest_compute": "compute20",
            "dest_host": "5.6.7.8",
            "dest_node": "node20",
            "id": 3,
            "instance_uuid": "9128d044-7b61-403e-b766-7547076ff6c1",
            "new_instance_type_id": 6,
            "old_instance_type_id": 5,
            "source_compute": "compute10",
            "source_node": "node10",
            "status": "error",
            "migration_type": "resize",
            "updated_at": "2016-06-23T13:42:02.000000",
            "uuid": "32341d4b-346a-40d0-83c6-5f4f6892b650",
            "user_id": "78348f0e-97ee-4d70-ad34-189692673ea2",
            "project_id": "9842f0f7-1229-4355-afe7-15ebdbb8c3d8"
        },
        {
            "created_at": "2016-01-29T12:42:02.000000",
            "dest_compute": "compute2",
            "dest_host": "1.2.3.4",
            "dest_node": "node2",
            "id": 2,
            "instance_uuid": "8600d31b-d1a1-4632-b2ff-45c2be1a70ff",
            "new_instance_type_id": 1,
            "old_instance_type_id": 1,
            "source_compute": "compute1",
            "source_node": "node1",
            "status": "error",
            "migration_type": "live-migration",
            "updated_at": "2016-01-29T12:42:02.000000",
            "uuid": "22341d4b-346a-40d0-83c6-5f4f6892b650",
            "user_id": "5c48ebaa-193f-4c5d-948a-f559cc92cd5e",
            "project_id": "ef92ccff-00f3-46e4-b015-811110e36ee4"
        },
        {
            "created_at": "2016-01-29T11:42:02.000000",
            "dest_compute": "compute2",
            "dest_host": "1.2.3.4",
            "dest_node": "node2",
            "id": 1,
            "instance_uuid": "8600d31b-d1a1-4632-b2ff-45c2be1a70ff",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/8600d31b-d1a1-4632-b2ff-45c2be1a70ff/migrations/1",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/8600d31b-d1a1-4632-b2ff-45c2be1a70ff/migrations/1",
                    "rel": "bookmark"
                }
            ],
            "new_instance_type_id": 1,
            "old_instance_type_id": 1,
            "source_compute": "compute1",
            "source_node": "node1",
            "status": "running",
            "migration_type": "live-migration",
            "updated_at": "2016-01-29T11:42:02.000000",
            "uuid": "12341d4b-346a-40d0-83c6-5f4f6892b650",
            "user_id": "5c48ebaa-193f-4c5d-948a-f559cc92cd5e",
            "project_id": "ef92ccff-00f3-46e4-b015-811110e36ee4"
        }
    ]
}

Example List Migrations With Paging (v2.80):

 {
    "migrations": [
        {
            "created_at": "2016-06-23T14:42:02.000000",
            "dest_compute": "compute20",
            "dest_host": "5.6.7.8",
            "dest_node": "node20",
            "id": 4,
            "instance_uuid": "9128d044-7b61-403e-b766-7547076ff6c1",
            "new_instance_type_id": 6,
            "old_instance_type_id": 5,
            "source_compute": "compute10",
            "source_node": "node10",
            "status": "migrating",
            "migration_type": "resize",
            "updated_at": "2016-06-23T14:42:02.000000",
            "uuid": "42341d4b-346a-40d0-83c6-5f4f6892b650",
            "user_id": "78348f0e-97ee-4d70-ad34-189692673ea2",
            "project_id": "9842f0f7-1229-4355-afe7-15ebdbb8c3d8"
        }
    ],
    "migrations_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-migrations?limit=1&marker=42341d4b-346a-40d0-83c6-5f4f6892b650",
            "rel": "next"
        }
    ]
}

Server migrations (servers, migrations)

List, show, perform actions on and delete server migrations.

GET
/servers/{server_id}/migrations

List Migrations

Lists in-progress live migrations for a given server.

Note

Microversion 2.23 or greater is required for this API.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

migrations

body

array

The list of server migration objects.

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.

dest_compute

body

string

The target compute for a migration.

dest_host

body

string

The target host for a migration.

dest_node

body

string

The target node for a migration.

disk_processed_bytes

body

integer

The amount of disk, in bytes, that has been processed during the migration.

disk_remaining_bytes

body

integer

The amount of disk, in bytes, that still needs to be migrated.

disk_total_bytes

body

integer

The total amount of disk, in bytes, that needs to be migrated.

id

body

integer

The ID of the server migration.

memory_processed_bytes

body

integer

The amount of memory, in bytes, that has been processed during the migration.

memory_remaining_bytes

body

integer

The amount of memory, in bytes, that still needs to be migrated.

memory_total_bytes

body

integer

The total amount of memory, in bytes, that needs to be migrated.

server_uuid

body

string

The UUID of the server.

source_compute

body

string

The source compute for a migration.

source_node

body

string

The source node for a migration.

status

body

string

The current status of the migration.

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.

uuid

body

string

The UUID of the migration.

New in version 2.59

user_id

body

string

The ID of the user which initiated the server migration. The value may be null for older migration records.

New in version 2.80

project_id

body

string

The ID of the project which initiated the server migration. The value may be null for older migration records.

New in version 2.80

Example List Migrations (2.80)

{
    "migrations": [
        {
            "created_at": "2016-01-29T13:42:02.000000",
            "dest_compute": "compute2",
            "dest_host": "1.2.3.4",
            "dest_node": "node2",
            "id": 1,
            "server_uuid": "4cfba335-03d8-49b2-8c52-e69043d1e8fe",
            "source_compute": "compute1",
            "source_node": "node1",
            "status": "running",
            "memory_total_bytes": 123456,
            "memory_processed_bytes": 12345,
            "memory_remaining_bytes": 111111,
            "disk_total_bytes": 234567,
            "disk_processed_bytes": 23456,
            "disk_remaining_bytes": 211111,
            "updated_at": "2016-01-29T13:42:02.000000",
            "uuid": "12341d4b-346a-40d0-83c6-5f4f6892b650",
            "user_id": "8dbaa0f0-ab95-4ffe-8cb4-9c89d2ac9d24",
            "project_id": "5f705771-3aa9-4f4c-8660-0d9522ffdbea"
        }
    ]
}
GET
/servers/{server_id}/migrations/{migration_id}

Show Migration Details

Show details for an in-progress live migration for a given server.

Note

Microversion 2.23 or greater is required for this API.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

migration_id

path

integer

The ID of the server migration.

Response

Name

In

Type

Description

migration

body

object

The server migration object.

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.

dest_compute

body

string

The target compute for a migration.

dest_host

body

string

The target host for a migration.

dest_node

body

string

The target node for a migration.

disk_processed_bytes

body

integer

The amount of disk, in bytes, that has been processed during the migration.

disk_remaining_bytes

body

integer

The amount of disk, in bytes, that still needs to be migrated.

disk_total_bytes

body

integer

The total amount of disk, in bytes, that needs to be migrated.

id

body

integer

The ID of the server migration.

memory_processed_bytes

body

integer

The amount of memory, in bytes, that has been processed during the migration.

memory_remaining_bytes

body

integer

The amount of memory, in bytes, that still needs to be migrated.

memory_total_bytes

body

integer

The total amount of memory, in bytes, that needs to be migrated.

server_uuid

body

string

The UUID of the server.

source_compute

body

string

The source compute for a migration.

source_node

body

string

The source node for a migration.

status

body

string

The current status of the migration.

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.

uuid

body

string

The UUID of the migration.

New in version 2.59

user_id

body

string

The ID of the user which initiated the server migration. The value may be null for older migration records.

New in version 2.80

project_id

body

string

The ID of the project which initiated the server migration. The value may be null for older migration records.

New in version 2.80

Example Show Migration Details (2.80)

{
    "migration": {
        "created_at": "2016-01-29T13:42:02.000000",
        "dest_compute": "compute2",
        "dest_host": "1.2.3.4",
        "dest_node": "node2",
        "id": 1,
        "server_uuid": "4cfba335-03d8-49b2-8c52-e69043d1e8fe",
        "source_compute": "compute1",
        "source_node": "node1",
        "status": "running",
        "memory_total_bytes": 123456,
        "memory_processed_bytes": 12345,
        "memory_remaining_bytes": 111111,
        "disk_total_bytes": 234567,
        "disk_processed_bytes": 23456,
        "disk_remaining_bytes": 211111,
        "updated_at": "2016-01-29T13:42:02.000000",
        "uuid": "12341d4b-346a-40d0-83c6-5f4f6892b650",
        "user_id": "8dbaa0f0-ab95-4ffe-8cb4-9c89d2ac9d24",
        "project_id": "5f705771-3aa9-4f4c-8660-0d9522ffdbea"
    }
}
POST
/servers/{server_id}/migrations/{migration_id}/action

Force Migration Complete Action (force_complete Action)

Force an in-progress live migration for a given server to complete.

Specify the force_complete action in the request body.

Note

Microversion 2.22 or greater is required for this API.

Note

Not all compute back ends support forcefully completing an in-progress live migration.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Preconditions

The server OS-EXT-STS:vm_state value must be active and the server OS-EXT-STS:task_state value must be migrating.

If the server is locked, you must have administrator privileges to force the completion of the server migration.

The migration status must be running.

Asynchronous Postconditions

After you make this request, you typically must keep polling the server status to determine whether the request succeeded.

Troubleshooting

If the server status remains MIGRATING for an inordinate amount of time, the request may have failed. Ensure you meet the preconditions and run the request again. If the request fails again, investigate the compute back end. More details can be found in the admin guide.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

migration_id

path

integer

The ID of the server migration.

force_complete

body

none

The action to force an in-progress live migration to complete.

Example Force Migration Complete (force_complete Action)

{
    "force_complete": null
}

Response

There is no body content for the response of a successful POST operation.

DELETE
/servers/{server_id}/migrations/{migration_id}

Delete (Abort) Migration

Abort an in-progress live migration.

Note

Microversion 2.24 or greater is required for this API.

Note

With microversion 2.65 or greater, you can abort live migrations also in queued and preparing status.

Note

Not all compute back ends support aborting an in-progress live migration.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Preconditions

The server OS-EXT-STS:task_state value must be migrating.

If the server is locked, you must have administrator privileges to force the completion of the server migration.

For microversions from 2.24 to 2.64 the migration status must be running, for microversion 2.65 and greater, the migration status can also be queued and preparing.

Asynchronous Postconditions

After you make this request, you typically must keep polling the server status to determine whether the request succeeded. You may also monitor the migration using:

GET /servers/{server_id}/migrations/{migration_id}

Troubleshooting

If the server status remains MIGRATING for an inordinate amount of time, the request may have failed. Ensure you meet the preconditions and run the request again. If the request fails again, investigate the compute back end.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

migration_id

path

integer

The ID of the server migration.

Response

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

Quota sets (os-quota-sets)

Permits administrators, depending on policy settings, to view default quotas, view details for quotas, revert quotas to defaults, and update the quotas for a project or a project and user.

GET
/os-quota-sets/{tenant_id}

Show A Quota

Show the quota for a project or a project and a user.

Normal response codes: 200

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

  • 400 - BadRequest - the tenant_id is not valid in your cloud, perhaps because it was typoed.

Request

Name

In

Type

Description

tenant_id

path

string

The UUID of the tenant in a multi-tenancy cloud.

user_id (Optional)

query

string

ID of user to list the quotas for.

Response

Name

In

Type

Description

quota_set

body

object

A quota_set object.

cores

body

integer

The number of allowed server cores for each tenant.

id

body

string

The UUID of the tenant/user the quotas listed for.

instances

body

integer

The number of allowed servers for each tenant.

key_pairs

body

integer

The number of allowed key pairs for each user.

metadata_items

body

integer

The number of allowed metadata items for each server.

ram

body

integer

The amount of allowed server RAM, in MiB, for each tenant.

server_groups

body

integer

The number of allowed server groups for each tenant.

server_group_members

body

integer

The number of allowed members for each server group.

fixed_ips

body

integer

The number of allowed fixed IP addresses for each tenant. Must be equal to or greater than the number of allowed servers.

Available until version 2.35

floating_ips

body

integer

The number of allowed floating IP addresses for each tenant.

Available until version 2.35

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.35

security_group_rules

body

integer

The number of allowed rules for each security group.

Available until version 2.35

security_groups

body

integer

The number of allowed security groups for each tenant.

Available until version 2.35

injected_file_content_bytes

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

injected_file_path_bytes

body

integer

The number of allowed bytes for each injected file path.

Available until version 2.56

injected_files

body

integer

The number of allowed injected files for each tenant.

Available until version 2.56

Example Show A Quota: JSON response

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": -1,
        "id": "fake_tenant",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": -1,
        "security_groups": -1,
        "server_groups": 10,
        "server_group_members": 10
    }
}
PUT
/os-quota-sets/{tenant_id}

Update Quotas

Update the quotas for a project or a project and a user.

Users can force the update even if the quota has already been used and the reserved quota exceeds the new quota. To force the update, specify the "force": True attribute in the request body, the default value is false.

Normal response codes: 200

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

  • 400 - BadRequest - the tenant_id is not valid in your cloud, perhaps because it was typoed.

Request

Name

In

Type

Description

tenant_id

path

string

The UUID of the tenant in a multi-tenancy cloud.

user_id (Optional)

query

string

ID of user to set the quotas for.

quota_set

body

object

A quota_set object.

force (Optional)

body

boolean

You can force the update even if the quota has already been used and the reserved quota exceeds the new quota. To force the update, specify the "force": "True". Default is False.

cores (Optional)

body

integer

The number of allowed server cores for each tenant.

instances (Optional)

body

integer

The number of allowed servers for each tenant.

key_pairs (Optional)

body

integer

The number of allowed key pairs for each user.

metadata_items (Optional)

body

integer

The number of allowed metadata items for each server.

ram (Optional)

body

integer

The amount of allowed server RAM, in MiB, for each tenant.

server_groups (Optional)

body

integer

The number of allowed server groups for each tenant.

server_group_members (Optional)

body

integer

The number of allowed members for each server group.

fixed_ips (Optional)

body

integer

The number of allowed fixed IP addresses for each tenant. Must be equal to or greater than the number of allowed servers.

Available until version 2.35

floating_ips (Optional)

body

integer

The number of allowed floating IP addresses for each tenant.

Available until version 2.35

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.35

security_group_rules (Optional)

body

integer

The number of allowed rules for each security group.

Available until version 2.35

security_groups (Optional)

body

integer

The number of allowed security groups for each tenant.

Available until version 2.35

injected_file_content_bytes (Optional)

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

injected_file_path_bytes (Optional)

body

integer

The number of allowed bytes for each injected file path.

Available until version 2.56

injected_files (Optional)

body

integer

The number of allowed injected files for each tenant.

Available until version 2.56

Example Update Quotas: JSON request

{
    "quota_set": {
        "cores": 45
    }
}

Example Update Quotas with the optional ``force`` attribute: JSON request

{
    "quota_set": {
        "force": "True",
        "instances": 45
    }
}

Response

Name

In

Type

Description

quota_set

body

object

A quota_set object.

cores

body

integer

The number of allowed server cores for each tenant.

instances

body

integer

The number of allowed servers for each tenant.

key_pairs

body

integer

The number of allowed key pairs for each user.

metadata_items

body

integer

The number of allowed metadata items for each server.

ram

body

integer

The amount of allowed server RAM, in MiB, for each tenant.

server_groups

body

integer

The number of allowed server groups for each tenant.

server_group_members

body

integer

The number of allowed members for each server group.

fixed_ips

body

integer

The number of allowed fixed IP addresses for each tenant. Must be equal to or greater than the number of allowed servers.

Available until version 2.35

floating_ips

body

integer

The number of allowed floating IP addresses for each tenant.

Available until version 2.35

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.35

security_group_rules

body

integer

The number of allowed rules for each security group.

Available until version 2.35

security_groups

body

integer

The number of allowed security groups for each tenant.

Available until version 2.35

injected_file_content_bytes

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

injected_file_path_bytes

body

integer

The number of allowed bytes for each injected file path.

Available until version 2.56

injected_files

body

integer

The number of allowed injected files for each tenant.

Available until version 2.56

Example Update Quotas: JSON response

{
    "quota_set": {
        "cores": 45,
        "fixed_ips": -1,
        "floating_ips": -1,
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": -1,
        "security_groups": -1,
        "server_groups": 10,
        "server_group_members": 10
    }
}
DELETE
/os-quota-sets/{tenant_id}

Revert Quotas To Defaults

Reverts the quotas to default values for a project or a project and a user.

To revert quotas for a project and a user, specify the user_id query parameter.

Normal response codes: 202

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

Request

Name

In

Type

Description

tenant_id

path

string

The UUID of the tenant in a multi-tenancy cloud.

user_id (Optional)

query

string

ID of user to delete quotas for.

Response

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

GET
/os-quota-sets/{tenant_id}/defaults

List Default Quotas For Tenant

Lists the default quotas for a project.

Normal response codes: 200

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

Request

Name

In

Type

Description

tenant_id

path

string

The UUID of the tenant in a multi-tenancy cloud.

Response

Name

In

Type

Description

quota_set

body

object

A quota_set object.

cores

body

integer

The number of allowed server cores for each tenant.

id

body

string

The UUID of the tenant/user the quotas listed for.

instances

body

integer

The number of allowed servers for each tenant.

key_pairs

body

integer

The number of allowed key pairs for each user.

metadata_items

body

integer

The number of allowed metadata items for each server.

ram

body

integer

The amount of allowed server RAM, in MiB, for each tenant.

server_groups

body

integer

The number of allowed server groups for each tenant.

server_group_members

body

integer

The number of allowed members for each server group.

fixed_ips

body

integer

The number of allowed fixed IP addresses for each tenant. Must be equal to or greater than the number of allowed servers.

Available until version 2.35

floating_ips

body

integer

The number of allowed floating IP addresses for each tenant.

Available until version 2.35

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.35

security_group_rules

body

integer

The number of allowed rules for each security group.

Available until version 2.35

security_groups

body

integer

The number of allowed security groups for each tenant.

Available until version 2.35

injected_file_content_bytes

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

injected_file_path_bytes

body

integer

The number of allowed bytes for each injected file path.

Available until version 2.56

injected_files

body

integer

The number of allowed injected files for each tenant.

Available until version 2.56

Example List Default Quotas For Tenant: JSON response

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": -1,
        "id": "fake_tenant",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": -1,
        "security_groups": -1,
        "server_groups": 10,
        "server_group_members": 10
    }
}
GET
/os-quota-sets/{tenant_id}/detail

Show The Detail of Quota

Show the detail of quota for a project or a project and a user.

To show a quota for a project and a user, specify the user_id query parameter.

Normal response codes: 200

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

  • 400 - BadRequest - the {tenant_id} is not valid in your cloud, perhaps because it was typoed.

Request

Name

In

Type

Description

tenant_id

path

string

The UUID of the tenant in a multi-tenancy cloud.

user_id (Optional)

query

string

ID of user to list the quotas for.

Response

Name

In

Type

Description

quota_set

body

object

A quota_set object.

cores

body

object

The object of detailed cores quota, including in_use, limit and reserved number of cores.

id

body

string

The UUID of the tenant/user the quotas listed for.

instances

body

object

The object of detailed servers quota, including in_use, limit and reserved number of instances.

key_pairs

body

object

The object of detailed key pairs quota, including in_use, limit and reserved number of key pairs.

Note

in_use field value for keypair quota details is always zero. In Nova, key_pairs are a user-level resource, not a project- level resource, so for legacy reasons, the keypair in-use information is not counted.

metadata_items

body

object

The object of detailed key metadata items quota, including in_use, limit and reserved number of metadata items.

ram

body

object

The object of detailed key ram quota, including in_use, limit and reserved number of ram.

server_groups

body

object

The object of detailed server groups, including in_use, limit and reserved number of server groups.

server_group_members

body

object

The object of detailed server group members, including in_use, limit and reserved number of server group members.

fixed_ips

body

object

The object of detailed fixed ips quota, including in_use, limit and reserved number of fixed ips.

Available until version 2.35

floating_ips

body

object

The object of detailed floating ips quota, including in_use, limit and reserved number of floating ips.

Available until version 2.35

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.35

security_group_rules

body

object

The object of detailed security group rules quota, including in_use, limit and reserved number of security group rules.

Available until version 2.35

security_groups

body

object

The object of detailed security groups, including in_use, limit and reserved number of security groups.

Available until version 2.35

injected_file_content_bytes

body

object

The object of detailed injected file content bytes quota, including in_use, limit and reserved number of injected file content bytes.

Available until version 2.56

injected_file_path_bytes

body

object

The object of detailed injected file path bytes quota, including in_use, limit and reserved number of injected file path bytes.

Available until version 2.56

injected_files

body

object

The object of detailed injected files quota, including in_use, limit and reserved number of injected files.

Available until version 2.56

Example Show A Quota: JSON response

{
    "quota_set": {
        "cores": {
            "in_use": 0,
            "limit": 20,
            "reserved": 0
        },
        "fixed_ips": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "floating_ips": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "id": "fake_tenant",
        "injected_file_content_bytes": {
            "in_use": 0,
            "limit": 10240,
            "reserved": 0
        },
        "injected_file_path_bytes": {
            "in_use": 0,
            "limit": 255,
            "reserved": 0
        },
        "injected_files": {
            "in_use": 0,
            "limit": 5,
            "reserved": 0
        },
        "instances": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "key_pairs": {
            "in_use": 0,
            "limit": 100,
            "reserved": 0
        },
        "metadata_items": {
            "in_use": 0,
            "limit": 128,
            "reserved": 0
        },
        "ram": {
            "in_use": 0,
            "limit": 51200,
            "reserved": 0
        },
        "security_group_rules": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "security_groups": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "server_group_members": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "server_groups": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        }
    }
}

Quota class sets (os-quota-class-sets)

Show, Create or Update the quotas for a Quota Class. Nova supports implicit ‘default’ Quota Class only.

Note

Once a default limit is set via the default quota class via the API, that takes precedence over any changes to that resource limit in the configuration options. In other words, once you’ve changed things via the API, you either have to keep those synchronized with the configuration values or remove the default limit from the database manually as there is no REST API for removing quota class values from the database.

For Example: If you updated default quotas for instances, to 20, but didn’t change quota_instances in your nova.conf, you’d now have default quota for instances as 20 for all projects. If you then change quota_instances=5 in nova.conf, but didn’t update the default quota class via the API, you’ll still have a default quota of 20 for instances regardless of nova.conf. Refer: Quotas for more details.

Warning

There is a bug in the v2.1 API until microversion 2.49 and the legacy v2 compatible API which does not return the server_groups and server_group_members quotas in GET and PUT os-quota-class-sets API response, whereas the v2 API used to return those keys in the API response. There is workaround to get the server_groups and server_group_members quotas using “List Default Quotas For Tenant” API in Quota sets (os-quota-sets) but that is per project quota. This issue is fixed in microversion 2.50, here onwards server_groups and server_group_members keys are returned in API response body.

GET
/os-quota-class-sets/{id}

Show the quota for Quota Class

Show the quota for the Quota Class.

Normal response codes: 200

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

Request

Name

In

Type

Description

id

path

string

The ID of the quota class. Nova supports the default Quota Class only.

Response

Name

In

Type

Description

quota_class_set

body

object

A quota_class_set object.

cores

body

integer

The number of allowed server cores for the quota class.

id

body

string

The ID of the quota class. Nova supports the default Quota Class only.

instances

body

integer

The number of allowed servers for the quota class.

key_pairs

body

integer

The number of allowed key pairs for the quota class.

metadata_items

body

integer

The number of allowed metadata items for each server.

ram

body

integer

The amount of allowed instance RAM, in MiB, for the quota class.

fixed_ips

body

integer

The number of allowed fixed IP addresses for the quota class. Must be equal to or greater than the number of allowed servers.

Available until version 2.49

floating_ips

body

integer

The number of allowed floating IP addresses for the quota class.

Available until version 2.49

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.49

security_group_rules

body

integer

The number of allowed rules for each security group.

Available until version 2.49

security_groups

body

integer

The number of allowed security groups for the quota class.

Available until version 2.49

server_groups

body

integer

The number of allowed server groups for the quota class.

New in version 2.50

server_group_members

body

integer

The number of allowed members for each server group.

New in version 2.50

injected_file_content_bytes

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

injected_file_path_bytes

body

integer

The number of allowed bytes for each injected file path.

Available until version 2.56

injected_files

body

integer

The number of allowed injected files for the quota class.

Available until version 2.56

Example Show A Quota Class: JSON response(2.50)

{
    "quota_class_set": {
        "cores": 20,
        "id": "test_class",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "server_groups": 10,
        "server_group_members": 10
    }
}
PUT
/os-quota-class-sets/{id}

Create or Update Quotas for Quota Class

Update the quotas for the Quota Class.

If the requested Quota Class is not found in the DB, then the API will create the one. Only ‘default’ quota class is valid and used to set the default quotas, all other quota class would not be used anywhere.

Normal response codes: 200

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

Request

Name

In

Type

Description

id

path

string

The ID of the quota class. Nova supports the default Quota Class only.

quota_class_set

body

object

A quota_class_set object.

cores (Optional)

body

integer

The number of allowed server cores for the quota class.

instances (Optional)

body

integer

The number of allowed servers for the quota class.

key_pairs (Optional)

body

integer

The number of allowed key pairs for the quota class.

metadata_items (Optional)

body

integer

The number of allowed metadata items for each server.

ram (Optional)

body

integer

The amount of allowed instance RAM, in MiB, for the quota class.

server_groups (Optional)

body

integer

The number of allowed server groups for the quota class.

server_group_members (Optional)

body

integer

The number of allowed members for each server group.

fixed_ips (Optional)

body

integer

The number of allowed fixed IP addresses for the quota class. Must be equal to or greater than the number of allowed servers.

Available until version 2.49

floating_ips (Optional)

body

integer

The number of allowed floating IP addresses for the quota class.

Available until version 2.49

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.49

security_group_rules (Optional)

body

integer

The number of allowed rules for each security group.

Available until version 2.49

security_groups (Optional)

body

integer

The number of allowed security groups for the quota class.

Available until version 2.49

injected_file_content_bytes (Optional)

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

injected_file_path_bytes (Optional)

body

integer

The number of allowed bytes for each injected file path.

Available until version 2.56

injected_files (Optional)

body

integer

The number of allowed injected files for the quota class.

Available until version 2.56

Example Update Quotas: JSON request(2.50)

{
    "quota_class_set": {
        "instances": 50,
        "cores": 50,
        "ram": 51200,
        "metadata_items": 128,
        "injected_files": 5,
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "key_pairs": 100,
        "server_groups": 10,
        "server_group_members": 10
    }
}

Response

Name

In

Type

Description

quota_class_set

body

object

A quota_class_set object.

cores

body

integer

The number of allowed server cores for the quota class.

instances

body

integer

The number of allowed servers for the quota class.

key_pairs

body

integer

The number of allowed key pairs for the quota class.

metadata_items

body

integer

The number of allowed metadata items for each server.

ram

body

integer

The amount of allowed instance RAM, in MiB, for the quota class.

fixed_ips

body

integer

The number of allowed fixed IP addresses for the quota class. Must be equal to or greater than the number of allowed servers.

Available until version 2.49

floating_ips

body

integer

The number of allowed floating IP addresses for the quota class.

Available until version 2.49

networks (Optional)

body

integer

The number of private networks that can be created per project.

Available until version 2.49

security_group_rules

body

integer

The number of allowed rules for each security group.

Available until version 2.49

security_groups

body

integer

The number of allowed security groups for the quota class.

Available until version 2.49

server_groups

body

integer

The number of allowed server groups for the quota class.

New in version 2.50

server_group_members

body

integer

The number of allowed members for each server group.

New in version 2.50

injected_file_content_bytes

body

integer

The number of allowed bytes of content for each injected file.

Available until version 2.56

injected_file_path_bytes

body

integer

The number of allowed bytes for each injected file path.

Available until version 2.56

injected_files

body

integer

The number of allowed injected files for the quota class.

Available until version 2.56

Example Update Quotas: JSON response(2.50)

{
    "quota_class_set": {
        "cores": 50,
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 50,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "server_groups": 10,
        "server_group_members": 10
    }
}

Server groups (os-server-groups)

Lists, shows information for, creates, and deletes server groups.

GET
/os-server-groups

List Server Groups

Lists all server groups for the tenant.

Administrative users can use the all_projects query parameter to list all server groups for all projects.

Normal response codes: 200

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

Request

Name

In

Type

Description

all_projects (Optional)

query

string

Administrator only. Lists server groups for all projects. For example:

GET /os-server-groups?all_projects=True

If you specify a tenant ID for a non-administrative user with this query parameter, the call lists all server groups for the tenant, or project, rather than for all projects. Value of this query parameter is not checked, only presence is considered as request for all projects.

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name

In

Type

Description

server_groups

body

array

The list of existing server groups.

id

body

string

The UUID of the server group.

name

body

string

The name 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 hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

Available until version 2.63

members

body

array

A list of members in the server group.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes. It’s always empty and only used for keeping compatibility.

Available until version 2.63

project_id

body

string

The project ID who owns the server group.

New in version 2.13

user_id

body

string

The user ID who owns the server group.

New in version 2.13

policy

body

string

The policy field represents the name of the policy. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

New in version 2.64

rules

body

object

The rules field, which is a dict, can be applied to the policy. Currently, only the max_server_per_host rule is supported for the anti-affinity policy. The max_server_per_host rule allows specifying how many members of the anti-affinity group can reside on the same compute host. If not specified, only one member from the same anti-affinity group can reside on a given host.

New in version 2.64

Example List Server Groups (2.64): JSON response

{
    "server_groups": [
        {
            "id": "616fb98f-46ca-475e-917e-2563e5a8cd19",
            "name": "test",
            "policy": "anti-affinity",
            "rules": {"max_server_per_host": 3},
            "members": [],
            "project_id": "6f70656e737461636b20342065766572",
            "user_id": "fake"
        }
    ]
}
POST
/os-server-groups

Create Server Group

Creates a server group.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_group

body

object

The server group object.

name

body

string

The name 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 hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

Available until version 2.63

policy

body

string

The policy field represents the name of the policy. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

New in version 2.64

rules (Optional)

body

object

The rules field, which is a dict, can be applied to the policy. Currently, only the max_server_per_host rule is supported for the anti-affinity policy. The max_server_per_host rule allows specifying how many members of the anti-affinity group can reside on the same compute host. If not specified, only one member from the same anti-affinity group can reside on a given host. Requesting policy rules with any other policy than anti-affinity will be 400.

New in version 2.64

Example Create Server Group (2.64): JSON request

{
    "server_group": {
        "name": "test",
        "policy": "anti-affinity",
        "rules": {"max_server_per_host": 3}
    }
}

Response

Name

In

Type

Description

server_group

body

object

The server group object.

id

body

string

The UUID of the server group.

name

body

string

The name 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 hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

Available until version 2.63

members

body

array

A list of members in the server group.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes. It’s always empty and only used for keeping compatibility.

Available until version 2.63

project_id

body

string

The project ID who owns the server group.

New in version 2.13

user_id

body

string

The user ID who owns the server group.

New in version 2.13

policy

body

string

The policy field represents the name of the policy. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

New in version 2.64

rules

body

object

The rules field, which is a dict, can be applied to the policy. Currently, only the max_server_per_host rule is supported for the anti-affinity policy. The max_server_per_host rule allows specifying how many members of the anti-affinity group can reside on the same compute host. If not specified, only one member from the same anti-affinity group can reside on a given host.

New in version 2.64

Example Create Server Group (2.64): JSON response

{
    "server_group": {
        "id": "5bbcc3c4-1da2-4437-a48a-66f15b1b13f9",
        "name": "test",
        "policy": "anti-affinity",
        "rules": {"max_server_per_host": 3},
        "members": [],
        "project_id": "6f70656e737461636b20342065766572",
        "user_id": "fake"
    }
}
GET
/os-server-groups/{server_group_id}

Show Server Group 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_id

path

string

The UUID of the server group.

Response

Name

In

Type

Description

server_group

body

object

The server group object.

id

body

string

The UUID of the server group.

name

body

string

The name 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 hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure. This policy was added in microversion 2.15.

Available until version 2.63

members

body

array

A list of members in the server group.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes. It’s always empty and only used for keeping compatibility.

Available until version 2.63

project_id

body

string

The project ID who owns the server group.

New in version 2.13

user_id

body

string

The user ID who owns the server group.

New in version 2.13

policy

body

string

The policy field represents the name of the policy. The current valid policy names are:

  • anti-affinity - servers in this group must be scheduled to different hosts.

  • affinity - servers in this group must be scheduled to the same host.

  • soft-anti-affinity - servers in this group should be scheduled to different hosts if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

  • soft-affinity - servers in this group should be scheduled to the same host if possible, but if not possible then they should still be scheduled instead of resulting in a build failure.

New in version 2.64

rules

body

object

The rules field, which is a dict, can be applied to the policy. Currently, only the max_server_per_host rule is supported for the anti-affinity policy. The max_server_per_host rule allows specifying how many members of the anti-affinity group can reside on the same compute host. If not specified, only one member from the same anti-affinity group can reside on a given host.

New in version 2.64

Example Show Server Group Details (2.64): JSON response

{
    "server_group": {
        "id": "5bbcc3c4-1da2-4437-a48a-66f15b1b13f9",
        "name": "test",
        "policy": "anti-affinity",
        "rules": {"max_server_per_host": 3},
        "members": [],
        "project_id": "6f70656e737461636b20342065766572",
        "user_id": "fake"
    }
}
DELETE
/os-server-groups/{server_group_id}

Delete Server Group

Deletes a server group.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_group_id

path

string

The UUID of the server group.

Response

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

Server tags (servers, tags)

Lists tags, creates, replaces or deletes one or more tags for a server, checks the existence of a tag for a server.

Available since version 2.26

Tags have the following restrictions:

  • Tag is a Unicode bytestring no longer than 60 characters.

  • Tag is a non-empty string.

  • ‘/’ is not allowed to be in a tag name

  • Comma is not allowed to be in a tag name in order to simplify requests that specify lists of tags

  • All other characters are allowed to be in a tag name

  • Each server can have up to 50 tags.

GET
/servers/{server_id}/tags

List Tags

Lists all tags for a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

tags

body

array

A list of tags. The maximum count of tags in this list is 50.

Example List Tags:

{
    "tags": ["tag1", "tag2"]
}
PUT
/servers/{server_id}/tags

Replace Tags

Replaces all tags on specified server with the new set of tags.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

tags

body

array

A list of tags. The maximum count of tags in this list is 50.

Example Replace Tags:

{
    "tags": ["tag1", "tag2"]
}

Response

Name

In

Type

Description

tags

body

array

A list of tags. The maximum count of tags in this list is 50.

Example Replace Tags:

{
    "tags": ["tag1", "tag2"]
}
DELETE
/servers/{server_id}/tags

Delete All Tags

Deletes all tags from the specified server.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

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

GET
/servers/{server_id}/tags/{tag}

Check Tag Existence

Checks tag existence on the server. If tag exists response with 204 status code will be returned. Otherwise returns 404.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

tag

path

string

The tag as a string.

PUT
/servers/{server_id}/tags/{tag}

Add a Single Tag

Adds a single tag to the server if server has no specified tag. Response code in this case is 201.

If the server has specified tag just returns 204.

Normal response codes: 201, 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

tag

path

string

The tag as a string.

Response

Name

In

Type

Description

Location

header

string

The location of the tag. It’s individual tag URL which can be used for checking the existence of the tag on the server or deleting the tag from the server.

DELETE
/servers/{server_id}/tags/{tag}

Delete a Single Tag

Deletes a single tag from the specified server.

Normal response codes: 204

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

tag

path

string

The tag as a string.

Response

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

Compute services (os-services)

Lists all running Compute services in a region, enables or disables scheduling for a Compute service and deletes a Compute service.

For an overview of Compute services, see OpenStack Compute.

GET
/os-services

List Compute Services

Lists all running Compute services.

Provides details why any services were disabled.

Note

Starting with microversion 2.69 if service details cannot be loaded due to a transient condition in the deployment like infrastructure failure, the response body for those unavailable compute services in the down cells will be missing keys. See handling down cells section of the Compute API guide for more information on the keys that would be returned in the partial constructs.

Normal response codes: 200

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

Request

Name

In

Type

Description

binary (Optional)

query

string

Filter the service list result by binary name of the service.

host (Optional)

query

string

Filter the service list result by the host name.

Response

Name

In

Type

Description

services

body

array

A list of service objects.

id

body

integer

The id of the service.

Available until version 2.52

id

body

string

The id of the service as a uuid.

New in version 2.53

binary

body

string

The binary name of the service.

disabled_reason

body

string

The reason for disabling a service.

host

body

string

The name of the host.

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.

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.

zone

body

string

The availability zone name.

forced_down

body

boolean

Whether or not this service was forced down manually by an administrator after the service was fenced. This value is useful to know that some 3rd party has verified the service should be marked down.

New in version 2.11

Example List Compute Services (v2.11)

{
    "services": [
        {
            "id": 1,
            "binary": "nova-scheduler",
            "disabled_reason": "test1",
            "host": "host1",
            "state": "up",
            "status": "disabled",
            "updated_at": "2012-10-29T13:42:02.000000",
            "forced_down": false,
            "zone": "internal"
        },
        {
            "id": 2,
            "binary": "nova-compute",
            "disabled_reason": "test2",
            "host": "host1",
            "state": "up",
            "status": "disabled",
            "updated_at": "2012-10-29T13:42:05.000000",
            "forced_down": false,
            "zone": "nova"
        },
        {
            "id": 3,
            "binary": "nova-scheduler",
            "disabled_reason": null,
            "host": "host2",
            "state": "down",
            "status": "enabled",
            "updated_at": "2012-09-19T06:55:34.000000",
            "forced_down": false,
            "zone": "internal"
        },
        {
            "id": 4,
            "binary": "nova-compute",
            "disabled_reason": "test4",
            "host": "host2",
            "state": "down",
            "status": "disabled",
            "updated_at": "2012-09-18T08:03:38.000000",
            "forced_down": false,
            "zone": "nova"
        }
    ]
}

Example List Compute Services (v2.69)

This is a sample response for the services from the non-responsive part of the deployment. The responses for the available service records will be normal without any missing keys.

{
    "services": [
        {
            "binary": "nova-compute",
            "host": "host1",
            "status": "UNKNOWN"
        },
        {
            "binary": "nova-compute",
            "host": "host2",
            "status": "UNKNOWN"
        }
    ]
}
PUT
/os-services/disable

Disable Scheduling For A Compute Service

Disables scheduling for a Compute service.

Specify the service by its host name and binary name.

Note

Starting with microversion 2.53 this API is superseded by PUT /os-services/{service_id}.

Normal response codes: 200

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

Request

Name

In

Type

Description

host

body

string

The name of the host.

binary

body

string

The binary name of the service.

Example Disable Scheduling For A Compute Service

{
    "host": "host1",
    "binary": "nova-compute"
}

Response

Name

In

Type

Description

service

body

object

Object representing a compute service.

binary

body

string

The binary name of the service.

host

body

string

The name of the host.

status

body

string

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

Example Disable Scheduling For A Compute Service

{
    "service": {
        "binary": "nova-compute",
        "host": "host1",
        "status": "disabled"
    }
}
PUT
/os-services/disable-log-reason

Disable Scheduling For A Compute Service and Log Disabled Reason

Disables scheduling for a Compute service and logs information to the Compute service table about why a Compute service was disabled.

Specify the service by its host name and binary name.

Note

Starting with microversion 2.53 this API is superseded by PUT /os-services/{service_id}.

Normal response codes: 200

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

Request

Name

In

Type

Description

host

body

string

The name of the host.

binary

body

string

The binary name of the service.

disabled_reason

body

string

The reason for disabling a service.

Example Disable Scheduling For A Compute Service and Log Disabled Reason

{
    "host": "host1",
    "binary": "nova-compute",
    "disabled_reason": "test2"
}

Response

Name

In

Type

Description

service

body

object

Object representing a compute service.

binary

body

string

The binary name of the service.

disabled_reason

body

string

The reason for disabling a service.

host

body

string

The name of the host.

status

body

string

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

Example Disable Scheduling For A Compute Service and Log Disabled Reason

{
    "service": {
        "binary": "nova-compute",
        "disabled_reason": "test2",
        "host": "host1",
        "status": "disabled"
    }
}
PUT
/os-services/enable

Enable Scheduling For A Compute Service

Enables scheduling for a Compute service.

Specify the service by its host name and binary name.

Note

Starting with microversion 2.53 this API is superseded by PUT /os-services/{service_id}.

Normal response codes: 200

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

Request

Name

In

Type

Description

host

body

string

The name of the host.

binary

body

string

The binary name of the service.

Example Enable Scheduling For A Compute Service

{
    "host": "host1",
    "binary": "nova-compute"
}

Response

Name

In

Type

Description

service

body

object

Object representing a compute service.

binary

body

string

The binary name of the service.

host

body

string

The name of the host.

status

body

string

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

Example Enable Scheduling For A Compute Service

{
    "service": {
        "binary": "nova-compute",
        "host": "host1",
        "status": "enabled"
    }
}
PUT
/os-services/force-down

Update Forced Down

Set or unset forced_down flag for the service. forced_down is a manual override to tell nova that the service in question has been fenced manually by the operations team (either hard powered off, or network unplugged). That signals that it is safe to proceed with evacuate or other operations that nova has safety checks to prevent for hosts that are up.

Warning

Setting a service forced down without completely fencing it will likely result in the corruption of VMs on that host.

Action force-down available as of microversion 2.11.

Specify the service by its host name and binary name.

Note

Starting with microversion 2.53 this API is superseded by PUT /os-services/{service_id}.

Normal response codes: 200

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

Request

Name

In

Type

Description

host

body

string

The name of the host.

binary

body

string

The binary name of the service.

forced_down

body

boolean

Whether or not this service was forced down manually by an administrator after the service was fenced. This value is useful to know that some 3rd party has verified the service should be marked down.

New in version 2.11

Example Update Forced Down

{
    "host": "host1",
    "binary": "nova-compute",
    "forced_down": true
}

Response

Name

In

Type

Description

service

body

object

Object representing a compute service.

binary

body

string

The binary name of the service.

host

body

string

The name of the host.

forced_down

body

boolean

Whether or not this service was forced down manually by an administrator after the service was fenced. This value is useful to know that some 3rd party has verified the service should be marked down.

New in version 2.11


Example Update Forced Down

{
    "service": {
        "binary": "nova-compute",
        "host": "host1",
        "forced_down": true
    }
}
PUT
/os-services/{service_id}

Update Compute Service

Update a compute service to enable or disable scheduling, including recording a reason why a compute service was disabled from scheduling. Set or unset the forced_down flag for the service. This operation is only allowed on services whose binary is nova-compute.

This API is available starting with microversion 2.53.

Normal response codes: 200

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

Request

Name

In

Type

Description

service_id

path

string

The id of the service as a uuid. This uniquely identifies the service in a multi-cell deployment.

status (Optional)

body

string

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

disabled_reason (Optional)

body

string

The reason for disabling a service. The minimum length is 1 and the maximum length is 255. This may only be requested with status=disabled.

forced_down (Optional)

body

boolean

forced_down is a manual override to tell nova that the service in question has been fenced manually by the operations team (either hard powered off, or network unplugged). That signals that it is safe to proceed with evacuate or other operations that nova has safety checks to prevent for hosts that are up.

Warning

Setting a service forced down without completely fencing it will likely result in the corruption of VMs on that host.

Example Disable Scheduling For A Compute Service (v2.53)

{
    "status": "disabled",
    "disabled_reason": "maintenance"
}

Example Enable Scheduling For A Compute Service (v2.53)

{
    "status": "enabled"
}

Example Update Forced Down (v2.53)

{
    "forced_down": true
}

Response

Name

In

Type

Description

service

body

object

Object representing a compute service.

id

body

string

The id of the service as a uuid.

binary

body

string

The binary name of the service.

disabled_reason

body

string

The reason for disabling a service.

host

body

string

The name of the host.

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.

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.

zone

body

string

The availability zone name.

forced_down

body

boolean

Whether or not this service was forced down manually by an administrator after the service was fenced. This value is useful to know that some 3rd party has verified the service should be marked down.

Example Disable Scheduling For A Compute Service (v2.53)

{
    "service": {
        "id": "e81d66a4-ddd3-4aba-8a84-171d1cb4d339",
        "binary": "nova-compute",
        "disabled_reason": "maintenance",
        "host": "host1",
        "state": "up",
        "status": "disabled",
        "updated_at": "2012-10-29T13:42:05.000000",
        "forced_down": false,
        "zone": "nova"
    }
}

Example Enable Scheduling For A Compute Service (v2.53)

{
    "service": {
        "id": "e81d66a4-ddd3-4aba-8a84-171d1cb4d339",
        "binary": "nova-compute",
        "disabled_reason": null,
        "host": "host1",
        "state": "up",
        "status": "enabled",
        "updated_at": "2012-10-29T13:42:05.000000",
        "forced_down": false,
        "zone": "nova"
    }
}

Example Update Forced Down (v2.53)

{
    "service": {
        "id": "e81d66a4-ddd3-4aba-8a84-171d1cb4d339",
        "binary": "nova-compute",
        "disabled_reason": "test2",
        "host": "host1",
        "state": "down",
        "status": "disabled",
        "updated_at": "2012-10-29T13:42:05.000000",
        "forced_down": true,
        "zone": "nova"
    }
}
DELETE
/os-services/{service_id}

Delete Compute Service

Deletes a service. If it’s a nova-compute service, then the corresponding host will be removed from all the host aggregates as well.

Attempts to delete a nova-compute service which is still hosting instances will result in a 409 HTTPConflict response. The instances will need to be migrated or deleted before a compute service can be deleted.

Similarly, attempts to delete a nova-compute service which is involved in in-progress migrations will result in a 409 HTTPConflict response. The migrations will need to be completed, for example confirming or reverting a resize, or the instances will need to be deleted before the compute service can be deleted.

Important

Be sure to stop the actual nova-compute process on the physical host before deleting the service with this API. Failing to do so can lead to the running service re-creating orphaned compute_nodes table records in the database.

Normal response codes: 204

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

Request

Name

In

Type

Description

service_id

path

integer

The id of the service.

Note

This may not uniquely identify a service in a multi-cell deployment.

Available until version 2.52

service_id

path

string

The id of the service as a uuid. This uniquely identifies the service in a multi-cell deployment.

New in version 2.53

Response

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

Usage reports (os-simple-tenant-usage)

Reports usage statistics of compute and storage resources periodically for an individual tenant or all tenants. The usage statistics will include all instances’ CPU, memory and local disk during a specific period.

Warning

The os-simple-tenant-usage will report usage statistics based on the latest flavor that is configured in the virtual machine (VM), and ignoring stop, pause, and other events that might have happened with the VM. Therefore, it uses the time the VM existed in the cloud environment to execute the usage accounting.

More information can be found at http://eavesdrop.openstack.org/meetings/nova/2020/nova.2020-12-03-16.00.log.txt, and https://review.opendev.org/c/openstack/nova/+/711113

Microversion 2.40 added pagination (and next links) to the usage statistics via optional limit and marker query parameters. If limit isn’t provided, the configurable max_limit will be used which currently defaults to 1000. Older microversions will not accept these new paging query parameters, but they will start to silently limit by max_limit.

/os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
/os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}

Note

A tenant’s usage statistics may span multiple pages when the number of instances exceeds limit, and API consumers will need to stitch together the aggregate results if they still want totals for all instances in a specific time window, grouped by tenant.

GET
/os-simple-tenant-usage

List Tenant Usage Statistics For All Tenants

Lists usage statistics for all tenants.

Normal response codes: 200

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

Request

Name

In

Type

Description

detailed (Optional)

query

integer

Specify the detailed=1 query parameter to get detail information (‘server_usages’ information).

end (Optional)

query

string

The ending time to calculate usage statistics on compute and storage resources. The date and time stamp format is any of the following ones:

CCYY-MM-DDThh:mm:ss

For example, 2015-08-27T09:49:58.

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

CCYY-MM-DD hh:mm:ss.NNNNNN

For example, 2015-08-27 09:49:58.123456. If you omit this parameter, the current time is used.

start (Optional)

query

string

The beginning time to calculate usage statistics on compute and storage resources. The date and time stamp format is any of the following ones:

CCYY-MM-DDThh:mm:ss

For example, 2015-08-27T09:49:58.

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

CCYY-MM-DD hh:mm:ss.NNNNNN

For example, 2015-08-27 09:49:58.123456. If you omit this parameter, the current time is used.

limit (Optional)

query

integer

Requests a page size of items. Calculate usage for the limited number of instances. Use the limit parameter to make an initial limited request and use the last-seen instance UUID from the response as the marker parameter value in a subsequent limited request.

New in version 2.40

marker (Optional)

query

string

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

New in version 2.40

Response

Name

In

Type

Description

tenant_usages

body

array

A list of the tenant usage objects.

start

body

string

The beginning time to calculate usage statistics on compute and storage resources. The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

stop

body

string

The ending time to calculate usage statistics on compute and storage resources. The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

total_hours

body

float

The total duration that servers exist (in hours).

total_local_gb_usage

body

float

Multiplying the server disk size (in GiB) by hours the server exists, and then adding that all together for each server.

total_memory_mb_usage

body

float

Multiplying the server memory size (in MiB) by hours the server exists, and then adding that all together for each server.

total_vcpus_usage

body

float

Multiplying the number of virtual CPUs of the server by hours the server exists, and then adding that all together for each server.

server_usages (Optional)

body

array

A list of the server usage objects.

server_usages.ended_at (Optional)

body

string

The date and time when the server was deleted.

The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456. If the server hasn’t been deleted yet, its value is null.

server_usages.flavor (Optional)

body

string

The display name of a flavor.

server_usages.hours (Optional)

body

float

The duration that the server exists (in hours).

server_usages.instance_id (Optional)

body

string

The UUID of the server.

server_usages.local_gb (Optional)

body

integer

The sum of the root disk size of the server and the ephemeral disk size of it (in GiB).

server_usages.memory_mb (Optional)

body

integer

The memory size of the server (in MiB).

server_usages.name (Optional)

body

string

The server name.

server_usages.started_at (Optional)

body

string

The date and time when the server was launched.

The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

server_usages.state (Optional)

body

string

The VM state.

server_usages.tenant_id (Optional)

body

string

The UUID of the tenant in a multi-tenancy cloud.

server_usages.uptime (Optional)

body

integer

The uptime of the server.

server_usages.vcpus (Optional)

body

integer

The number of virtual CPUs that the server uses.

tenant_usages_links (Optional)

body

array

Links pertaining to usage. See API Guide / Links and References for more info.

New in version 2.40

Example List Tenant Usage For All Tenants (v2.40): JSON response

If the detailed query parameter is not specified or is set to other than 1 (e.g. detailed=0), the response is as follows:

{
    "tenant_usages": [
        {
            "start": "2012-10-08T21:10:44.587336",
            "stop": "2012-10-08T22:10:44.587336",
            "tenant_id": "6f70656e737461636b20342065766572",
            "total_hours": 1.0,
            "total_local_gb_usage": 1.0,
            "total_memory_mb_usage": 512.0,
            "total_vcpus_usage": 1.0
        }
    ],
    "tenant_usages_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-simple-tenant-usage?end=2016-10-12+18%3A22%3A04.868106&limit=1&marker=1f1deceb-17b5-4c04-84c7-e0d4499c8fe0&start=2016-10-12+18%3A22%3A04.868106",
            "rel": "next"
        }
    ]
}

If the detailed query parameter is set to one (detailed=1), the response includes server_usages information for each tenant. The response is as follows:

{
    "tenant_usages": [
        {
            "start": "2012-10-08T20:10:44.587336",
            "stop": "2012-10-08T21:10:44.587336",
            "tenant_id": "6f70656e737461636b20342065766572",
            "total_hours": 1.0,
            "total_local_gb_usage": 1.0,
            "total_memory_mb_usage": 512.0,
            "total_vcpus_usage": 1.0,
            "server_usages": [
                {
                    "ended_at": null,
                    "flavor": "m1.tiny",
                    "hours": 1.0,
                    "instance_id": "1f1deceb-17b5-4c04-84c7-e0d4499c8fe0",
                    "local_gb": 1,
                    "memory_mb": 512,
                    "name": "instance-2",
                    "started_at": "2012-10-08T20:10:44.541277",
                    "state": "active",
                    "tenant_id": "6f70656e737461636b20342065766572",
                    "uptime": 3600,
                    "vcpus": 1
                }
            ]
        }
    ],
    "tenant_usages_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-simple-tenant-usage?detailed=1&end=2016-10-12+18%3A22%3A04.868106&limit=1&marker=1f1deceb-17b5-4c04-84c7-e0d4499c8fe0&start=2016-10-12+18%3A22%3A04.868106",
            "rel": "next"
        }
    ]
}
GET
/os-simple-tenant-usage/{tenant_id}

Show Usage Statistics For Tenant

Shows usage statistics for a tenant.

Normal response codes: 200

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

Request

Name

In

Type

Description

tenant_id

path

string

The UUID of the tenant in a multi-tenancy cloud.

end (Optional)

query

string

The ending time to calculate usage statistics on compute and storage resources. The date and time stamp format is any of the following ones:

CCYY-MM-DDThh:mm:ss

For example, 2015-08-27T09:49:58.

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

CCYY-MM-DD hh:mm:ss.NNNNNN

For example, 2015-08-27 09:49:58.123456. If you omit this parameter, the current time is used.

start (Optional)

query

string

The beginning time to calculate usage statistics on compute and storage resources. The date and time stamp format is any of the following ones:

CCYY-MM-DDThh:mm:ss

For example, 2015-08-27T09:49:58.

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

CCYY-MM-DD hh:mm:ss.NNNNNN

For example, 2015-08-27 09:49:58.123456. If you omit this parameter, the current time is used.

limit (Optional)

query

integer

Requests a page size of items. Calculate usage for the limited number of instances. Use the limit parameter to make an initial limited request and use the last-seen instance UUID from the response as the marker parameter value in a subsequent limited request.

New in version 2.40

marker (Optional)

query

string

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

New in version 2.40

Response

Name

In

Type

Description

tenant_usage

body

object

The tenant usage object.

server_usages

body

array

A list of the server usage objects.

server_usages.ended_at

body

string

The date and time when the server was deleted.

The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456. If the server hasn’t been deleted yet, its value is null.

server_usages.flavor

body

string

The display name of a flavor.

server_usages.hours

body

float

The duration that the server exists (in hours).

server_usages.instance_id

body

string

The UUID of the server.

server_usages.local_gb

body

integer

The sum of the root disk size of the server and the ephemeral disk size of it (in GiB).

server_usages.memory_mb

body

integer

The memory size of the server (in MiB).

server_usages.name

body

string

The server name.

server_usages.started_at

body

string

The date and time when the server was launched.

The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

server_usages.state

body

string

The VM state.

server_usages.tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

server_usages.uptime

body

integer

The uptime of the server.

server_usages.vcpus

body

integer

The number of virtual CPUs that the server uses.

start

body

string

The beginning time to calculate usage statistics on compute and storage resources. The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

stop

body

string

The ending time to calculate usage statistics on compute and storage resources. The date and time stamp format is as follows:

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, 2015-08-27T09:49:58.123456.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

total_hours

body

float

The total duration that servers exist (in hours).

total_local_gb_usage

body

float

Multiplying the server disk size (in GiB) by hours the server exists, and then adding that all together for each server.

total_memory_mb_usage

body

float

Multiplying the server memory size (in MiB) by hours the server exists, and then adding that all together for each server.

total_vcpus_usage

body

float

Multiplying the number of virtual CPUs of the server by hours the server exists, and then adding that all together for each server.

tenant_usage_links (Optional)

body

array

Links pertaining to usage. See API Guide / Links and References for more info.

New in version 2.40

Example Show Usage Details For Tenant (v2.40): JSON response

{
    "tenant_usage": {
        "server_usages": [
            {
                "ended_at": null,
                "flavor": "m1.tiny",
                "hours": 1.0,
                "instance_id": "1f1deceb-17b5-4c04-84c7-e0d4499c8fe0",
                "local_gb": 1,
                "memory_mb": 512,
                "name": "instance-2",
                "started_at": "2012-10-08T20:10:44.541277",
                "state": "active",
                "tenant_id": "6f70656e737461636b20342065766572",
                "uptime": 3600,
                "vcpus": 1
            }
        ],
        "start": "2012-10-08T20:10:44.587336",
        "stop": "2012-10-08T21:10:44.587336",
        "tenant_id": "6f70656e737461636b20342065766572",
        "total_hours": 1.0,
        "total_local_gb_usage": 1.0,
        "total_memory_mb_usage": 512.0,
        "total_vcpus_usage": 1.0
    },
    "tenant_usage_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-simple-tenant-usage/6f70656e737461636b20342065766572?end=2016-10-12+18%3A22%3A04.868106&limit=1&marker=1f1deceb-17b5-4c04-84c7-e0d4499c8fe0&start=2016-10-12+18%3A22%3A04.868106",
            "rel": "next"
        }
    ]
}

Create external events (os-server-external-events)

Warning

This is an admin level service API only designed to be used by other OpenStack services. The point of this API is to coordinate between Nova and Neutron, Nova and Cinder, Nova and Ironic (and potentially future services) on activities they both need to be involved in, such as network hotplugging.

Unless you are writing Neutron, Cinder or Ironic code you should not be using this API.

Creates one or more external events. The API dispatches each event to a server instance.

POST
/os-server-external-events

Run Events

Creates one or more external events, which the API dispatches to the host a server is assigned to. If the server is not currently assigned to a host the event will not be delivered.

You will receive back the list of events that you submitted, with an updated code and status indicating their level of success.

Normal response codes: 200, 207

A 200 will be returned if all events succeeded, 207 will be returned if any events could not be processed. The code attribute for the event will explain further what went wrong.

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

Note

Prior to the fix for bug 1855752, error response code 404 may be erroneously returned when all events failed.

Request

Name

In

Type

Description

events

body

array

List of external events to process.

name

body

string

The event name. A valid value is:

  • network-changed

  • network-vif-plugged

  • network-vif-unplugged

  • network-vif-deleted

  • volume-extended (since microversion 2.51)

  • power-update (since microversion 2.76)

  • accelerator-request-bound (since microversion 2.82)

server_uuid

body

string

The UUID of the server instance to which the API dispatches the event. You must assign this instance to a host. Otherwise, this call does not dispatch the event to the instance.

status (Optional)

body

string

The event status. A valid value is failed, completed, or in-progress. Default is completed.

tag (Optional)

body

string

A string value that identifies the event. Certain types of events require specific tags:

  • For the accelerator-request-bound event, the tag must be the accelerator request UUID.

  • For the power-update event the tag must be either be POWER_ON or POWER_OFF.

  • For the volume-extended event the tag must be the volume id.

Example Run Events

{
    "events": [
        {
            "name": "test-event",
            "tag": "foo",
            "status": "completed",
            "server_uuid": "3df201cf-2451-44f2-8d25-a4ca826fc1f3"
        }
    ]
}

Response

Name

In

Type

Description

events

body

array

List of external events to process.

code

body

string

The HTTP response code for the event. The following codes are currently used:

  • 200 - successfully submitted event

  • 400 - the request is missing required parameter

  • 404 - the instance specified by server_uuid was not found

  • 422 - no host was found for the server specified by server_uuid,

    so there is no route to this server.

name

body

string

The event name. A valid value is:

  • network-changed

  • network-vif-plugged

  • network-vif-unplugged

  • network-vif-deleted

  • volume-extended (since microversion 2.51)

  • power-update (since microversion 2.76)

  • accelerator-request-bound (since microversion 2.82)

server_uuid

body

string

The UUID of the server instance to which the API dispatches the event. You must assign this instance to a host. Otherwise, this call does not dispatch the event to the instance.

status (Optional)

body

string

The event status. A valid value is failed, completed, or in-progress. Default is completed.

tag (Optional)

body

string

A string value that identifies the event. Certain types of events require specific tags:

  • For the accelerator-request-bound event, the tag must be the accelerator request UUID.

  • For the power-update event the tag must be either be POWER_ON or POWER_OFF.

  • For the volume-extended event the tag must be the volume id.

Example Run Events

{
    "events": [
        {
            "code": 200,
            "name": "network-changed",
            "server_uuid": "ff1df7b2-6772-45fd-9326-c0a3b05591c2",
            "status": "completed",
            "tag": "foo"
        }
    ]
}

Servers Topology (servers, topology)

Shows the NUMA topology information for a server.

GET
/servers/{server_id}/topology

Show Server Topology

New in version 2.78.

Shows NUMA topology information for a server.

Policy defaults enable only users with the administrative role or the owners of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

All response fields are listed below. If some information is not available or not allow by policy, the corresponding key value will not exist in response.

Name

In

Type

Description

nodes

body

array

NUMA nodes information of a server.

nodes.cpu_pinning (Optional)

body

dict

The mapping of server cores to host physical CPU. for example:

cpu_pinning: { 0: 0, 1: 5}

This means vcpu 0 is mapped to physical CPU 0, and vcpu 1 is mapped physical CPU 5.

By default the cpu_pinning field is only visible to users with the administrative role. You can change the default behavior via the policy rule:

compute:server:topology:host:index

nodes.vcpu_set (Optional)

body

list

A list of IDs of the virtual CPU assigned to this NUMA node.

nodes.siblings (Optional)

body

list

A mapping of host cpus thread sibling. For example:

siblings: [[0,1],[2,3]]

This means vcpu 0 and vcpu 1 belong to same CPU core, vcpu 2, vcpu 3 belong to another CPU core.

By default the siblings field is only visible to users with the administrative role. You can change the default behavior via the policy rule:

compute:server:topology:host:index

nodes.memory_mb (Optional)

body

integer

The amount of memory assigned to this NUMA node in MB.

nodes.host_node (Optional)

body

integer

The host NUMA node the virtual NUMA node is map to.

By default the host_node field is only visible to users with the administrator role. You can change the default behavior via the policy rule:

compute:server:topology:host:index

pagesize_kb

body

integer

The page size in KB of a server. This field is null if the page size information is not available.

Example Server topology (2.xx)

{
    "nodes": [
        {
            "cpu_pinning": {
                "0": 0,
                "1": 5
            },
            "host_node": 0,
            "memory_mb": 1024,
            "siblings": [
                [
                    0,
                    1
                ]
            ],
            "vcpu_set": [
                0,
                1
            ]
        },
        {
            "cpu_pinning": {
                "2": 1,
                "3": 8
            },
            "host_node": 1,
            "memory_mb": 2048,
            "siblings": [
                [
                    2,
                    3
                ]
            ],
            "vcpu_set": [
                2,
                3
            ]
        }
    ],
    "pagesize_kb": 4
}

Deprecated APIs

This section contains references for APIs which are deprecated and usually limited to some maximum microversion.

Extensions (extensions) (DEPRECATED)

Lists available extensions and shows information for an extension, by alias.

Nova originally supported the concept of API extensions, that allowed implementations of Nova to change the API (add new resources, or attributes to existing resource objects) via extensions. In an attempt to expose to the user what was supported in a particular site, the extensions resource provided a list of extensions and detailed information on each. The net result was gratuitous differentiation in the API that required all users of OpenStack clouds to write specific code to interact with every cloud.

As such, the entire extensions concept is deprecated, and will be removed in the near future.

GET
/extensions

List Extensions

Lists all extensions to the API.

Normal response codes: 200

Error response codes: unauthorized(401)

Response

Name

In

Type

Description

extensions

body

array

List of extension objects.

name

body

string

Name of the extension.

alias

body

string

A short name by which this extension is also known.

links

body

array

Links pertaining to this extension. This is a list of dictionaries, each including keys href and rel.

namespace

body

string

A URL pointing to the namespace for this extension.

description

body

string

Text describing this extension’s purpose.

updated

body

string

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

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

For example, 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 Extensions

Lists all extensions to the API.

{
    "extensions": [
        {
            "alias": "NMN",
            "description": "Multiple network support.",
            "links": [],
            "name": "Multinic",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-DCF",
            "description": "Disk Management Extension.",
            "links": [],
            "name": "DiskConfig",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-AZ",
            "description": "Extended Availability Zone support.",
            "links": [],
            "name": "ExtendedAvailabilityZone",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-IMG-SIZE",
            "description": "Adds image size to image listings.",
            "links": [],
            "name": "ImageSize",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-IPS",
            "description": "Adds type parameter to the ip list.",
            "links": [],
            "name": "ExtendedIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-IPS-MAC",
            "description": "Adds mac address parameter to the ip list.",
            "links": [],
            "name": "ExtendedIpsMac",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-SRV-ATTR",
            "description": "Extended Server Attributes support.",
            "links": [],
            "name": "ExtendedServerAttributes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-STS",
            "description": "Extended Status support.",
            "links": [],
            "name": "ExtendedStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-FLV-DISABLED",
            "description": "Support to show the disabled status of a flavor.",
            "links": [],
            "name": "FlavorDisabled",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-FLV-EXT-DATA",
            "description": "Provide additional data for flavors.",
            "links": [],
            "name": "FlavorExtraData",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-SCH-HNT",
            "description": "Pass arbitrary key/value pairs to the scheduler.",
            "links": [],
            "name": "SchedulerHints",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-SRV-USG",
            "description": "Adds launched_at and terminated_at on Servers.",
            "links": [],
            "name": "ServerUsage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-access-ips",
            "description": "Access IPs support.",
            "links": [],
            "name": "AccessIPs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-admin-actions",
            "description": "Enable admin-only server actions\n\n    Actions include: resetNetwork, injectNetworkInfo, os-resetState\n    ",
            "links": [],
            "name": "AdminActions",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-admin-password",
            "description": "Admin password management support.",
            "links": [],
            "name": "AdminPassword",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-agents",
            "description": "Agents support.",
            "links": [],
            "name": "Agents",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-aggregates",
            "description": "Admin-only aggregate administration.",
            "links": [],
            "name": "Aggregates",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-assisted-volume-snapshots",
            "description": "Assisted volume snapshots.",
            "links": [],
            "name": "AssistedVolumeSnapshots",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-attach-interfaces",
            "description": "Attach interface support.",
            "links": [],
            "name": "AttachInterfaces",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-availability-zone",
            "description": "1. Add availability_zone to the Create Server API.\n       2. Add availability zones describing.\n    ",
            "links": [],
            "name": "AvailabilityZone",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-baremetal-ext-status",
            "description": "Add extended status in Baremetal Nodes v2 API.",
            "links": [],
            "name": "BareMetalExtStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-baremetal-nodes",
            "description": "Admin-only bare-metal node administration.",
            "links": [],
            "name": "BareMetalNodes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-block-device-mapping",
            "description": "Block device mapping boot support.",
            "links": [],
            "name": "BlockDeviceMapping",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-block-device-mapping-v2-boot",
            "description": "Allow boot with the new BDM data format.",
            "links": [],
            "name": "BlockDeviceMappingV2Boot",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cell-capacities",
            "description": "Adding functionality to get cell capacities.",
            "links": [],
            "name": "CellCapacities",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cells",
            "description": "Enables cells-related functionality such as adding neighbor cells,\n    listing neighbor cells, and getting the capabilities of the local cell.\n    ",
            "links": [],
            "name": "Cells",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-certificates",
            "description": "Certificates support.",
            "links": [],
            "name": "Certificates",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cloudpipe",
            "description": "Adds actions to create cloudpipe instances.\n\n    When running with the Vlan network mode, you need a mechanism to route\n    from the public Internet to your vlans.  This mechanism is known as a\n    cloudpipe.\n\n    At the time of creating this class, only OpenVPN is supported.  Support for\n    a SSH Bastion host is forthcoming.\n    ",
            "links": [],
            "name": "Cloudpipe",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cloudpipe-update",
            "description": "Adds the ability to set the vpn ip/port for cloudpipe instances.",
            "links": [],
            "name": "CloudpipeUpdate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-config-drive",
            "description": "Config Drive Extension.",
            "links": [],
            "name": "ConfigDrive",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-console-auth-tokens",
            "description": "Console token authentication support.",
            "links": [],
            "name": "ConsoleAuthTokens",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-console-output",
            "description": "Console log output support, with tailing ability.",
            "links": [],
            "name": "ConsoleOutput",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-consoles",
            "description": "Interactive Console support.",
            "links": [],
            "name": "Consoles",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-create-backup",
            "description": "Create a backup of a server.",
            "links": [],
            "name": "CreateBackup",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-create-server-ext",
            "description": "Extended support to the Create Server v1.1 API.",
            "links": [],
            "name": "Createserverext",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-deferred-delete",
            "description": "Instance deferred delete.",
            "links": [],
            "name": "DeferredDelete",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-evacuate",
            "description": "Enables server evacuation.",
            "links": [],
            "name": "Evacuate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-evacuate-find-host",
            "description": "Enables server evacuation without target host. Scheduler will select one to target.",
            "links": [],
            "name": "ExtendedEvacuateFindHost",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-floating-ips",
            "description": "Adds optional fixed_address to the add floating IP command.",
            "links": [],
            "name": "ExtendedFloatingIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-hypervisors",
            "description": "Extended hypervisors support.",
            "links": [],
            "name": "ExtendedHypervisors",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-networks",
            "description": "Adds additional fields to networks.",
            "links": [],
            "name": "ExtendedNetworks",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-quotas",
            "description": "Adds ability for admins to delete quota and optionally force the update Quota command.",
            "links": [],
            "name": "ExtendedQuotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-rescue-with-image",
            "description": "Allow the user to specify the image to use for rescue.",
            "links": [],
            "name": "ExtendedRescueWithImage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-services",
            "description": "Extended services support.",
            "links": [],
            "name": "ExtendedServices",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-services-delete",
            "description": "Extended services deletion support.",
            "links": [],
            "name": "ExtendedServicesDelete",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-status",
            "description": "Extended Status support.",
            "links": [],
            "name": "ExtendedStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-volumes",
            "description": "Extended Volumes support.",
            "links": [],
            "name": "ExtendedVolumes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-fixed-ips",
            "description": "Fixed IPs support.",
            "links": [],
            "name": "FixedIPs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-access",
            "description": "Flavor access support.",
            "links": [],
            "name": "FlavorAccess",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-extra-specs",
            "description": "Flavors extra specs support.",
            "links": [],
            "name": "FlavorExtraSpecs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-manage",
            "description": "Flavor create/delete API support.",
            "links": [],
            "name": "FlavorManage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-rxtx",
            "description": "Support to show the rxtx status of a flavor.",
            "links": [],
            "name": "FlavorRxtx",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-swap",
            "description": "Support to show the swap status of a flavor.",
            "links": [],
            "name": "FlavorSwap",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ip-dns",
            "description": "Floating IP DNS support.",
            "links": [],
            "name": "FloatingIpDns",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ip-pools",
            "description": "Floating IPs support.",
            "links": [],
            "name": "FloatingIpPools",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ips",
            "description": "Floating IPs support.",
            "links": [],
            "name": "FloatingIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ips-bulk",
            "description": "Bulk handling of Floating IPs.",
            "links": [],
            "name": "FloatingIpsBulk",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-fping",
            "description": "Fping Management Extension.",
            "links": [],
            "name": "Fping",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hide-server-addresses",
            "description": "Support hiding server addresses in certain states.",
            "links": [],
            "name": "HideServerAddresses",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hosts",
            "description": "Admin-only host administration.",
            "links": [],
            "name": "Hosts",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hypervisor-status",
            "description": "Show hypervisor status.",
            "links": [],
            "name": "HypervisorStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hypervisors",
            "description": "Admin-only hypervisor administration.",
            "links": [],
            "name": "Hypervisors",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-instance-actions",
            "description": "View a log of actions and events taken on an instance.",
            "links": [],
            "name": "InstanceActions",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-instance_usage_audit_log",
            "description": "Admin-only Task Log Monitoring.",
            "links": [],
            "name": "OSInstanceUsageAuditLog",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-keypairs",
            "description": "Keypair Support.",
            "links": [],
            "name": "Keypairs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-lock-server",
            "description": "Enable lock/unlock server actions.",
            "links": [],
            "name": "LockServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-migrate-server",
            "description": "Enable migrate and live-migrate server actions.",
            "links": [],
            "name": "MigrateServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-migrations",
            "description": "Provide data on migrations.",
            "links": [],
            "name": "Migrations",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-multiple-create",
            "description": "Allow multiple create in the Create Server v2.1 API.",
            "links": [],
            "name": "MultipleCreate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-networks",
            "description": "Admin-only Network Management Extension.",
            "links": [],
            "name": "Networks",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-networks-associate",
            "description": "Network association support.",
            "links": [],
            "name": "NetworkAssociationSupport",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-pause-server",
            "description": "Enable pause/unpause server actions.",
            "links": [],
            "name": "PauseServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-personality",
            "description": "Personality support.",
            "links": [],
            "name": "Personality",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-preserve-ephemeral-rebuild",
            "description": "Allow preservation of the ephemeral partition on rebuild.",
            "links": [],
            "name": "PreserveEphemeralOnRebuild",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-quota-class-sets",
            "description": "Quota classes management support.",
            "links": [],
            "name": "QuotaClasses",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-quota-sets",
            "description": "Quotas management support.",
            "links": [],
            "name": "Quotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-rescue",
            "description": "Instance rescue mode.",
            "links": [],
            "name": "Rescue",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-security-group-default-rules",
            "description": "Default rules for security group support.",
            "links": [],
            "name": "SecurityGroupDefaultRules",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-security-groups",
            "description": "Security group support.",
            "links": [],
            "name": "SecurityGroups",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-diagnostics",
            "description": "Allow Admins to view server diagnostics through server action.",
            "links": [],
            "name": "ServerDiagnostics",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-external-events",
            "description": "Server External Event Triggers.",
            "links": [],
            "name": "ServerExternalEvents",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-group-quotas",
            "description": "Adds quota support to server groups.",
            "links": [],
            "name": "ServerGroupQuotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-groups",
            "description": "Server group support.",
            "links": [],
            "name": "ServerGroups",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-list-multi-status",
            "description": "Allow to filter the servers by a set of status values.",
            "links": [],
            "name": "ServerListMultiStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-password",
            "description": "Server password support.",
            "links": [],
            "name": "ServerPassword",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-sort-keys",
            "description": "Add sorting support in get Server v2 API.",
            "links": [],
            "name": "ServerSortKeys",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-start-stop",
            "description": "Start/Stop instance compute API support.",
            "links": [],
            "name": "ServerStartStop",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-services",
            "description": "Services support.",
            "links": [],
            "name": "Services",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-shelve",
            "description": "Instance shelve mode.",
            "links": [],
            "name": "Shelve",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-simple-tenant-usage",
            "description": "Simple tenant usage extension.",
            "links": [],
            "name": "SimpleTenantUsage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-suspend-server",
            "description": "Enable suspend/resume server actions.",
            "links": [],
            "name": "SuspendServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-tenant-networks",
            "description": "Tenant-based Network Management Extension.",
            "links": [],
            "name": "OSTenantNetworks",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-used-limits",
            "description": "Provide data on limited resources that are being used.",
            "links": [],
            "name": "UsedLimits",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-used-limits-for-admin",
            "description": "Provide data to admin on limited resources used by other tenants.",
            "links": [],
            "name": "UsedLimitsForAdmin",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-user-data",
            "description": "Add user_data to the Create Server API.",
            "links": [],
            "name": "UserData",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-user-quotas",
            "description": "Project user quota support.",
            "links": [],
            "name": "UserQuotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-virtual-interfaces",
            "description": "Virtual interface support.",
            "links": [],
            "name": "VirtualInterfaces",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-volume-attachment-update",
            "description": "Support for updating a volume attachment.",
            "links": [],
            "name": "VolumeAttachmentUpdate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-volumes",
            "description": "Volumes support.",
            "links": [],
            "name": "Volumes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        }
    ]
}
GET
/extensions/{alias}

Show Extension Details

Shows details for an extension, by alias.

Normal response codes: 200

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

Request

Name

In

Type

Description

alias

body

string

A short name by which this extension is also known.

Response

Name

In

Type

Description

extension

body

object

An extension object.

name

body

string

Name of the extension.

alias

body

string

A short name by which this extension is also known.

links

body

array

Links pertaining to this extension. This is a list of dictionaries, each including keys href and rel.

namespace

body

string

A URL pointing to the namespace for this extension.

description

body

string

Text describing this extension’s purpose.

updated

body

string

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

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

For example, 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 Extension Details

Shows details about the os-agents extension.

{
    "extension": {
        "alias": "os-agents",
        "description": "Agents support.",
        "links": [],
        "name": "Agents",
        "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
        "updated": "2014-12-03T00:00:00Z"
    }
}

Networks (os-networks) (DEPRECATED)

Warning

This API was designed to work with nova-network which was deprecated in the 14.0.0 (Newton) release and removed in the 21.0.0 (Ussuri) release. Some features are proxied to the Network service (neutron) when appropriate, but as with all translation proxies, this is far from perfect compatibility. These APIs should be avoided in new applications in favor of using neutron directly. These will fail with a 404 starting from microversion 2.36. They were removed in the 21.0.0 (Ussuri) release.

Creates, lists, shows information for, and deletes networks.

Adds network to a project, disassociates a network from a project, and disassociates a project from a network.

Associates host with and disassociates host from a network.

GET
/os-networks

List Networks

Lists networks for the project.

Policy defaults enable all users to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Response

Example List Networks: JSON response

{
    "networks": [
        {
            "bridge": null,
            "bridge_interface": null,
            "broadcast": null,
            "cidr": null,
            "cidr_v6": null,
            "created_at": null,
            "deleted": null,
            "deleted_at": null,
            "dhcp_server": null,
            "dhcp_start": null,
            "dns1": null,
            "dns2": null,
            "enable_dhcp": null,
            "gateway": null,
            "gateway_v6": null,
            "host": null,
            "id": "20c8acc0-f747-4d71-a389-46d078ebf047",
            "injected": null,
            "label": "private",
            "mtu": null,
            "multi_host": null,
            "netmask": null,
            "netmask_v6": null,
            "priority": null,
            "project_id": null,
            "rxtx_base": null,
            "share_address": null,
            "updated_at": null,
            "vlan": null,
            "vpn_private_address": null,
            "vpn_public_address": null,
            "vpn_public_port": null
        }
    ]
}
POST
/os-networks

Create Network

Creates a network.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Example Create Network: JSON request

{
    "network": {
        "label": "new net 111",
        "cidr": "10.20.105.0/24",
        "mtu": 9000,
        "dhcp_server": "10.20.105.2",
        "enable_dhcp": false,
        "share_address": true,
        "allowed_start": "10.20.105.10",
        "allowed_end": "10.20.105.200"
    }
}

Response

Example Create Network: JSON response

{
    "network": {
        "bridge": null,
        "bridge_interface": null,
        "broadcast": "10.20.105.255",
        "cidr": "10.20.105.0/24",
        "cidr_v6": null,
        "created_at": null,
        "deleted": null,
        "deleted_at": null,
        "dhcp_server": "10.20.105.2",
        "dhcp_start": "10.20.105.2",
        "dns1": null,
        "dns2": null,
        "enable_dhcp": false,
        "gateway": "10.20.105.1",
        "gateway_v6": null,
        "host": null,
        "id": "d7a17c0c-457e-4ab4-a99c-4fa1762f5359",
        "injected": null,
        "label": "new net 111",
        "mtu": 9000,
        "multi_host": null,
        "netmask": "255.255.255.0",
        "netmask_v6": null,
        "priority": null,
        "project_id": null,
        "rxtx_base": null,
        "share_address": true,
        "updated_at": null,
        "vlan": null,
        "vpn_private_address": null,
        "vpn_public_address": null,
        "vpn_public_port": null
    }
}
POST
/os-networks/add

Add Network

Adds a network to a project.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), gone(410), notImplemented(501)

Request

Example Add Network: JSON request

{
    "id": "1"
}

Response

GET
/os-networks/{network_id}

Show Network Details

Shows details for a network.

Policy defaults enable all users to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

Response

Example Show Network Details: JSON response

{
    "network": {
        "bridge": null,
        "bridge_interface": null,
        "broadcast": null,
        "cidr": null,
        "cidr_v6": null,
        "created_at": null,
        "deleted": null,
        "deleted_at": null,
        "dhcp_server": null,
        "dhcp_start": null,
        "dns1": null,
        "dns2": null,
        "enable_dhcp": null,
        "gateway": null,
        "gateway_v6": null,
        "host": null,
        "id": "20c8acc0-f747-4d71-a389-46d078ebf047",
        "injected": null,
        "label": "private",
        "mtu": null,
        "multi_host": null,
        "netmask": null,
        "netmask_v6": null,
        "priority": null,
        "project_id": null,
        "rxtx_base": null,
        "share_address": null,
        "updated_at": null,
        "vlan": null,
        "vpn_private_address": null,
        "vpn_public_address": null,
        "vpn_public_port": null
    }
}
DELETE
/os-networks/{network_id}

Delete Network

Deletes a network.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409), gone(410)

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

Response

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

POST
/os-networks/{network_id}/action

Associate Host

Associates a network with a host.

Specify the associate_host action in the request body.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

associate_host

body

string

The name of the host to associate.

Example Associate Host to Network: JSON request

{
    "associate_host": "testHost"
}

Response

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

POST
/os-networks/{network_id}/action

Disassociate Network

Disassociates a network from a project. You can then reuse the network.

Specify the disassociate action in the request body.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

Example Disassociate Network: JSON request

{
    "disassociate": null
}

Response

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

POST
/os-networks/{network_id}/action

Disassociate Host

Disassociates a host from a network.

Specify the disassociate_host action in the request body.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

Example Disassociate Host from Network: JSON request

{
    "disassociate_host": null
}

Response

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

POST
/os-networks/{network_id}/action

Disassociate Project

Disassociates a project from a network.

Specify the disassociate_project action in the request body.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

Example Disassociate Project from Network: JSON request

{
    "disassociate_project": null
}

Response

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

Volume extension (os-volumes, os-snapshots) (DEPRECATED)

Warning

These APIs are proxy calls to the Volume service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Volume APIs.

Manages volumes and snapshots for use with the Compute API. Lists, shows details, creates, and deletes volumes and snapshots.

GET
/os-volumes

List Volumes

Lists the volumes associated with the account.

Normal response codes: 200

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

Request

Name

In

Type

Description

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name

In

Type

Description

volumes

body

array

The list of volume objects.

attachments

body

array

The list of volume attachments.

attachments.device (Optional)

body

string

Name of the device in the attachment object, such as, /dev/vdb.

attachments.id (Optional)

body

string

The UUID of the attachment.

attachments.serverId (Optional)

body

string

The UUID of the server.

attachments.volumeId (Optional)

body

string

The UUID of the attached volume.

availabilityZone

body

string

The availability zone name.

createdAt

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.

displayDescription

body

string

The volume description.

displayName

body

string

The volume name.

id

body

string

The UUID of the volume.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

size

body

integer

The size of the volume, in gibibytes (GiB).

snapshotId

body

string

The UUID for a snapshot.

status

body

string

The status of the volume.

volumeType

body

string

The name or unique identifier for a volume type.


Example List Volumes

{
    "volumes": [
        {
            "attachments": [
                {
                    "device": "/",
                    "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                    "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                    "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
                }
            ],
            "availabilityZone": "zone1:host1",
            "createdAt": "2013-02-19T20:01:40.274897",
            "displayDescription": "Volume Description",
            "displayName": "Volume Name",
            "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
            "metadata": {},
            "size": 100,
            "snapshotId": null,
            "status": "in-use",
            "volumeType": "Backup"
        }
    ]
}
POST
/os-volumes

Create Volume

Creates a new volume.

Normal response codes: 200

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

Request

Name

In

Type

Description

volume

body

object

The volume object.

size

body

integer

The size of the volume, in gibibytes (GiB).

availability_zone (Optional)

body

string

The availability zone name.

display_name (Optional)

body

string

The volume name.

display_description (Optional)

body

string

The volume description.

metadata (Optional)

body

object

Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.

volume_type (Optional)

body

string

The unique identifier for a volume type.

snapshot_id (Optional)

body

string

The UUID for a snapshot.

Example Create Volume

{
    "volume": {
        "availability_zone": "zone1:host1",
        "display_name": "Volume Name",
        "display_description": "Volume Description",
        "size": 100
    }
}

Response

Name

In

Type

Description

volume

body

object

The volume object.

attachments

body

array

The list of volume attachments.

attachments.device (Optional)

body

string

Name of the device in the attachment object, such as, /dev/vdb.

attachments.id (Optional)

body

string

The UUID of the attachment.

attachments.serverId (Optional)

body

string

The UUID of the server.

attachments.volumeId (Optional)

body

string

The UUID of the attached volume.

availabilityZone

body

string

The availability zone name.

createdAt

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.

displayName

body

string

The volume name.

displayDescription

body

string

The volume description.

id

body

string

The UUID of the volume.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

size

body

integer

The size of the volume, in gibibytes (GiB).

snapshotId

body

string

The UUID for a snapshot.

status

body

string

The status of the volume.

volumeType

body

string

The name or unique identifier for a volume type.


Example Create Volume

{
    "volume": {
        "attachments": [
            {
                "device": "/",
                "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
            }
        ],
        "availabilityZone": "zone1:host1",
        "createdAt": "2013-02-18T14:51:17.970024",
        "displayDescription": "Volume Description",
        "displayName": "Volume Name",
        "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "metadata": {},
        "size": 100,
        "snapshotId": null,
        "status": "in-use",
        "volumeType": "Backup"
    }
}
GET
/os-volumes/detail

List Volumes With Details

Lists all volumes with details.

Normal response codes: 200

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

Request

Name

In

Type

Description

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name

In

Type

Description

volumes

body

array

The list of volume objects.

attachments

body

array

The list of volume attachments.

attachments.device (Optional)

body

string

Name of the device in the attachment object, such as, /dev/vdb.

attachments.id (Optional)

body

string

The UUID of the attachment.

attachments.serverId (Optional)

body

string

The UUID of the server.

attachments.volumeId (Optional)

body

string

The UUID of the attached volume.

availabilityZone

body

string

The availability zone name.

createdAt

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.

displayName

body

string

The volume name.

displayDescription

body

string

The volume description.

id

body

string

The UUID of the volume.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

size

body

integer

The size of the volume, in gibibytes (GiB).

snapshotId

body

string

The UUID for a snapshot.

status

body

string

The status of the volume.

volumeType

body

string

The name or unique identifier for a volume type.


Example List Volumes With Details

{
    "volumes": [
        {
            "attachments": [
                {
                    "device": "/",
                    "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                    "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                    "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
                }
            ],
            "availabilityZone": "zone1:host1",
            "createdAt": "1999-01-01T01:01:01.000000",
            "displayDescription": "Volume Description",
            "displayName": "Volume Name",
            "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
            "metadata": {},
            "size": 100,
            "snapshotId": null,
            "status": "in-use",
            "volumeType": "Backup"
        }
    ]
}
GET
/os-volumes/{volume_id}

Show Volume Details

Shows details for a given volume.

Normal response codes: 200

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

Request

Name

In

Type

Description

volume_id

path

string

The unique ID for a volume.

Response

Name

In

Type

Description

volume

body

object

The volume object.

attachments

body

array

The list of volume attachments.

attachment.device (Optional)

body

string

Name of the device in the attachment object, such as, /dev/vdb.

attachments.id (Optional)

body

string

The UUID of the attachment.

attachments.serverId (Optional)

body

string

The UUID of the server.

attachments.volumeId (Optional)

body

string

The UUID of the attached volume.

availabilityZone

body

string

The availability zone name.

createdAt

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.

displayName

body

string

The volume name.

displayDescription

body

string

The volume description.

id

body

string

The UUID of the volume.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

size

body

integer

The size of the volume, in gibibytes (GiB).

snapshotId

body

string

The UUID for a snapshot.

status

body

string

The status of the volume.

volumeType

body

string

The name or unique identifier for a volume type.


Example Show Volume Details

{
    "volume": {
        "attachments": [
            {
                "device": "/",
                "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
            }
        ],
        "availabilityZone": "zone1:host1",
        "createdAt": "2013-02-18T14:51:18.528085",
        "displayDescription": "Volume Description",
        "displayName": "Volume Name",
        "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "metadata": {},
        "size": 100,
        "snapshotId": null,
        "status": "in-use",
        "volumeType": "Backup"
    }
}
DELETE
/os-volumes/{volume_id}

Delete Volume

Deletes a volume.

Normal response codes: 202

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

Request

Name

In

Type

Description

volume_id

path

string

The unique ID for a volume.

Response

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

GET
/os-snapshots

List Snapshots

Lists snapshots.

Normal response codes: 200

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

Request

Name

In

Type

Description

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name

In

Type

Description

snapshots

body

array

A list of snapshot objects.

id

body

string

The UUID for a snapshot.

createdAt

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.

displayName

body

string

The snapshot name.

displayDescription

body

string

The snapshot description.

size

body

integer

The size of the volume, in gibibytes (GiB).

status

body

string

The status of the snapshot. Valid status values are:

  • available

  • creating

  • deleting

  • error

  • error_deleting

volumeId

body

string

The source volume ID.


Example List Snapshots

{
    "snapshots": [
        {
            "createdAt": "2013-02-25T16:27:54.684999",
            "displayDescription": "Default description",
            "displayName": "Default name",
            "id": 100,
            "size": 100,
            "status": "available",
            "volumeId": 12
        },
        {
            "createdAt": "2013-02-25T16:27:54.685005",
            "displayDescription": "Default description",
            "displayName": "Default name",
            "id": 101,
            "size": 100,
            "status": "available",
            "volumeId": 12
        },
        {
            "createdAt": "2013-02-25T16:27:54.685008",
            "displayDescription": "Default description",
            "displayName": "Default name",
            "id": 102,
            "size": 100,
            "status": "available",
            "volumeId": 12
        }
    ]
}
POST
/os-snapshots

Create Snapshot

Creates a new snapshot.

Normal response codes: 200

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

Request

Name

In

Type

Description

snapshot

body

object

A partial representation of a snapshot that is used to create a snapshot.

volume_id

body

string

The source volume ID.

display_description (Optional)

body

string

The snapshot description.

display_name (Optional)

body

string

The snapshot name.

force (Optional)

body

boolean

Indicates whether to create a snapshot, even if the volume is attached.

Example Create Snapshot

{
    "snapshot": {
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "force": false
     }
}

Response

Name

In

Type

Description

snapshot

body

object

A partial representation of a snapshot that is used to create a snapshot.

id

body

string

The UUID for a snapshot.

createdAt

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.

displayName

body

string

The snapshot name.

displayDescription

body

string

The snapshot description.

volumeId

body

string

The source volume ID.

size

body

integer

The size of the volume, in gibibytes (GiB).

status

body

string

The status of the snapshot. Valid status values are:

  • available

  • creating

  • deleting

  • error

  • error_deleting

Example Create Snapshot

{
    "snapshot": {
        "createdAt": "2013-02-25T16:27:54.680544",
        "displayDescription": "Daily backup",
        "displayName": "snap-001",
        "id": 100,
        "size": 100,
        "status": "available",
        "volumeId": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"
    }
}
GET
/os-snapshots/detail

List Snapshots With Details

Lists all snapshots with details.

Normal response codes: 200

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

Request

Name

In

Type

Description

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name

In

Type

Description

snapshots

body

array

A list of snapshot objects.

id

body

string

The UUID for a snapshot.

createdAt

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.

displayName

body

string

The snapshot name.

displayDescription

body

string

The snapshot description.

volumeId

body

string

The source volume ID.

size

body

integer

The size of the volume, in gibibytes (GiB).

status

body

string

The status of the snapshot. Valid status values are:

  • available

  • creating

  • deleting

  • error

  • error_deleting


Example List Snapshots With Details

{
    "snapshots": [
        {
            "createdAt": "2013-02-25T16:27:54.671372",
            "displayDescription": "Default description",
            "displayName": "Default name",
            "id": 100,
            "size": 100,
            "status": "available",
            "volumeId": 12
        },
        {
            "createdAt": "2013-02-25T16:27:54.671378",
            "displayDescription": "Default description",
            "displayName": "Default name",
            "id": 101,
            "size": 100,
            "status": "available",
            "volumeId": 12
        },
        {
            "createdAt": "2013-02-25T16:27:54.671381",
            "displayDescription": "Default description",
            "displayName": "Default name",
            "id": 102,
            "size": 100,
            "status": "available",
            "volumeId": 12
        }
    ]
}
GET
/os-snapshots/{snapshot_id}

Show Snapshot Details

Shows details for a given snapshot.

Normal response codes: 200

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

Request

Name

In

Type

Description

snapshot_id

path

string

The UUID of the snapshot.

Response

Name

In

Type

Description

snapshot

body

object

A partial representation of a snapshot that is used to create a snapshot.

id

body

string

The UUID for a snapshot.

createdAt

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.

displayName

body

string

The snapshot name.

displayDescription

body

string

The snapshot description.

volumeId

body

string

The source volume ID.

size

body

integer

The size of the volume, in gibibytes (GiB).

status

body

string

The status of the snapshot. Valid status values are:

  • available

  • creating

  • deleting

  • error

  • error_deleting


Example Show Snapshot Details

{
    "snapshot": {
        "createdAt": "2013-02-25T16:27:54.724209",
        "displayDescription": "Default description",
        "displayName": "Default name",
        "id": "100",
        "size": 100,
        "status": "available",
        "volumeId": 12
    }
}
DELETE
/os-snapshots/{snapshot_id}

Delete Snapshot

Deletes a snapshot from the account.

This operation is asynchronous. You must list snapshots repeatedly to determine whether the snapshot was deleted.

Normal response codes: 202

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

Request

Name

In

Type

Description

snapshot_id

path

string

The UUID of the snapshot.

Response

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

Images (DEPRECATED)

Warning

These APIs are proxy calls to the Image service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. All the Image services proxy APIs except image metadata APIs will fail with a 404 starting from microversion 2.36. The image metadata APIs will fail with a 404 starting from microversion 2.39. See: Relevant Image APIs.

Lists, shows details and deletes images. Also sets, lists, shows details, create, update and deletes image metadata.

An image is a collection of files that you use to create and rebuild a server. By default, operators provide pre-built operating system images. You can also create custom images. See: Create Image Action.

By default, the policy.json file authorizes all users to view the image size in the OS-EXT-IMG-SIZE:size extended attribute.

GET
/images

List Images

List images.

Normal response codes: 200

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

Request

Name

In

Type

Description

changes-since (Optional)

query

string

Filters the response by a date and time when the image last changed status. Use this query parameter to check for changes since a previous request rather than re-downloading and re-parsing the full status at each polling interval. If data has changed, the call returns only the items changed since the changes-since time. If data has not changed since the changes-since time, the call returns an empty list. To enable you to keep track of changes, this filter also displays images that were deleted if the changes-since value specifies a date in the last 30 days. Items deleted more than 30 days ago might be returned, but it is not guaranteed. The date and time stamp format is ISO 8601:

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

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

server (Optional)

query

string

Filters the response by a server, as a URL.

name (Optional)

query

string

Filters the response by an image name, as a string.

status (Optional)

query

string

Filters the response by an image status, as a string. For example, ACTIVE.

minDisk (Optional)

query

integer

Filters the response by a minimum disk space, in GiB. For example, 100.

minRam (Optional)

query

integer

Filters the response by a minimum RAM, in MiB. For example, 512.

type (Optional)

query

string

Filters the response by an image type. For example, snapshot or backup.

limit (Optional)

query

integer

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

marker (Optional)

query

string

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

Response

Name

In

Type

Description

images

body

array

An array of Image objects.

id

body

string

The ID of the Image.

name

body

string

The display name of an Image.

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

Example List Images: JSON response

{
    "images": [
        {
            "id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "a2459075-d96c-40d5-893e-577ff92e721c",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "cedef40a-ed67-4d10-800e-17455edce175",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "c905cedb-7281-47e4-8a62-f26bc5fc4c77",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "a440c04b-79fa-479c-bed1-0b816eaec379",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage6"
        },
        {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage7"
        },
        {
            "id": "a2293931-dc33-45cc-85ef-232aa9491710",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a2293931-dc33-45cc-85ef-232aa9491710",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a2293931-dc33-45cc-85ef-232aa9491710",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a2293931-dc33-45cc-85ef-232aa9491710",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "e78f0ee9-96ef-4ce7-accf-e816f273be45",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/e78f0ee9-96ef-4ce7-accf-e816f273be45",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/e78f0ee9-96ef-4ce7-accf-e816f273be45",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/e78f0ee9-96ef-4ce7-accf-e816f273be45",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "54eadb78-eeb6-4b13-beed-20b9894eeadf",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/54eadb78-eeb6-4b13-beed-20b9894eeadf",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/54eadb78-eeb6-4b13-beed-20b9894eeadf",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/54eadb78-eeb6-4b13-beed-20b9894eeadf",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "eb7458f3-d003-4187-8027-595591dc2723",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/eb7458f3-d003-4187-8027-595591dc2723",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/eb7458f3-d003-4187-8027-595591dc2723",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/eb7458f3-d003-4187-8027-595591dc2723",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        }
    ]
}
GET
/images/detail

List Images With Details

List images with details.

Normal response codes: 200

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

Request

Name

In

Type

Description

changes-since (Optional)

query

string

Filters the response by a date and time when the image last changed status. Use this query parameter to check for changes since a previous request rather than re-downloading and re-parsing the full status at each polling interval. If data has changed, the call returns only the items changed since the changes-since time. If data has not changed since the changes-since time, the call returns an empty list. To enable you to keep track of changes, this filter also displays images that were deleted if the changes-since value specifies a date in the last 30 days. Items deleted more than 30 days ago might be returned, but it is not guaranteed. The date and time stamp format is ISO 8601:

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

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

server (Optional)

query

string

Filters the response by a server, as a URL.

name (Optional)

query

string

Filters the response by an image name, as a string.

status (Optional)

query

string

Filters the response by an image status, as a string. For example, ACTIVE.

minDisk (Optional)

query

integer

Filters the response by a minimum disk space, in GiB. For example, 100.

minRam (Optional)

query

integer

Filters the response by a minimum RAM, in MiB. For example, 512.

type (Optional)

query

string

Filters the response by an image type. For example, snapshot or backup.

limit (Optional)

query

integer

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

marker (Optional)

query

string

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

Response

Name

In

Type

Description

images

body

array

An array of Image objects.

id

body

string

The ID of the Image.

name

body

string

The display name of an Image.

minRam

body

integer

The minimum amount of RAM an image requires to function, in MiB. For example, 512.

minDisk

body

integer

The minimum amount of disk space an image requires to boot, in GiB. For example, 100.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

created

body

string

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

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

For example, 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

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.

status

body

string

The status of image, as a string. This can be one of:

  • ACTIVE: image is in active state

  • SAVING: image is in queued or in saving process

  • DELETED: image is deleted or in progress of deletion

  • ERROR: image is in error state

  • UNKNOWN: image is in unknown state

progress

body

integer

A percentage value of the image save progress. This can be one of:

  • ACTIVE: 100

  • SAVING: 25 or 50

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

server (Optional)

body

object

The server booted from image.

OS-EXT-IMG-SIZE:size

body

integer

The size of the image.

OS-DCF:diskConfig (Optional)

body

string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

Example List Images Details: JSON response

{
    "images": [
        {
            "OS-EXT-IMG-SIZE:size": "25165824",
            "created": "2011-01-01T01:02:03Z",
            "id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "architecture": "x86_64",
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "58145823",
            "created": "2011-01-01T01:02:03Z",
            "id": "a2459075-d96c-40d5-893e-577ff92e721c",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "83594576",
            "created": "2011-01-01T01:02:03Z",
            "id": "76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "architecture": "x86_64",
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "84035174",
            "created": "2011-01-01T01:02:03Z",
            "id": "cedef40a-ed67-4d10-800e-17455edce175",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "26360814",
            "created": "2011-01-01T01:02:03Z",
            "id": "c905cedb-7281-47e4-8a62-f26bc5fc4c77",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "kernel_id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
                "ramdisk_id": null
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-DCF:diskConfig": "MANUAL",
            "OS-EXT-IMG-SIZE:size": "49163826",
            "created": "2011-01-01T01:02:03Z",
            "id": "a440c04b-79fa-479c-bed1-0b816eaec379",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "architecture": "x86_64",
                "auto_disk_config": "False",
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage6",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-DCF:diskConfig": "AUTO",
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "architecture": "x86_64",
                "auto_disk_config": "True",
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage7",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "25165824",
            "created": "2011-01-01T01:02:03Z",
            "id": "95fad737-9325-4855-b37e-20a62268ec88",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/95fad737-9325-4855-b37e-20a62268ec88",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/95fad737-9325-4855-b37e-20a62268ec88",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/95fad737-9325-4855-b37e-20a62268ec88",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "hw_ephemeral_encryption": "True"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "25165824",
            "created": "2011-01-01T01:02:03Z",
            "id": "535426d4-5d75-44f4-9591-a2123d23c33f",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/535426d4-5d75-44f4-9591-a2123d23c33f",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/535426d4-5d75-44f4-9591-a2123d23c33f",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/535426d4-5d75-44f4-9591-a2123d23c33f",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "hw_ephemeral_encryption": "False"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "25165824",
            "created": "2011-01-01T01:02:03Z",
            "id": "5f7d4f5b-3781-4a4e-9046-a2a800e807e5",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/5f7d4f5b-3781-4a4e-9046-a2a800e807e5",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/5f7d4f5b-3781-4a4e-9046-a2a800e807e5",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/5f7d4f5b-3781-4a4e-9046-a2a800e807e5",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "hw_ephemeral_encryption": "True",
                "hw_ephemeral_encryption_format": "luks"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "25165824",
            "created": "2011-01-01T01:02:03Z",
            "id": "261b52ed-f693-4147-8f3b-d25df5efd968",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/261b52ed-f693-4147-8f3b-d25df5efd968",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/261b52ed-f693-4147-8f3b-d25df5efd968",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/261b52ed-f693-4147-8f3b-d25df5efd968",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "hw_ephemeral_encryption": "True",
                "hw_ephemeral_encryption_format": "plain"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        }
    ]
}
GET
/images/{image_id}

Show Image Details

Shows details for an image.

Normal response codes: 200

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

Response

Name

In

Type

Description

images

body

array

An array of Image objects.

id

body

string

The ID of the Image.

name

body

string

The display name of an Image.

minRam

body

integer

The minimum amount of RAM an image requires to function, in MiB. For example, 512.

minDisk

body

integer

The minimum amount of disk space an image requires to boot, in GiB. For example, 100.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

created

body

string

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

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

For example, 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

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.

status

body

string

The status of image, as a string. This can be one of:

  • ACTIVE: image is in active state

  • SAVING: image is in queued or in saving process

  • DELETED: image is deleted or in progress of deletion

  • ERROR: image is in error state

  • UNKNOWN: image is in unknown state

progress

body

integer

A percentage value of the image save progress. This can be one of:

  • ACTIVE: 100

  • SAVING: 25 or 50

links

body

array

Links to the resources in question. See API Guide / Links and References for more info.

server (Optional)

body

object

The server booted from image.

OS-EXT-IMG-SIZE:size

body

integer

The size of the image.

OS-DCF:diskConfig (Optional)

body

string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.

  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

Example Show Image Details: JSON response

{
    "image": {
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-IMG-SIZE:size": "74185822",
        "created": "2011-01-01T01:02:03Z",
        "id": "70a599e0-31e7-49b7-b260-868f441e862b",
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                "rel": "bookmark"
            },
            {
                "href": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
                "rel": "alternate",
                "type": "application/vnd.openstack.image"
            }
        ],
        "metadata": {
            "architecture": "x86_64",
            "auto_disk_config": "True",
            "kernel_id": "nokernel",
            "ramdisk_id": "nokernel"
        },
        "minDisk": 0,
        "minRam": 0,
        "name": "fakeimage7",
        "progress": 100,
        "status": "ACTIVE",
        "updated": "2011-01-01T01:02:03Z"
    }
}
DELETE
/images/{image_id}

Delete Image

Deletes an image.

Normal response codes: 204

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

Response

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

GET
/images/{image_id}/metadata

List Image Metadata

List metadata of an image.

Normal response codes: 200

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

Response

Name

In

Type

Description

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example List Image Metadata Details: JSON response

{
    "metadata": {
        "architecture": "x86_64",
        "auto_disk_config": "True",
        "kernel_id": "nokernel",
        "ramdisk_id": "nokernel"
    }
}
POST
/images/{image_id}/metadata

Create Image Metadata

Create an image metadata.

Normal response codes: 200

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Image Metadata: JSON request

{
    "metadata": {
        "kernel_id": "False",
        "Label": "UpdatedImage"
    }
}

Response

Name

In

Type

Description

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Image Metadata: JSON response

{
    "metadata": {
        "Label": "UpdatedImage",
        "architecture": "x86_64",
        "auto_disk_config": "True",
        "kernel_id": "False",
        "ramdisk_id": "nokernel"
    }
}
PUT
/images/{image_id}/metadata

Update Image Metadata

Update an image metadata

Normal response codes: 200

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Image Metadata: JSON request

{
    "metadata": {
        "auto_disk_config": "True",
        "Label": "Changed"
    }
}

Response

Name

In

Type

Description

metadata

body

object

Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Image Metadata: JSON response

{
    "metadata": {
        "Label": "Changed",
        "auto_disk_config": "True"
    }
}
GET
/images/{image_id}/metadata/{key}

Show Image Metadata Item

Shows metadata item, by key, for an image.

Normal response codes: 200

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

key

path

string

The metadata item key, as a string. Maximum length is 255 characters.

Response

Name

In

Type

Description

meta

body

object

The object of detailed key metadata items.

Example Show Image Metadata Item Details: JSON response

{
    "meta": {
        "kernel_id": "nokernel"
    }
}
PUT
/images/{image_id}/metadata/{key}

Create Or Update Image Metadata Item

Creates or updates a metadata item, by key, for an image.

Normal response codes: 200

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

key

path

string

The metadata item key, as a string. Maximum length is 255 characters.

meta

body

object

The object of detailed key metadata items.

Example Create Or Update Image Metadata Item: JSON request

{
    "meta": {
        "auto_disk_config": "False"
    }
}

Response

Name

In

Type

Description

meta

body

object

The object of detailed key metadata items.

Example Create Or Update Image Metadata Item: JSON response

{
    "meta": {
        "auto_disk_config": "False"
    }
}
DELETE
/images/{image_id}/metadata/{key}

Delete Image Metadata Item

Deletes a metadata item, by key, for an image.

Normal response codes: 204

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

Request

Name

In

Type

Description

image_id

path

string

The UUID of the image.

key

path

string

The metadata item key, as a string. Maximum length is 255 characters.

Response

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

Bare metal nodes (os-baremetal-nodes) (DEPRECATED)

Warning

These APIs are proxy calls to the Ironic service. They exist for legacy compatibility, but no new applications should use them. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Bare metal APIs.

Bare metal nodes.

GET
/os-baremetal-nodes

List Bare Metal Nodes

Lists the bare metal nodes known by the compute environment.

Normal response codes: 202

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

Response

Name

In

Type

Description

nodes

body

array

An array of baremetal node objects.

id

body

string

UUID of the baremetal node.

interfaces

body

array

A list of interface objects for active interfaces on the baremetal node. Each will have an address field with the address.

host

body

string

This will always have the value IRONIC MANAGED.

task_state

body

string

The Ironic task state for the node. See Ironic project for more details.

cpus

body

string

Number of CPUs the node has.

Note

This is a JSON string, even though it will look like an int value.

memory_mb

body

string

Amount of memory in MiB the node has.

Note

This is a JSON string, even though it will look like an int value.

disk_gb

body

string

Amount of disk in GiB the node has.

Note

This is a JSON string, even though it will look like an int value.

Example List Bare Metal Nodes

{
    "nodes": [
        {
            "cpus": "2",
            "disk_gb": "10",
            "host": "IRONIC MANAGED",
            "id": "058d27fa-241b-445a-a386-08c04f96db43",
            "interfaces": [],
            "memory_mb": "1024",
            "task_state": "active"
        },
        {
            "cpus": "2",
            "disk_gb": "10",
            "host": "IRONIC MANAGED",
            "id": "e2025409-f3ce-4d6a-9788-c565cf3b1b1c",
            "interfaces": [],
            "memory_mb": "1024",
            "task_state": "active"
        }
    ]
}
GET
/os-baremetal-nodes/{node_id}

Show Bare Metal Node Details

Shows details for a bare metal node.

Normal response codes: 202

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

Request

Name

In

Type

Description

node_id

path

string

The node ID.

Response

Name

In

Type

Description

node

body

object

A baremetal node object.

id

body

string

UUID of the baremetal node.

instance_uuid

body

string

UUID of the server instance on this node.

interfaces

body

array

A list of interface objects for active interfaces on the baremetal node. Each will have an address field with the address.

host

body

string

This will always have the value IRONIC MANAGED.

task_state

body

string

The Ironic task state for the node. See Ironic project for more details.

cpus

body

string

Number of CPUs the node has.

Note

This is a JSON string, even though it will look like an int value.

memory_mb

body

string

Amount of memory in MiB the node has.

Note

This is a JSON string, even though it will look like an int value.

disk_gb

body

string

Amount of disk in GiB the node has.

Note

This is a JSON string, even though it will look like an int value.

Example Show Bare Metal Node Details

{
    "node": {
        "cpus": "2",
        "disk_gb": "10",
        "host": "IRONIC MANAGED",
        "id": "058d27fa-241b-445a-a386-08c04f96db43",
        "instance_uuid": "1ea4e53e-149a-4f02-9515-590c9fb2315a",
        "interfaces": [],
        "memory_mb": "1024",
        "task_state": "active"
    }
}

Project networks (os-tenant-networks) (DEPRECATED)

Warning

These APIs are proxy calls to the Network service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Network APIs.

Creates, lists, shows information for, and deletes project networks.

GET
/os-tenant-networks

List Project Networks

Lists all project networks.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Response

Example List Project Networks: JSON response

{
    "networks": [
        {
            "cidr": "None",
            "id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6",
            "label": "private"
        }
    ]
}
POST
/os-tenant-networks

Create Project Network

Note

This API is only implemented for the nova-network service and will result in a 503 error response if the cloud is using the Neutron networking service. Use the Neutron networks API to create a new network.

Creates a project network.

Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409), gone(410), serviceUnavailable(503)

Example Create Project Network: JSON request

{
    "network": {
        "label": "public",
        "cidr": "172.0.0.0/24",
        "vlan_start": 1,
        "num_networks": 1,
        "network_size": 255
    }
}

Response

Example Create Project Network: JSON response

{
    "network": {
        "cidr": "172.0.0.0/24",
        "id": "5bbcc3c4-1da2-4437-a48a-66f15b1b13f9",
        "label": "public"
    }
}
GET
/os-tenant-networks/{network_id}

Show Project Network Details

Shows details for a project network.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

Response

Example Show Project Network Details: JSON response

{
    "network": {
        "cidr": "172.0.0.0/24",
        "id": "5bbcc3c4-1da2-4437-a48a-66f15b1b13f9",
        "label": "public"
    }
}
DELETE
/os-tenant-networks/{network_id}

Delete Project Network

Note

This API is only implemented for the nova-network service and will result in a 500 error response if the cloud is using the Neutron networking service. Use the Neutron networks API to delete an existing network.

Deletes a project network.

Policy defaults enable only users with the administrative role or the owner of the network to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409), gone(410)

Request

Name

In

Type

Description

network_id

path

string

The UUID of the network.

Response

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

Floating IP pools (os-floating-ip-pools) (DEPRECATED)

Warning

This API is a proxy call to the Network service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. This API will fail with a 404 starting from microversion 2.36.

For the equivalent functionality in the Network service, one can request:

GET /networks?router:external=True&fields=name

Manages groups of floating IPs.

GET
/os-floating-ip-pools

List Floating Ip Pools

Lists floating IP pools.

Policy defaults enable only users with the administrative role or user who is authorized to operate on tenant <tenant_id> to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Response

Name

In

Type

Description

floating_ip_pools

body

array

The floating_ip_pools object.

name

body

string

The name or ID of the floating IP pool.

Example List Floating Ip Pools: JSON response

{
    "floating_ip_pools": [
        {
            "name": "pool1"
        },
        {
            "name": "pool2"
        }
    ]
}

Floating IPs (os-floating-ips) (DEPRECATED)

Warning

These APIs are proxy calls to the Network service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Network APIs.

Lists floating IP addresses for a project. Also, creates (allocates) a floating IP address for a project, shows floating IP address details, and deletes (deallocates) a floating IP address from a project.

The cloud administrator configures a pool of floating IP addresses in OpenStack Compute. The project quota defines the maximum number of floating IP addresses that you can allocate to the project. After you allocate a floating IP address for a project, you can:

GET
/os-floating-ips

List Floating Ip Addresses

Lists floating IP addresses associated with the tenant or account.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Response

Name

In

Type

Description

floating_ips

body

array

An array of floating ip objects.

fixed_ip

body

string

Fixed IP associated with floating IP network.

id

body

string

The floating IP id value.

Note

For nova-network, the value will be of type integer, whereas for neutron, the value will be of type string.

instance_id

body

string

The UUID of the server.

ip

body

string

The floating ip address.

pool

body

string

The name or ID of the floating IP pool.

Example List Floating Ip Addresses

{
    "floating_ips": [
        {
            "fixed_ip": null,
            "id": "8baeddb4-45e2-4c36-8cb7-d79439a5f67c",
            "instance_id": null,
            "ip": "172.24.4.17",
            "pool": "public"
        },
        {
            "fixed_ip": null,
            "id": "05ef7490-745a-4af9-98e5-610dc97493c4",
            "instance_id": null,
            "ip": "172.24.4.78",
            "pool": "public"
        }
    ]
}
POST
/os-floating-ips

Create (Allocate) Floating Ip Address

Creates, or allocates, a floating IP address for the current project. By default, the floating IP address is allocated from the public pool.

If more than one floating IP address pool is available, use the pool parameter to specify from which pool to allocate the IP address.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

pool

body

string

The name or ID of the floating IP pool.

Example Create (Allocate) Floating Ip Address

{
    "pool": "public"
}

Response

Name

In

Type

Description

floating_ip

body

object

A floating IP address object.

fixed_ip

body

string

Fixed IP associated with floating IP network.

id

body

string

The floating IP id value.

Note

For nova-network, the value will be of type integer, whereas for neutron, the value will be of type string.

instance_id

body

string

The UUID of the server.

ip

body

string

The floating ip address.

pool

body

string

The name or ID of the floating IP pool.

Example Create (Allocate) Floating Ip Address: JSON response

{
    "floating_ip": {
        "fixed_ip": null,
        "id": "8baeddb4-45e2-4c36-8cb7-d79439a5f67c",
        "instance_id": null,
        "ip": "172.24.4.17",
        "pool": "public"
    }
}
GET
/os-floating-ips/{floating_ip_id}

Show Floating Ip Address Details

Shows details for a floating IP address, by ID, that is associated with the tenant or account.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

floating_ip_id

path

string

The ID of the floating IP address.

Response

Name

In

Type

Description

floating_ip

body

object

A floating IP address object.

fixed_ip

body

string

Fixed IP associated with floating IP network.

id

body

string

The floating IP id value.

Note

For nova-network, the value will be of type integer, whereas for neutron, the value will be of type string.

instance_id

body

string

The UUID of the server.

ip

body

string

The floating ip address.

pool

body

string

The name or ID of the floating IP pool.

Example Show Floating Ip Address Details: JSON response

{
    "floating_ip": {
        "fixed_ip": null,
        "id": "8baeddb4-45e2-4c36-8cb7-d79439a5f67c",
        "instance_id": null,
        "ip": "172.24.4.17",
        "pool": "public"
    }
}
DELETE
/os-floating-ips/{floating_ip_id}

Delete (Deallocate) Floating Ip Address

Deletes, or deallocates, a floating IP address from the current project and returns it to the pool from which it was allocated.

If the IP address is still associated with a running instance, it is automatically disassociated from that instance.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 202

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

Request

Name

In

Type

Description

floating_ip_id

path

string

The ID of the floating IP address.

Response

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

Security groups (os-security-groups) (DEPRECATED)

Warning

These APIs are proxy calls to the Network service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Network APIs.

Lists, shows information for, creates, updates and deletes security groups.

GET
/os-security-groups

List Security Groups

Lists security groups.

Normal response codes: 200

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

Request

Name

In

Type

Description

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

all_tenants (Optional)

query

string

Specify the all_tenants query parameter to list all security groups for all projects. This is only allowed for admin users. Value of this query parameter is not checked, only presence is considered as request for all tenants.

Response

Name

In

Type

Description

security_groups

body

array

One or more security groups objects.

description

body

string

Security group description.

id

body

string

The ID of the security group.

name

body

string

The security group name.

rules

body

array

The list of security group rules.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

Example List security groups: JSON response

{
    "security_groups": [
        {
            "description": "default",
            "id": 1,
            "name": "default",
            "rules": [],
            "tenant_id": "6f70656e737461636b20342065766572"
        }
    ]
}
POST
/os-security-groups

Create Security Group

Creates a security group.

Normal response codes: 200

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

Request

Name

In

Type

Description

security_group

body

string

Specify the security_group action in the request body.

name

body

string

The security group name.

description

body

string

Security group description.

Example Create security group: JSON request

{
    "security_group": {
        "name": "test",
        "description": "description"
    }
}

Response

Name

In

Type

Description

security_group

body

string

Specify the security_group action in the request body.

description

body

string

Security group description.

id

body

string

The ID of the security group.

name

body

string

The security group name.

rules

body

array

The list of security group rules.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

Example Create security group: JSON response

{
    "security_group": {
        "description": "default",
        "id": 1,
        "name": "default",
        "rules": [],
        "tenant_id": "6f70656e737461636b20342065766572"
    }
}
GET
/os-security-groups/{security_group_id}

Show Security Group Details

Shows details for a security group.

Normal response codes: 200

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

Request

Name

In

Type

Description

security_group_id

path

string

The ID of the security group.

Response

Name

In

Type

Description

security_group

body

string

Specify the security_group action in the request body.

description

body

string

Security group description.

id

body

string

The ID of the security group.

name

body

string

The security group name.

rules

body

array

The list of security group rules.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

Example Show security group: JSON response

{
    "security_group": {
        "description": "default",
        "id": 1,
        "name": "default",
        "rules": [],
        "tenant_id": "6f70656e737461636b20342065766572"
    }
}
PUT
/os-security-groups/{security_group_id}

Update Security Group

Updates a security group.

Normal response codes: 200

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

Request

Name

In

Type

Description

security_group_id

path

string

The ID of the security group.

name

body

string

The security group name.

description

body

string

Security group description.

Example Update security group: JSON request

{
    "security_group": {
        "name": "test",
        "description": "description"
    }
}

Response

Name

In

Type

Description

security_group

body

string

Specify the security_group action in the request body.

description

body

string

Security group description.

id

body

string

The ID of the security group.

name

body

string

The security group name.

rules

body

array

The list of security group rules.

tenant_id

body

string

The UUID of the tenant in a multi-tenancy cloud.

Example Update security group: JSON response

{
    "security_group": {
        "description": "default",
        "id": 1,
        "name": "default",
        "rules": [],
        "tenant_id": "6f70656e737461636b20342065766572"
    }
}
DELETE
/os-security-groups/{security_group_id}

Delete Security Group

Deletes a security group.

Normal response codes: 202

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

Request

Name

In

Type

Description

security_group_id

path

string

The ID of the security group.

Response

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

Rules for security group (os-security-group-rules) (DEPRECATED)

Warning

These APIs are proxy calls to the Network service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Network APIs.

Creates and deletes security group rules.

POST
/os-security-group-rules

Create Security Group Rule

Creates a rule for a security group. Either cidr or group_id must be specified when creating a rule.

Note

nova-network only supports ingress rules. If you want to define egress rules you must use the Neutron networking service.

Normal response codes: 200

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

Request

Name

In

Type

Description

security_group_rule

body

object

A security_group_rule object.

parent_group_id

body

string

Security group ID.

ip_protocol

body

string

The IP protocol. A valid value is ICMP, TCP, or UDP.

from_port

body

integer

The port at start of range.

to_port

body

integer

The port at end of range.

cidr (Optional)

body

string

The CIDR for address range.

group_id (Optional)

body

string

The source security group ID.

Example Create security group rule: JSON request

{
    "security_group_rule": {
        "parent_group_id": "21111111-1111-1111-1111-111111111112",
        "ip_protocol": "tcp",
        "from_port": 22,
        "to_port": 22,
        "cidr": "10.0.0.0/24"
    }
}

Response

The group is empty if group_id was not provided on the request.

The ip_range is empty if cidr was not provided on the request.

Name

In

Type

Description

security_group_rule

body

object

A security_group_rule object.

ip_protocol

body

string

The IP protocol. A valid value is ICMP, TCP, or UDP.

from_port

body

integer

The port at start of range.

to_port

body

integer

The port at end of range.

ip_range

body

object

An IP range object. Includes the security group rule cidr.

ip_range.cidr (Optional)

body

string

The CIDR for address range.

id

body

string

The security group rule ID.

parent_group_id

body

string

Security group ID.

group

body

object

A group object. Includes the tenant_id and the source security group name.

group.name (Optional)

body

string

The security group name.

group.tenant_id (Optional)

body

string

The UUID of the tenant that owns this security group.

Example Create security group rule: JSON response

{
    "security_group_rule": {
        "from_port": 22,
        "group": {},
        "id": "00000000-0000-0000-0000-000000000000",
        "ip_protocol": "tcp",
        "ip_range": {
            "cidr": "10.0.0.0/24"
        },
        "parent_group_id": "11111111-1111-1111-1111-111111111111",
        "to_port": 22
    }
}
DELETE
/os-security-group-rules/{security_group_rule_id}

Delete Security Group Rule

Deletes a security group rule.

Normal response codes: 202

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

Request

Name

In

Type

Description

security_group_rule_id

path

string

The ID of the security group rule.

Response

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

Hosts (os-hosts) (DEPRECATED)

Warning

The os-hosts API is deprecated as of the 2.43 microversion. Requests made with microversion >= 2.43 will result in a 404 error. To list and show host details, use the Hypervisors (os-hypervisors) API. To enable or disable a service, use the Compute services (os-services) API. There is no replacement for the shutdown, startup, reboot, or maintenance_mode actions as those are system-level operations which should be outside of the control of the compute service.

Manages physical hosts. Some virt drivers do not support all host functions. For more information, see nova virt support matrix

Policy defaults enable only users with the administrative role to perform all os-hosts related operations. Cloud providers can change these permissions through the policy.json file.

GET
/os-hosts

List Hosts

Lists hosts.

Normal response codes: 200

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

Response

Name

In

Type

Description

hosts

body

array

An array of host information.

zone

body

string

The available zone of the host.

host_name

body

string

The name of the host.

service

body

string

The name of the service which is running on the host.

Example List Hosts

{
    "hosts": [
        {
            "host_name": "b6e4adbc193d428ea923899d07fb001e",
            "service": "conductor",
            "zone": "internal"
        },
        {
            "host_name": "09c025b0efc64211bd23fc50fa974cdf",
            "service": "compute",
            "zone": "nova"
        },
        {
            "host_name": "abffda96592c4eacaf4111c28fddee17",
            "service": "scheduler",
            "zone": "internal"
        }
    ]
}
GET
/os-hosts/{host_name}

Show Host Details

Shows details for a host.

Normal response codes: 200

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

Request

Name

In

Type

Description

host_name

path

string

The name of the host.

Response

Name

In

Type

Description

host

body

array

The array that includes resource info of the host.

resource

body

object

The resource info of the host.

resource.project

body

string

The project id (or special name like total, used_now, used_max).

resource.cpu

body

integer

The number of virtual CPUs on the host.

resource.memory_mb

body

integer

The memory size on the host (in MiB).

resource.disk_gb

body

integer

The disk size on the host (in GiB).

resource.host

body

string

The name of the host.

Example Show Host Details

{
    "host": [
        {
            "resource": {
                "cpu": 2,
                "disk_gb": 1028,
                "host": "c1a7de0ac9d94e4baceae031d05caae3",
                "memory_mb": 8192,
                "project": "(total)"
            }
        },
        {
            "resource": {
                "cpu": 0,
                "disk_gb": 0,
                "host": "c1a7de0ac9d94e4baceae031d05caae3",
                "memory_mb": 512,
                "project": "(used_now)"
            }
        },
        {
            "resource": {
                "cpu": 0,
                "disk_gb": 0,
                "host": "c1a7de0ac9d94e4baceae031d05caae3",
                "memory_mb": 0,
                "project": "(used_max)"
            }
        }
    ]
}
PUT
/os-hosts/{host_name}

Update Host status

Enables, disables a host or put a host in maintenance or normal mode.

Warning

Putting a host into maintenance mode is only implemented by the XenServer compute driver and it has been reported that it does not actually evacuate all of the guests from the host, it just sets a flag in the Xen management console, and is therefore useless. There are other APIs that allow you to do the same thing which are supported across all compute drivers, which would be disabling a service and then migrating the instances off that host. See the Operations Guide for more information on maintenance.

Normal response codes: 200

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

Request

Name

In

Type

Description

host_name

path

string

The name of the host.

status (Optional)

body

string

The status of the host, either enable or disable.

maintenance_mode (Optional)

body

string

Mode of maintenance state, either enable or disable.

Example Enable Host: JSON request

{
    "status": "enable",
    "maintenance_mode": "disable"
}

Response

Name

In

Type

Description

host

body

string

The name of the host.

status (Optional)

body

string

The status of the current host, either enabled or disabled.

maintenance_mode (Optional)

body

string

Mode of maintenance state, either on_maintenance or off_maintenance.

Example Enable Host

{
    "host": "65c5d5b7e3bd44308e67fc50f362aee6",
    "maintenance_mode": "off_maintenance",
    "status": "enabled"
}
GET
/os-hosts/{host_name}/reboot

Reboot Host

Reboots a host.

Warning

This is only supported by the XenServer and Hyper-v drivers. The backing drivers do no orchestration of dealing with guests in the nova database when performing a reboot of the host. The nova-compute service for that host may be temporarily disabled by the service group health check which would take it out of scheduling decisions, and the guests would be down, but the periodic task which checks for unexpectedly stopped instances runs in the nova-compute service, which might be dead now so the nova API would show the instances as running when in fact they are actually stopped. This API is also not tested in a live running OpenStack environment. Needless to say, it is not recommended to use this API and it is deprecated as of the 2.43 microversion.

Normal response codes: 200

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

Request

Name

In

Type

Description

host_name

path

string

The name of the host.

Response

Name

In

Type

Description

host

body

string

The name of the host.

power_action

body

string

The power action on the host.

Example Reboot Host: JSON response

{
    "host": "9557750dbc464741a89c907921c1cb31",
    "power_action": "reboot"
}
GET
/os-hosts/{host_name}/shutdown

Shut Down Host

Shuts down a host.

Warning

This is only supported by the XenServer and Hyper-v drivers. The backing drivers do no orchestration of dealing with guests in the nova database when performing a shutdown of the host. The nova-compute service for that host may be temporarily disabled by the service group health check which would take it out of scheduling decisions, and the guests would be down, but the periodic task which checks for unexpectedly stopped instances runs in the nova-compute service, which might be dead now so the nova API would show the instances as running when in fact they are actually stopped. This API is also not tested in a live running OpenStack environment. Needless to say, it is not recommended to use this API and it is deprecated as of the 2.43 microversion.

Normal response codes: 200

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

Request

Name

In

Type

Description

host_name

path

string

The name of the host.

Response

Name

In

Type

Description

host

body

string

The name of the host.

power_action

body

string

The power action on the host.

Example Shut Down Host

{
    "host": "77cfa0002e4d45fe97f185968111b27b",
    "power_action": "shutdown"
}
GET
/os-hosts/{host_name}/startup

Start Host

Starts a host.

Warning

This is not implemented by any in-tree compute drivers and therefore will always fail with a 501 NotImplemented error. Needless to say, it is not recommended to use this API and it is deprecated as of the 2.43 microversion.

Normal response codes: 200

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

Request

Name

In

Type

Description

host_name

path

string

The name of the host.

Response

Name

In

Type

Description

host

body

string

The name of the host.

power_action

body

string

The power action on the host.

Example Start Host

{
    "host": "4b392b27930343bbaa27fd5d8328a564",
    "power_action": "startup"
}

Obsolete APIs

This section contains the reference for APIs that were part of the OpenStack Compute API in the past, but no longer exist.

Root certificates (os-certificates)

Creates and shows details for a root certificate.

Warning

This API existed solely because of the need to build euca bundles when Nova had an in tree EC2 API. It no longer interacts with any parts of the system besides its own certificate daemon. It was removed in the 16.0.0 Pike release.

POST
/os-certificates

Create Root Certificate

Creates a root certificate.

Normal response codes: 200

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

Response

Name

In

Type

Description

certificate

body

object

The certificate object.

data

body

string

The certificate.

private_key

body

string

The secret key.


Example Create Root Certificate

{
    "certificate": {
        "data": "Certificate:\n    Data:\n        Version: 1 (0x0)\n        Serial Number: 1018 (0x3fa)\n    Signature Algorithm: md5WithRSAEncryption\n        Issuer: O=NOVA ROOT, L=Mountain View, ST=California, C=US\n        Validity\n            Not Before: Aug 12 07:20:30 2013 GMT\n            Not After : Aug 12 07:20:30 2014 GMT\n        Subject: C=US, ST=California, O=OpenStack, OU=NovaDev, CN=openstack-fake-2013-08-12T07:20:30Z\n        Subject Public Key Info:\n            Public Key Algorithm: rsaEncryption\n                Public-Key: (1024 bit)\n                Modulus:\n                    00:ac:ff:b1:d1:ed:54:4e:35:6c:34:b4:8f:0b:04:\n                    50:25:a3:e2:4f:02:4c:4f:26:59:bd:f3:fd:eb:da:\n                    18:c2:36:aa:63:42:72:1f:88:4f:3a:ec:e7:9f:8e:\n                    44:2a:d3:b8:94:7b:20:41:f8:48:02:57:91:4c:16:\n                    62:f1:21:d4:f2:40:b5:86:50:d9:61:f0:be:ff:d8:\n                    8d:9f:4b:aa:6a:07:38:a2:7f:87:21:fc:e6:6e:1d:\n                    0a:95:1a:90:0e:60:c2:24:e9:8e:e8:68:1b:e9:f3:\n                    c6:b0:7c:da:c5:20:66:9b:85:ea:f5:c9:a7:de:ee:\n                    16:b1:51:a0:4d:e3:95:98:df\n                Exponent: 65537 (0x10001)\n    Signature Algorithm: md5WithRSAEncryption\n         15:42:ca:71:cc:32:af:dc:cf:45:91:df:8a:b8:30:c4:7f:78:\n         80:a7:25:c2:d9:81:3e:b3:dd:22:cc:3b:f8:94:e7:8f:04:f6:\n         93:04:9e:85:d4:10:40:ff:5a:07:47:24:b5:ae:93:ad:8d:e1:\n         e6:54:4a:8d:4a:29:53:c4:8d:04:6b:0b:f6:af:38:78:02:c5:\n         05:19:89:82:2d:ba:fd:11:3c:1e:18:c9:0c:3d:03:93:6e:bc:\n         66:70:34:ee:03:78:8a:1d:3d:64:e8:20:2f:90:81:8e:49:1d:\n         07:37:15:66:42:cb:58:39:ad:56:ce:ed:47:c6:78:0b:0e:75:\n         29:ca\n-----BEGIN CERTIFICATE-----\nMIICNDCCAZ0CAgP6MA0GCSqGSIb3DQEBBAUAME4xEjAQBgNVBAoTCU5PVkEgUk9P\nVDEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzETMBEGA1UECBMKQ2FsaWZvcm5pYTEL\nMAkGA1UEBhMCVVMwHhcNMTMwODEyMDcyMDMwWhcNMTQwODEyMDcyMDMwWjB2MQsw\nCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTESMBAGA1UECgwJT3BlblN0\nYWNrMRAwDgYDVQQLDAdOb3ZhRGV2MSwwKgYDVQQDDCNvcGVuc3RhY2stZmFrZS0y\nMDEzLTA4LTEyVDA3OjIwOjMwWjCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA\nrP+x0e1UTjVsNLSPCwRQJaPiTwJMTyZZvfP969oYwjaqY0JyH4hPOuznn45EKtO4\nlHsgQfhIAleRTBZi8SHU8kC1hlDZYfC+/9iNn0uqagc4on+HIfzmbh0KlRqQDmDC\nJOmO6Ggb6fPGsHzaxSBmm4Xq9cmn3u4WsVGgTeOVmN8CAwEAATANBgkqhkiG9w0B\nAQQFAAOBgQAVQspxzDKv3M9Fkd+KuDDEf3iApyXC2YE+s90izDv4lOePBPaTBJ6F\n1BBA/1oHRyS1rpOtjeHmVEqNSilTxI0Eawv2rzh4AsUFGYmCLbr9ETweGMkMPQOT\nbrxmcDTuA3iKHT1k6CAvkIGOSR0HNxVmQstYOa1Wzu1HxngLDnUpyg==\n-----END CERTIFICATE-----\n",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIICXgIBAAKBgQCs/7HR7VRONWw0tI8LBFAlo+JPAkxPJlm98/3r2hjCNqpjQnIf\niE867OefjkQq07iUeyBB+EgCV5FMFmLxIdTyQLWGUNlh8L7/2I2fS6pqBziif4ch\n/OZuHQqVGpAOYMIk6Y7oaBvp88awfNrFIGabher1yafe7haxUaBN45WY3wIDAQAB\nAoGBAIrcr2I/KyWf0hw4Nn10V9TuyE/9Gz2JHg3QFKjFJox2DqygADT5WAeHc6Bq\nNKNf0NA2SL1LSpm+ql01tvOw4VjE5TF6OHiIzHuTTnXggG6vuA8rxp6L24HtkAcC\n0CBno9ggSX6jVornJPBfxpkwITYSvH57BUFVD7ovbPyWGzS5AkEA1JeUtL6zxwps\nWRr1aJ8Ill2uQk/RUIvSZOU61s+B190zvHikFy8LD8CI6vvBmjC/IZuZVedufjqs\n4vX82uDO3QJBANBSh2b2dyB4AGVFY9vXMRtALAspJHbLHy+zTKxlGPFiuz7Se3ps\n8Kehz4C/CBXgQkk194dwFSGE19/PQfyJROsCQQCFFDJZhrtBUMwMZ2zSRiN5BUGt\nbwuncS+OS1Su3Yz5VRYq2BZYEPHKtYrAFkLWQ8eRwTaWaN5pFE/fb38OgQXdAkA4\nDm0W/K0zlHbuyUxEpNQ28/6mBi0ktiWvLT0tioq6sYmXLwZA/D2JrhXrG/xt/ol3\nr8jqrfNRsLByLhAgh0N/AkEAl2eR0O97lTEgFNqzIQwVmIAn9mBO3cnf3tycvlDU\nm6eb2CS242y4QalfCCAEjxoJURdfsm3/D1iFo00X+IWF+A==\n-----END RSA PRIVATE KEY-----\n"
    }
}
GET
/os-certificates/root

Show Root Certificate Details

Shows details for a root certificate.

Normal response codes: 200

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

Response

Name

In

Type

Description

certificate

body

object

The certificate object.

data

body

string

The certificate.

private_key

body

string

The secret key.


Example Show Root Certificate Details

{
    "certificate": {
        "data": "-----BEGIN CERTIFICATE-----\nMIICyzCCAjSgAwIBAgIJAJ8zSIxUp/m4MA0GCSqGSIb3DQEBBAUAME4xEjAQBgNV\nBAoTCU5PVkEgUk9PVDEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzETMBEGA1UECBMK\nQ2FsaWZvcm5pYTELMAkGA1UEBhMCVVMwHhcNMTIxMDE3MDEzMzM5WhcNMTMxMDE3\nMDEzMzM5WjBOMRIwEAYDVQQKEwlOT1ZBIFJPT1QxFjAUBgNVBAcTDU1vdW50YWlu\nIFZpZXcxEzARBgNVBAgTCkNhbGlmb3JuaWExCzAJBgNVBAYTAlVTMIGfMA0GCSqG\nSIb3DQEBAQUAA4GNADCBiQKBgQDXW4QfQQxJG4MqurqK8nU/Lge0mfNKxXj/Gwvg\n2sQVwxzmKfoxih8Nn6yt0yHMNjhoji1UoWI03TXUnPZRAZmsypGKZeBd7Y1ZOCPB\nXGZVGrQm+PB2kZU+3cD8fVKcueMLLeZ+LRt5d0njnoKhc5xjqMlfFPimHMba4OL6\nTnYzPQIDAQABo4GwMIGtMAwGA1UdEwQFMAMBAf8wHQYDVR0OBBYEFKyoKu4SMOFM\ngx5Ec7p0nrCkabvxMH4GA1UdIwR3MHWAFKyoKu4SMOFMgx5Ec7p0nrCkabvxoVKk\nUDBOMRIwEAYDVQQKEwlOT1ZBIFJPT1QxFjAUBgNVBAcTDU1vdW50YWluIFZpZXcx\nEzARBgNVBAgTCkNhbGlmb3JuaWExCzAJBgNVBAYTAlVTggkAnzNIjFSn+bgwDQYJ\nKoZIhvcNAQEEBQADgYEAXuvXlu1o/SVvykSLhHW8QiAY00yzN/eDzYmZGomgiuoO\n/x+ayVzbrz1UWZnBD+lC4hll2iELSmf22LjLoF+s/9NyPqHxGL3FrfatBkndaiF8\nAx/TMEyCPl7IQWi+3zzatqOKHSHiG7a9SGn/7o2aNTIWKVulfy5GvmbBjBM/0UE=\n-----END CERTIFICATE-----\n",
        "private_key": null
    }
}

Cloudpipe (os-cloudpipe)

Warning

This API only works with nova-network which is deprecated in favor of Neutron. It should be avoided in any new applications. It was removed in the 16.0.0 Pike release.

Manages virtual VPNs for projects.

GET
/os-cloudpipe

List Cloudpipes

Lists cloudpipes.

Normal response codes: 200

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

Response

Name

In

Type

Description

cloudpipes

body

array

The list of cloudpipe objects.

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.

instance_id

body

string

The UUID of the cloudpipe instance.

internal_ip (Optional)

body

string

A fixed IPv4 address for the NIC. Valid with a neutron or nova-networks network.

project_id

body

string

The ID of the project that this server belongs to.

public_ip (Optional)

body

string

The VPN public IP address.

public_port (Optional)

body

string

The VPN public port.

state (Optional)

body

string

The VPN state.

Example List Cloudpipes: JSON response

{
    "cloudpipes": [
        {
            "created_at": "2012-11-27T17:18:01Z",
            "instance_id": "27deecdb-baa3-4a26-9c82-32994b815b01",
            "internal_ip": "192.168.1.30",
            "project_id": "fa1765bd-a352-49c7-a6b7-8ee108a3cb0c",
            "public_ip": "127.0.0.1",
            "public_port": 22,
            "state": "down"
        }
    ]
}
POST
/os-cloudpipe

Create Cloudpipe

Creates a cloudpipe.

Normal response codes: 200

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

Request

Name

In

Type

Description

cloudpipe

body

object

The cloudpipe object.

project_id (Optional)

body

string

The UUID of the project. If omitted, the project ID defaults to the calling tenant.

Example Create Cloudpipe: JSON request

{
    "cloudpipe": {
        "project_id": "059f21e3-c20e-4efc-9e7a-eba2ab3c6f9a"
    }
}

Response

Name

In

Type

Description

instance_id

body

string

The UUID of the cloudpipe instance.

Example Create Cloudpipe: JSON response

{
    "instance_id": "1e9b8425-34af-488e-b969-4d46f4a6382e"
}
PUT
/os-cloudpipe/configure-project

Update Cloudpipe

Updates the virtual private network (VPN) IP address and port for a cloudpipe instance.

Normal response codes: 202

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

Request

Name

In

Type

Description

configure_project

body

object

VPN IP and Port information to configure the cloudpipe instance..

vpn_ip

body

string

The VPN IP address.

vpn_port

body

string

The VPN port.

Example Update Cloudpipe: JSON request

{
    "configure_project": {
        "vpn_ip": "192.168.1.1",
        "vpn_port": "2000"
    }
}

Response

There is no body content for the response of a successful PUT request

Ping instances (os-fping)

Warning

This API only works with nova-network which is deprecated. It should be avoided in any new applications. These will fail with a 404 starting from microversion 2.36. It was removed in the 18.0.0 Rocky release.

Pings instances and reports which instances are alive.

GET
/os-fping

Ping Instances

Runs the fping utility to ping instances and reports which instances are alive.

Specify the all_tenants=1 query parameter to ping instances for all tenants. For example:

GET /os-fping?all_tenants=1

Specify the include and exclude query parameters to filter the results. For example:

GET /os-fping?all_tenants=1&include=uuid1,uuid2&exclude=uuid3,uuid4

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

Error response codes: serviceUnavailable(503), unauthorized(401), forbidden(403), itemNotFound(404), gone(410)

Request

Name

In

Type

Description

all_tenants (Optional)

query

string

Specify the all_tenants query parameter to ping instances for all tenants. By default this is only allowed by admin users. Value of this query parameter is not checked, only presence is considered as request for all tenants.

include (Optional)

query

string

Specify include=uuid[,uuid...] to include the instances in the results.

exclude (Optional)

query

string

Specify exclude=uuid[,uuid...] to exclude the instances from the results.

Response

Name

In

Type

Description

servers

body

array

A list of server objects.

alive

body

boolean

Returns true if the instance is alive.

id

body

string

The UUID of the server.

project_id (Optional)

body

string

The UUID of the project. If omitted, the project ID defaults to the calling tenant.


Example Ping Instances

{
    "servers": [
        {
            "alive": false,
            "id": "1d1aea35-472b-40cf-9337-8eb68480aaa1",
            "project_id": "6f70656e737461636b20342065766572"
        }
    ]
}
GET
/os-fping/{instance_id}

Ping An Instance

Runs the fping utility to ping an instance and reports whether the instance is alive.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

Error response codes: serviceUnavailable(503), unauthorized(401), forbidden(403), itemNotFound(404), gone(410)

Request

Name

In

Type

Description

instance_id

path

string

The UUID of the instance.

Response

Name

In

Type

Description

server

body

object

A server object.

alive

body

boolean

Returns true if the instance is alive.

id

body

string

The UUID of the server.

project_id (Optional)

body

string

The UUID of the project. If omitted, the project ID defaults to the calling tenant.


Example Ping An Instance

{
    "server": {
        "alive": false,
        "id": "f5e6fd6d-c0a3-4f9e-aabf-d69196b6d11a",
        "project_id": "6f70656e737461636b20342065766572"
    }
}

Servers virtual interfaces (servers, os-virtual-interfaces)

Lists virtual interfaces for a server.

Warning

Since this API is only implemented for the nova-network, the API is deprecated from the Microversion 2.44. This API will fail with a 404 starting from microversion 2.44. It was removed in the 18.0.0 Rocky release.

To query the server attached neutron interface, please use the API GET /servers/{server_uuid}/os-interface.

Note

This API is only implemented for the nova-network service and will result in a 400 error response if the cloud is using the Neutron networking service. Use the Neutron ports API to list ports for a given server by filtering ports based on the port device_id which is the {server_id}.

GET
/servers/{server_id}/os-virtual-interfaces

List Virtual Interfaces

Lists the virtual interfaces for an instance.

Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Change these permissions through the policy.json file.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name

In

Type

Description

virtual_interfaces

body

array

An array of virtual interfaces.

id

body

string

The UUID of the virtual interface.

mac_address

body

string

The MAC address.

net_id

body

string

The network ID.

New in version 2.12

Note

The API v2 returns the network ID in the “OS-EXT-VIF-NET:net_id” response attribute. But API v2.1 base version does not return the network ID. Network ID has been added in v2.12 micro-version and returns it in the “net_id” attribute.

Example List Virtual Interfaces: JSON response

{
    "virtual_interfaces": [
        {
            "id": "cec8b9bb-5d22-4104-b3c8-4c35db3210a6",
            "mac_address": "fa:16:3e:3c:ce:6f",
            "net_id": "cec8b9bb-5d22-4104-b3c8-4c35db3210a7"
        }
    ]
}

Fixed IPs (os-fixed-ips)

Warning

These APIs only work with nova-network which is deprecated. These will fail with a 404 starting from microversion 2.36. They were removed in the 18.0.0 Rocky release.

Shows data for a fixed IP, such as host name, CIDR, and address. Also, reserves and releases a fixed IP address.

GET
/os-fixed-ips/{fixed_ip}

Show Fixed Ip Details

Shows details for a fixed IP address.

Normal response codes: 200

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

Request

Name

In

Type

Description

fixed_ip

path

string

The fixed IP of interest to you.

Response

Name

In

Type

Description

fixed_ip

body

object

A fixed IP address object.

address

body

string

The IP address.

cidr

body

string

The CIDR for address range.

host

body

string

The hostname of the host that manages the server that is associated with this fixed IP address.

hostname

body

string

The hostname of the server that is associated with this fixed IP address.

reserved

body

boolean

True if the fixed ip is reserved, otherwise False.

New in version 2.4

Example Show Fixed Ip Details: JSON response

{
    "fixed_ip": {
        "address": "192.168.1.1",
        "cidr": "192.168.1.0/24",
        "host": "host",
        "hostname": "compute.host.pvt"
    }
}
POST
/os-fixed-ips/{fixed_ip}/action

Reserve Or Release A Fixed Ip

Reserves or releases a fixed IP.

To reserve a fixed IP address, specify reserve in the request body. To release a fixed IP address, specify unreserve in the request body.

Normal response codes: 202

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

Request

Name

In

Type

Description

fixed_ip

path

string

The fixed IP of interest to you.

reserve (Optional)

body

string

The attribute to reserve an IP with a value of null.

unreserve (Optional)

body

string

The attribute to release an IP with a value of null.

Example Reserve Or Release A Fixed Ip: JSON request

{
    "reserve": null
}

Response

There is no body content for the response of a successful POST operation.

Floating IPs bulk (os-floating-ips-bulk)

Warning

Since these APIs are only implemented for nova-network, they are deprecated. These will fail with a 404 starting from microversion 2.36. They were removed in the 18.0.0 Rocky release.

Bulk-creates, deletes, and lists floating IPs. Default pool name is nova.

To view available pools, use the os-floating-ip-pools extension.

GET
/os-floating-ips-bulk

List Floating Ips

Lists all floating IPs.

Normal response codes: 200

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

Response

Name

In

Type

Description

floating_ip_info

body

array

An array of floating ip objects.

address

body

string

The floating ip address.

fixed_ip

body

string

Fixed IP associated with floating IP network.

instance_uuid

body

string

The UUID of the server.

interface

body

string

Virtual interface for the floating ip address.

pool

body

string

The name of the floating IP pool.

project_id

body

string

The project id under which the bulk ip addresses are created

Example List Floating Ips: JSON response

{
    "floating_ip_info": [
        {
            "address": "10.10.10.1",
            "instance_uuid": null,
            "fixed_ip": null,
            "interface": "eth0",
            "pool": "nova",
            "project_id": null
        },
        {
            "address": "10.10.10.2",
            "instance_uuid": null,
            "fixed_ip": null,
            "interface": "eth0",
            "pool": "nova",
            "project_id": null
        },
        {
            "address": "10.10.10.3",
            "instance_uuid": null,
            "fixed_ip": null,
            "interface": "eth0",
            "pool": "nova",
            "project_id": null
        }
    ]
}
POST
/os-floating-ips-bulk

Create Floating Ips

Bulk-creates floating IPs.

Normal response codes: 200

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

Request

Name

In

Type

Description

floating_ips_bulk_create

body

object

The floating ip bulk address object.

ip_range

body

string

The range of IP addresses to use for creating floating IPs.

interface (Optional)

body

string

Virtual interface for the floating ip address

pool (Optional)

body

string

The name of the floating IP pool

Example Create Floating Ips: JSON request

{
    "floating_ips_bulk_create": {
        "ip_range": "192.168.1.0/24",
        "pool": "nova",
        "interface": "eth0"
    }
}

Response

Name

In

Type

Description

floating_ips_bulk_create

body

object

The floating ip bulk address object.

interface

body

string

Virtual interface for the floating ip address.

ip_range

body

string

The range of IP addresses to use for creating floating IPs.

pool

body

string

The name of the floating IP pool.

Example Create Floating Ips: JSON response

{
    "floating_ips_bulk_create": {
        "interface": "eth0",
        "ip_range": "192.168.1.0/24",
        "pool": "nova"
    }
}
PUT
/os-floating-ips-bulk/delete

Bulk-Delete Floating Ips

Bulk-deletes floating IPs.

Normal response codes: 200

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

Request

Name

In

Type

Description

ip_range

body

string

The range of IP addresses from which to bulk-delete floating IPs.

Example Bulk-Delete Floating Ips: JSON request

{
    "ip_range": "192.168.1.0/24"
}

Response

Name

In

Type

Description

floating_ips_bulk_delete

body

string

The range of IP addresses from which to bulk-delete floating IPs.

Example Bulk-Delete Floating Ips: JSON response

{
    "floating_ips_bulk_delete": "192.168.1.0/24"
}
GET
/os-floating-ips-bulk/{host_name}

List Floating Ips By Host

Lists all floating IPs for a host.

Normal response codes: 200

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

Request

Name

In

Type

Description

host_name

path

string

The name of the host.

Response

Name

In

Type

Description

floating_ip_info

body

array

An array of floating ip objects.

address

body

string

The floating ip address.

fixed_ip

body

string

Fixed IP associated with floating IP network.

instance_uuid

body

string

The UUID of the server.

interface

body

string

Virtual interface for the floating ip address.

pool

body

string

The name of the floating IP pool.

project_id

body

string

The project id under which the bulk ip addresses are created

Example List Floating Ips By Host: JSON response

{
    "floating_ip_info": [
        {
            "address": "10.10.10.3",
            "instance_uuid": null,
            "fixed_ip": null,
            "interface": "eth0",
            "pool": "nova",
            "project_id": null
        }
    ]
}

Floating IP DNS records (os-floating-ip-dns)

Warning

Since these APIs are only implemented for nova-network, they are deprecated. These will fail with a 404 starting from microversion 2.36. They were removed in the 18.0.0 Rocky release.

Manages DNS records associated with floating IP addresses. The API dispatches requests to a DNS driver that is selected at startup.

GET
/os-floating-ip-dns

List DNS Domains

Lists registered DNS domains published by the DNS drivers.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), gone(410), notImplemented(501)

Response

Example List Dns Domains: JSON response

{
    "domain_entries": [
        {
            "availability_zone": null,
            "domain": "domain1.example.org",
            "project": "project1",
            "scope": "public"
        }
    ]
}
PUT
/os-floating-ip-dns/{domain}

Create Or Update DNS Domain

Creates or updates a DNS domain.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), gone(410), notImplemented(501)

Request

Name

In

Type

Description

domain

path

string

The registered DNS domain that the DNS drivers publish.

Example Create Or Update Dns Domain: JSON request

{
    "domain_entry": {
        "scope": "public",
        "project": "project1"
    }
}

Response

Example Create Or Update Dns Domain: JSON response

{
    "domain_entry": {
        "availability_zone": null,
        "domain": "domain1.example.org",
        "project": "project1",
        "scope": "public"
    }
}
DELETE
/os-floating-ip-dns/{domain}

Delete DNS Domain

Deletes a DNS domain and all associated host entries.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

domain

path

string

The registered DNS domain that the DNS drivers publish.

Response

GET
/os-floating-ip-dns/{domain}/entries/{ip}

List DNS Entries

Lists DNS entries for a domain and IP.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

domain

path

string

The registered DNS domain that the DNS drivers publish.

ip

path

string

The IP address.

Response

Example List DNS Entries: JSON response

{
    "dns_entries": [
        {
            "domain": "domain1.example.org",
            "id": null,
            "ip": "192.168.1.1",
            "name": "instance1",
            "type": null
        }
    ]
}
GET
/os-floating-ip-dns/{domain}/entries/{name}

Find Unique DNS Entry

Finds a unique DNS entry for a domain and name.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

domain

path

string

The registered DNS domain that the DNS drivers publish.

name

body

string

The security group name.

Response

Example Find Unique DNS Entry: JSON response

{
    "dns_entry": {
        "domain": "domain1.example.org",
        "id": null,
        "ip": "192.168.1.1",
        "name": "instance1",
        "type": null
    }
}
PUT
/os-floating-ip-dns/{domain}/entries/{name}

Create Or Update DNS Entry

Creates or updates a DNS entry.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), gone(410), notImplemented(501)

Request

Name

In

Type

Description

domain

path

string

The registered DNS domain that the DNS drivers publish.

name

body

string

The security group name.

Example Create Or Update DNS Entry: JSON request

{
    "dns_entry": {
        "ip": "192.168.53.11",
        "dns_type": "A"
    }
}

Response

Example Create Or Update DNS Entry: JSON response

{
    "dns_entry": {
        "domain": "domain1.example.org",
        "id": null,
        "ip": "192.168.1.1",
        "name": "instance1",
        "type": "A"
    }
}
DELETE
/os-floating-ip-dns/{domain}/entries/{name}

Delete DNS Entry

Deletes a DNS entry.

Normal response codes: 202

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Request

Name

In

Type

Description

domain

path

string

The registered DNS domain that the DNS drivers publish.

name

body

string

The security group name.

Response

Cells (os-cells, capacities)

Adds neighbor cells, lists neighbor cells, and shows the capabilities of the local cell. By default, only administrators can manage cells.

Warning

These APIs refer to a Cells v1 deployment which was deprecated in the 16.0.0 Pike release. These are not used with Cells v2 which is required beginning with the 15.0.0 Ocata release where all Nova deployments consist of at least one Cells v2 cell. They were removed in the 20.0.0 Train release.

GET
/os-cells

List Cells

Lists cells.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), gone(410), notImplemented(501)

Request

Name

In

Type

Description

tenant_id

path

string

The UUID of the tenant in a multi-tenancy cloud.

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Example List Cells: JSON response

{
    "cells": [
        {
            "name": "cell1",
            "rpc_host": null,
            "rpc_port": null,
            "type": "child",
            "username": "username1"
        },
        {
            "name": "cell3",
            "rpc_host": null,
            "rpc_port": null,
            "type": "child",
            "username": "username3"
        },
        {
            "name": "cell5",
            "rpc_host": null,
            "rpc_port": null,
            "type": "child",
            "username": "username5"
        },
        {
            "name": "cell2",
            "rpc_host": null,
            "rpc_port": null,
            "type": "parent",
            "username": "username2"
        },
        {
            "name": "cell4",
            "rpc_host": null,
            "rpc_port": null,
            "type": "parent",
            "username": "username4"
        }
    ]
}
POST
/os-cells

Create Cell

Create a new cell.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), gone(410), notImplemented(501)

GET
/os-cells/capacities

Capacities

Retrieve capacities.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), gone(410), notImplemented(501)

GET
/os-cells/detail

List Cells With Details

Lists cells with details of capabilities.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), gone(410), notImplemented(501)

Request

Name

In

Type

Description

limit (Optional)

query

integer

Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.

offset (Optional)

query

integer

Used in conjunction with limit to return a slice of items. offset is where to start in the list.

GET
/os-cells/info

Info For This Cell

Retrieve info about the current cell.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), gone(410), notImplemented(501)

GET
/os-cells/{cell_id}

Show Cell Data

Shows data for a cell.

Normal response codes: 200

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

Request

Name

In

Type

Description

cell_id

path

string

The UUID of the cell.

Response

Example Show Cell Data: JSON response

{
    "cell": {
        "name": "cell3",
        "rpc_host": null,
        "rpc_port": null,
        "type": "child",
        "username": "username3"
    }
}
PUT
/os-cells/{cell_id}

Update a Cell

Update an existing cell.

Normal response codes: 200

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

Request

Name

In

Type

Description

cell_id

path

string

The UUID of the cell.

DELETE
/os-cells/{cell_id}

Delete a Cell

Remove a cell.

Normal response codes: 200

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

Request

Name

In

Type

Description

cell_id

path

string

The UUID of the cell.

GET
/os-cells/{cell_id}/capacities

Show Cell Capacities

Shows capacities for a cell.

Normal response codes: 200

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

Request

Name

In

Type

Description

cell_id

path

string

The UUID of the cell.

Response

Example Show Cell Capacities: JSON response

{
    "cell": {
        "capacities": {
            "disk_free": {
                "total_mb": 1052672,
                "units_by_mb": {
                    "0": 0,
                    "163840": 5,
                    "20480": 46,
                    "40960": 23,
                    "81920": 11
                }
            },
            "ram_free": {
                "total_mb": 7680,
                "units_by_mb": {
                    "16384": 0,
                    "2048": 3,
                    "4096": 1,
                    "512": 13,
                    "8192": 0
                }
            }
        }
    }
}

XenServer VNC Proxy (XVP) consoles (os-consoles)

Manages server XVP consoles.

Warning

These APIs are only applicable when using the XenServer virt driver. They were removed in the 21.0.0 (Ussuri) release.

GET
/servers/{server_id}/consoles

Lists Consoles

Lists all consoles for a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

Name

In

Type

Description

consoles

body

array

The list of console objects.

console

body

object

The console object.

console_type

body

string

The type of the console.

id

body

string

The UUID of the console.


Example List Consoles

{
    "consoles": [
        {
            "console": {
                "console_type": "fake",
                "id": 1
            }
        }
    ]
}
POST
/servers/{server_id}/consoles

Create Console

Creates a console for a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

Response

If successful, this method does not return a response body.

GET
/servers/{server_id}/consoles/{console_id}

Show Console Details

Shows console details for a server.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

console_id

path

string

The UUID of the console.

Response

Name

In

Type

Description

console

body

object

The console object.

console_type

body

string

The type of the console.

host (Optional)

body

string

The name or ID of the host.

id

body

string

The UUID of the console.

instance_name

body

string

The name of the instance.

password

body

string

The password for the console.

port

body

integer

The port number.


Example Show Console Details

{
    "console": {
        "console_type": "fake",
        "host": "fake",
        "id": 1,
        "instance_name": "instance-00000001",
        "password": "C4jBpJ6x",
        "port": 5999
    }
}
DELETE
/servers/{server_id}/consoles/{console_id}

Delete Console

Deletes a console for a server.

Normal response codes: 202

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

console_id

path

string

The UUID of the console.

Response

If successful, this method does not return a response body.

Rules for default security group (os-security-group-default-rules)

Warning

This API only available with nova-network which is deprecated. It should be avoided in any new applications. These will fail with a 404 starting from microversion 2.36. They were completely removed in the 21.0.0 (Ussuri) release.

Lists, shows information for, and creates default security group rules.

GET
/os-security-group-default-rules

List Default Security Group Rules

Lists default security group rules.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), gone(410), notImplemented(501)

Response

Name

In

Type

Description

security_group_default_rules

body

array

A list of the security_group_default_rule object.

from_port

body

integer

The port at start of range.

id

body

string

The security group default rule ID.

ip_protocol

body

string

The IP protocol. A valid value is ICMP, TCP, or UDP.

ip_range

body

object

An IP range object. Includes the security group rule cidr.

ip_range.cidr (Optional)

body

string

The CIDR for address range.

to_port

body

integer

The port at end of range.

Example List default security group rules: JSON response

{
    "security_group_default_rules": [
        {
            "from_port": 80,
            "id": 1,
            "ip_protocol": "TCP",
            "ip_range": {
                "cidr": "10.10.10.0/24"
            },
            "to_port": 80
        }
    ]
}
GET
/os-security-group-default-rules/{security_group_default_rule_id}

Show Default Security Group Rule Details

Shows details for a security group rule.

Normal response codes: 200

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

Request

Name

In

Type

Description

security_group_default_rule_id

path

string

The UUID of the security group rule.

Response

Name

In

Type

Description

security_group_default_rule

body

object

A security_group_default_rule object.

from_port

body

integer

The port at start of range.

id

body

string

The security group default rule ID.

ip_protocol

body

string

The IP protocol. A valid value is ICMP, TCP, or UDP.

ip_range

body

object

An IP range object. Includes the security group rule cidr.

ip_range.cidr (Optional)

body

string

The CIDR for address range.

to_port

body

integer

The port at end of range.

Example Show default security group rule: JSON response

{
    "security_group_default_rule": {
        "from_port": 80,
        "id": 1,
        "ip_protocol": "TCP",
        "ip_range": {
            "cidr": "10.10.10.0/24"
        },
        "to_port": 80
    }
}
POST
/os-security-group-default-rules

Create Default Security Group Rule

Creates a default security group rule.

If you specify a source port ( from_port ) or destination port ( to_port ) value, you must specify an IP protocol ( ip_protocol ) value. Otherwise, the operation returns the Bad Request (400) response code.

Normal response codes: 200

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

Request

Name

In

Type

Description

security_group_default_rule

body

object

A security_group_default_rule object.

ip_protocol

body

string

The IP protocol. A valid value is ICMP, TCP, or UDP.

from_port

body

integer

The port at start of range.

to_port

body

integer

The port at end of range.

cidr (Optional)

body

string

The CIDR for address range.

Example Create default security group rule: JSON request

{
    "security_group_default_rule": {
        "ip_protocol": "TCP",
        "from_port": "80",
        "to_port": "80",
        "cidr": "10.10.10.0/24"
    }
}

Response

Name

In

Type

Description

security_group_default_rule

body

object

A security_group_default_rule object.

from_port

body

integer

The port at start of range.

id

body

string

The security group default rule ID.

ip_protocol

body

string

The IP protocol. A valid value is ICMP, TCP, or UDP.

ip_range

body

object

An IP range object. Includes the security group rule cidr.

ip_range.cidr (Optional)

body

string

The CIDR for address range.

to_port

body

integer

The port at end of range.

Example Create default security group rule: JSON response

{
    "security_group_default_rule": {
        "from_port": 80,
        "id": 1,
        "ip_protocol": "TCP",
        "ip_range": {
            "cidr": "10.10.10.0/24"
        },
        "to_port": 80
    }
}
DELETE
/os-security-group-default-rules/{security_group_default_rule_id}

Delete Default Security Group Rule

Deletes a security group rule.

Normal response codes: 204

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

Request

Name

In

Type

Description

security_group_default_rule_id

path

string

The UUID of the security group rule.

Response

Guest agents (os-agents)

Creates, lists, updates, and deletes guest agent builds. Use guest agents to access files on the disk, configure networking, or run other applications or scripts in the guest while the agent is running. This hypervisor-specific extension is currently only for the Xen driver. Use of guest agents is possible only if the underlying service provider uses the Xen driver.

Warning

These APIs only works with the Xen virt driver, which was deprecated in the 20.0.0 (Train) release. They were removed in the 22.0.0 (Victoria) release.

GET
/os-agents

List Agent Builds

Lists agent builds.

Normal response codes: 200

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

Request

Name

In

Type

Description

hypervisor (Optional)

query

string

Filters the response by a hypervisor type.

Response

Name

In

Type

Description

agents

body

array

A list of guest agent objects.

agent_id

body

integer

The agent ID.

architecture

body

string

The name of the cpu architecture.

hypervisor

body

string

The hypervisor type for the agent. Currently only xen is supported.

md5hash

body

string

The MD5 hash.

os

body

string

The name of the operating system.

url

body

string

The URL associated with the agent.

version

body

string

The version.

Example List Agent Builds: JSON response

{
    "agents": [
        {
            "agent_id": 1,
            "architecture": "x86",
            "hypervisor": "xen",
            "md5hash": "add6bb58e139be103324d04d82d8f545",
            "os": "os",
            "url": "http://example.com/path/to/resource",
            "version": "8.0"
        }
    ]
}
POST
/os-agents

Create Agent Build

Creates an agent build.

Normal response codes: 200

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

Request

Name

In

Type

Description

agent

body

object

The guest agent object.

hypervisor

body

string

The hypervisor type for the agent. Currently only xen is supported.

os

body

string

The name of the operating system.

architecture

body

string

The name of the cpu architecture.

version

body

string

The version.

md5hash

body

string

The MD5 hash.

url

body

string

The URL associated with the agent.

Example Create Agent Build: JSON request

{
    "agent": {
        "hypervisor": "xen",
        "os": "os",
        "architecture": "x86",
        "version": "8.0",
        "md5hash": "add6bb58e139be103324d04d82d8f545",
        "url": "http://example.com/path/to/resource"
    }
}

Response

Name

In

Type

Description

agent

body

object

The guest agent object.

agent_id

body

integer

The agent ID.

architecture

body

string

The name of the cpu architecture.

hypervisor

body

string

The hypervisor type for the agent. Currently only xen is supported.

md5hash

body

string

The MD5 hash.

os

body

string

The name of the operating system.

url

body

string

The URL associated with the agent.

version

body

string

The version.

Example Create Agent Build: JSON response

{
    "agent": {
        "agent_id": 1,
        "architecture": "x86",
        "hypervisor": "xen",
        "md5hash": "add6bb58e139be103324d04d82d8f545",
        "os": "os",
        "url": "http://example.com/path/to/resource",
        "version": "8.0"
    }
}
PUT
/os-agents/{agent_build_id}

Update Agent Build

Updates an agent build.

Normal response codes: 200

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

Request

Name

In

Type

Description

agent_build_id

path

string

The id of the agent build.

para

body

object

The parameter object.

url

body

string

The URL associated with the agent.

md5hash

body

string

The MD5 hash.

version

body

string

The version.

Example Update Agent Build: JSON request

{
    "para": {
        "url": "http://example.com/path/to/resource",
        "md5hash": "add6bb58e139be103324d04d82d8f545",
        "version": "7.0"
    }
}

Response

Name

In

Type

Description

agent

body

object

The guest agent object.

agent_id

body

string

The agent ID. (This is a bug of API, this should be integer type which is consistent with the responses of agent create and list. This will be fixed in later microversion.)

md5hash

body

string

The MD5 hash.

url

body

string

The URL associated with the agent.

version

body

string

The version.

Example Update Agent Build: JSON response

{
    "agent": {
        "agent_id": "1",
        "md5hash": "add6bb58e139be103324d04d82d8f545",
        "url": "http://example.com/path/to/resource",
        "version": "7.0"
    }
}
DELETE
/os-agents/{agent_build_id}

Delete Agent Build

Deletes an existing agent build.

Normal response codes: 200

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

Request

Name

In

Type

Description

agent_build_id

path

string

The id of the agent build.

Response

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

POST
/servers/{server_id}/action

Get RDP Console (os-getRDPConsole Action)

Gets an RDP console for a server.

Warning

Along with HyperV driver, this action was removed in Nova 29.0.0 (caracal) release.

The only supported connect type is rdp-html5. The type parameter should be set as rdp-html5.

Specify the os-getRDPConsole action in the request body.

Normal response codes: 200

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

Request

Name

In

Type

Description

server_id

path

string

The UUID of the server.

os-getRDPConsole

body

object

The action.

type

body

string

The type of RDP console. The only valid value is rdp-html5.

Example Get RDP Console (os-getRDPConsole Action)

{
    "os-getRDPConsole": {
        "type": "rdp-html5"
    }
}

Response

Name

In

Type

Description

console

body

object

The remote console object.

type

body

string

The type of RDP console. The only valid value is rdp-html5.

url

body

string

The URL used to connect to the RDP console.

Example Get RDP Console (os-getRDPConsole Action)

{
    "console": {
        "type": "rdp-html5",
        "url": "http://127.0.0.1:6083/?token=191996c3-7b0f-42f3-95a7-f1839f2da6ed"
    }
}