Compute API

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

API Versions

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

• ''major versions'', which have dedicated urls
• ''microversions'', which can be requested through the use of the X-OpenStack-Nova-API-Version header, or since microversion 2.27 the OpenStack-API-Version header may also be used.

For more details about Microversions, please reference: Microversions

注釈

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

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

GET

/

List All Major Versions

detail

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

Normal Response Codes: 200

Response

Name	In	Type	Description
versions	body	array	A list of version objects that describe the API versions available.
id	body	string	A common name for the version in question. Informative only, it has no real semantic meaning.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
min_version	body	string	If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
status	body	string	The status of this API version. This can be one of: CURRENT: this is the preferred version of the API to use SUPPORTED: this is an older, but still supported version of the API DEPRECATED: a deprecated version of the API that is slated for removal
updated	body	string	This is a fixed string. It is 2011-01-21T11:33:21Z in version 2.0, 2013-07-23T11:33:21Z in version 2.1. 注釈 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.

GET

/{api_version}

Show Details of Specific API Version

detail

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

Normal Response Codes: 200

Request

Name	In	Type	Description
api_version	path	string	The API version as returned in the links from the GET / call.

Response

Name	In	Type	Description
version	body	string	The version.
id	body	string	A common name for the version in question. Informative only, it has no real semantic meaning.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
media-types	body	array	The media types. It is an array of a fixed dict. 注釈 It is vestigial and provide no useful information. It will be deprecated and removed in the future.
min_version	body	string	If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
status	body	string	The status of this API version. This can be one of: CURRENT: this is the preferred version of the API to use SUPPORTED: this is an older, but still supported version of the API DEPRECATED: a deprecated version of the API that is slated for removal
updated	body	string	This is a fixed string. It is 2011-01-21T11:33:21Z in version 2.0, 2013-07-23T11:33:21Z in version 2.1. 注釈 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.

Service URLs

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

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

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

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

Request IDs

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

For more details about Request IDs, please reference: Faults

Request

Name	In	Type	Description
X-Openstack-Request-Id (Optional)	header	string	The global request ID, which is a unique common ID for tracking each request in OpenStack components. The format of the global request ID must be req- + UUID (UUID4). If not in accordance with the format, it is ignored. It is associated with the request and appears in the log lines for that request. By default, the middleware configuration ensures that the global request ID appears in the log files. New in version 2.46

Response

Name	In	Type	Description
X-Compute-Request-Id	header	string	The local request ID, which is a unique ID generated automatically for tracking each request to nova. It is associated with the request and appears in the log lines for that request. By default, the middleware configuration ensures that the local request ID appears in the log files. 注釈 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.

注釈

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

注釈

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.

  注釈

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

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

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

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

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

Server access addresses

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

GET

/servers

List Servers

detail

Lists IDs, names, and links for all servers.

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. This status appears for only the XenServer/XCP, KVM, and ESXi hypervisors. Administrative users can suspend an instance if it is infrequently used or to perform system maintenance. When you suspend an instance, its VM state is stored on disk, all memory is written to disk, and the virtual machine is stopped. Suspending an instance is similar to placing a device in hibernation; memory and vCPUs become available to create other instances.
• 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. Valid whitelist for non-admin users includes
  • all_tenants
  • changes-since
  • flavor
  • image
  • ip
  • ip6 (New in version 2.5)
  • name
  • not-tags (New in version 2.26)
  • not-tags-any (New in version 2.26)
  • reservation_id
  • status
  • tags (New in version 2.26)
  • tags-any (New in version 2.26)
• For admin user, whitelist includes all filter keys mentioned in Request Section.

Normal response codes: 200

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

Request

Name	In	Type	Description
access_ip_v4 (Optional)	query	string	Filter server list result by IPv4 address that should be used to access the server.
access_ip_v6 (Optional)	query	string	Filter server list result by IPv6 address that should be used to access the server.
all_tenants (Optional)	query	boolean	Specify the all_tenants query parameter to list all instances for all projects. A value of all_tenants` need not be specified. If it is specified, it must be 'boolean'. By default this is only allowed by admin users.
auto_disk_config (Optional)	query	string	Filter the server list result by the disk_config setting of the server, Valid values are: AUTO MANUAL
availability_zone (Optional)	query	string	Filter the server list result by server availability zone.
config_drive (Optional)	query	boolean	Filter the server list result by the config drive setting of the server.
changes-since (Optional)	query	string	Filters the response by a date and time stamp when the server last changed status. To help keep track of changes this may also return recently deleted servers. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
created_at (Optional)	query	string	Filter the server list result by a date and time stamp when server was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
deleted (Optional)	query	boolean	Show deleted items. 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. It is typically only available to administrators.
description (Optional)	query	string	Filter the server list result by description. 注釈 display_description can also be requested which is alias of description but that is not recommended to use as that will be removed in future.
flavor (Optional)	query	string	Filters the response by a flavor, as a UUID. A flavor is a combination of memory, disk size, and CPUs.
host (Optional)	query	string	Filter the server list result by the host name of compute node. Only allowed for Admin.
hostname (Optional)	query	string	Filter the server list result by the host name of server.
image (Optional)	query	string	Filters the response by an image, as a UUID. 注釈 '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. New in version 2.5
kernel_id (Optional)	query	string	Filter the server list result by the UUID of the kernel image when using an AMI.
key_name (Optional)	query	string	Filter the server list result by keypair name.
launch_index (Optional)	query	string	Filter the server list result by the sequence in which the servers were launched.
launched_at (Optional)	query	string	Filter the server list result by a date and time stamp when the instance was launched. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
locked_by (Optional)	query	string	Filter the server list result by who locked the server, possible value could be admin, owner or none.
marker (Optional)	query	string	The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
name (Optional)	query	string	Filters the response by a server name, as a string. You can use regular expressions in the query. For example, the ?name=bob regular expression returns both bob and bobb. If you must match on only bob, you can use a regular expression that matches the syntax of the underlying database server that is implemented for Compute, such as MySQL or PostgreSQL. 注釈 '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. Only allowed for Admin.
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
power_state (Optional)	query	string	Filter the server list result by server power state.
progress (Optional)	query	string	Filter the server list result by the progress of the server.
project_id (Optional)	body	string	Filter the list of servers by the given project ID. This filter only works when the all_tenants=1 filter is also specified. 注釈 '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.
reservation_id (Optional)	query	string	A reservation id as returned by a servers multiple create call.
root_device_name	query	string	Filter the server list result by the root device name of the server
sort_dir (Optional)	query	string	Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the server sort_key attribute.
sort_key (Optional)	query	string	Sorts by a server attribute. Default attribute is created_at. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server sort_key attribute. The sort keys are limited to: access_ip_v4 access_ip_v6 auto_disk_config availability_zone config_drive created_at display_description display_name host hostname image_ref instance_type_id kernel_id key_name launch_index launched_at locked_by node power_state progress project_id ramdisk_id root_device_name task_state terminated_at updated_at user_id uuid vm_state
status (Optional)	query	string	Filters the response by a server status, as a string. For example, ACTIVE.
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
task_state (Optional)	query	string	Filter the server list result by task state.
terminated_at (Optional)	query	string	Filter the server list result by a date and time stamp when instance was terminated. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
user_id (Optional)	query	string	Filter the list of servers by the given user ID.
uuid (Optional)	query	string	Filter the server list result by the UUID of the server.
vm_state (Optional)	query	string	Filter the server list result by vm state.

Response

Name	In	Type	Description
servers	body	array	A list of server objects.
id	body	string	The UUID of the server.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
name	body	string	The server name.

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"
        }
    ]
}

POST

/servers

Create Server

detail

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.

注釈

Starting with microversion 2.37 the networks field is required.

Preconditions

• The user must have sufficient server quota to create the number of servers requested.
• The connection to the Image service is valid.

Asynchronous postconditions

• With correct permissions, you can see the server status as ACTIVE through API calls.
• With correct access, you can see the created server in the compute node that OpenStack Compute manages.

Troubleshooting

• If the server status remains BUILDING or shows another error status, the request failed. Ensure you meet the preconditions then investigate the compute node.
• The server is not created in the compute node that OpenStack Compute manages.
• The compute node needs enough free resource to match the resource of the server creation request.
• Ensure that the scheduler selection filter can fulfill the request with the available compute nodes that match the selection criteria of the filter.

Normal response codes: 202

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

Request

Name	In	Type	Description
server	body	object	A server object.
name	body	string	The server name.
flavorRef	body	string	The flavor reference, as an ID (including a UUID) or full URL, for the flavor for your server instance.
imageRef	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.
security_groups (Optional)	body	array	One or more security groups. Specify the name of the security group in the name attribute. If you omit this attribute, the API creates the server in the default security group. Requested security groups are not applied to pre-existing ports.
metadata (Optional)	body	object	Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
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.
user_data (Optional)	body	string	Configuration information or scripts to use upon launch. Must be Base64 encoded. 注釈 The null value allowed in Nova legacy v2 API, but due to the strict input validation, it isn't allowed in Nova v2.1 API.
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. You can list the available availability zones by calling the os-availability-zone API, but you should avoid using the default availability zone when booting the instance. In general, the default availability zone is named nova. This AZ is only shown when listing the availability zones as an admin.
networks	body	object	A networks object. Required parameter when there are multiple networks defined for the tenant. When you do not specify the networks parameter, the server attaches to the only network created for the current tenant. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a network, specify the UUID of the network in the uuid attribute in a networks object. To provision the server instance with a NIC for an already existing port, specify the port-id in the port attribute in a networks object. If multiple networks are defined, the order in which they appear in the guest operating system will not necessarily reflect the order in which they are given in the server boot request. Guests should therefore not depend on device order to deduce any information about their network devices. Instead, device role tags should be used: introduced in 2.32, broken in 2.37, and re-introduced and fixed in 2.42, the tag is an optional, string attribute that can be used to assign a tag to a virtual network interface. This tag is then exposed to the guest in the metadata API and the config drive and is associated to hardware metadata for that network interface, such as bus (ex: PCI), bus address (ex: 0000:00:02.0), and MAC address. A bug has caused the tag attribute to no longer be accepted starting with version 2.37. Therefore, network interfaces could only be tagged in versions 2.32 to 2.36 inclusively. Version 2.42 has restored the tag attribute. Starting with microversion 2.37, this field is required and the special values auto and none can be specified for networks. auto tells the Compute service to use a network that is available to the project, if one exists. If one does not exist, the Compute service will attempt to automatically allocate a network for the project (if possible). none tells the Compute service to not allocate a network for the instance. The auto and none values cannot be used with any other network values, including other network uuids, ports, fixed IPs or device tags. These are requested as strings for the networks value, not in a list. See the associated example.
networks.uuid (Optional)	body	string	To provision the server instance with a NIC for a network, specify the UUID of the network in the uuid attribute in a networks object. Required if you omit the port attribute. Starting with microversion 2.37, this value is strictly enforced to be in UUID format.
networks.port (Optional)	body	string	To provision the server instance with a NIC for an already existing port, specify the port-id in the port attribute in a networks object. The port status must be DOWN. Required if you omit the uuid attribute. Requested security groups are not applied to pre-existing ports.
networks.fixed_ip (Optional)	body	string	A fixed IPv4 address for the NIC. Valid with a neutron or nova-networks network.
networks.tag (Optional)	body	string	A device role tag that can be applied to a network interface. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled. 注釈 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
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
block_device_mapping_v2 (Optional)	body	array	Enables fine grained control of the block device mapping for an instance. This is typically used for booting servers from volumes. An example format would look as follows: "block_device_mapping_v2": [{ "boot_index": "0", "uuid": "ac408821-c95a-448f-9292-73986c790911", "source_type": "image", "volume_size": "25", "destination_type": "volume", "delete_on_termination": true, "tag": "disk1", "disk_bus": "scsi"}] In microversion 2.32, tag is an optional string attribute that can be used to assign a tag to the block device. This tag is then exposed to the guest in the metadata API and the config drive and is associated to hardware metadata for that block device, such as bus (ex: SCSI), bus address (ex: 1:0:2:0), and serial. A bug has caused the tag attribute to no longer be accepted starting with version 2.33. It has been restored in version 2.42.
block_device_mapping_v2.device_name	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.source_type	body	string	The source type of the volume. A valid value is blank, snapshot, volume, or image.
block_device_mapping_v2.destination_type (Optional)	body	string	Defines where the volume comes from. A valid value is local or volume.
block_device_mapping_v2.delete_on_termination (Optional)	body	string	To delete the boot volume when the server is destroyed, specify true. Otherwise, specify false. Default: false
block_device_mapping_v2.guest_format (Optional)	body	string	Specifies the guest server disk file system format, such as ext2, ext3, ext4, xfs or swap. This parameter affects only the libvirt virt driver.
block_device_mapping_v2.boot_index	body	string	Defines the order in which a hypervisor tries devices when it attempts to boot the guest from storage. Give each device a unique boot index starting from 0. To disable a device from booting, set the boot index to a negative value or use the default boot index value, which is None. The simplest usage is, set the boot index of the boot device to 0 and use the default boot index value, None, for any other devices. Some hypervisors might not support booting from multiple devices; these hypervisors consider only the device with a boot index of 0. Some hypervisors support booting from multiple devices but only if the devices are of different types. For example, a disk and CD-ROM.
block_device_mapping_v2.uuid (Optional)	body	string	This is the uuid of source resource. The uuid is point to different resource based on the source_type. For example, if source_type is image as the above sample, the block device is created based on the specified image which is gotten from the image service.
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. 注釈 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.disk_bus (Optional)	body	string	Disk bus type, some hypervisors (currently only libvirt) support specify this parameter. Some example disk_bus values can be: ide, usb, virtio, scsi. This is not an exhaustive list as it depends on the virtualization driver, and may change as more support is added.
config_drive (Optional)	body	boolean	Indicates whether a configuration drive enables metadata injection. The config_drive setting provides information about a drive that the instance can mount at boot time. The instance reads files from the drive to get information that is normally available through the metadata service. This metadata is different from the user data. Not all cloud providers enable the config_drive. Read more in the OpenStack End User Guide.
key_name (Optional)	body	string	Key pair name. 注釈 The null value was allowed in the Nova legacy v2 API, but due to strict input validation, it is not allowed in the Nova v2.1 API.
os:scheduler_hints (Optional)	body	object	The dictionary of data to send to the scheduler. Alternatively, you can specify OS-SCH-HNT:scheduler_hints as the key in the request body. 注釈 This is a top-level key in the request body, not part of the server portion of the request body. There are a few caveats with scheduler hints: The request validation schema is per hint. For example, some require a single string value, and some accept a list of values. Hints are only used based on the cloud scheduler configuration, which varies per deployment. Hints are pluggable per deployment, meaning that a cloud can have custom hints which may not be available in another cloud. For these reasons, it is important to consult each cloud's user documentation to know what is available for scheduler hints.
OS-DCF:diskConfig (Optional)	body	string	Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.
description (Optional)	body	string	A free form description of the server. Limited to 255 characters in length. Before microversion 2.19 this was set to the server name. New in version 2.19
tags (Optional)	body	array	A list of tags. Tags have the following restrictions: Tag is a Unicode bytestring no longer than 60 characters. Tag is a non-empty string. '/' is not allowed to be in a tag name Comma is not allowed to be in a tag name in order to simplify requests that specify lists of tags All other characters are allowed to be in a tag name Each server can have up to 50 tags. New in version 2.52

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": "nova",
        "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 Automatic Networking (v2.37)

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

Response

Name	In	Type	Description
server	body	object	A server object.
id	body	string	The UUID of the server.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
OS-DCF:diskConfig	body	string	Disk configuration. The value is either: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.
security_groups	body	array	One or more security groups objects.
security_groups.name	body	string	The security group name.
adminPass (Optional)	body	string	The administrative password for the server. If you set enable_instance_password configuration option to False, the API wouldn't return the adminPass field in response.

Example Create Server

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

POST

/servers

Create Multiple Servers

detail

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. A unique string will be appended to the end of this base name for every server created.
min_count (Optional)	body	string	The min number of servers to be created. Defaults to 1.
max_count (Optional)	body	string	The max number of servers to be created. Defaults to the value of min_count.
return_reservation_id (Optional)	body	boolean	Set to True to request that the response return a reservation ID instead of instance information. Default is False.

Example Multiple Create with reservation ID

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

Response

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

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

Example Create multiple servers with reservation ID

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

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

Example Create multiple servers without reservation ID

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

GET

/servers/detail

List Servers Detailed

detail

For each server, shows 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.

To hide addresses information for instances in a certain state, set the osapi_hide_server_address_states configuration option. Set this option to a valid VM state in the nova.conf configuration file.

HostId is unique per account and is not globally unique.

Normal response codes: 200

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

Request

Name	In	Type	Description
access_ip_v4 (Optional)	query	string	Filter server list result by IPv4 address that should be used to access the server.
access_ip_v6 (Optional)	query	string	Filter server list result by IPv6 address that should be used to access the server.
all_tenants (Optional)	query	boolean	Specify the all_tenants query parameter to list all instances for all projects. A value of all_tenants` need not be specified. If it is specified, it must be 'boolean'. By default this is only allowed by admin users.
auto_disk_config (Optional)	query	string	Filter the server list result by the disk_config setting of the server, Valid values are: AUTO MANUAL
availability_zone (Optional)	query	string	Filter the server list result by server availability zone.
config_drive (Optional)	query	boolean	Filter the server list result by the config drive setting of the server.
changes-since (Optional)	query	string	Filters the response by a date and time stamp when the server last changed status. To help keep track of changes this may also return recently deleted servers. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
created_at (Optional)	query	string	Filter the server list result by a date and time stamp when server was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
deleted (Optional)	query	boolean	Show deleted items. 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. It is typically only available to administrators.
description (Optional)	query	string	Filter the server list result by description. 注釈 display_description can also be requested which is alias of description but that is not recommended to use as that will be removed in future.
flavor (Optional)	query	string	Filters the response by a flavor, as a UUID. A flavor is a combination of memory, disk size, and CPUs.
host (Optional)	query	string	Filter the server list result by the host name of compute node. Only allowed for Admin.
hostname (Optional)	query	string	Filter the server list result by the host name of server.
image (Optional)	query	string	Filters the response by an image, as a UUID. 注釈 '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. New in version 2.5
kernel_id (Optional)	query	string	Filter the server list result by the UUID of the kernel image when using an AMI.
key_name (Optional)	query	string	Filter the server list result by keypair name.
launch_index (Optional)	query	string	Filter the server list result by the sequence in which the servers were launched.
launched_at (Optional)	query	string	Filter the server list result by a date and time stamp when the instance was launched. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
locked_by (Optional)	query	string	Filter the server list result by who locked the server, possible value could be admin, owner or none.
marker (Optional)	query	string	The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
name (Optional)	query	string	Filters the response by a server name, as a string. You can use regular expressions in the query. For example, the ?name=bob regular expression returns both bob and bobb. If you must match on only bob, you can use a regular expression that matches the syntax of the underlying database server that is implemented for Compute, such as MySQL or PostgreSQL. 注釈 '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. Only allowed for Admin.
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
power_state (Optional)	query	string	Filter the server list result by server power state.
progress (Optional)	query	string	Filter the server list result by the progress of the server.
project_id (Optional)	body	string	Filter the list of servers by the given project ID. This filter only works when the all_tenants=1 filter is also specified. 注釈 '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.
reservation_id (Optional)	query	string	A reservation id as returned by a servers multiple create call.
root_device_name	query	string	Filter the server list result by the root device name of the server
sort_dir (Optional)	query	string	Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the server sort_key attribute.
sort_key (Optional)	query	string	Sorts by a server attribute. Default attribute is created_at. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server sort_key attribute. The sort keys are limited to: access_ip_v4 access_ip_v6 auto_disk_config availability_zone config_drive created_at display_description display_name host hostname image_ref instance_type_id kernel_id key_name launch_index launched_at locked_by node power_state progress project_id ramdisk_id root_device_name task_state terminated_at updated_at user_id uuid vm_state
status (Optional)	query	string	Filters the response by a server status, as a string. For example, ACTIVE.
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
task_state (Optional)	query	string	Filter the server list result by task state.
terminated_at (Optional)	query	string	Filter the server list result by a date and time stamp when instance was terminated. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
user_id (Optional)	query	string	Filter the list of servers by the given user ID.
uuid (Optional)	query	string	Filter the server list result by the UUID of the server.
vm_state (Optional)	query	string	Filter the server list result by vm state.

