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-Versionheader, or since microversion 2.27 theOpenStack-API-Versionheader 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.
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:
|
updated |
body |
string |
This is a fixed string. It is 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"
}
]
}
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 |
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:
|
updated |
body |
string |
This is a fixed string. It is 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 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
maxPersonalityabsolute limit defines the maximum number of file path and content pairs that you can supply. The compute provider determines this value.The
maxPersonalitySizeabsolute 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.
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_filterspolicy rule. By default, the valid whitelist for non-admin users includeschanges-sinceflavorimageipip6(New in version 2.5)namenot-tags(New in version 2.26)not-tags-any(New in version 2.26)reservation_idstatustags(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 |
auto_disk_config (Optional) |
query |
string |
Filter the server list result by the
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 |
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 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. 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
|
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 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 |
locked_by (Optional) |
query |
string |
Filter the server list result by who locked the server, possible value
could be 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 |
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 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 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 |
sort_dir (Optional) |
query |
string |
Sort direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts by a server attribute. Default attribute is
|
status (Optional) |
query |
string |
Filters the response by a server status, as a string. For example, 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 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:
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 New in version 2.66 |
locked (Optional) |
query |
boolean |
Specify the New in version 2.73 |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
servers |
body |
array |
A list of |
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
|
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"
}
]
}
]
}
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
ACTIVEthrough 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
BUILDINGor 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 |
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 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 A bug has caused the 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 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 |
networks.fixed_ip (Optional) |
body |
string |
A fixed IPv4 address for the NIC. Valid with a |
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 |
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:
In microversion 2.32, A bug has caused the |
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 |
block_device_mapping_v2.delete_on_termination (Optional) |
body |
boolean |
To delete the boot volume when the server is destroyed, specify |
block_device_mapping_v2.destination_type (Optional) |
body |
string |
Defines where the block device mapping will reside. Valid values are:
|
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, |
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: |
block_device_mapping_v2.guest_format (Optional) |
body |
string |
Specifies the guest server disk file system format, such as Swap block device mappings have the following restrictions:
|
block_device_mapping_v2.no_device (Optional) |
body |
boolean |
It is no device if |
block_device_mapping_v2.source_type (Optional) |
body |
string |
The source type of the block device. Valid values are:
This parameter is required unless 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 |
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:
|
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
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 |
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 |
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
|
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
|
user_data (Optional) |
body |
string |
Configuration information or scripts to use upon launch. Must be Base64 encoded. Restricted to 65535 bytes. Note The |
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 New in version 2.90 |
tags (Optional) |
body |
array |
A list of tags. Tags have the following restrictions:
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
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:
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 (Optional) |
body |
string |
Schedule the server on a host in the network specified with an IP address
( |
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 |
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 |
os:scheduler_hints.group (Optional) |
body |
string |
The server group UUID. Schedule the server according to a policy of
the server group ( |
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 |
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 |
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 |
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 |
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:
|
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 |
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"
}
]
}
}
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 |
return_reservation_id (Optional) |
body |
boolean |
Set to |
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"
}
]
}
}
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 |
auto_disk_config (Optional) |
query |
string |
Filter the server list result by the
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 |
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 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. 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
|
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 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 |
locked_by (Optional) |
query |
string |
Filter the server list result by who locked the server, possible value
could be 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 |
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 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 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 |
sort_dir (Optional) |
query |
string |
Sort direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts by a server attribute. Default attribute is
|
status (Optional) |
query |
string |
Filters the response by a server status, as a string. For example, 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 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:
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 New in version 2.66 |
locked (Optional) |
query |
boolean |
Specify the New in version 2.73 |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
servers |
body |
array |
A list of |
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 |
config_drive |
body |
string |
Indicates whether or not a config drive was used for this server.
The value is |
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, |
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 |
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:
|
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 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, The |
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, |
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, |
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 |
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, |
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 |
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
|
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:
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 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"
}
]
}
]
}
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 |
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 |
config_drive |
body |
string |
Indicates whether or not a config drive was used for this server.
The value is |
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, |
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 |
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:
|
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 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, The |
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, |
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, |
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 |
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, |
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 |
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:
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 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"
}
]
}
}
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 |
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 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
|
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 |
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 |
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, |
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 |
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:
|
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, |
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 |
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, |
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 |
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 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 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 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, The 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, 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:
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"
}
}
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
deletingstatus 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.
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 |
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.
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.
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.
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:
If the server is running and networking works, a user with proper authority could reset the status of the server to
activeusing the Reset Server State (os-resetState Action) API.If the server is not running, you can try hard rebooting the server using the Reboot Server (reboot Action) API.
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.
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, |
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"
}
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"
}
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 |
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.
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.
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:
ACTIVEERRORHARD_REBOOTPAUSEDREBOOTSHUTOFFSUSPENDED
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 |
Example Reboot Server (reboot Action)
{
"reboot" : {
"type" : "HARD"
}
}
Response¶
If successful, this method does not return content in the response body.
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 |
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
|
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 ( 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 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 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 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 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 |
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, |
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.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:
|
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, |
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 |
progress (Optional) |
body |
integer |
A percentage value of the operation progress.
This parameter only appears when the server status is |
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 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 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 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, The 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, 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:
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"
}
}
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.
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.
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 |
Example Rescue server (rescue Action)
{
"adminPass": "MySecretPass"
}
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 |
OS-DCF:diskConfig (Optional) |
body |
string |
Controls how the API partitions the disk when you create, rebuild, or resize servers.
A server inherits the
|
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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"
}
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.
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.
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”. |
Unshelve body parameters
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 Since microversion 2.91 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.
Added 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.
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 |
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 |
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"
}
}
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 |
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 |
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"
}
}
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 |
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 |
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.
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.
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 |
host (Optional) |
body |
string |
The host to which to migrate the server. If you specify 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.
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 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 |
block_migration |
body |
boolean |
Set to Available until version 2.24 |
block_migration |
body |
string |
Migrates local disks by using block migration. Set to New in version 2.25 |
disk_over_commit |
body |
boolean |
Set to 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
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.
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.
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, |
Example Reset Server State (os-resetState Action)
{
"os-resetState": {
"state": "active"
}
}
Response¶
If successful, this method does not return content in the response body.
Evacuates a server from a failed host to a new host.
Specify the
evacuateaction in the request body.In the request body, if
onSharedStorageis set, then do not setadminPass.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 |
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 |
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
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 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.
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 |
type |
body |
string |
The type of remote console. The valid values are |
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 |
type |
body |
string |
The type of remote console. The valid values are |
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"
}
}
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.
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.
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:
New in version 2.48 |
driver |
body |
string |
The driver on which the VM is running. Possible values are:
New in version 2.48 |
hypervisor |
body |
string |
The hypervisor on which the VM is running. Examples for libvirt driver
may be: 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:
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:
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:
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:
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.
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 |
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
}
]
}
}
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 |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
network_label |
body |
array |
List of IP address and IP version pairs.
The |
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.
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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.
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 New in version 2.58 |
marker (Optional) |
query |
string |
The 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 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 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, |
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, 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"
}
]
}
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, |
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 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 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, |
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, |
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 |
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 New in version 2.62 |
events.details |
body |
string |
Details of the event. May be 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, 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.
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 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"
}
]
}
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 |
port_id (Optional) |
body |
string |
The ID of the port for which you want to create an interface. The |
net_id (Optional) |
body |
string |
The ID of the network for which you want to create a port interface. The |
fixed_ips (Optional) |
body |
array |
Fixed IP addresses. If you request a specific fixed IP address without
a |
ip_address |
body |
string |
The IP address. It is required when |
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 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"
}
}
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 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"
}
}
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.
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=="
}
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.
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 (Optional) |
query |
integer |
Used in conjunction with |
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, |
tag |
body |
string |
The device tag applied to the volume block device or 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"
}
]
}
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
|
volumeId |
body |
string |
The UUID of the volume to attach. |
device (Optional) |
body |
string |
Name of the device such as, |
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 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 |
body |
string |
Name of the device such as, |
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 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"
}
}
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
|
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, |
tag |
body |
string |
The device tag applied to the volume block device or 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"
}
}
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 |
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, 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 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.
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.
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
|
sort_dir (Optional) |
query |
string |
Sort direction. A valid value is |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit value.
Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
minDisk (Optional) |
query |
integer |
Filters the response by a minimum disk space, in GiB. For example, |
minRam (Optional) |
query |
integer |
Filters the response by a minimum RAM, in MiB. For example, |
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 |
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"
}
]
}
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 |
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 |
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": {}
}
}
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
|
sort_dir (Optional) |
query |
string |
Sort direction. A valid value is |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit value.
Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
minDisk (Optional) |
query |
integer |
Filters the response by a minimum disk space, in GiB. For example, |
minRam (Optional) |
query |
integer |
Filters the response by a minimum RAM, in MiB. For example, |
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 |
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 |
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"
}
}
]
}
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 |
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"
}
}
}
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 |
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": {}
}
}
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.
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 |
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"
}
]
}
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 |
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"
}
]
}
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 |
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.
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"
}
}
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"
}
}
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"
}
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"
}
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.
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 New in version 2.35 |
marker (Optional) |
query |
string |
The last-seen item. Use the 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 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"
}
]
}
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
|
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 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 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"
}
}
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, |
deleted |
body |
boolean |
A boolean indicates whether this keypair is deleted or not.
The value is always |
deleted_at |
body |
none |
It is always |
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 |
user_id |
body |
string |
The user_id for a keypair. |
type |
body |
string |
The type of the keypair. Allowed values are 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
}
}
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.
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.
If non integer value is specified, it is the same as |
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 |
totalInstancesUsed |
body |
integer |
The number of servers in each tenant.
If |
totalRAMUsed |
body |
integer |
The amount of used server RAM in each tenant.
If |
totalServerGroupsUsed |
body |
integer |
The number of used server groups in each tenant.
If |
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 Available until version 2.35 |
totalSecurityGroupsUsed |
body |
integer |
The number of used security groups in each tenant.
If 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.
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, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
deleted |
body |
boolean |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
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"
}
]
}
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, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
deleted |
body |
boolean |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
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"
}
}
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, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
deleted |
body |
boolean |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
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"
}
}
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, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
deleted |
body |
boolean |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
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"
}
}
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.
Adds a host to an aggregate.
Specify the add_host action and host name in the request body.
It is not allowed to move a host with servers between Availability Zones. Such request is rejected with 409 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. |
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, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
deleted |
body |
boolean |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
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"
}
}
Removes a host from an aggregate.
Specify the remove_host action and host name in the request body.
It is not allowed to move a host with servers between Availability Zones. Such request is rejected with 409 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. |
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, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
deleted |
body |
boolean |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
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"
}
}
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 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, |
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 CCYY-MM-DDThh:mm:ss±hh:mm
For example, |
deleted |
body |
boolean |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, |
hosts |
body |
array |
An array of host information. |
id |
body |
integer </ |