Response

Name	In	Type	Description
server	body	object	A server object.
addresses	body	object	The addresses for the server. Addresses information is hidden for any server in a state set in the hide_server_address_states configuration option. By default, servers in building state hide their addresses information. See nova.conf configuration options for more information.
created	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
flavor	body	object	Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system. As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.
flavor.id	body	string	The ID of the flavor. While people often make this look like an int, this is really a string. Available until version 2.46
flavor.links	body	array	Links to the flavor resource. See API Guide / Links and References for more info. Available until version 2.46
flavor.vcpus	body	integer	The number of virtual CPUs that were allocated to the server. New in version 2.47
flavor.ram	body	integer	The amount of RAM a flavor has, in MiB. New in version 2.47
flavor.disk	body	integer	The size of the root disk that was created in GiB. New in version 2.47
flavor.ephemeral	body	integer	The size of the ephemeral disk that was created, in GiB. New in version 2.47
flavor.swap	body	integer	The size of a dedicated swap disk that was allocated, in MiB. New in version 2.47
flavor.original_name	body	string	The display name of a flavor. New in version 2.47
flavor.extra_specs (Optional)	body	object	A dictionary of the flavor's extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs. New in version 2.47
flavor.extra_specs.key	body	string	The extra spec key of a flavor. New in version 2.47
flavor.extra_specs.value	body	string	The extra spec value of a flavor. New in version 2.47
hostId	body	string	An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.
id	body	string	The UUID of the server.
image	body	object	The UUID and links for the image for your server instance. The image object might be an empty string when you boot the server from a volume.
key_name	body	string	The name of associated key pair, if any.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
metadata	body	object	A dictionary of metadata key-and-value pairs, which is maintained for backward compatibility.
name	body	string	The server name.
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.
config_drive	body	boolean	Indicates whether or not a config drive was used for this server.
OS-DCF:diskConfig	body	string	Disk configuration. The value is either: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.
OS-EXT-AZ:availability_zone	body	string	The availability zone name.
OS-EXT-SRV-ATTR:host	body	string	The name of the compute host on which this instance is running. Appears in the response for administrative users only.
OS-EXT-SRV-ATTR: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-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 and can only be set when creating a volume while creating a server, which is commonly referred to as boot from volume. New in version 2.3
OS-SRV-USG:launched_at	body	string	The date and time when the server was launched. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The hh±:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.
OS-SRV-USG:terminated_at	body	string	The date and time when the server was deleted. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.
progress	body	integer	A percentage value of the build progress.
security_groups	body	array	One or more security groups objects.
security_group.name	body	string	The security group name.
status	body	string	The server status.
host_status	body	string	The host status. Values where next value in list can override the previous: UP if nova-compute up. UNKNOWN if nova-compute not reported by servicegroup driver. DOWN if nova-compute forced down. MAINTENANCE if nova-compute is disabled. Empty string indicates there is no host for server. This attribute appears in the response only if the policy permits. New in version 2.16
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.
updated	body	string	The date and time when the resource was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
user_id	body	string	The user ID of the user who owns the server.
OS-EXT-SRV-ATTR:hostname	body	string	The hostname set on the instance when it is booted. New in version 2.3
OS-EXT-SRV-ATTR: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. New in version 2.3
OS-EXT-SRV-ATTR:launch_index	body	integer	When servers are launched via multiple create, this is the sequence in which the servers were launched. New in version 2.3
OS-EXT-SRV-ATTR:kernel_id	body	string	The UUID of the kernel image when using an AMI. Will be null if not. New in version 2.3
OS-EXT-SRV-ATTR:ramdisk_id	body	string	The UUID of the ramdisk image when using an AMI. Will be null if not. New in version 2.3
OS-EXT-SRV-ATTR:root_device_name	body	string	The root device name for the instance New in version 2.3
OS-EXT-SRV-ATTR:user_data	body	string	The user_data the instance was created with. New in version 2.3
locked	body	boolean	True if the instance is locked otherwise False. New in version 2.9

Example List Servers Detailed (2.47)

GET

/servers/{server_id}

Show Server Details

detail

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.

To hide addresses information for instances in a certain state, set the osapi_hide_server_address_states configuration option. Set this option to a valid VM state in the nova.conf configuration file.

HostId is unique per account and is not globally unique.

Preconditions

The server must exist.

Normal response codes: 200

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

Request

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

Response

Name	In	Type	Description
server	body	object	A server object.
addresses	body	object	The addresses for the server. Addresses information is hidden for any server in a state set in the hide_server_address_states configuration option. By default, servers in building state hide their addresses information. See nova.conf configuration options for more information.
created	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
flavor	body	object	Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system. As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.
flavor.id	body	string	The ID of the flavor. While people often make this look like an int, this is really a string. Available until version 2.46
flavor.links	body	array	Links to the flavor resource. See API Guide / Links and References for more info. Available until version 2.46
flavor.vcpus	body	integer	The number of virtual CPUs that were allocated to the server. New in version 2.47
flavor.ram	body	integer	The amount of RAM a flavor has, in MiB. New in version 2.47
flavor.disk	body	integer	The size of the root disk that was created in GiB. New in version 2.47
flavor.ephemeral	body	integer	The size of the ephemeral disk that was created, in GiB. New in version 2.47
flavor.swap	body	integer	The size of a dedicated swap disk that was allocated, in MiB. New in version 2.47
flavor.original_name	body	string	The display name of a flavor. New in version 2.47
flavor.extra_specs (Optional)	body	object	A dictionary of the flavor's extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs. New in version 2.47
flavor.extra_specs.key	body	string	The extra spec key of a flavor. New in version 2.47
flavor.extra_specs.value	body	string	The extra spec value of a flavor. New in version 2.47
hostId	body	string	An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.
id	body	string	The UUID of the server.
image	body	object	The UUID and links for the image for your server instance. The image object might be an empty string when you boot the server from a volume.
key_name	body	string	The name of associated key pair, if any.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
metadata	body	object	A dictionary of metadata key-and-value pairs, which is maintained for backward compatibility.
name	body	string	The server name.
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.
config_drive	body	boolean	Indicates whether or not a config drive was used for this server.
OS-DCF:diskConfig	body	string	Disk configuration. The value is either: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.
OS-EXT-AZ:availability_zone	body	string	The availability zone name.
OS-EXT-SRV-ATTR:host	body	string	The name of the compute host on which this instance is running. Appears in the response for administrative users only.
OS-EXT-SRV-ATTR: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-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 and can only be set when creating a volume while creating a server, which is commonly referred to as boot from volume. New in version 2.3
OS-SRV-USG:launched_at	body	string	The date and time when the server was launched. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The hh±:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.
OS-SRV-USG:terminated_at	body	string	The date and time when the server was deleted. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.
progress	body	integer	A percentage value of the build progress.
security_groups	body	array	One or more security groups objects.
security_group.name	body	string	The security group name.
status	body	string	The server status.
host_status	body	string	The host status. Values where next value in list can override the previous: UP if nova-compute up. UNKNOWN if nova-compute not reported by servicegroup driver. DOWN if nova-compute forced down. MAINTENANCE if nova-compute is disabled. Empty string indicates there is no host for server. This attribute appears in the response only if the policy permits. New in version 2.16
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.
updated	body	string	The date and time when the resource was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
user_id	body	string	The user ID of the user who owns the server.
fault (Optional)	body	object	A fault object. Only displayed in the failed response. Default keys are code, created, and message (response code, created time, and message respectively). In addition, the key details (stack trace) is available if you have the administrator privilege.
OS-EXT-SRV-ATTR:hostname	body	string	The hostname set on the instance when it is booted. New in version 2.3
OS-EXT-SRV-ATTR: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. New in version 2.3
OS-EXT-SRV-ATTR:launch_index	body	integer	When servers are launched via multiple create, this is the sequence in which the servers were launched. New in version 2.3
OS-EXT-SRV-ATTR:kernel_id	body	string	The UUID of the kernel image when using an AMI. Will be null if not. New in version 2.3
OS-EXT-SRV-ATTR:ramdisk_id	body	string	The UUID of the ramdisk image when using an AMI. Will be null if not. New in version 2.3
OS-EXT-SRV-ATTR:root_device_name	body	string	The root device name for the instance New in version 2.3
OS-EXT-SRV-ATTR:user_data	body	string	The user_data the instance was created with. New in version 2.3
locked	body	boolean	True if the instance is locked otherwise False. New in version 2.9

Example Show Server Details (2.47)

{
    "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-ov3q80zj",
        "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": "2017-02-14T19:23:59.895661",
        "OS-SRV-USG:terminated_at": null,
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "addresses": {
            "private": [
                {
                    "OS-EXT-IPS-MAC:mac_addr": "aa:bb:cc:dd:ee:ff",
                    "OS-EXT-IPS:type": "fixed",
                    "addr": "192.168.0.3",
                    "version": 4
                }
            ]
        },
        "config_drive": "",
        "created": "2017-02-14T19:23:58Z",
        "description": null,
        "flavor": {
            "disk": 1,
            "ephemeral": 0,
            "extra_specs": {
                "hw:cpu_model": "SandyBridge",
                "hw:mem_page_size": "2048",
                "hw:cpu_policy": "dedicated"
            },
            "original_name": "m1.tiny.specs",
            "ram": 512,
            "swap": 0,
            "vcpus": 1
        },
        "hostId": "2091634baaccdc4c5a1d57069c833e402921df696b7f970791b12ec6",
        "host_status": "UP",
        "id": "9168b536-cd40-4630-b43f-b259807c6e87",
        "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/9168b536-cd40-4630-b43f-b259807c6e87",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/9168b536-cd40-4630-b43f-b259807c6e87",
                "rel": "bookmark"
            }
        ],
        "locked": false,
        "metadata": {
            "My Server Name": "Apache1"
        },
        "name": "new-server-test",
        "os-extended-volumes:volumes_attached": [
            {
                "delete_on_termination": false,
                "id": "volume_id1"
            },
            {
                "delete_on_termination": false,
                "id": "volume_id2"
            }
        ],
        "progress": 0,
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "status": "ACTIVE",
        "tags": [],
        "tenant_id": "6f70656e737461636b20342065766572",
        "updated": "2017-02-14T19:24:00Z",
        "user_id": "fake"
    }
}

PUT

/servers/{server_id}

Update Server

detail

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.
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.
OS-DCF:diskConfig (Optional)	body	string	Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.
description (Optional)	body	string	A free form description of the server. Limited to 255 characters in length. Before microversion 2.19 this was set to the server name. New in version 2.19

Example Update server name (2.47)

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

Response

Name	In	Type	Description
server	body	object	A server object.
addresses	body	object	The addresses for the server. Addresses information is hidden for any server in a state set in the hide_server_address_states configuration option. By default, servers in building state hide their addresses information. See nova.conf configuration options for more information.
created	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
flavor	body	object	Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system. As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.
flavor.id	body	string	The ID of the flavor. While people often make this look like an int, this is really a string. Available until version 2.46
flavor.links	body	array	Links to the flavor resource. See API Guide / Links and References for more info. Available until version 2.46
flavor.vcpus	body	integer	The number of virtual CPUs that were allocated to the server. New in version 2.47
flavor.ram	body	integer	The amount of RAM a flavor has, in MiB. New in version 2.47
flavor.disk	body	integer	The size of the root disk that was created in GiB. New in version 2.47
flavor.ephemeral	body	integer	The size of the ephemeral disk that was created, in GiB. New in version 2.47
flavor.swap	body	integer	The size of a dedicated swap disk that was allocated, in MiB. New in version 2.47
flavor.original_name	body	string	The display name of a flavor. New in version 2.47
flavor.extra_specs (Optional)	body	object	A dictionary of the flavor's extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs. New in version 2.47
flavor.extra_specs.key	body	string	The extra spec key of a flavor. New in version 2.47
flavor.extra_specs.value	body	string	The extra spec value of a flavor. New in version 2.47
hostId	body	string	An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.
id	body	string	The UUID of the server.
image	body	object	The UUID and links for the image for your server instance. The image object might be an empty string when you boot the server from a volume.
key_name (Optional)	body	string	Key pair name. 注釈 The null value was allowed in the Nova legacy v2 API, but due to strict input validation, it is not allowed in the Nova v2.1 API.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
metadata (Optional)	body	object	Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
name	body	string	The server name.
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.
OS-DCF:diskConfig (Optional)	body	string	Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.
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: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-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-SRV-USG:launched_at	body	string	The date and time when the server was launched. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The hh±:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.
OS-SRV-USG:terminated_at	body	string	The date and time when the server was deleted. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.
progress	body	integer	A percentage value of the build progress.
security_groups	body	array	One or more security groups objects.
security_group.name	body	string	The security group name.
status	body	string	The server status.
host_status	body	string	The host status. Values where next value in list can override the previous: UP if nova-compute up. UNKNOWN if nova-compute not reported by servicegroup driver. DOWN if nova-compute forced down. MAINTENANCE if nova-compute is disabled. Empty string indicates there is no host for server. This attribute appears in the response only if the policy permits. New in version 2.16
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.
updated	body	string	The date and time when the resource was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
user_id	body	string	The user ID of the user who owns the server.
OS-EXT-SRV-ATTR:hostname	body	string	The hostname set on the instance when it is booted. New in version 2.3
OS-EXT-SRV-ATTR: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. New in version 2.3
OS-EXT-SRV-ATTR:launch_index	body	integer	When servers are launched via multiple create, this is the sequence in which the servers were launched. New in version 2.3
OS-EXT-SRV-ATTR:kernel_id	body	string	The UUID of the kernel image when using an AMI. Will be null if not. New in version 2.3
OS-EXT-SRV-ATTR:ramdisk_id	body	string	The UUID of the ramdisk image when using an AMI. Will be null if not. New in version 2.3
OS-EXT-SRV-ATTR:root_device_name	body	string	The root device name for the instance New in version 2.3
OS-EXT-SRV-ATTR:user_data	body	string	The user_data the instance was created with. New in version 2.3
locked	body	boolean	True if the instance is locked otherwise False. New in version 2.9

Example Update server name (2.47)

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "accessIPv4": "1.2.3.4",
        "accessIPv6": "80fe::",
        "addresses": {
            "private": [
                {
                    "addr": "192.168.0.3",
                    "version": 4
                }
            ]
        },
        "created": "2012-12-02T02:11:57Z",
        "description": null,
        "flavor": {
            "disk": 1,
            "ephemeral": 0,
            "extra_specs": {},
            "original_name": "m1.tiny",
            "ram": 512,
            "swap": 0,
            "vcpus": 1
        },
        "hostId": "6e84af987b4e7ec1c039b16d21f508f4a505672bd94fb0218b668d07",
        "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"
                }
            ]
        },
        "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,
        "metadata": {
            "My Server Name": "Apache1"
        },
        "name": "new-server-test",
        "progress": 0,
        "status": "ACTIVE",
        "tags": [],
        "tenant_id": "6f70656e737461636b20342065766572",
        "updated": "2012-12-02T02:11:58Z",
        "user_id": "fake"
    }
}

DELETE

/servers/{server_id}

Delete Server

detail

Deletes a server.

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

Preconditions

• The server must exist.
• Anyone can delete a server when the status of the server is not locked and when the policy allows.
• If the server is locked, you must have administrator privileges to delete the server.

Asynchronous postconditions

• With correct permissions, you can see the server status as deleting.
• The ports attached to the server, which Nova created during the server create process or when attaching interfaces later, are deleted.
• The server does not appear in the list servers response.
• If hard delete, the server managed by OpenStack Compute is deleted on the compute node.

Troubleshooting

• If server status remains in deleting status or another error status, the request failed. Ensure that you meet the preconditions. Then, investigate the compute back end.
• The request returns the HTTP 409 response code when the server is locked even if you have correct permissions. Ensure that you meet the preconditions then investigate the server status.
• The server managed by OpenStack Compute is not deleted from the compute node.

Normal response codes: 204

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

Request

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

Response

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

Servers - run an action (servers, action)

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

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

You can create an image from a server, create a backup of a server, evacuate a server from a failed host to a new host, 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 RDP, serial, SPICE, or VNC console for a server.

POST

/servers/{server_id}/action

Add Security Group To A Server (addSecurityGroup Action)

detail

Adds a security group to a server.

Specify the addSecurityGroup action in the request body.

Normal response codes: 202

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
addSecurityGroup	body	object	The action to add a security group to a server.
name	body	string	The security group name.

Example Add Security Group To A Server (addSecurityGroup Action)

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

Response

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

POST

/servers/{server_id}/action

Create Image (createImage Action)

detail

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.

注釈

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, PAUSED, or SUSPENDED.

The connection to the Image service is valid.

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. 注釈 The URL returned may not be accessible to users and should not be relied upon. Use microversion 2.45 or simply parse the image ID out of the URL in the Location response header. Available until version 2.44
image_id	body	string	The UUID for the resulting image snapshot. New in version 2.45

Example Create Image (v2.45)

{
    "image_id": "0e7761dd-ee98-41f0-ba35-05994e446431"
}

POST

/servers/{server_id}/action

Reboot Server (reboot Action)

detail

Reboots a server.

Specify the reboot action in the request body.

Normal response codes: 202

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
reboot	body	object	The action to reboot a server.
type	body	string	The type of the reboot action. The valid values are HARD and SOFT. A SOFT reboot attempts a graceful shutdown and restart of the server. A HARD reboot attempts a forced shutdown and restart of the server. The HARD reboot corresponds to the power cycles of the server.

Example Reboot Server (reboot Action)

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

Response

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

POST

/servers/{server_id}/action

Remove Security Group From A Server (removeSecurityGroup Action)

detail

Removes a security group from a server.

Specify the removeSecurityGroup action in the request body.

Normal response codes: 202

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
removeSecurityGroup	body	object	The action to remove a security group from the server.
name	body	string	The security group name.

Example Remove Security Group From A Server (removeSecurityGroup Action)

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

Response

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

POST

/servers/{server_id}/action

Resize Server (resize Action)

detail

Resizes a server.

Specify the resize action in the request body.

A successfully resized server shows a VERIFY_RESIZE status, RESIZED VM status, and finished migration status. If you set the resize_confirm_window option of the Compute service to an integer value, the Compute service automatically confirms the resize operation after the set interval in seconds.

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.

Normal response codes: 202

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
resize	body	object	The action to resize a server.
flavorRef	body	string	The flavor ID for resizing the server. The size of the disk in the flavor being resized to must be greater than or equal to the size of the disk in the current flavor. If a specified flavor ID is the same as the current one of the server, the request returns a Bad Request (400) response code.
OS-DCF:diskConfig (Optional)	body	string	Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

Example Resize Server (Resize Action)

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

Response

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

POST

/servers/{server_id}/action

Start Server (os-start Action)

detail

Starts a stopped server and changes its status to ACTIVE.

Specify the os-start action in the request body.

Preconditions

The server status must be SHUTOFF.

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

Asynchronous Postconditions

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

Troubleshooting

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

Normal response codes: 202

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
os-start	body	none	The action to start a stopped server.

Example Start server

{
    "os-start" : null
}

Response

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

POST

/servers/{server_id}/action

Stop Server (os-stop Action)

detail

Stops a running server and changes its status to SHUTOFF.

Specify the os-stop action in the request body.

Preconditions

The server status must be ACTIVE or ERROR.

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

Asynchronous Postconditions

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

Normal response codes: 202

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
os-stop	body	none	The action to stop a running server.

Example Stop server

{
    "os-stop" : null
}

Response

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

POST

/servers/{server_id}/action

Trigger Crash Dump In Server

detail

バージョン 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.

警告

This action can cause data loss. Also, network connectivity can be lost both during and after this operation.

Normal response codes: 202

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

• 400 is returned if the server does not support a crash dump (either by configuration or because the backend does not support it)
• 409 is returned if the server is not in a state where a crash dump action is allowed.

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
trigger_crash_dump	body	none	Specifies the trigger crash dump action should be run

Example Trigger crash dump: JSON request

{
    "trigger_crash_dump": null
}

Response

No body is returned on a successful submission.

POST

/servers/{server_id}/action

Show Console Output (os-getConsoleOutput Action)

detail

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. 注釈 This parameter can be specified as not only 'integer' but also 'string'.

Example Show Console Output (os-getConsoleOutput Action)

This example requests the last 50 lines of console content from the specified server.

{
    "os-getConsoleOutput": {
        "length": 50
    }
}

Response

Name	In	Type	Description
output	body	string	The console output as a string. Control characters will be escaped to create a valid JSON string.

Example Show Console Output (os-getConsoleOutput Action)

{
    "output": "FAKE CONSOLE OUTPUT\nANOTHER\nLAST LINE"
}

POST

/servers/{server_id}/action

Get VNC Console (os-getVNCConsole Action) (DEPRECATED)

detail

Gets a VNC console for a server.

警告

This action is deprecated in microversion 2.5 and superseded by the API Server Remote 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.

The supported connection types are novnc, xvpvnc. Such as connect with novnc, set type parameter to novnc.

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 valid values are novnc and xvpvnc.

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 valid values are novnc and xvpvnc.
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?token=191996c3-7b0f-42f3-95a7-f1839f2da6ed"
    }
}

Server Remote Consoles

Create server remote console.

POST

/servers/{server_id}/remote-consoles

Create Remote Console

detail

注釈

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 RDP, set the protocol parameter to rdp. For the same protocol, there may be different connection types such as vnc protocol and novnc type or vnc protocol and xvpvnc type.

Normal response codes: 200

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
remote_console	body	object	The remote console object.
protocol	body	string	The protocol of remote console. The valid values are vnc, spice, rdp, serial and mks. The protocol mks is added since Microversion 2.8.
type	body	string	The type of remote console. The valid values are novnc, xvpvnc, rdp-html5, spice-html5, serial, and webmks. The type webmks is added since Microversion 2.8.

Example Get Remote VNC Console

{
    "remote_console": {
        "protocol": "vnc",
        "type": "novnc"
    }
}

Response

Name	In	Type	Description
remote_console	body	object	The remote console object.
protocol	body	string	The protocol of remote console. The valid values are vnc, spice, rdp, serial and mks. The protocol mks is added since Microversion 2.8.
type	body	string	The type of remote console. The valid values are novnc, xvpvnc, rdp-html5, spice-html5, serial, and webmks. The type webmks is added since Microversion 2.8.
url	body	string	The URL is used to connect the console.

Example Get Remote VNC Console

{
    "remote_console": {
        "protocol": "vnc",
        "type": "novnc",
        "url": "http://example.com:6080/vnc_auto.html?token=b60bcfc3-5fd4-4d21-986c-e83379107819"
    }
}

Servers Security Groups (servers, os-security-groups)

Lists Security Groups for a server.

GET

/servers/{server_id}/os-security-groups

List Security Groups By Server

detail

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"
        }
    ]
}

Server metadata (servers, metadata)

Lists metadata, creates or replaces one or more metadata items, and updates one or more metadata items for a server.

Shows details for, creates or replaces, and updates a metadata item, by key, for a server.

GET

/servers/{server_id}/metadata

List All Metadata

detail

Lists all metadata for a server.

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

Normal response codes: 200

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

Request

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

Response

Name	In	Type	Description
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example List All Metadata

{
    "metadata": {
        "foo": "Foo Value"
    }
}

POST

/servers/{server_id}/metadata

Create or Update Metadata Items

detail

Create or update one or more metadata items for a server.

Creates any metadata items that do not already exist in the server, replaces exists metadata items that match keys. Does not modify items that are not in the request.

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

Normal response codes: 200

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}

Response

Name	In	Type	Description
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}

PUT

/servers/{server_id}/metadata

Replace Metadata Items

detail

Replaces one or more metadata items for a server.

Creates any metadata items that do not already exist in the server. Removes and completely replaces any metadata items that already exist in the server with the metadata items in the request.

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

Normal response codes: 200

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Or Replace Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}

Response

Name	In	Type	Description
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Or Replace Metadata Items

{
    "metadata": {
        "foo": "Foo Value"
    }
}

GET

/servers/{server_id}/metadata/{key}

Show Metadata Item Details

detail

Shows details for a metadata item, by key, for a server.

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

Normal response codes: 200

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
key	path	string	The metadata item key, as a string. Maximum length is 255 characters.

Response

Name	In	Type	Description
meta	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Show Metadata Item Details

{
    "meta": {
        "foo": "Foo Value"
    }
}

PUT

/servers/{server_id}/metadata/{key}

Create Or Update Metadata Item

detail

Creates or replaces a metadata item, by key, for a server.

Creates a metadata item that does not already exist in the server. Replaces existing metadata items that match keys with the metadata item in the request.

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

Normal response codes: 200

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
key	path	string	The metadata item key, as a string. Maximum length is 255 characters.

Example Create Or Update Metadata Item

{
    "meta": {
        "foo": "Bar Value"
    }
}

Response

Name	In	Type	Description
meta	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Or Update Metadata Item

{
    "meta": {
        "foo": "Foo Value"
    }
}

DELETE

/servers/{server_id}/metadata/{key}

Delete Metadata Item

detail

Deletes a metadata item, by key, from a server.

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

Normal response codes: 204

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
key	path	string	The metadata item key, as a string. Maximum length is 255 characters.

Response

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

Servers actions (servers, os-instance-actions)

List actions and action details for a server.

GET

/servers/{server_id}/os-instance-actions

List Actions For Server

detail

Lists actions for a server.

Action information 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: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the last-seen item from the response as the marker parameter value in a subsequent limited request. New in version 2.58
marker (Optional)	query	string	The request_id of the last-seen instance action. Use the limit parameter to make an initial limited request and use the last-seen item from the response as the marker parameter value in a subsequent limited request. New in version 2.58
changes-since (Optional)	query	string	Filters the response by a date and time stamp when the instance action last changed. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. New in version 2.58

Response

Name	In	Type	Description
instanceActions	body	array	List of the actions for the given instance.
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 UUID of the project that this server belongs to.
request_id	body	string	The request id generated when execute the API of this action.
start_time	body	string	The date and time when the action was started. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
user_id	body	string	The user ID of the user who owns the server.
updated_at	body	string	The date and time when the instance action or the action event of instance action was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. New in version 2.58
links (Optional)	body	array	Links pertaining to the instance action. This parameter is returned when paging and more data is available. See API Guide / Links and References for more info. New in version 2.58

Example List Actions For Server: JSON response

{
    "instanceActions": [
        {
            "action": "resize",
            "instance_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
            "message": "",
            "project_id": "842",
            "request_id": "req-25517360-b757-47d3-be45-0e8d2a01b36a",
            "start_time": "2012-12-05T01:00:00.000000",
            "user_id": "789"
        },
        {
            "action": "reboot",
            "instance_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
            "message": "",
            "project_id": "147",
            "request_id": "req-3293a3f1-b44c-4609-b8d2-d81b105636b8",
            "start_time": "2012-12-05T00:00:00.000000",
            "user_id": "789"
        }
    ]
}

Example List Actions For Server With Links (v2.58):

{
    "instanceActions": [
        {
            "instance_uuid": "e357e6d8-952e-4d1d-b74f-c8519e937706",
            "user_id": "fake",
            "start_time": "2017-12-07T11:07:06.088644",
            "updated_at": "2017-12-07T11:07:06.431902",
            "request_id": "req-e80018f1-c5bd-45ee-aaa9-290f2f5ef7bc",
            "action": "stop",
            "message": null,
            "project_id": "6f70656e737461636b20342065766572"
        }
    ],
    "links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/e357e6d8-952e-4d1d-b74f-c8519e937706/os-instance-actions?limit=1&marker=req-e80018f1-c5bd-45ee-aaa9-290f2f5ef7bc",
            "rel": "next"
        }
    ]
}

GET

/servers/{server_id}/os-instance-actions/{request_id}

Show Server Action Details

detail

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 UUID of the project that this server belongs to.
request_id	body	string	The request id generated when execute the API of this action.
start_time	body	string	The date and time when the action was started. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
user_id	body	string	The user ID of the user who owns the server.
events (Optional)	body	array	The events which occurred in this action. Policy defaults enable only users with the administrative role to see instance action event information. Cloud providers can change these permissions through the policy.json file. Available until version 2.50
events	body	array	The events which occurred in this action. Policy defaults enable only users with the administrative role or the owner of the server to see instance action event information. Cloud providers can change these permissions through the policy.json file. New in version 2.51
events.event	body	string	The name of the event.
events.start_time	body	string	The date and time when the event was started. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
events.finish_time	body	string	The date and time when the event was finished. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
events.result	body	string	The result of the event.
events.traceback	body	string	The traceback stack if an error occurred in this event. Policy defaults enable only users with the administrative role to see an instance action event traceback. Cloud providers can change these permissions through the policy.json file.
updated_at	body	string	The date and time when the instance action or the action event of instance action was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. New in version 2.58

Example Show Server Action Details For Admin (v2.1)

{
    "instanceAction": {
        "action": "reboot",
        "events": [
            {
                "event": "schedule",
                "finish_time": "2012-12-05T01:02:00.000000",
                "result": "Success",
                "start_time": "2012-12-05T01:00:02.000000",
                "traceback": ""
            },
            {
                "event": "compute_create",
                "finish_time": "2012-12-05T01:04:00.000000",
                "result": "Success",
                "start_time": "2012-12-05T01:03:00.000000",
                "traceback": ""
            }
        ],
        "instance_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
        "message": "",
        "project_id": "147",
        "request_id": "req-3293a3f1-b44c-4609-b8d2-d81b105636b8",
        "start_time": "2012-12-05T00:00:00.000000",
        "user_id": "789"
    }
}

Example Show Server Action Details For Non-Admin (v2.51)

{
    "instanceAction": {
        "action": "reboot",
        "events": [
            {
                "event": "schedule",
                "finish_time": "2012-12-05T01:02:00.000000",
                "result": "Success",
                "start_time": "2012-12-05T01:00:02.000000"
            },
            {
                "event": "compute_create",
                "finish_time": "2012-12-05T01:04:00.000000",
                "result": "Success",
                "start_time": "2012-12-05T01:03:00.000000"
            }
        ],
        "instance_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
        "message": "",
        "project_id": "147",
        "request_id": "req-3293a3f1-b44c-4609-b8d2-d81b105636b8",
        "start_time": "2012-12-05T00:00:00.000000",
        "user_id": "789"
    }
}

Port interfaces (servers, os-interface)

List port interfaces, show port interface details of the given server. Create a port interface and uses it to attach a port to the given server, detach a port interface from the given server.

GET

/servers/{server_id}/os-interface

List Port Interfaces

detail

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.

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"
        }
    ]
}

POST

/servers/{server_id}/os-interface

Create Interface

detail

Creates a port interface and uses it to attach a port to a server.

Normal response codes: 200

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
interfaceAttachment	body	string	Specify the interfaceAttachment action in the request body.
port_id (Optional)	body	string	The ID of the port for which you want to create an interface. The net_id and port_id parameters are mutually exclusive. If you do not specify the port_id parameter, the OpenStack Networking API v2.0 allocates a port and creates an interface for it on the network.
net_id (Optional)	body	string	The ID of the network for which you want to create a port interface. The net_id and port_id parameters are mutually exclusive. If you do not specify the net_id parameter, the OpenStack Networking API v2.0 uses the network information cache that is associated with the instance.
fixed_ips (Optional)	body	array	Fixed IP addresses. If you request a specific fixed IP address without a net_id, the request returns a Bad Request (400) response code.
ip_address	body	string	The IP address. It is required when fixed_ips is specified.
tag (Optional)	body	string	A device role tag that can be applied to a network interface when attaching it to the VM. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled. New in version 2.49

Example Create Interface: JSON request

Create interface with net_id and fixed_ips.

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "192.168.1.3"
            }
        ],
        "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6"
    }
}

Create interface with port_id.

{
    "interfaceAttachment": {
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442"
    }
}

Example Create Tagged Interface (v2.49): JSON request

{
    "interfaceAttachment": {
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442",
        "tag": "foo"
    }
}

Response

Name	In	Type	Description
interfaceAttachment	body	object	The interface attachment.
fixed_ips	body	array	Fixed IP addresses with subnet IDs.
ip_address	body	string	The IP address.
subnet_id	body	string	The UUID of the subnet.
mac_addr	body	string	The MAC address.
net_id	body	string	The network ID.
port_id	body	string	The port ID.
port_state	body	string	The port state.

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

GET

/servers/{server_id}/os-interface/{port_id}

Show Port Interface Details

detail

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.

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

DELETE

/servers/{server_id}/os-interface/{port_id}

Detach Interface

detail

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 with volume attachments (servers, os-volume_attachments)

Attaches volumes that are created through the volume API to server instances. Also, lists volume attachments for a server, shows details for a volume attachment, and detaches a volume.

GET

/servers/{server_id}/os-volume_attachments

List volume attachments for an instance

detail

List volume attachments for an instance.

Normal response codes: 200

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

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
limit (Optional)	query	integer	Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.
offset (Optional)	query	integer	Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name	In	Type	Description
volumeAttachments	body	array	The list of volume attachments.
device	body	string	Name of the device such as, /dev/vdb.
id	body	string	The UUID of the attachment.
serverId	body	string	The UUID of the server.
volumeId	body	string	The UUID of the attached volume.

Example List volume attachments for an instance: JSON response

{
    "volumeAttachments": [
        {
            "device": "/dev/sdd",
            "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
            "serverId": "4d8c3732-a248-40ed-bebc-539a6ffd25c0",
            "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
        },
        {
            "device": "/dev/sdc",
            "id": "a26887c6-c47b-4654-abb5-dfadf7d3f804",
            "serverId": "4d8c3732-a248-40ed-bebc-539a6ffd25c0",
            "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f804"
        }
    ]
}

POST

/servers/{server_id}/os-volume_attachments

Attach a volume to an instance

detail

Attach a volume to an instance.

Normal response codes: 200

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

注釈

From v2.20 attach a volume to an instance in SHELVED or SHELVED_OFFLOADED state is allowed.

注釈

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.

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
volumeAttachment	body	object	A dictionary representation of a volume attachment containing the fields device and volumeId.
volumeId	body	string	The UUID of the volume to attach.
device (Optional)	body	string	Name of the device such as, /dev/vdb. Omit or set this parameter to null for auto-assignment, if supported. If you specify this parameter, the device must not exist in the guest operating system. Note that as of the 12.0.0 Liberty release, the Nova libvirt driver no longer honors a user-supplied device name. This is the same behavior as if the device name parameter is not supplied on the request.
tag (Optional)	body	string	A device role tag that can be applied to a volume when attaching it to the VM. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled. 注釈 Tagged volume attachment is not supported for shelved-offloaded instances. New in version 2.49

Example Attach a volume to an instance: JSON request

{
    "volumeAttachment": {
        "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "device": "/dev/vdd"
    }
}

Example Attach a volume to an instance and tag it (v2.49): JSON request

{
    "volumeAttachment": {
        "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "tag": "foo"
    }
}

Response

Name	In	Type	Description
volumeAttachment	body	object	A dictionary representation of a volume attachment containing the fields device, id, serverId and volumeId.
device	body	string	Name of the device such as, /dev/vdb.
id	body	string	The UUID of the attachment.
serverId	body	string	The UUID of the server.
volumeId	body	string	The UUID of the attached volume.

Example Attach a volume to an instance: JSON response

{
    "volumeAttachment": {
        "device": "/dev/vdd",
        "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "serverId": "0c92f3f6-c253-4c9b-bd43-e880a8d2eb0a",
        "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
    }
}

No body is returned on successful request.

DELETE

/servers/{server_id}/os-volume_attachments/{volume_id}

Detach a volume from an instance

detail

Detach a volume from an instance.

Normal response codes: 202

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

注釈

From v2.20 detach a volume from an instance in SHELVED or SHELVED_OFFLOADED state is allowed.

Request

Name	In	Type	Description
server_id	path	string	The UUID of the server.
volume_id	body	string	The source volume ID.

Response

No body is returned on successful request.

Flavors

Show and manage server flavors.

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

GET

/flavors

List Flavors

detail

Lists all flavors accessible to your project.

Normal response codes: 200

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

Request

Name	In	Type	Description
sort_key (Optional)	query	string	Sorts by a flavor attribute. Default attribute is flavorid. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the flavor sort_key attribute. The sort keys are limited to: created_at description disabled ephemeral_gb flavorid id is_public memory_mb name root_gb rxtx_factor swap updated_at vcpu_weight vcpus
sort_dir (Optional)	query	string	Sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the flavor sort_key attribute.
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional)	query	string	The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
minDisk (Optional)	query	integer	Filters the response by a minimum disk space, in GiB. For example, 100.
minRam (Optional)	query	integer	Filters the response by a minimum RAM, in MB. For example, 512.
is_public (Optional)	query	boolean	Filters the flavor list by only public flavors. By default non admin users only see public flavors, and admin users can see additional non public flavors.

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"
        }
    ]
}

GET

/flavors/detail

List Flavors With Details

detail

Lists flavors with details.

Normal response codes: 200

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

Request

Name	In	Type	Description
sort_key (Optional)	query	string	Sorts by a flavor attribute. Default attribute is flavorid. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the flavor sort_key attribute. The sort keys are limited to: created_at description disabled ephemeral_gb flavorid id is_public memory_mb name root_gb rxtx_factor swap updated_at vcpu_weight vcpus
sort_dir (Optional)	query	string	Sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the flavor sort_key attribute.
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional)	query	string	The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
minDisk (Optional)	query	integer	Filters the response by a minimum disk space, in GiB. For example, 100.
minRam (Optional)	query	integer	Filters the response by a minimum RAM, in MB. For example, 512.
is_public (Optional)	query	boolean	Filters the flavor list by only public flavors. By default non admin users only see public flavors, and admin users can see additional non public flavors.

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 filter scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the os_compute_api:servers:create:zero_disk_flavor policy rule.
vcpus	body	integer	The number of virtual CPUs that will be allocated to the server.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
OS-FLV-EXT-DATA:ephemeral	body	integer	The size of the ephemeral disk that will be created, in GiB. Ephemeral disks may be written over on server state changes. So should only be used as a scratch space for applications that are aware of its limitations. Defaults to 0.
OS-FLV-DISABLED:disabled (Optional)	body	boolean	Whether or not the flavor has been administratively disabled. This is typically only visible to administrative users.
swap	body	integer	The size of a dedicated swap disk that will be allocated, in MiB. If 0 (the default), no dedicated swap disk will be created. Currently, the empty string ('') is used to represent 0.
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.

Example List Flavors With Details (v2.55)

{
    "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": "",
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": null
        },
        {
            "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": "",
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": null
        },
        {
            "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": "",
            "vcpus": 2,
            "rxtx_factor": 1.0,
            "description": null
        },
        {
            "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": "",
            "vcpus": 4,
            "rxtx_factor": 1.0,
            "description": null
        },
        {
            "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": "",
            "vcpus": 8,
            "rxtx_factor": 1.0,
            "description": null
        },
        {
            "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": "",
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": null
        },
        {
            "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": "",
            "vcpus": 1,
            "rxtx_factor": 1.0,
            "description": "test description"
        }
    ]
}

GET

/flavors/{flavor_id}

Show Flavor Details

detail

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 filter scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the os_compute_api:servers:create:zero_disk_flavor policy rule.
vcpus	body	integer	The number of virtual CPUs that will be allocated to the server.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
OS-FLV-EXT-DATA:ephemeral	body	integer	The size of the ephemeral disk that will be created, in GiB. Ephemeral disks may be written over on server state changes. So should only be used as a scratch space for applications that are aware of its limitations. Defaults to 0.
OS-FLV-DISABLED:disabled (Optional)	body	boolean	Whether or not the flavor has been administratively disabled. This is typically only visible to administrative users.
swap	body	integer	The size of a dedicated swap disk that will be allocated, in MiB. If 0 (the default), no dedicated swap disk will be created. Currently, the empty string ('') is used to represent 0.
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.

Example Show Flavor Details (v2.55)

{
    "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": "",
        "vcpus": 1,
        "rxtx_factor": 1.0,
        "description": "test description"
    }
}

Flavors extra-specs (flavors, os-flavor-extra-specs)

Lists, creates, deletes, and updates the extra-specs or keys for a flavor.

GET

/flavors/{flavor_id}/os-extra_specs

List Extra Specs For A Flavor

detail

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": {
        "key1": "value1",
        "key2": "value2"
    }
}

Keypairs (keypairs)

Generates, imports, and deletes SSH keys.

GET

/os-keypairs

List Keypairs

detail

Lists keypairs that are associated with the account.

Normal response codes: 200

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

Request

Name	In	Type	Description
user_id (Optional)	query	string	This allows administrative users to operate key-pairs of specified user ID. New in version 2.10
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the last-seen item from the response as the marker parameter value in a subsequent limited request. New in version 2.35
marker (Optional)	query	string	The last-seen item. Use the limit parameter to make an initial limited request and use the last-seen item from the response as the marker parameter value in a subsequent limited request. New in version 2.35

Response

Name	In	Type	Description
keypairs	body	array	Array of Keypair objects
keypair	body	object	Keypair object
name	body	string	A name for the keypair which will be used to reference it later.
public_key	body	string	The keypair public key.
fingerprint	body	string	The fingerprint for the keypair.
type	body	string	The type of the keypair. Allowed values are ssh or x509. New in version 2.2
keypairs_links (Optional)	body	array	Links pertaining to keypair. See API Guide / Links and References for more info. New in version 2.35

Example List Keypairs (v2.35): JSON response

{
    "keypairs": [
        {
            "keypair": {
                "fingerprint": "7e:eb:ab:24:ba:d1:e1:88:ae:9a:fb:66:53:df:d3:bd",
                "name": "keypair-5d935425-31d5-48a7-a0f1-e76e9813f2c3",
                "type": "ssh",
                "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCkF3MX59OrlBs3dH5CU7lNmvpbrgZxSpyGjlnE8Flkirnc/Up22lpjznoxqeoTAwTW034k7Dz6aYIrZGmQwe2TkE084yqvlj45Dkyoj95fW/sZacm0cZNuL69EObEGHdprfGJQajrpz22NQoCD8TFB8Wv+8om9NH9Le6s+WPe98WC77KLw8qgfQsbIey+JawPWl4O67ZdL5xrypuRjfIPWjgy/VH85IXg/Z/GONZ2nxHgSShMkwqSFECAC5L3PHB+0+/12M/iikdatFSVGjpuHvkLOs3oe7m6HlOfluSJ85BzLWBbvva93qkGmLg4ZAc8rPh2O+YIsBUHNLLMM/oQp Generated-by-Nova\n"
            }
        }
    ],
    "keypairs_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/keypairs?limit=1&marker=keypair-5d935425-31d5-48a7-a0f1-e76e9813f2c3",
            "rel": "next"
        }
    ]
}

POST

/os-keypairs

Create Or Import Keypair

detail

Generates or imports a keypair.

Normal response codes: 200, 201

注釈

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.
public_key (Optional)	body	string	The public ssh key to import. If you omit this value, a keypair is generated for you.
type (Optional)	body	string	The type of the keypair. Allowed values are ssh or x509. New in version 2.2
user_id (Optional)	body	string	The user_id for a keypair. This allows administrative users to upload keys for other users than themselves. New in version 2.10

Example Create Or Import Keypair (v2.10): JSON request

{
    "keypair": {
        "name": "keypair-d20a3d59-9433-4b79-8726-20b431d89c78",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova",
        "user_id": "fake"
    }
}

Response

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.
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.
type	body	string	The type of the keypair. Allowed values are ssh or x509. New in version 2.2

Example Create Or Import Keypair (v2.10): JSON response

{
    "keypair": {
        "fingerprint": "1e:2c:9b:56:79:4b:45:77:f9:ca:7a:98:2c:b0:d5:3c",
        "name": "keypair-803a1926-af78-4b05-902a-1d6f7a8d9d3e",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova",
        "user_id": "fake"
    }
}

GET

/os-keypairs/{keypair_name}

Show Keypair Details

detail

Shows details for a keypair that is associated with the account.

Normal response codes: 200

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

Request

Name	In	Type	Description
keypair_name	path	string	The keypair name.
user_id (Optional)	query	string	This allows administrative users to operate key-pairs of specified user ID. New in version 2.10

Response

Name	In	Type	Description
keypair	body	object	Keypair object
created_at	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
deleted	body	boolean	A boolean indicates whether this keypair is deleted or not. The value is always false (not deleted).
deleted_at	body	none	It is always null.
fingerprint	body	string	The fingerprint for the keypair.
id	body	integer	The keypair ID.
name	body	string	A name for the keypair which will be used to reference it later.
public_key	body	string	The keypair public key.
updated_at	body	none	It is always null.
user_id	body	string	The user_id for a keypair.
type	body	string	The type of the keypair. Allowed values are ssh or x509. New in version 2.2

Example Show Keypair Details (v2.10): JSON response

{
    "keypair": {
        "fingerprint": "44:fe:29:6e:23:14:b9:53:5b:65:82:58:1c:fe:5a:c3",
        "name": "keypair-6638abdb-c4e8-407c-ba88-c8dd7cc3c4f1",
        "type": "ssh",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1HTrHCbb9NawNLSV8N6tSa8i637+EC2dA+lsdHHfQlT54t+N0nHhJPlKWDLhc579j87vp6RDFriFJ/smsTnDnf64O12z0kBaJpJPH2zXrBkZFK6q2rmxydURzX/z0yLSCP77SFJ0fdXWH2hMsAusflGyryHGX20n+mZK6mDrxVzGxEz228dwQ5G7Az5OoZDWygH2pqPvKjkifRw0jwUKf3BbkP0QvANACOk26cv16mNFpFJfI1N3OC5lUsZQtKGR01ptJoWijYKccqhkAKuo902tg/qup58J5kflNm7I61sy1mJon6SGqNUSfoQagqtBH6vd/tU1jnlwZ03uUroAL Generated-by-Nova\n",
        "user_id": "fake",
        "deleted": false,
        "created_at": "2014-05-07T12:06:13.681238",
        "updated_at": null,
        "deleted_at": null,
        "id": 1
    }
}

DELETE

/os-keypairs/{keypair_name}

Delete Keypair

detail

Deletes a keypair.

Normal response codes: 202, 204

注釈

The normal return code is 204 in version 2.2 to match the fact that no body content is returned.

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

Request

Name	In	Type	Description
keypair_name	path	string	The keypair name.
user_id (Optional)	query	string	This allows administrative users to operate key-pairs of specified user ID. New in version 2.10

Response

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

Limits (limits)

Shows rate and absolute limits for the project.

GET

/limits

Show Rate And Absolute Limits

detail

Shows rate and absolute limits for the project.

Normal response codes: 200

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

Request

Name	In	Type	Description
reserved (Optional)	query	integer	Specify whether the result of resource total includes reserved resources or not. 0: Not include reserved resources. Other than 0: Include reserved resources. If non integer value is specified, it is the same as 0.
tenant_id (Optional)	query	string	Specify the project ID (tenant ID) to show the rate and absolute limits. This parameter can be specified by admin only.

Response

Name	In	Type	Description
limits	body	object	Data structure that contains both absolute limits within a deployment.
absolute	body	object	Name/value pairs that set quota limits within a deployment and Name/value pairs of resource usage.
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
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
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.
maxTotalFloatingIps	body	integer	The number of allowed floating IP addresses for each tenant. Available until version 2.35
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 MB, for each tenant.
totalCoresUsed	body	integer	The number of used server cores in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved server cores are also included.
totalFloatingIpsUsed	body	integer	The number of used floating IP addresses in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved floating IP addresses are also included. Available until version 2.35
totalInstancesUsed	body	integer	The number of servers in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved servers are also included.
totalRAMUsed	body	integer	The amount of used server RAM in each tenant. If reserved query parameter is specified and it is not 0, the amount of reserved server RAM is also included.
totalSecurityGroupsUsed	body	integer	The number of used security groups in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved security groups are also included. Available until version 2.35
totalServerGroupsUsed	body	integer	The number of used server groups in each tenant. If reserved query parameter is specified and it is not 0, the number of reserved server groups are also included.
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": 20,
            "maxSecurityGroups": 10,
            "maxServerMeta": 128,
            "maxTotalCores": 20,
            "maxTotalFloatingIps": 10,
            "maxTotalInstances": 10,
            "maxTotalKeypairs": 100,
            "maxTotalRAMSize": 51200,
            "maxServerGroups": 10,
            "maxServerGroupMembers": 10,
            "totalCoresUsed": 0,
            "totalInstancesUsed": 0,
            "totalRAMUsed": 0,
            "totalSecurityGroupsUsed": 0,
            "totalFloatingIpsUsed": 0,
            "totalServerGroupsUsed": 0
        },
        "rate": []
    }
}

Availability zones (os-availability-zone)

Lists and gets detailed availability zone information.

An availability zone is created or updated by setting the availability_zone parameter in the create, update, or create or update methods of the Host Aggregates API. See Host Aggregates for more details.

GET

/os-availability-zone

Get Availability Zone Information

detail

Lists availability zone information.

Normal response codes: 200

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

Response

Name	In	Type	Description
availabilityZoneInfo	body	array	The list of availability zone information.
hosts	body	none	It is always null.
zoneName	body	string	The availability zone name.
zoneState	body	object	The current state of the availability zone.
available	body	boolean	Returns true if the availability zone is available.

Example Get availability zone information

{
    "availabilityZoneInfo": [
        {
            "hosts": null,
            "zoneName": "nova",
            "zoneState": {
                "available": true
            }
        }
    ]
}

GET

/os-availability-zone/detail

Get Detailed Availability Zone Information

detail

Gets detailed availability zone information. Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the policy.json file.

Normal response codes: 200

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

Response

Name	In	Type	Description
availabilityZoneInfo	body	array	The list of availability zone information.
hosts	body	object	An object containing a list of host information. The host information is comprised of host and service objects. The service object returns three parameters representing the states of the service: active, available, and updated_at.
zoneName	body	string	The availability zone name.
zoneState	body	object	The current state of the availability zone.
available	body	boolean	Returns true if the availability zone is available.

Example Get detailed availability zone information

{
    "availabilityZoneInfo": [
        {
            "hosts": {
                "conductor": {
                    "nova-conductor": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                },
                "consoleauth": {
                    "nova-consoleauth": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                },
                "network": {
                    "nova-network": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                },
                "scheduler": {
                    "nova-scheduler": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                }
            },
            "zoneName": "internal",
            "zoneState": {
                "available": true
            }
        },
        {
            "hosts": {
                "compute": {
                    "nova-compute": {
                        "active": true,
                        "available": true,
                        "updated_at": null
                    }
                }
            },
            "zoneName": "nova",
            "zoneState": {
                "available": true
            }
        }
    ]
}

Usage reports (os-simple-tenant-usage)

Reports usage statistics of compute and storage resources periodically for an individual tenant or all tenants. The usage statistics will include all instances' CPU, memory and local disk during a specific period.

Microversion 2.40 added pagination (and next links) to the usage statistics via optional limit and marker query parameters. If limit isn't provided, the configurable max_limit will be used which currently defaults to 1000. Older microversions will not accept these new paging query parameters, but they will start to silently limit by max_limit.

/os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
/os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}

注釈

A tenant's usage statistics may span multiple pages when the number of instances exceeds limit, and API consumers will need to stitch together the aggregate results if they still want totals for all instances in a specific time window, grouped by tenant.

GET

/os-simple-tenant-usage/{tenant_id}

Show Usage Statistics For Tenant

detail

Shows usage statistics for a tenant.

Normal response codes: 200

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

Request

Name	In	Type	Description
tenant_id	path	string	The UUID of the tenant in a multi-tenancy cloud.
end (Optional)	query	string	The ending time to calculate usage statistics on compute and storage resources. The date and time stamp format is any of the following ones: CCYY-MM-DDThh:mm:ss For example, 2015-08-27T09:49:58. CCYY-MM-DDThh:mm:ss.NNNNNN For example, 2015-08-27T09:49:58.123456. CCYY-MM-DD hh:mm:ss.NNNNNN For example, 2015-08-27 09:49:58.123456. If you omit this parameter, the current time is used.
start (Optional)	query	string	The beginning time to calculate usage statistics on compute and storage resources. The date and time stamp format is any of the following ones: CCYY-MM-DDThh:mm:ss For example, 2015-08-27T09:49:58. CCYY-MM-DDThh:mm:ss.NNNNNN For example, 2015-08-27T09:49:58.123456. CCYY-MM-DD hh:mm:ss.NNNNNN For example, 2015-08-27 09:49:58.123456. If you omit this parameter, the current time is used.
limit (Optional)	query	integer	Requests a page size of items. Calculate usage for the limited number of instances. Use the limit parameter to make an initial limited request and use the last-seen instance UUID from the response as the marker parameter value in a subsequent limited request. New in version 2.40
marker (Optional)	query	string	The last-seen item. Use the limit parameter to make an initial limited request and use the last-seen instance UUID from the response as the marker parameter value in a subsequent limited request. New in version 2.40

Response

Name	In	Type	Description
tenant_usage	body	object	The tenant usage object.
server_usages	body	array	A list of the server usage objects.
server_usages.ended_at	body	string	The date and time when the server was deleted. The date and time stamp format is as follows: CCYY-MM-DDThh:mm:ss.NNNNNN For example, 2015-08-27T09:49:58.123456. If the server hasn't been deleted yet, its value is null.
server_usages.flavor	body	string	The display name of a flavor.
server_usages.hours	body	float	The duration that the server exists (in hours).
server_usages.instance_id	body	string	The UUID of the server.
server_usages.local_gb	body	integer	The sum of the root disk size of the server and the ephemeral disk size of it (in GiB).
server_usages.memory_mb	body	integer	The memory size of the server (in MB).
server_usages.name	body	string	The server name.
server_usages.started_at	body	string	The date and time when the server was launched. The date and time stamp format is as follows: CCYY-MM-DDThh:mm:ss.NNNNNN For example, 2015-08-27T09:49:58.123456.
server_usages.state	body	string	The VM state.
server_usages.tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.
server_usages.uptime	body	integer	The uptime of the server.
server_usages.vcpus	body	integer	The number of virtual CPUs that the server uses.
start	body	string	The beginning time to calculate usage statistics on compute and storage resources. The date and time stamp format is as follows: CCYY-MM-DDThh:mm:ss.NNNNNN For example, 2015-08-27T09:49:58.123456.
stop	body	string	The ending time to calculate usage statistics on compute and storage resources. The date and time stamp format is as follows: CCYY-MM-DDThh:mm:ss.NNNNNN For example, 2015-08-27T09:49:58.123456.
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.
total_hours	body	float	The total duration that servers exist (in hours).
total_local_gb_usage	body	float	Multiplying the server disk size (in GiB) by hours the server exists, and then adding that all together for each server.
total_memory_mb_usage	body	float	Multiplying the server memory size (in MB) by hours the server exists, and then adding that all together for each server.
total_vcpus_usage	body	float	Multiplying the number of virtual CPUs of the server by hours the server exists, and then adding that all together for each server.
tenant_usage_links (Optional)	body	array	Links pertaining to usage. See API Guide / Links and References for more info. New in version 2.40

Example Show Usage Details For Tenant (v2.40): JSON response

{
    "tenant_usage": {
        "server_usages": [
            {
                "ended_at": null,
                "flavor": "m1.tiny",
                "hours": 1.0,
                "instance_id": "1f1deceb-17b5-4c04-84c7-e0d4499c8fe0",
                "local_gb": 1,
                "memory_mb": 512,
                "name": "instance-2",
                "started_at": "2012-10-08T20:10:44.541277",
                "state": "active",
                "tenant_id": "6f70656e737461636b20342065766572",
                "uptime": 3600,
                "vcpus": 1
            }
        ],
        "start": "2012-10-08T20:10:44.587336",
        "stop": "2012-10-08T21:10:44.587336",
        "tenant_id": "6f70656e737461636b20342065766572",
        "total_hours": 1.0,
        "total_local_gb_usage": 1.0,
        "total_memory_mb_usage": 512.0,
        "total_vcpus_usage": 1.0
    },
    "tenant_usage_links": [
        {
            "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/os-simple-tenant-usage/6f70656e737461636b20342065766572?end=2016-10-12+18%3A22%3A04.868106&limit=1&marker=1f1deceb-17b5-4c04-84c7-e0d4499c8fe0&start=2016-10-12+18%3A22%3A04.868106",
            "rel": "next"
        }
    ]
}

Quota sets (os-quota-sets)

Permits administrators, depending on policy settings, to view default quotas, view details for quotas, revert quotas to defaults, and update the quotas for a project or a project and user.

GET

/os-quota-sets/{tenant_id}

Show A Quota

detail

Show the quota for a project or a project and a user.

Normal response codes: 200

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

• 400 - BadRequest - the tenant_id is not valid in your cloud, perhaps because it was typoed.

Request

Name	In	Type	Description
tenant_id	path	string	The UUID of the tenant in a multi-tenancy cloud.
user_id (Optional)	query	string	ID of user to list the quotas for.

Response

Name	In	Type	Description
quota_set	body	object	A quota_set object.
cores	body	integer	The number of allowed server cores for each tenant.
fixed_ips	body	integer	The number of allowed fixed IP addresses for each tenant. Must be equal to or greater than the number of allowed servers. Available until version 2.35
floating_ips	body	integer	The number of allowed floating IP addresses for each tenant. Available until version 2.35
id	body	string	The UUID of the tenant/user the quotas listed for.
injected_file_content_bytes	body	integer	The number of allowed bytes of content for each injected file. Available until version 2.56
injected_file_path_bytes	body	integer	The number of allowed bytes for each injected file path. Available until version 2.56
injected_files	body	integer	The number of allowed injected files for each tenant. Available until version 2.56
instances	body	integer	The number of allowed servers for each tenant.
key_pairs	body	integer	The number of allowed key pairs for each user.
metadata_items	body	integer	The number of allowed metadata items for each server.
ram	body	integer	The amount of allowed server RAM, in MB, for each tenant.
security_group_rules	body	integer	The number of allowed rules for each security group. Available until version 2.35
security_groups	body	integer	The number of allowed security groups for each tenant. Available until version 2.35
server_groups	body	integer	The number of allowed server groups for each tenant.
server_group_members	body	integer	The number of allowed members for each server group.
networks (Optional)	body	integer	The number of private networks that can be created per project. Available until version 2.35

Example Show A Quota: JSON response

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": 10,
        "id": "fake_tenant",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": 20,
        "security_groups": 10,
        "server_groups": 10,
        "server_group_members": 10,
        "networks": 3
    }
}

GET

/os-quota-sets/{tenant_id}/defaults

List Default Quotas For Tenant

detail

Lists the default quotas for a project.

Normal response codes: 200

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

Request

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

Response

Name	In	Type	Description
quota_set	body	object	A quota_set object.
cores	body	integer	The number of allowed server cores for each tenant.
fixed_ips	body	integer	The number of allowed fixed IP addresses for each tenant. Must be equal to or greater than the number of allowed servers. Available until version 2.35
floating_ips	body	integer	The number of allowed floating IP addresses for each tenant. Available until version 2.35
id	body	string	The UUID of the tenant/user the quotas listed for.
injected_file_content_bytes	body	integer	The number of allowed bytes of content for each injected file. Available until version 2.56
injected_file_path_bytes	body	integer	The number of allowed bytes for each injected file path. Available until version 2.56
injected_files	body	integer	The number of allowed injected files for each tenant. Available until version 2.56
instances	body	integer	The number of allowed servers for each tenant.
key_pairs	body	integer	The number of allowed key pairs for each user.
metadata_items	body	integer	The number of allowed metadata items for each server.
ram	body	integer	The amount of allowed server RAM, in MB, for each tenant.
security_group_rules	body	integer	The number of allowed rules for each security group. Available until version 2.35
security_groups	body	integer	The number of allowed security groups for each tenant. Available until version 2.35
server_groups	body	integer	The number of allowed server groups for each tenant.
server_group_members	body	integer	The number of allowed members for each server group.
networks (Optional)	body	integer	The number of private networks that can be created per project. Available until version 2.35

Example List Default Quotas For Tenant: JSON response

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": 10,
        "id": "fake_tenant",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": 20,
        "security_groups": 10,
        "server_groups": 10,
        "server_group_members": 10,
        "networks": 3
    }
}

Extensions (extensions) (DEPRECATED)

Lists available extensions and shows information for an extension, by alias.

Nova originally supported the concept of API extensions, that allowed implementations of Nova to change the API (add new resources, or attributes to existing resource objects) via extensions. In an attempt to expose to the user what was supported in a particular site, the extensions resource provided a list of extensions and detailed information on each. The net result was gratuitous differentiation in the API that required all users of OpenStack clouds to write specific code to interact with every cloud.

As such, the entire extensions concept is deprecated, and will be removed in the near future.

For information about extensions, see Extensions.

GET

/extensions

List Extensions

detail

Lists all extensions to the API.

Normal response codes: 200

Error response codes: unauthorized(401)

Response

Name	In	Type	Description
extensions	body	array	List of extension objects.
name	body	string	Name of the extension.
alias	body	string	A short name by which this extension is also known.
links	body	array	Links pertaining to this extension. This is a list of dictionaries, each including keys href and rel.
namespace	body	string	A URL pointing to the namespace for this extension.
description	body	string	Text describing this extension's purpose.
updated	body	string	The date and time when the resource was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

Example List Extensions

Lists all extensions to the API.

{
    "extensions": [
        {
            "alias": "NMN",
            "description": "Multiple network support.",
            "links": [],
            "name": "Multinic",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-DCF",
            "description": "Disk Management Extension.",
            "links": [],
            "name": "DiskConfig",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-AZ",
            "description": "Extended Availability Zone support.",
            "links": [],
            "name": "ExtendedAvailabilityZone",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-IMG-SIZE",
            "description": "Adds image size to image listings.",
            "links": [],
            "name": "ImageSize",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-IPS",
            "description": "Adds type parameter to the ip list.",
            "links": [],
            "name": "ExtendedIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-IPS-MAC",
            "description": "Adds mac address parameter to the ip list.",
            "links": [],
            "name": "ExtendedIpsMac",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-SRV-ATTR",
            "description": "Extended Server Attributes support.",
            "links": [],
            "name": "ExtendedServerAttributes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-STS",
            "description": "Extended Status support.",
            "links": [],
            "name": "ExtendedStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-FLV-DISABLED",
            "description": "Support to show the disabled status of a flavor.",
            "links": [],
            "name": "FlavorDisabled",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-FLV-EXT-DATA",
            "description": "Provide additional data for flavors.",
            "links": [],
            "name": "FlavorExtraData",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-SCH-HNT",
            "description": "Pass arbitrary key/value pairs to the scheduler.",
            "links": [],
            "name": "SchedulerHints",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-SRV-USG",
            "description": "Adds launched_at and terminated_at on Servers.",
            "links": [],
            "name": "ServerUsage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-access-ips",
            "description": "Access IPs support.",
            "links": [],
            "name": "AccessIPs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-admin-actions",
            "description": "Enable admin-only server actions\n\n    Actions include: resetNetwork, injectNetworkInfo, os-resetState\n    ",
            "links": [],
            "name": "AdminActions",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-admin-password",
            "description": "Admin password management support.",
            "links": [],
            "name": "AdminPassword",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-agents",
            "description": "Agents support.",
            "links": [],
            "name": "Agents",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-aggregates",
            "description": "Admin-only aggregate administration.",
            "links": [],
            "name": "Aggregates",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-assisted-volume-snapshots",
            "description": "Assisted volume snapshots.",
            "links": [],
            "name": "AssistedVolumeSnapshots",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-attach-interfaces",
            "description": "Attach interface support.",
            "links": [],
            "name": "AttachInterfaces",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-availability-zone",
            "description": "1. Add availability_zone to the Create Server API.\n       2. Add availability zones describing.\n    ",
            "links": [],
            "name": "AvailabilityZone",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-baremetal-ext-status",
            "description": "Add extended status in Baremetal Nodes v2 API.",
            "links": [],
            "name": "BareMetalExtStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-baremetal-nodes",
            "description": "Admin-only bare-metal node administration.",
            "links": [],
            "name": "BareMetalNodes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-block-device-mapping",
            "description": "Block device mapping boot support.",
            "links": [],
            "name": "BlockDeviceMapping",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-block-device-mapping-v2-boot",
            "description": "Allow boot with the new BDM data format.",
            "links": [],
            "name": "BlockDeviceMappingV2Boot",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cell-capacities",
            "description": "Adding functionality to get cell capacities.",
            "links": [],
            "name": "CellCapacities",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cells",
            "description": "Enables cells-related functionality such as adding neighbor cells,\n    listing neighbor cells, and getting the capabilities of the local cell.\n    ",
            "links": [],
            "name": "Cells",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-certificates",
            "description": "Certificates support.",
            "links": [],
            "name": "Certificates",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cloudpipe",
            "description": "Adds actions to create cloudpipe instances.\n\n    When running with the Vlan network mode, you need a mechanism to route\n    from the public Internet to your vlans.  This mechanism is known as a\n    cloudpipe.\n\n    At the time of creating this class, only OpenVPN is supported.  Support for\n    a SSH Bastion host is forthcoming.\n    ",
            "links": [],
            "name": "Cloudpipe",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cloudpipe-update",
            "description": "Adds the ability to set the vpn ip/port for cloudpipe instances.",
            "links": [],
            "name": "CloudpipeUpdate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-config-drive",
            "description": "Config Drive Extension.",
            "links": [],
            "name": "ConfigDrive",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-console-auth-tokens",
            "description": "Console token authentication support.",
            "links": [],
            "name": "ConsoleAuthTokens",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-console-output",
            "description": "Console log output support, with tailing ability.",
            "links": [],
            "name": "ConsoleOutput",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-consoles",
            "description": "Interactive Console support.",
            "links": [],
            "name": "Consoles",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-create-backup",
            "description": "Create a backup of a server.",
            "links": [],
            "name": "CreateBackup",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-create-server-ext",
            "description": "Extended support to the Create Server v1.1 API.",
            "links": [],
            "name": "Createserverext",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-deferred-delete",
            "description": "Instance deferred delete.",
            "links": [],
            "name": "DeferredDelete",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-evacuate",
            "description": "Enables server evacuation.",
            "links": [],
            "name": "Evacuate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-evacuate-find-host",
            "description": "Enables server evacuation without target host. Scheduler will select one to target.",
            "links": [],
            "name": "ExtendedEvacuateFindHost",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-floating-ips",
            "description": "Adds optional fixed_address to the add floating IP command.",
            "links": [],
            "name": "ExtendedFloatingIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-hypervisors",
            "description": "Extended hypervisors support.",
            "links": [],
            "name": "ExtendedHypervisors",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-networks",
            "description": "Adds additional fields to networks.",
            "links": [],
            "name": "ExtendedNetworks",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-quotas",
            "description": "Adds ability for admins to delete quota and optionally force the update Quota command.",
            "links": [],
            "name": "ExtendedQuotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-rescue-with-image",
            "description": "Allow the user to specify the image to use for rescue.",
            "links": [],
            "name": "ExtendedRescueWithImage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-services",
            "description": "Extended services support.",
            "links": [],
            "name": "ExtendedServices",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-services-delete",
            "description": "Extended services deletion support.",
            "links": [],
            "name": "ExtendedServicesDelete",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-status",
            "description": "Extended Status support.",
            "links": [],
            "name": "ExtendedStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-volumes",
            "description": "Extended Volumes support.",
            "links": [],
            "name": "ExtendedVolumes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-fixed-ips",
            "description": "Fixed IPs support.",
            "links": [],
            "name": "FixedIPs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-access",
            "description": "Flavor access support.",
            "links": [],
            "name": "FlavorAccess",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-extra-specs",
            "description": "Flavors extra specs support.",
            "links": [],
            "name": "FlavorExtraSpecs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-manage",
            "description": "Flavor create/delete API support.",
            "links": [],
            "name": "FlavorManage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-rxtx",
            "description": "Support to show the rxtx status of a flavor.",
            "links": [],
            "name": "FlavorRxtx",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-flavor-swap",
            "description": "Support to show the swap status of a flavor.",
            "links": [],
            "name": "FlavorSwap",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ip-dns",
            "description": "Floating IP DNS support.",
            "links": [],
            "name": "FloatingIpDns",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ip-pools",
            "description": "Floating IPs support.",
            "links": [],
            "name": "FloatingIpPools",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ips",
            "description": "Floating IPs support.",
            "links": [],
            "name": "FloatingIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-floating-ips-bulk",
            "description": "Bulk handling of Floating IPs.",
            "links": [],
            "name": "FloatingIpsBulk",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-fping",
            "description": "Fping Management Extension.",
            "links": [],
            "name": "Fping",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hide-server-addresses",
            "description": "Support hiding server addresses in certain states.",
            "links": [],
            "name": "HideServerAddresses",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hosts",
            "description": "Admin-only host administration.",
            "links": [],
            "name": "Hosts",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hypervisor-status",
            "description": "Show hypervisor status.",
            "links": [],
            "name": "HypervisorStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-hypervisors",
            "description": "Admin-only hypervisor administration.",
            "links": [],
            "name": "Hypervisors",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-instance-actions",
            "description": "View a log of actions and events taken on an instance.",
            "links": [],
            "name": "InstanceActions",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-instance_usage_audit_log",
            "description": "Admin-only Task Log Monitoring.",
            "links": [],
            "name": "OSInstanceUsageAuditLog",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-keypairs",
            "description": "Keypair Support.",
            "links": [],
            "name": "Keypairs",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-lock-server",
            "description": "Enable lock/unlock server actions.",
            "links": [],
            "name": "LockServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-migrate-server",
            "description": "Enable migrate and live-migrate server actions.",
            "links": [],
            "name": "MigrateServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-migrations",
            "description": "Provide data on migrations.",
            "links": [],
            "name": "Migrations",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-multiple-create",
            "description": "Allow multiple create in the Create Server v2.1 API.",
            "links": [],
            "name": "MultipleCreate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-networks",
            "description": "Admin-only Network Management Extension.",
            "links": [],
            "name": "Networks",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-networks-associate",
            "description": "Network association support.",
            "links": [],
            "name": "NetworkAssociationSupport",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-pause-server",
            "description": "Enable pause/unpause server actions.",
            "links": [],
            "name": "PauseServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-personality",
            "description": "Personality support.",
            "links": [],
            "name": "Personality",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-preserve-ephemeral-rebuild",
            "description": "Allow preservation of the ephemeral partition on rebuild.",
            "links": [],
            "name": "PreserveEphemeralOnRebuild",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-quota-class-sets",
            "description": "Quota classes management support.",
            "links": [],
            "name": "QuotaClasses",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-quota-sets",
            "description": "Quotas management support.",
            "links": [],
            "name": "Quotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-rescue",
            "description": "Instance rescue mode.",
            "links": [],
            "name": "Rescue",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-security-group-default-rules",
            "description": "Default rules for security group support.",
            "links": [],
            "name": "SecurityGroupDefaultRules",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-security-groups",
            "description": "Security group support.",
            "links": [],
            "name": "SecurityGroups",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-diagnostics",
            "description": "Allow Admins to view server diagnostics through server action.",
            "links": [],
            "name": "ServerDiagnostics",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-external-events",
            "description": "Server External Event Triggers.",
            "links": [],
            "name": "ServerExternalEvents",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-group-quotas",
            "description": "Adds quota support to server groups.",
            "links": [],
            "name": "ServerGroupQuotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-groups",
            "description": "Server group support.",
            "links": [],
            "name": "ServerGroups",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-list-multi-status",
            "description": "Allow to filter the servers by a set of status values.",
            "links": [],
            "name": "ServerListMultiStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-password",
            "description": "Server password support.",
            "links": [],
            "name": "ServerPassword",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-sort-keys",
            "description": "Add sorting support in get Server v2 API.",
            "links": [],
            "name": "ServerSortKeys",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-start-stop",
            "description": "Start/Stop instance compute API support.",
            "links": [],
            "name": "ServerStartStop",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-services",
            "description": "Services support.",
            "links": [],
            "name": "Services",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-shelve",
            "description": "Instance shelve mode.",
            "links": [],
            "name": "Shelve",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-simple-tenant-usage",
            "description": "Simple tenant usage extension.",
            "links": [],
            "name": "SimpleTenantUsage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-suspend-server",
            "description": "Enable suspend/resume server actions.",
            "links": [],
            "name": "SuspendServer",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-tenant-networks",
            "description": "Tenant-based Network Management Extension.",
            "links": [],
            "name": "OSTenantNetworks",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-used-limits",
            "description": "Provide data on limited resources that are being used.",
            "links": [],
            "name": "UsedLimits",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-used-limits-for-admin",
            "description": "Provide data to admin on limited resources used by other tenants.",
            "links": [],
            "name": "UsedLimitsForAdmin",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-user-data",
            "description": "Add user_data to the Create Server API.",
            "links": [],
            "name": "UserData",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-user-quotas",
            "description": "Project user quota support.",
            "links": [],
            "name": "UserQuotas",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-virtual-interfaces",
            "description": "Virtual interface support.",
            "links": [],
            "name": "VirtualInterfaces",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-volume-attachment-update",
            "description": "Support for updating a volume attachment.",
            "links": [],
            "name": "VolumeAttachmentUpdate",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-volumes",
            "description": "Volumes support.",
            "links": [],
            "name": "Volumes",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        }
    ]
}

GET

/extensions/{alias}

Show Extension Details

detail

Shows details for an extension, by alias.

Normal response codes: 200

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

Request

Name	In	Type	Description
alias	body	string	A short name by which this extension is also known.

Response

Name	In	Type	Description
extension	body	object	An extension object.
name	body	string	Name of the extension.
alias	body	string	A short name by which this extension is also known.
links	body	array	Links pertaining to this extension. This is a list of dictionaries, each including keys href and rel.
namespace	body	string	A URL pointing to the namespace for this extension.
description	body	string	Text describing this extension's purpose.
updated	body	string	The date and time when the resource was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

Example Show Extension Details

Shows details about the os-agents extension.

{
    "extension": {
        "alias": "os-agents",
        "description": "Agents support.",
        "links": [],
        "name": "Agents",
        "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
        "updated": "2014-12-03T00:00:00Z"
    }
}

Volume extension (os-volumes, os-snapshots) (DEPRECATED)

警告

These APIs are proxy calls to the Volume service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Volume APIs.

Manages volumes and snapshots for use with the Compute API. Lists, shows details, creates, and deletes volumes and snapshots.

GET

/os-volumes

List Volumes

detail

Lists the volumes associated with the account.

Normal response codes: 200

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

Request

Name	In	Type	Description
limit (Optional)	query	integer	Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.
offset (Optional)	query	integer	Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name	In	Type	Description
volumes	body	array	The list of volume objects.
attachments	body	array	The list of volume attachments.
attachments.device (Optional)	body	string	Name of the device in the attachment object, such as, /dev/vdb.
attachments.id (Optional)	body	string	The UUID of the attachment.
attachments.serverId (Optional)	body	string	The UUID of the server.
attachments.volumeId (Optional)	body	string	The UUID of the attached volume.
availabilityZone	body	string	The availability zone name.
createdAt	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
displayDescription	body	string	The volume description.
displayName	body	string	The volume name.
id	body	string	The UUID of the volume.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.
size	body	integer	The size of the volume, in gibibytes (GiB).
snapshotId	body	string	The UUID for a snapshot.
status	body	string	The status of the volume.
volumeType	body	string	The name or unique identifier for a volume type.

Example List Volumes

{
    "volumes": [
        {
            "attachments": [
                {
                    "device": "/",
                    "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                    "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                    "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
                }
            ],
            "availabilityZone": "zone1:host1",
            "createdAt": "2013-02-19T20:01:40.274897",
            "displayDescription": "Volume Description",
            "displayName": "Volume Name",
            "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
            "metadata": {},
            "size": 100,
            "snapshotId": null,
            "status": "in-use",
            "volumeType": "Backup"
        }
    ]
}

POST

/os-volumes

Create Volume

detail

Creates a new volume.

Normal response codes: 200

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

Request

Name	In	Type	Description
volume	body	object	The volume object.
size	body	integer	The size of the volume, in gibibytes (GiB).
availability_zone (Optional)	body	string	The availability zone name.
display_name (Optional)	body	string	The volume name.
display_description (Optional)	body	string	The volume description.
metadata (Optional)	body	object	Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
volume_type (Optional)	body	string	The unique identifier for a volume type.
snapshot_id (Optional)	body	string	The UUID for a snapshot.

Example Create Volume

{
    "volume": {
        "availability_zone": "zone1:host1",
        "display_name": "Volume Name",
        "display_description": "Volume Description",
        "size": 100
    }
}

Response

Name	In	Type	Description
volume	body	object	The volume object.
attachments	body	array	The list of volume attachments.
attachments.device (Optional)	body	string	Name of the device in the attachment object, such as, /dev/vdb.
attachments.id (Optional)	body	string	The UUID of the attachment.
attachments.serverId (Optional)	body	string	The UUID of the server.
attachments.volumeId (Optional)	body	string	The UUID of the attached volume.
availabilityZone	body	string	The availability zone name.
createdAt	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
displayName	body	string	The volume name.
displayDescription	body	string	The volume description.
id	body	string	The UUID of the volume.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.
size	body	integer	The size of the volume, in gibibytes (GiB).
snapshotId	body	string	The UUID for a snapshot.
status	body	string	The status of the volume.
volumeType	body	string	The name or unique identifier for a volume type.

Example Create Volume

{
    "volume": {
        "attachments": [
            {
                "device": "/",
                "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
            }
        ],
        "availabilityZone": "zone1:host1",
        "createdAt": "2013-02-18T14:51:17.970024",
        "displayDescription": "Volume Description",
        "displayName": "Volume Name",
        "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "metadata": {},
        "size": 100,
        "snapshotId": null,
        "status": "in-use",
        "volumeType": "Backup"
    }
}

GET

/os-volumes/detail

List Volumes With Details

detail

Lists all volumes with details.

Normal response codes: 200

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

Request

Name	In	Type	Description
limit (Optional)	query	integer	Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.
offset (Optional)	query	integer	Used in conjunction with limit to return a slice of items. offset is where to start in the list.

Response

Name	In	Type	Description
volumes	body	array	The list of volume objects.
attachments	body	array	The list of volume attachments.
attachments.device (Optional)	body	string	Name of the device in the attachment object, such as, /dev/vdb.
attachments.id (Optional)	body	string	The UUID of the attachment.
attachments.serverId (Optional)	body	string	The UUID of the server.
attachments.volumeId (Optional)	body	string	The UUID of the attached volume.
availabilityZone	body	string	The availability zone name.
createdAt	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
displayName	body	string	The volume name.
displayDescription	body	string	The volume description.
id	body	string	The UUID of the volume.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.
size	body	integer	The size of the volume, in gibibytes (GiB).
snapshotId	body	string	The UUID for a snapshot.
status	body	string	The status of the volume.
volumeType	body	string	The name or unique identifier for a volume type.

Example List Volumes With Details

{
    "volumes": [
        {
            "attachments": [
                {
                    "device": "/",
                    "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                    "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                    "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
                }
            ],
            "availabilityZone": "zone1:host1",
            "createdAt": "1999-01-01T01:01:01.000000",
            "displayDescription": "Volume Description",
            "displayName": "Volume Name",
            "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
            "metadata": {},
            "size": 100,
            "snapshotId": null,
            "status": "in-use",
            "volumeType": "Backup"
        }
    ]
}

GET

/os-volumes/{volume_id}

Show Volume Details

detail

Shows details for a given volume.

Normal response codes: 200

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

Request

Name	In	Type	Description
volume_id	path	string	The unique ID for a volume.

Response

Name	In	Type	Description
volume	body	object	The volume object.
attachments	body	array	The list of volume attachments.
attachment.device (Optional)	body	string	Name of the device in the attachment object, such as, /dev/vdb.
attachments.id (Optional)	body	string	The UUID of the attachment.
attachments.serverId (Optional)	body	string	The UUID of the server.
attachments.volumeId (Optional)	body	string	The UUID of the attached volume.
availabilityZone	body	string	The availability zone name.
createdAt	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
displayName	body	string	The volume name.
displayDescription	body	string	The volume description.
id	body	string	The UUID of the volume.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.
size	body	integer	The size of the volume, in gibibytes (GiB).
snapshotId	body	string	The UUID for a snapshot.
status	body	string	The status of the volume.
volumeType	body	string	The name or unique identifier for a volume type.

Example Show Volume Details

{
    "volume": {
        "attachments": [
            {
                "device": "/",
                "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
                "serverId": "3912f2b4-c5ba-4aec-9165-872876fe202e",
                "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
            }
        ],
        "availabilityZone": "zone1:host1",
        "createdAt": "2013-02-18T14:51:18.528085",
        "displayDescription": "Volume Description",
        "displayName": "Volume Name",
        "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "metadata": {},
        "size": 100,
        "snapshotId": null,
        "status": "in-use",
        "volumeType": "Backup"
    }
}

DELETE

/os-volumes/{volume_id}

Delete Volume

detail

Deletes a volume.

Normal response codes: 202

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

Request

Name	In	Type	Description
volume_id	path	string	The unique ID for a volume.

Response

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

Images (DEPRECATED)

警告

These APIs are proxy calls to the Image service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Image APIs.

Lists, shows details and deletes images. Also sets, lists, shows details, create, update and deletes image metadata.

An image is a collection of files that you use to create and rebuild a server. By default, operators provide pre-built operating system images. You can also create custom images. See: Create Image Action.

By default, the policy.json file authorizes all users to view the image size in the OS-EXT-IMG-SIZE:size extended attribute.

GET

/images

List Images

detail

List images.

Normal response codes: 200

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

Request

Name	In	Type	Description
changes-since (Optional)	query	string	Filters the response by a date and time when the image last changed status. Use this query parameter to check for changes since a previous request rather than re-downloading and re-parsing the full status at each polling interval. If data has changed, the call returns only the items changed since the changes-since time. If data has not changed since the changes-since time, the call returns an empty list. To enable you to keep track of changes, this filter also displays images that were deleted if the changes-since value specifies a date in the last 30 days. Items deleted more than 30 days ago might be returned, but it is not guaranteed. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
server (Optional)	query	string	Filters the response by a server, as a URL.
name (Optional)	query	string	Filters the response by an image name, as a string.
status (Optional)	query	string	Filters the response by an image status, as a string. For example, ACTIVE.
minDisk (Optional)	query	integer	Filters the response by a minimum disk space, in GiB. For example, 100.
minRam (Optional)	query	integer	Filters the response by a minimum RAM, in MB. For example, 512.
type (Optional)	query	string	Filters the response by an image type. For example, snapshot or backup.
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional)	query	string	The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response

Name	In	Type	Description
images	body	array	An array of Image objects.
id	body	string	The ID of the Image.
name	body	string	The display name of an Image.
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.

Example List Images: JSON response

{
    "images": [
        {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage7"
        },
        {
            "id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "a2459075-d96c-40d5-893e-577ff92e721c",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "a440c04b-79fa-479c-bed1-0b816eaec379",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage6"
        },
        {
            "id": "c905cedb-7281-47e4-8a62-f26bc5fc4c77",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "cedef40a-ed67-4d10-800e-17455edce175",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        },
        {
            "id": "76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "name": "fakeimage123456"
        }
    ]
}

GET

/images/detail

List Images With Details

detail

List images with details.

Normal response codes: 200

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

Request

Name	In	Type	Description
changes-since (Optional)	query	string	Filters the response by a date and time when the image last changed status. Use this query parameter to check for changes since a previous request rather than re-downloading and re-parsing the full status at each polling interval. If data has changed, the call returns only the items changed since the changes-since time. If data has not changed since the changes-since time, the call returns an empty list. To enable you to keep track of changes, this filter also displays images that were deleted if the changes-since value specifies a date in the last 30 days. Items deleted more than 30 days ago might be returned, but it is not guaranteed. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.
server (Optional)	query	string	Filters the response by a server, as a URL.
name (Optional)	query	string	Filters the response by an image name, as a string.
status (Optional)	query	string	Filters the response by an image status, as a string. For example, ACTIVE.
minDisk (Optional)	query	integer	Filters the response by a minimum disk space, in GiB. For example, 100.
minRam (Optional)	query	integer	Filters the response by a minimum RAM, in MB. For example, 512.
type (Optional)	query	string	Filters the response by an image type. For example, snapshot or backup.
limit (Optional)	query	integer	Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional)	query	string	The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

Response

Name	In	Type	Description
images	body	array	An array of Image objects.
id	body	string	The ID of the Image.
name	body	string	The display name of an Image.
minRam	body	integer	The minimum amount of RAM an image requires to function, in MB. For example, 512.
minDisk	body	integer	The minimum amount of disk space an image requires to boot, in GiB. For example, 100.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.
created	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
updated	body	string	The date and time when the resource was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
status	body	string	The status of image, as a string. This can be one of: ACTIVE: image is in active state SAVING: image is in queued or in saving process DELETED: image is deleted or in progress of deletion ERROR: image is in error state UNKNOWN: image is in unknown state
progress	body	integer	A percentage value of the image save progress. This can be one of: ACTIVE: 100 SAVING: 25 or 50
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
server (Optional)	body	object	The server booted from image.
OS-EXT-IMG-SIZE:size	body	integer	The size of the image.
OS-DCF:diskConfig (Optional)	body	string	Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

Example List Images Details: JSON response

{
    "images": [
        {
            "OS-DCF:diskConfig": "AUTO",
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "architecture": "x86_64",
                "auto_disk_config": "True",
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage7",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "architecture": "x86_64",
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "a2459075-d96c-40d5-893e-577ff92e721c",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-DCF:diskConfig": "MANUAL",
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "a440c04b-79fa-479c-bed1-0b816eaec379",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "architecture": "x86_64",
                "auto_disk_config": "False",
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage6",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "c905cedb-7281-47e4-8a62-f26bc5fc4c77",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "kernel_id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
                "ramdisk_id": null
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "cedef40a-ed67-4d10-800e-17455edce175",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        },
        {
            "OS-EXT-IMG-SIZE:size": "74185822",
            "created": "2011-01-01T01:02:03Z",
            "id": "76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "bookmark"
                },
                {
                    "href": "http://glance.openstack.example.com/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "alternate",
                    "type": "application/vnd.openstack.image"
                }
            ],
            "metadata": {
                "kernel_id": "nokernel",
                "ramdisk_id": "nokernel"
            },
            "minDisk": 0,
            "minRam": 0,
            "name": "fakeimage123456",
            "progress": 100,
            "status": "ACTIVE",
            "updated": "2011-01-01T01:02:03Z"
        }
    ]
}

GET

/images/{image_id}

Show Image Details

detail

Shows details for an image.

Normal response codes: 200

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.

Response

Name	In	Type	Description
images	body	array	An array of Image objects.
id	body	string	The ID of the Image.
name	body	string	The display name of an Image.
minRam	body	integer	The minimum amount of RAM an image requires to function, in MB. For example, 512.
minDisk	body	integer	The minimum amount of disk space an image requires to boot, in GiB. For example, 100.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.
created	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
updated	body	string	The date and time when the resource was updated. The date and time stamp format is ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
status	body	string	The status of image, as a string. This can be one of: ACTIVE: image is in active state SAVING: image is in queued or in saving process DELETED: image is deleted or in progress of deletion ERROR: image is in error state UNKNOWN: image is in unknown state
progress	body	integer	A percentage value of the image save progress. This can be one of: ACTIVE: 100 SAVING: 25 or 50
links	body	array	Links to the resources in question. See API Guide / Links and References for more info.
server (Optional)	body	object	The server booted from image.
OS-EXT-IMG-SIZE:size	body	integer	The size of the image.
OS-DCF:diskConfig (Optional)	body	string	Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is: AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition. MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.

Example Show Image Details: JSON response

{
    "image": {
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-IMG-SIZE:size": "74185822",
        "created": "2011-01-01T01:02:03Z",
        "id": "70a599e0-31e7-49b7-b260-868f441e862b",
        "links": [
            {
                "href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
                "rel": "bookmark"
            },
            {
                "href": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
                "rel": "alternate",
                "type": "application/vnd.openstack.image"
            }
        ],
        "metadata": {
            "architecture": "x86_64",
            "auto_disk_config": "True",
            "kernel_id": "nokernel",
            "ramdisk_id": "nokernel"
        },
        "minDisk": 0,
        "minRam": 0,
        "name": "fakeimage7",
        "progress": 100,
        "status": "ACTIVE",
        "updated": "2011-01-01T01:02:03Z"
    }
}

DELETE

/images/{image_id}

Delete Image

detail

Deletes an image.

Normal response codes: 204

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.

Response

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

GET

/images/{image_id}/metadata

List Image Metadata

detail

List metadata of an image.

Normal response codes: 200

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.

Response

Name	In	Type	Description
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example List Image Metadata Details: JSON response

{
    "metadata": {
        "architecture": "x86_64",
        "auto_disk_config": "True",
        "kernel_id": "nokernel",
        "ramdisk_id": "nokernel"
    }
}

POST

/images/{image_id}/metadata

Create Image Metadata

detail

Create an image metadata.

Normal response codes: 200

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Image Metadata: JSON request

{
    "metadata": {
        "kernel_id": "False",
        "Label": "UpdatedImage"
    }
}

Response

Name	In	Type	Description
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Create Image Metadata: JSON response

{
    "metadata": {
        "Label": "UpdatedImage",
        "architecture": "x86_64",
        "auto_disk_config": "True",
        "kernel_id": "False",
        "ramdisk_id": "nokernel"
    }
}

PUT

/images/{image_id}/metadata

Update Image Metadata

detail

Update an image metadata

Normal response codes: 200

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Image Metadata: JSON request

{
    "metadata": {
        "auto_disk_config": "True",
        "Label": "Changed"
    }
}

Response

Name	In	Type	Description
metadata	body	object	Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes.

Example Update Image Metadata: JSON response

{
    "metadata": {
        "Label": "Changed",
        "auto_disk_config": "True"
    }
}

GET

/images/{image_id}/metadata/{key}

Show Image Metadata Item

detail

Shows metadata item, by key, for an image.

Normal response codes: 200

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.
key	path	string	The metadata item key, as a string. Maximum length is 255 characters.

Response

Name	In	Type	Description
meta	body	object	The object of detailed key metadata items.

Example Show Image Metadata Item Details: JSON response

{
    "meta": {
        "kernel_id": "nokernel"
    }
}

PUT

/images/{image_id}/metadata/{key}

Create Or Update Image Metadata Item

detail

Creates or updates a metadata item, by key, for an image.

Normal response codes: 200

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.
key	path	string	The metadata item key, as a string. Maximum length is 255 characters.
meta	body	object	The object of detailed key metadata items.

Example Create Or Update Image Metadata Item: JSON request

{
    "meta": {
        "auto_disk_config": "False"
    }
}

Response

Name	In	Type	Description
meta	body	object	The object of detailed key metadata items.

Example Create Or Update Image Metadata Item: JSON response

{
    "meta": {
        "auto_disk_config": "False"
    }
}

DELETE

/images/{image_id}/metadata/{key}

Delete Image Metadata Item

detail

Deletes a metadata item, by key, for an image.

Normal response codes: 204

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

Request

Name	In	Type	Description
image_id	path	string	The UUID of the image.
key	path	string	The metadata item key, as a string. Maximum length is 255 characters.

Response

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

Security groups (os-security-groups) (DEPRECATED)

警告

These APIs are proxy calls to the Network service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Network APIs.

Lists, shows information for, creates, updates and deletes security groups.

GET

/os-security-groups

List Security Groups

detail

Lists security groups.

Normal response codes: 200

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

Request

Name	In	Type	Description
limit (Optional)	query	integer	Used in conjunction with offset to return a slice of items. limit is the maximum number of items to return. If limit is not specified, or exceeds the configurable max_limit, then max_limit will be used instead.
offset (Optional)	query	integer	Used in conjunction with limit to return a slice of items. offset is where to start in the list.
all_tenants (Optional)	query	string	Specify the all_tenants query parameter to list all security groups for all projects. This is only allowed for admin users. Value of this query parameter is not checked, only presence is considered as request for all tenants.

Response

Name	In	Type	Description
security_groups	body	array	One or more security groups objects.
description	body	string	Security group description.
id	body	string	The ID of the security group.
name	body	string	The security group name.
rules	body	array	The list of security group rules.
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.

Example List security groups: JSON response

{
    "security_groups": [
        {
            "description": "default",
            "id": 1,
            "name": "default",
            "rules": [],
            "tenant_id": "6f70656e737461636b20342065766572"
        }
    ]
}

POST

/os-security-groups

Create Security Group

detail

Creates a security group.

Normal response codes: 200

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

Request

Name	In	Type	Description
security_group	body	string	Specify the security_group action in the request body.
name	body	string	The security group name.
description	body	string	Security group description.

Example Create security group: JSON request

{
    "security_group": {
        "name": "test",
        "description": "description"
    }
}

Response

Name	In	Type	Description
security_group	body	string	Specify the security_group action in the request body.
description	body	string	Security group description.
id	body	string	The ID of the security group.
name	body	string	The security group name.
rules	body	array	The list of security group rules.
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.

Example Create security group: JSON response

{
    "security_group": {
        "description": "default",
        "id": 1,
        "name": "default",
        "rules": [],
        "tenant_id": "6f70656e737461636b20342065766572"
    }
}

GET

/os-security-groups/{security_group_id}

Show Security Group Details

detail

Shows details for a security group.

Normal response codes: 200

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

Request

Name	In	Type	Description
security_group_id	path	string	The ID of the security group.

Response

Name	In	Type	Description
security_group	body	string	Specify the security_group action in the request body.
description	body	string	Security group description.
id	body	string	The ID of the security group.
name	body	string	The security group name.
rules	body	array	The list of security group rules.
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.

Example Show security group: JSON response

{
    "security_group": {
        "description": "default",
        "id": 1,
        "name": "default",
        "rules": [],
        "tenant_id": "6f70656e737461636b20342065766572"
    }
}

PUT

/os-security-groups/{security_group_id}

Update Security Group

detail

Updates a security group.

Normal response codes: 200

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

Request

Name	In	Type	Description
security_group_id	path	string	The ID of the security group.
name	body	string	The security group name.
description	body	string	Security group description.

Example Update security group: JSON request

{
    "security_group": {
        "name": "test",
        "description": "description"
    }
}

Response

Name	In	Type	Description
security_group	body	string	Specify the security_group action in the request body.
description	body	string	Security group description.
id	body	string	The ID of the security group.
name	body	string	The security group name.
rules	body	array	The list of security group rules.
tenant_id	body	string	The UUID of the tenant in a multi-tenancy cloud.

Example Update security group: JSON response

{
    "security_group": {
        "description": "default",
        "id": 1,
        "name": "default",
        "rules": [],
        "tenant_id": "6f70656e737461636b20342065766572"
    }
}

DELETE

/os-security-groups/{security_group_id}

Delete Security Group

detail

Deletes a security group.

Normal response codes: 202

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

Request

Name	In	Type	Description
security_group_id	path	string	The ID of the security group.

Response

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

Rules for security group (os-security-group-rules) (DEPRECATED)

警告

These APIs are proxy calls to the Network service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. These will fail with a 404 starting from microversion 2.36. See: Relevant Network APIs.

Creates and deletes security group rules.

POST

/os-security-group-rules

Create Security Group Rule

detail

Creates a rule for a security group. Either cidr or group_id must be specified when creating a rule.

注釈

nova-network only supports ingress rules. If you want to define egress rules you must use the Neutron networking service.

Normal response codes: 200

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

Request

Name	In	Type	Description
security_group_rule	body	object	A security_group_rule object.
parent_group_id	body	string	Security group ID.
ip_protocol	body	string	The IP protocol. A valid value is ICMP, TCP, or UDP.
from_port	body	integer	The port at start of range.
to_port	body	integer	The port at end of range.
cidr (Optional)	body	string	The CIDR for address range.
group_id (Optional)	body	string	The source security group ID.

Response

The group is empty if group_id was not provided on the request.

The ip_range is empty if cidr was not provided on the request.

Name	In	Type	Description
security_group_rule	body	object	A security_group_rule object.
ip_protocol	body	string	The IP protocol. A valid value is ICMP, TCP, or UDP.
from_port	body	integer	The port at start of range.
to_port	body	integer	The port at end of range.
ip_range	body	object	An IP range object. Includes the security group rule cidr.
cidr (Optional)	body	string	The CIDR for address range.
id	body	string	The security group rule ID.
group	body	object	A group object. Includes the tenant_id and the source security group name.
parent_group_id	body	string	Security group ID.
name	body	string	The security group name.
tenant_id	body	string	The UUID of the tenant that owns this security group.

DELETE

/os-security-group-rules/{security_group_rule_id}

Delete Security Group Rule

detail

Deletes a security group rule.

Normal response codes: 202

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

Request

Name	In	Type	Description
security_group_rule_id	path	string	The ID of the security group rule.

Response

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

目次

• 1. Smart Data Platform Virtual Server API List (JP1/JP2/JP3/JP4/JP5/JP6)
  • 1.1. Virtual Server (Nova)
  • 1.2. Virtual Server (Cinder)
• 2. Smart Data Platform Virtual Server DataType List
  • 2.1. Resource
• 3. Smart Data Platform Virtual Server API List (JP7)
  • 3.1. Virtual Server (Nova)
  • 3.2. Virtual Server (Cinder)
• 4. Revision History

---

3.1. Virtual Server (Nova)

3.2. Virtual Server (Cinder)