Compute API (CURRENT)

This documentation supports the API v2.1 base version. If you enable all extensions, the Compute API v1.1 and v2.0 requests and responses match the API v2.1 requests and responses.

Each API version lists the extensions that it requires to make the full request and responses available. API v2.1 must enable all extensions all the time. It uses micro-version headers to expose any additional functionality.

Effective in the OpenStack Kilo release, the Compute API no longer supports XML in requests and responses.

For details about the Compute API, see the Compute API.

API versions

Lists information for all API versions.

GET
/
List API versions

Lists information about all Compute API versions.

 
Normal response codes
200 300
Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

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

This operation does not accept a request body.

GET
/v2.1
Show API v2.1

Show information about Compute API v2.1.

 
Normal response codes
200
Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

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

This operation does not accept a request body.

GET
/v2
Show API v2

Show information about Compute API v2.

 
Normal response codes
200
Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "version": {
        "id": "v2.0",
        "links": [
            {
                "href": "http://openstack.example.com/v2/",
                "rel": "self"
            },
            {
                "href": "http://docs.openstack.org/",
                "rel": "describedby",
                "type": "text/html"
            }
        ],
        "media-types": [
            {
                "base": "application/json",
                "type": "application/vnd.openstack.compute+json;version=2"
            }
        ],
        "status": "SUPPORTED",
        "version": "",
        "min_version": "",
        "updated": "2011-01-21T11:33:21Z"
    }
}

This operation does not accept a request body.

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

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
/v2.1/​{tenant_id}​/servers
List servers

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:

    Server status values
  • ACTIVE. The server is active.

  • BUILDING. 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.

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

  • RESIZED. 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.

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

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

  • 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.

Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

changes-since (Optional) query xsd:dateTime

Filters the response by a date and time stamp when the server last changed status.

image (Optional) query csapi:UUID

Filters the response by an image, as a UUID.

flavor (Optional) query csapi:UUID

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

name (Optional) query regexp

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.

status (Optional) query csapi:ServerStatus

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

host (Optional) query xsd:string

Filters the response by a host name, as a string. This query parameter is typically available to only administrative users. If you are a non-administrative user, the API ignores this parameter.

limit (Optional) query xsd:int

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 xsd: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 parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique ID for tracking the request. The request ID associated with the request appears in the log lines for that request. By default, the middleware configuration ensures that the request ID appears in the log files.

servers plain xsd:list

A list of server objects.

id plain csapi:UUID

The UUID of the server.

links plain xsd:list

Server links.

name plain xsd:string

The server name. The user sets the server name.

{
    "servers": [
        {
            "id": "a291599e-6de2-41a6-88df-c443ddcef70d",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/openstack/servers/a291599e-6de2-41a6-88df-c443ddcef70d",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/servers/a291599e-6de2-41a6-88df-c443ddcef70d",
                    "rel": "bookmark"
                }
            ],
            "name": "new-server-test"
        }
    ]
}
POST
/v2.1/​{tenant_id}​/servers
Create server

Creates a server.

 

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

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

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

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

Include the block-device-mapping-v2 parameter in the create request body to boot a server from a volume.

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

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
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

security_groups (Optional) plain xsd:string

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.

user_data (Optional) plain xsd:string

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

os-availability-zone:availability_zone (Optional) plain xsd: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, you 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.

server plain xsd:dict

server.

imageRef plain xsd:string

The image reference, as a UUID or full URL, for the image to use for your server instance.

flavorRef plain xsd:string

The flavor reference, as a UUID or full URL, for the flavor for your server instance.

networks (Optional) plain xsd:string

A networks object. Required parameter when there are mulitple 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.

uuid (Optional) plain csapi:UUID

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.

port (Optional) plain xsd: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.

fixed_ip (Optional) plain xsd:string

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

name plain xsd:string

The server name.

metadata (Optional) plain xsd:dict

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

personality (Optional) plain xsd:string

The file path and contents, text only, to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit is The number of allowed bytes in the decoded, rather than encoded, data.

block_device_mapping_v2 (Optional) plain xsd:dict

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 }

device_name plain xsd:string

A path to the device for the volume that you want to use to boot the server.

source_type plain xsd:string

The source type of the volume. A valid value is blank, snapshot, volume, or image.

destination_type (Optional) plain xsd:string

Defines where the volume comes from. A valid value is local or volume.

delete_on_termination plain xsd:string

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

guest_format plain xsd:string

Specifies the guest server disk file system format, such as ephemeral or swap.

boot_index plain xsd: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.

config_drive (Optional) plain xsd: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) plain xsd:string

Key pair name.

os:scheduler_hints (Optional) plain xsd:dict

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

OS-DCF:diskConfig (Optional) plain xsd: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.

Response parameters
Parameter Style Type Description
server plain xsd:dict

A server object.

adminPass plain xsd:string

The administrative password of the server.

id plain csapi:UUID

The UUID of the server.

links plain xsd:list

Server links.

OS-DCF:diskConfig plain xsd: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 plain xsd:list

Security groups object.

{
    "server": {
        "name": "new-server-test",
        "imageRef": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef": "http://openstack.example.com/flavors/1",
        "metadata": {
            "My Server Name": "Apache1"
        }
    }
}
{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "adminPass": "zPnp2GseTqG4",
        "id": "8195065c-fea4-4d57-b93f-5c5c63fe90e8",
        "links": [
            {
                "href": "http://openstack.example.com/v2/openstack/servers/8195065c-fea4-4d57-b93f-5c5c63fe90e8",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/openstack/servers/8195065c-fea4-4d57-b93f-5c5c63fe90e8",
                "rel": "bookmark"
            }
        ],
        "security_groups": [
            {
                "name": "default"
            }
        ]
    }
}
GET
/v2.1/​{tenant_id}​/servers/detail
List details for servers

Lists all servers with details.

 

The compute provisioning algorithm has an anti-affinity property that attempts to spread customer VMs across hosts. Under certain situations, VMs from the same customer might be placed on the same host. The hostId property shows the host that your server runs on and can be used to determine this scenario if it is relevant to your application.

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
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

changes-since (Optional) query xsd:dateTime

Filters the response by a date and time stamp when the server last changed status.

image (Optional) query csapi:UUID

Filters the response by an image, as a UUID.

flavor (Optional) query csapi:UUID

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

name (Optional) query regexp

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.

status (Optional) query csapi:ServerStatus

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

host (Optional) query xsd:string

Filters the response by a host name, as a string. This query parameter is typically available to only administrative users. If you are a non-administrative user, the API ignores this parameter.

limit (Optional) query xsd:int

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 xsd: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 parameters
Parameter Style Type Description
servers plain xsd:list

A list of server objects.

addresses plain xsd:dict

The addresses for the server.

Addresses information is hidden for any server in a state set in the osapi_hide_server_address_states configuration option. By default, servers in building state hide their addresses information.

See nova.conf - configuration options.

created plain xsd:dateTime

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 plain xsd:dict

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

hostId plain csapi:UUID

The ID of the host.

id plain csapi:UUID

The UUID of the server.

image plain xsd:dict

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 plain xsd:string

The name of associated key pair, if any.

links plain xsd:list

Server links.

metadata plain xsd:dict

The associated metadata key and value pairs.

name plain xsd:string

The server name. The user sets the server name.

OS-DCF:diskConfig plain xsd: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 plain xsd:string

The availability zone.

OS-EXT-SRV-ATTR:host plain xsd:string

The host name. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:hypervisor_hostname plain xsd:string

The hypervisor host name. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:instance_name plain xsd: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 plain xsd:int

The power state of the instance.

OS-EXT-STS:task_state plain xsd:string

The task state of the instance.

OS-EXT-STS:vm_state plain xsd:string

The VM state.

os-extended-volumes:volumes_attached plain xsd:list

The attached volumes, if any.

OS-SRV-USG:launched_at plain xsd:dateTime

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 plain xsd:dateTime

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 plain xsd:int

A percentage value of the build progress.

security_groups plain xsd:list

Security groups object.

description plain xsd:string

The security group description.

id plain csapi:UUID

The security group ID.

name plain xsd:string

The security group name.

rules plain xsd:string

A rules object.

status plain xsd:string

The server status.

host_status plain xsd: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.

tenant_id plain csapi:UUID

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

updated plain xsd:dateTime

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

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

user_id plain xsd:string

The user ID of the user who owns the server.

{
    "servers": [
        {
            "addresses": {
                "private": [
                    {
                        "addr": "192.168.0.3",
                        "OS-EXT-IPS-MAC:mac_addr": "aa:bb:cc:dd:ee:ff",
                        "OS-EXT-IPS:type": "fixed",
                        "version": 4
                    }
                ]
            },
            "created": "2013-09-23T13:53:12Z",
            "flavor": {
                "id": "1",
                "links": [
                    {
                        "href": "http://openstack.example.com/openstack/flavors/1",
                        "rel": "bookmark"
                    }
                ]
            },
            "hostId": "f1e160ad2bf07084f3d3e0dfdd0795d80da18a60825322c15775c0dd",
            "id": "9cbefc35-d372-40c5-88e2-9fda1b6ea12c",
            "image": {
                "id": "70a599e0-31e7-49b7-b260-868f441e862b",
                "links": [
                    {
                        "href": "http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
                        "rel": "bookmark"
                    }
                ]
            },
            "key_name": null,
            "links": [
                {
                    "href": "http://openstack.example.com/v2/openstack/servers/9cbefc35-d372-40c5-88e2-9fda1b6ea12c",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/servers/9cbefc35-d372-40c5-88e2-9fda1b6ea12c",
                    "rel": "bookmark"
                }
            ],
            "metadata": {
                "My Server Name": "Apache1"
            },
            "name": "new-server-test",
            "accessIPv4": "",
            "accessIPv6": "",
            "config_drive": "",
            "OS-DCF:diskConfig": "AUTO",
            "OS-EXT-AZ:availability_zone": "nova",
            "OS-EXT-SRV-ATTR:host": "c3f14e9812ad496baf92ccfb3c61e15f",
            "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
            "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
            "OS-EXT-STS:power_state": 1,
            "OS-EXT-STS:task_state": null,
            "OS-EXT-STS:vm_state": "active",
            "os-extended-volumes:volumes_attached": [],
            "OS-SRV-USG:launched_at": "2013-09-23T13:53:12.774549",
            "OS-SRV-USG:terminated_at": null,
            "progress": 0,
            "security_groups": [
                {
                    "name": "default"
                }
            ],
            "status": "ACTIVE",
            "host_status": "UP",
            "tenant_id": "openstack",
            "updated": "2013-10-31T06:32:32Z",
            "user_id": "fake"
        }
    ]
}
GET
/v2.1/​{tenant_id}​/servers/​{server_id}​
Show server details

Shows details for a server.

 

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

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

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

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
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique ID for tracking the request. The request ID associated with the request appears in the log lines for that request. By default, the middleware configuration ensures that the request ID appears in the log files.

server plain xsd:dict

A server object.

addresses plain xsd:dict

The addresses for the server.

Addresses information is hidden for any server in a state set in the osapi_hide_server_address_states configuration option. By default, servers in building state hide their addresses information.

See nova.conf - configuration options.

created plain xsd:dateTime

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 plain xsd:dict

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

hostId plain csapi:UUID

The ID of the host.

id plain csapi:UUID

The UUID of the server.

image plain xsd:dict

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 plain xsd:string

The name of associated key pair, if any.

links plain xsd:list

Server links.

metadata plain xsd:dict

The associated metadata key and value pairs.

name plain xsd:string

The server name. The user sets the server name.

OS-DCF:diskConfig plain xsd: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 plain xsd:string

The availability zone.

OS-EXT-SRV-ATTR:host plain xsd:string

The host name. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:hypervisor_hostname plain xsd:string

The hypervisor host name. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:instance_name plain xsd: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 plain xsd:int

The power state of the instance.

OS-EXT-STS:task_state plain xsd:string

The task state of the instance.

OS-EXT-STS:vm_state plain xsd:string

The VM state.

os-extended-volumes:volumes_attached plain xsd:list

The attached volumes, if any.

OS-SRV-USG:launched_at plain xsd:dateTime

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 plain xsd:dateTime

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 plain xsd:int

A percentage value of the build progress.

security_groups plain xsd:list

Security groups object.

description plain xsd:string

The security group description.

id plain csapi:UUID

The security group ID.

name plain xsd:string

The security group name.

rules plain xsd:string

A rules object.

status plain xsd:string

The server status.

host_status plain xsd: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.

tenant_id plain csapi:UUID

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

updated plain xsd:dateTime

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

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

user_id plain xsd:string

The user ID of the user who owns the server.

{
    "server": {
        "addresses": {
            "private": [
                {
                    "addr": "192.168.0.3",
                    "OS-EXT-IPS-MAC:mac_addr": "aa:bb:cc:dd:ee:ff",
                    "OS-EXT-IPS:type": "fixed",
                    "version": 4
                }
            ]
        },
        "created": "2013-09-23T13:37:00Z",
        "flavor": {
            "id": "1",
            "links": [
                {
                    "href": "http://openstack.example.com/openstack/flavors/1",
                    "rel": "bookmark"
                }
            ]
        },
        "hostId": "9cc36101a27c2a69c1a18241f6228454d9d7f466bd90c62db8e8b856",
        "id": "f474386b-4fb6-4e1f-b1d5-d6bf4437f7d5",
        "image": {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                }
            ]
        },
        "key_name": null,
        "links": [
            {
                "href": "http://openstack.example.com/v2/openstack/servers/f474386b-4fb6-4e1f-b1d5-d6bf4437f7d5",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/openstack/servers/f474386b-4fb6-4e1f-b1d5-d6bf4437f7d5",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "My Server Name": "Apache1"
        },
        "name": "new-server-test",
        "accessIPv4": "192.0.2.0",
        "accessIPv6": "2002:0:0:0:0:0:c000:20e",
        "config_drive": "",
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-AZ:availability_zone": "nova",
        "OS-EXT-SRV-ATTR:host": "b8b357f7100d4391828f2177c922ef93",
        "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
        "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
        "OS-EXT-STS:power_state": 1,
        "OS-EXT-STS:task_state": null,
        "OS-EXT-STS:vm_state": "active",
        "os-extended-volumes:volumes_attached": [],
        "OS-SRV-USG:launched_at": "2013-09-23T13:37:00.880302",
        "OS-SRV-USG:terminated_at": null,
        "progress": 0,
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "status": "ACTIVE",
        "host_status": "UP",
        "tenant_id": "openstack",
        "updated": "2013-10-31T07:31:30Z",
        "user_id": "fake"
    }
}

This operation does not accept a request body.

PUT
/v2.1/​{tenant_id}​/servers/​{server_id}​
Update server

Updates the editable attributes of a server.

 

Preconditions

  • The server must exist.

  • You can edit the accessIPv4, accessIPv6, diskConfig and name attributes.

Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

security_groups (Optional) plain xsd:string

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.

user_data (Optional) plain xsd:string

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

os-availability-zone:availability_zone (Optional) plain xsd: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, you 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.

server plain xsd:dict

server.

imageRef plain xsd:string

The image reference, as a UUID or full URL, for the image to use for your server instance.

flavorRef plain xsd:string

The flavor reference, as a UUID or full URL, for the flavor for your server instance.

networks (Optional) plain xsd:string

A networks object. Required parameter when there are mulitple 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.

uuid (Optional) plain csapi:UUID

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.

port (Optional) plain xsd: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.

fixed_ip (Optional) plain xsd:string

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

name plain xsd:string

The server name.

metadata (Optional) plain xsd:dict

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

personality (Optional) plain xsd:string

The file path and contents, text only, to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit is The number of allowed bytes in the decoded, rather than encoded, data.

block_device_mapping_v2 (Optional) plain xsd:dict

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 }

device_name plain xsd:string

A path to the device for the volume that you want to use to boot the server.

source_type plain xsd:string

The source type of the volume. A valid value is blank, snapshot, volume, or image.

destination_type (Optional) plain xsd:string

Defines where the volume comes from. A valid value is local or volume.

delete_on_termination plain xsd:string

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

guest_format plain xsd:string

Specifies the guest server disk file system format, such as ephemeral or swap.

boot_index plain xsd: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.

config_drive (Optional) plain xsd: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) plain xsd:string

Key pair name.

os:scheduler_hints (Optional) plain xsd:dict

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

OS-DCF:diskConfig (Optional) plain xsd: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.

Response parameters
Parameter Style Type Description
server plain xsd:dict

A server object.

addresses plain xsd:dict

The addresses for the server.

Addresses information is hidden for any server in a state set in the osapi_hide_server_address_states configuration option. By default, servers in building state hide their addresses information.

See nova.conf - configuration options.

created plain xsd:dateTime

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 plain xsd:dict

The ID and links for the flavor for your server instance. A flavor is a combination of memory, disk size, and CPUs.

hostId plain csapi:UUID

The ID of the host.

id plain csapi:UUID

The UUID of the server.

image plain xsd:dict

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 plain xsd:string

The name of associated key pair, if any.

links plain xsd:list

Server links.

metadata plain xsd:dict

The associated metadata key and value pairs.

name plain xsd:string

The server name. The user sets the server name.

OS-DCF:diskConfig plain xsd: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 plain xsd:string

The availability zone.

OS-EXT-SRV-ATTR:host plain xsd:string

The host name. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:hypervisor_hostname plain xsd:string

The hypervisor host name. Appears in the response for administrative users only.

OS-EXT-SRV-ATTR:instance_name plain xsd: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 plain xsd:int

The power state of the instance.

OS-EXT-STS:task_state plain xsd:string

The task state of the instance.

OS-EXT-STS:vm_state plain xsd:string

The VM state.

os-extended-volumes:volumes_attached plain xsd:list

The attached volumes, if any.

OS-SRV-USG:launched_at plain xsd:dateTime

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 plain xsd:dateTime

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 plain xsd:int

A percentage value of the build progress.

security_groups plain xsd:list

Security groups object.

description plain xsd:string

The security group description.

id plain csapi:UUID

The security group ID.

name plain xsd:string

The security group name.

rules plain xsd:string

A rules object.

status plain xsd:string

The server status.

host_status plain xsd: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.

tenant_id plain csapi:UUID

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

updated plain xsd:dateTime

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

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

user_id plain xsd:string

The user ID of the user who owns the server.

{
    "server": {
        "name": "new-server-test",
        "imageRef": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef": "http://openstack.example.com/flavors/1",
        "metadata": {
            "My Server Name": "Apache1"
        }
    }
}
{
    "server": {
        "accessIPv4": "192.0.2.0",
        "accessIPv6": "2002:0:0:0:0:0:c000:20e"
    }
}
{
    "server": {
        "OS-DCF:diskConfig": "AUTO"
    }
}
{
    "server": {
        "id": "52415800-8b69-11e0-9b19-734f565bc83b",
        "tenant_id": "1234",
        "user_id": "5678",
        "name": "new-server-test",
        "created": "2010-11-11T12:00:00Z",
        "updated": "2010-11-12T12:44:44Z",
        "hostId": "e4d909c290d0fb1ca068ffaddf22cbd0",
        "accessIPv4": "192.0.2.0",
        "accessIPv6": "2002:0:0:0:0:0:c000:20e",
        "progress": 0,
        "status": "ACTIVE",
        "image": {
            "id": "52415800-8b69-11e0-9b19-734f6f006e54",
            "name": "CentOS 5.2",
            "links": [
                {
                    "rel": "self",
                    "href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
                },
                {
                    "rel": "bookmark",
                    "href": "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
                }
            ]
        },
        "flavor": {
            "id": "52415800-8b69-11e0-9b19-734f1195ff37",
            "name": "256 MB Server",
            "links": [
                {
                    "rel": "self",
                    "href": "http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f1195ff37"
                },
                {
                    "rel": "bookmark",
                    "href": "http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f1195ff37"
                }
            ]
        },
        "metadata": {
            "My Server Name": "Apache1"
        },
        "addresses": {
            "public": [
                {
                    "version": 4,
                    "addr": "192.0.2.0"
                },
                {
                    "version": 6,
                    "addr": "2002:0:0:0:0:0:c000:20e"
                }
            ],
            "private": [
                {
                    "version": 4,
                    "addr": "198.51.100.0"
                },
                {
                    "version": 6,
                    "addr": "2002:0:0:0:0:0:c633:640e"
                }
            ]
        },
        "links": [
            {
                "rel": "self",
                "href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"
            },
            {
                "rel": "bookmark",
                "href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"
            }
        ]
    }
}
DELETE
/v2.1/​{tenant_id}​/servers/​{server_id}​
Delete server

Deletes a server.

 

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 DELETED through API calls.

  • The port attached to the server is deleted.

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

  • 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
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

This operation does not accept a request body and does not return a response body.

Servers multiple create (servers)

Creates one or more servers.

Optionally, you can set "return_reservation_id": "True" in the request body to request that a reservation ID be returned instead of the newly created instance information. With this parameter, the response shows only the reservation ID.

POST
/v2.1/​{tenant_id}​/servers
Create multiple servers

Creates one or more servers.

 
Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

security_groups (Optional) plain xsd:string

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.

user_data (Optional) plain xsd:string

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

os-availability-zone:availability_zone (Optional) plain xsd: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, you 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.

server plain xsd:dict

server.

imageRef plain xsd:string

The image reference, as a UUID or full URL, for the image to use for your server instance.

flavorRef plain xsd:string

The flavor reference, as a UUID or full URL, for the flavor for your server instance.

networks (Optional) plain xsd:string

A networks object. Required parameter when there are mulitple 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.

uuid (Optional) plain csapi:UUID

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.

port (Optional) plain xsd: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.

fixed_ip (Optional) plain xsd:string

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

name plain xsd:string

The server name.

metadata (Optional) plain xsd:dict

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

personality (Optional) plain xsd:string

The file path and contents, text only, to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit is The number of allowed bytes in the decoded, rather than encoded, data.

block_device_mapping_v2 (Optional) plain xsd:dict

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 }

device_name plain xsd:string

A path to the device for the volume that you want to use to boot the server.

source_type plain xsd:string

The source type of the volume. A valid value is blank, snapshot, volume, or image.

destination_type (Optional) plain xsd:string

Defines where the volume comes from. A valid value is local or volume.

delete_on_termination plain xsd:string

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

guest_format plain xsd:string

Specifies the guest server disk file system format, such as ephemeral or swap.

boot_index plain xsd: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.

config_drive (Optional) plain xsd: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) plain xsd:string

Key pair name.

os:scheduler_hints (Optional) plain xsd:dict

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

OS-DCF:diskConfig (Optional) plain xsd: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.

return_reservation_id (Optional) plain xsd:boolean

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

Response parameters
Parameter Style Type Description
server plain xsd:dict

A server object.

adminPass plain xsd:string

The administrative password of the server.

id plain csapi:UUID

The UUID of the server.

links plain xsd:list

Server links.

OS-DCF:diskConfig plain xsd: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 plain xsd:list

Security groups object.

{
    "server": {
        "name": "new-server-test",
        "imageRef": "http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef": "http://openstack.example.com/openstack/flavors/1",
        "metadata": {
            "My Server Name": "Apache1"
        },
        "min_count": "2",
        "max_count": "3"
    }
}
{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "adminPass": "zPnp2GseTqG4",
        "id": "8195065c-fea4-4d57-b93f-5c5c63fe90e8",
        "links": [
            {
                "href": "http://openstack.example.com/v2/openstack/servers/8195065c-fea4-4d57-b93f-5c5c63fe90e8",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/openstack/servers/8195065c-fea4-4d57-b93f-5c5c63fe90e8",
                "rel": "bookmark"
            }
        ],
        "security_groups": [
            {
                "name": "default"
            }
        ]
    }
}
POST
/v2.1/​{tenant_id}​/servers
Create multiple servers with reservation ID

Creates one or more servers with a reservation ID.

 

Set "return_reservation_id": "True" in the request body to request that a reservation ID be returned instead of the newly created instance information. With this parameter, the response shows only the reservation ID.

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

security_groups (Optional) plain xsd:string

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.

user_data (Optional) plain xsd:string

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

os-availability-zone:availability_zone (Optional) plain xsd: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, you 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.

server plain xsd:dict

server.

imageRef plain xsd:string

The image reference, as a UUID or full URL, for the image to use for your server instance.

flavorRef plain xsd:string

The flavor reference, as a UUID or full URL, for the flavor for your server instance.

networks (Optional) plain xsd:string

A networks object. Required parameter when there are mulitple 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.

uuid (Optional) plain csapi:UUID

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.

port (Optional) plain xsd: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.

fixed_ip (Optional) plain xsd:string

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

name plain xsd:string

The server name.

metadata (Optional) plain xsd:dict

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

personality (Optional) plain xsd:string

The file path and contents, text only, to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit is The number of allowed bytes in the decoded, rather than encoded, data.

block_device_mapping_v2 (Optional) plain xsd:dict

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 }

device_name plain xsd:string

A path to the device for the volume that you want to use to boot the server.

source_type plain xsd:string

The source type of the volume. A valid value is blank, snapshot, volume, or image.

destination_type (Optional) plain xsd:string

Defines where the volume comes from. A valid value is local or volume.

delete_on_termination plain xsd:string

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

guest_format plain xsd:string

Specifies the guest server disk file system format, such as ephemeral or swap.

boot_index plain xsd: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.

config_drive (Optional) plain xsd: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) plain xsd:string

Key pair name.

os:scheduler_hints (Optional) plain xsd:dict

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

OS-DCF:diskConfig (Optional) plain xsd: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.

return_reservation_id (Optional) plain xsd:boolean

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

Response parameters
Parameter Style Type Description
reservation_id (Optional) plain xsd:string

The reservation ID of the server.

{
    "server": {
        "name": "new-server-test",
        "imageRef": "http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
        "flavorRef": "http://openstack.example.com/openstack/flavors/1",
        "metadata": {
            "My Server Name": "Apache1"
        },
        "return_reservation_id": true,
        "min_count": "2",
        "max_count": "3"
    }
}
{
    "reservation_id": "r-3fhpjulh"
}

Servers - run an action (servers, action)

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

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

You can create an image from 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
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Add (associate) fixed IP (addFixedIp action)

Adds a fixed IP address to a server instance, which associates that address with the server. The fixed IP address is retrieved from the network that you specify in the request.

 

Specify the addFixedIp action and the network ID in the request body.

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

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

addFixedIp plain xsd:dict

The action.

{
    "addFixedIp": {
        "networkId": 1
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Add (associate) floating IP (addFloatingIp action)

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

 

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

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

Preconditions

  • The server must exist.

  • You can only add a floating IP address to the server when its status is available.

Normal response codes
202
Error response codes
computeFault (400, 500, …), 409, serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

addFloatingIp plain xsd:dict

The action.

address plain xsd:string

The floating IP address.

fixed_address (Optional) plain xsd:string

The fixed IP address with which you want to associate the floating IP address.

{
    "addFloatingIp": {
        "address": "172.24.4.4"
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Change administrative password (changePassword action)

Changes the administrative password for a server.

 

Specify the changePassword action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

changePassword plain xsd:dict

The action.

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

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Confirm resized server (confirmResize action)

Confirms a pending resize action for a server.

 

Specify the confirmResize action in the request body.

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

Preconditions

  • You can only confirm the resized server where the status is VERIFY_RESIZED, the vm_status is RESIZED, and the migration_status is finished or confirming.

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

Troubleshooting

  • If the server status remains RESIZED, the request failed. Ensure you meet the preconditions and run the request again. If the request fails again, investigate the compute back end or ask your cloud provider.

Normal response codes
204
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

confirmResize plain xsd:string

The action.

{
    "confirmResize": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Create image (createImage action)

Creates an image from a server.

 

Specify the createImage action in the request body.

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

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

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
computeFault (400, 500, …), 409, serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

createImage plain xsd:dict

The action.

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

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Evacuate server (evacuate action)

Evacuates a server from a failed host to a new one.

 

Specify the evacuate action in the request body.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

evacuate plain xsd:string

Specify the evacuate action in the request body.

host (Optional) plain xsd:string

The name or ID of the host to which the server is evacuated.

adminPass (Optional) plain xsd:string

An administrative password to access the evacuated instance.

To set the administrative password, set the enable_instance_password configuration option to true. If you set this option to false and you try to set the administrative password, the API does not set the password and the response shows a null value for the adminPass parameter.

{
    "evacuate": {
        "host": "b419863b7d814906a68fb31703c0dbd6",
        "adminPass": "MySecretPass"
    }
}
{
    "adminPass": "MySecretPass"
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Force-delete server (forceDelete action)

Force-deletes a server before deferred cleanup.

 

Specify the forceDelete action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

forceDelete plain xsd:string

The action.

{
    "forceDelete": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Lock server (lock action)

Locks a server.

 

Specify the lock action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

lock plain xsd:string

The action.

{
    "lock": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Pause server (pause action)

Pauses a server. Changes its status to PAUSED.

 

Specify the pause action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

pause plain xsd:string

The action.

{
    "pause": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Show console output (os-getConsoleOutput action)

Shows console output for a server instance.

 

Specify the os-getConsoleOutput action in the request body.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-getConsoleOutput plain xsd:string

The action.

length (Optional) plain xsd:int

The number of lines to fetch from the end of console log. -1 indicates unlimited.

{
    "os-getConsoleOutput": {
        "length": 50
    }
}
{
    "output": "FAKE CONSOLE OUTPUT\nANOTHER\nLAST LINE"
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Get RDP console (os-getRDPConsole action)

Gets an RDP console for a server.

 

Specify the os-getRDPConsole action in the request body.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-getRDPConsole plain xsd:string

The action.

{
    "os-getRDPConsole": {
        "type": "rdp-html5"
    }
}
{
    "console": {
        "type": "rdp-html5",
        "url": "http://127.0.0.1:6083/?token=191996c3-7b0f-42f3-95a7-f1839f2da6ed"
    }
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Get serial console (os-getSerialConsole action)

Gets a serial console for a server.

 

Specify the os-getSerialConsole action in the request body.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-getSerialConsole plain xsd:string

The action.

{
    "os-getSerialConsole": {
        "type": "serial"
    }
}
{
    "console": {
        "type": "serial",
        "url": "ws://127.0.0.1:6083/?token=f9906a48-b71e-4f18-baca-c987da3ebdb3"
    }
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Get SPICE console (os-getSPICEConsole action)

Gets a SPICE console for a server.

 

Specify the os-getSPICEConsole action in the request body.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-getSPICEConsole plain xsd:string

The action.

{
    "os-getSPICEConsole": {
        "type": "spice-html5"
    }
}
{
    "console": {
        "type": "spice-html5",
        "url": "http://127.0.0.1:6082/spice_auto.html?token=a30e5d08-6a20-4043-958f-0852440c6af4"
    }
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Get VNC console (os-getVNCConsole action)

Gets a VNC console for a server.

 

Specify the os-getVNCConsole action in the request body.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-getVNCConsole plain xsd:string

The action.

{
    "os-getVNCConsole": {
        "type": "novnc"
    }
}
{
    "console": {
        "type": "novnc",
        "url": "http://127.0.0.1:6080/vnc_auto.html?token=191996c3-7b0f-42f3-95a7-f1839f2da6ed"
    }
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Reboot server (reboot action)

Reboots a server.

 

Specify the reboot action in the request body.

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), HTTPUnprocessableEntity (422), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

reboot plain xsd:string

The action.

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

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Rebuild server (rebuild action)

Rebuilds a server.

 

Specify the rebuild action in the request body.

To rebuild the server with preservation of the ephemeral partition, set the preserve_ephemeral parameter to true.

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

rebuild plain xsd:string

The action.

imageRef (Optional) plain xsd:string

The image reference, as an ID or full URL, for the image for your server instance.

Required if you define a block device mapping.

name plain xsd:string

The server name.

adminPass plain xsd:string

The administrative password of the server.

metadata (Optional) plain xsd:string

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

personality (Optional) plain xsd:string

The file path and contents, text only, to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit is the number of allowed bytes in the decoded, rather than the encoded, data.

preserve_ephemeral (Optional) plain xsd:boolean

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

{
    "rebuild": {
        "imageRef": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
        "name": "foobar",
        "adminPass": "seekr3t",
        "metadata": {
            "meta_var": "meta_val"
        },
        "personality": [
            {
                "path": "/etc/banner.txt",
                "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ],
        "preserve_ephemeral": true
    }
}
{
    "server": {
        "accessIPv4": "192.0.2.0",
        "accessIPv6": "2002:0:0:0:0:0:c000:20e",
        "addresses": {
            "private": [
                {
                    "addr": "192.168.0.3",
                    "version": 4
                }
            ]
        },
        "adminPass": "seekr3t",
        "created": "2013-11-14T06:29:00Z",
        "flavor": {
            "id": "1",
            "links": [
                {
                    "href": "http://openstack.example.com/openstack/flavors/1",
                    "rel": "bookmark"
                }
            ]
        },
        "hostId": "28d8d56f0e3a77e20891f455721cbb68032e017045e20aa5dfc6cb66",
        "id": "a0a80a94-3d81-4a10-822a-daa0cf9e870b",
        "image": {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "bookmark"
                }
            ]
        },
        "links": [
            {
                "href": "http://openstack.example.com/v2.1/servers/a0a80a94-3d81-4a10-822a-daa0cf9e870b",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/openstack/servers/a0a80a94-3d81-4a10-822a-daa0cf9e870b",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "meta_var": "meta_val"
        },
        "name": "foobar",
        "progress": 0,
        "status": "ACTIVE",
        "tenant_id": "openstack",
        "updated": "2013-11-14T06:29:02Z",
        "user_id": "fake"
    }
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Remove (disassociate) fixed IP (removeFixedIp action)

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

 

Specify the removeFixedIp action in the request body.

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

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

removeFixedIp plain xsd:string

The action.

{
    "removeFixedIp": {
        "address": "10.0.0.4"
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Remove (disassociate) floating IP (removeFloatingIp action)

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

 

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

Specify the removeFloatingIp action in the request body.

Normal response codes
202
Error response codes
computeFault (400, 500, …), 409, serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

removeFloatingIp plain xsd:string

The action.

address plain xsd:string

The floating IP address.

{
    "removeFloatingIp": {
        "address": "172.24.4.4"
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Rescue server (rescue action)

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

 

Specify the rescue action in the request body.

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

Asynchronous Postconditions

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

rescue plain xsd:string

The action.

adminPass (Optional) plain xsd:string

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

rescue_image_ref (Optional) plain xsd:string

The image reference to use to rescue your server instance. Specify the image reference by ID or full URL.

If you omit an image reference, default is the base image reference.

Response parameters
Parameter Style Type Description
adminPass plain xsd:string

The password that enables the administrator to access the rescued instance.

{
    "rescue": {
        "adminPass": "MySecretPass"
    }
}
{
    "rescue": {
        "adminPass": "MySecretPass",
        "rescue_image_ref": "70a599e0-31e7-49b7-b260-868f441e862b"
    }
}
{
    "adminPass": "MySecretPass"
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Resize server (resize action)

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
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

resize plain xsd:string

The action.

{
    "resize": {
        "flavorRef": "2"
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Restore soft-deleted instance (restore action)

Restores a previously soft-deleted server instance. You cannot use this method to restore deleted instances.

 

Specify the restore action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

restore plain xsd:string

The action.

{
    "restore": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Resume suspended server (resume action)

Resumes a suspended server and changes its status to ACTIVE.

 

Specify the resume action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

resume plain xsd:string

The action.

{
    "resume": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Revert resized server (revertResize action)

Cancels and reverts a pending resize action for a server.

 

Specify the revertResize action in the request body.

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

Preconditions

  • You can only confirm the resized server where the status is VERIFY_RESIZE and the vm_status is RESIZED.

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

Troubleshooting

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

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

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), serverCapacityUnavailable (503), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

revertResize plain xsd:string

The action.

{
    "revertResize": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Shelve server (shelve action)

Shelves a server.

 

Specify the shelve action in the request body.

All associated data and resources are kept but anything still in memory is not retained. To restore a shelved instance, use the unshelve action. To remove a shelved instance, use the shelveOffload action.

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

Preconditions

  • The server status must be ACTIVE, SHUTOFF, PAUSED, or SUSPENDED.

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

Asynchronous Postconditions

  • After you successfully shelve a server, its status changes to SHELVED and the image status is ACTIVE. The server instance data appears on the compute node that the Compute service manages.

  • If you boot the server from volumes or set the shelved_offload_time option to 0, the Compute service automatically deletes the instance on compute nodes and changes the server status to SHELVED_OFFLOADED.

Troubleshooting

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

shelve plain xsd:string

The action.

{
    "shelve": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Shelf-offload (remove) server (shelveOffload action)

Shelf-offloads, or removes, a shelved server.

 

Specify the shelveOffload action in the request body.

Data and resource associations are deleted. If an instance is no longer needed, you can remove that instance from the hypervisor to minimize resource usage.

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

Preconditions

  • The server status must be SHELVED.

  • If the server is locked, you must have administrator privileges to shelve-offload the server.

Asynchronous Postconditions

  • After you successfully shelve-offload a server, its status changes to SHELVED_OFFLOADED. The server instance data appears on the compute node.

Troubleshooting

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

shelveOffload plain xsd:string

The action.

{
    "shelveOffload": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Start server (os-start action)

Starts a stopped server and changes its status to ACTIVE.

 

Specify the os-start action in the request body.

Preconditions

  • The server status must be SHUTOFF.

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

Asynchronous Postconditions

  • After you successfully start a server, its status changes to ACTIVE. The server appears on the compute node that the Compute service manages.

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
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-start plain xsd:string

The action.

{
    "os-start": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Stop server (os-stop action)

Stops a running server and changes its status to SHUTOFF.

 

Specify the os-stop action in the request body.

Preconditions

  • The server status must be ACTIVE or ERROR.

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

Asynchronous Postconditions

  • After you successfully stop a server, its status changes to SHUTOFF. The server instance data appears only on the compute node that Compute service manages.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-stop plain xsd:string

The action.

{
    "os-stop": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Unlock server (unlock action)

Unlocks a locked server.

 

Specify the unlock action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

unlock plain xsd:string

The action.

{
    "unlock": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Unpause server (unpause action)

Unpauses a paused server and changes its status to ACTIVE.

 

Specify the unpause action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

unpause plain xsd:string

The action.

{
    "unpause": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Unrescue server (unrescue action)

Unrescues a server. Changes status to ACTIVE.

 

Specify the unrescue action in the request body.

Preconditions

  • The server must exist.

  • You can only unrescue a server when its status is RESCUE.

Asynchronous Postconditions

  • After you successfully unrescue a server and make a GET /v2.1/​{tenant_id}​/servers/​{server_id}​ request, its status changes to ACTIVE.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

unrescue plain xsd:string

The action.

{
    "unrescue": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Unshelve (restore) shelved server (unshelve action)

Unshelves, or restores, a shelved server.

 

Specify the unshelve action in the request body.

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

Preconditions

  • The server status must be SHELVED or SHELVED_OFFLOADED.

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

Asynchronous Postconditions

  • After you successfully shelve a server, its status changes to ACTIVE. The server appears on the compute node.

  • The shelved image is deleted from the list of images returned by an API call.

Troubleshooting

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

unshelve plain xsd:string

The action.

{
    "unshelve": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Add security group to a server (addSecurityGroup action)

Adds a security group to a server.

 

Specify the addSecurityGroup action in the request body.

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), badMediaType (415), NetworkNotFound (400)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

addSecurityGroup plain xsd:string

The action.

name plain xsd:string

The security group name.

{
    "addSecurityGroup": {
        "name": "default"
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Remove security group from a server (removeSecurityGroup action)

Removes a security group from a server.

 

Specify the removeSecurityGroup action in the request body.

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), badMediaType (415), NetworkNotFound (400)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

removeSecurityGroup plain xsd:string

The action.

name plain xsd:string

The security group name.

{
    "removeSecurityGroup": {
        "name": "default"
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Trigger crash dump in server (trigger_crash_dump action)

Trigger a crash dump in a server.

 

Specify the trigger_crash_dump action in the request body.

When a crash dump is triggered for a virtual server, it causes a system reboot. This action can cause data loss. Also, network connectivity can be lost. 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.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

trigger_crash_dump plain xsd:string

The action.

{
    "trigger_crash_dump": null
}

This operation does not return a response body.

Servers - run an administrative action (servers, action)

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

You can change the administrative password for, create a back up of, and inject network information into a server.

You can migrate, live-migrate, reset networking on, and reset the state of a server.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Create server back up (createBackup action)

Creates a back up of a server.

 

Specify the createBackup action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

createBackup plain xsd:string

The action.

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

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Inject network information (injectNetworkInfo action)

Injects network information into a server.

 

Specify the injectNetworkInfo action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

injectNetworkInfo plain xsd:string

The action.

{
    "injectNetworkInfo": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Migrate server (migrate action)

Migrates a server to a host. The scheduler chooses the host.

 

Specify the migrate action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

migrate plain xsd:string

The action.

{
    "migrate": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Live-migrate server (os-migrateLive action)

Live-migrates a server to a new host without rebooting.

 

Use the host parameter to specify the destination host. If you omit this parameter, the scheduler chooses a host. If a scheduled host is not suitable, the scheduler tries up to migrate_max_retries rescheduling attempts.

If both source and destination hosts provide local disks, you can set the block_migration parameter to true. If either host uses shared storage, the migration fails if you set this parameter to true.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

host plain xsd:string

The host to which to migrate the server. If you omit this parameter, the scheduler chooses a host.

block_migration plain xsd:boolean

Set to true to migrate local disks by using block migration. If the source or destination host uses shared storage and you set this value to true, the live migration fails.

disk_over_commit plain xsd:boolean

Set to true to enable over commit when the destination host is checked for available disk space.

Set to false to disable over commit. This setting affects only the libvirt virt driver.

{
    "os-migrateLive": {
        "host": "01c0cadef72d47e28a672a76060d492c",
        "block_migration": false,
        "disk_over_commit": false
    }
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Reset networking on a server (resetNetwork action)

Resets networking on a server.

 

Specify the resetNetwork action in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

resetNetwork plain xsd:string

The action.

{
    "resetNetwork": null
}

This operation does not return a response body.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/action
Reset server state (os-resetState action)

Resets the state of a server.

 

Specify the os-resetState action and the state in the request body.

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

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

os-resetState plain xsd:string

The action.

{
    "os-resetState": {
        "state": "active"
    }
}

This operation does not return a response body.

Servers diagnostics (servers, diagnostics)

Shows the usage data for a server.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/diagnostics
Show server diagnostics

Shows basic usage data 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
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

{
    "cpu0_time": 17300000000,
    "memory": 524288,
    "vda_errors": -1,
    "vda_read": 262144,
    "vda_read_req": 112,
    "vda_write": 5778432,
    "vda_write_req": 488,
    "vnet1_rx": 2070139,
    "vnet1_rx_drop": 0,
    "vnet1_rx_errors": 0,
    "vnet1_rx_packets": 26701,
    "vnet1_tx": 140208,
    "vnet1_tx_drop": 0,
    "vnet1_tx_errors": 0,
    "vnet1_tx_packets": 662
}

This operation does not accept a request body.

Servers IPs (servers, ips)

Lists the IP addresses for an instance and shows details for an IP address.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/ips
List IPs

Lists IP addresses that are assigned to an instance.

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

{
    "addresses": {
        "private": [
            {
                "addr": "192.168.0.3",
                "version": 4
            }
        ]
    }
}

This operation does not accept a request body.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/ips/​{network_label}​
Show IP details

Shows IP addresses details for a network label of a server instance.

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

network_label URI xsd:string

The network label, such as public or private.

{
    "private": [
        {
            "addr": "192.168.0.3",
            "version": 4
        }
    ]
}

This operation does not accept a request body.

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
/v2.1/​{tenant_id}​/servers/​{server_id}​/metadata
List all metadata

Lists all metadata for a server.

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

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

This operation does not accept a request body.

PUT
/v2.1/​{tenant_id}​/servers/​{server_id}​/metadata
Create or replace metadata items

Creates or 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
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

{
    "metadata": {
        "foo": "Foo Value"
    }
}
{
    "metadata": {
        "foo": "Foo Value"
    }
}
POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/metadata
Update metadata items

Updates one or more metadata items for a server.

 

Replaces 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
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

{
    "metadata": {
        "foo": "Foo Value"
    }
}
{
    "metadata": {
        "foo": "Foo Value"
    }
}
GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/metadata/​{key}​
Show metadata item details

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

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

key URI xsd:string

The metadata item key, as a string. Maximum length is 255 characters.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

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

This operation does not accept a request body.

PUT
/v2.1/​{tenant_id}​/servers/​{server_id}​/metadata/​{key}​
Create or update metadata item

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

 

Creates a metadata item that does not already exist in the server. Removes and completely replaces a metadata item that already exists in the server 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
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

key URI xsd:string

The metadata item key, as a string. Maximum length is 255 characters.

{
    "meta": {
        "foo": "Bar Value"
    }
}
{
    "meta": {
        "foo": "Bar Value"
    }
}
DELETE
/v2.1/​{tenant_id}​/servers/​{server_id}​/metadata/​{key}​
Delete metadata item

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

 

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

Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

key URI xsd:string

The metadata item key, as a string. Maximum length is 255 characters.

This operation does not accept a request body and does not return a response body.

Servers - list actions (servers, os-instance-actions)

All users can list available actions for a server.

All users can show details for a server action; however, only administrators can view server events in server action details.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-instance-actions
List actions for server

Lists actions for a server.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a 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"
        }
    ]
}

This operation does not accept a request body.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-instance-actions/​{request_id}​
Show server action details

Shows details for a server action.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

request_id URI xsd:string

The ID of the request.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

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

This operation does not accept a request body.

Port interfaces (servers, os-interface)

Creates a port interface and uses it to attach a port to a server and detaches a port interface from a server. Also, lists all port interfaces and shows details for a port interface.

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-interface
Create interface

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

 
Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), badMediaType (415), NetworkNotFound (400)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

interfaceAttachment plain xsd:string

Specify the interfaceAttachment action in the request body.

port_id (Optional) plain csapi:UUID

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) plain csapi:UUID

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) plain xsd:list

Fixed IP addresses with subnet IDs.

If you request a specific fixed IP address without a net_id, the request returns a Bad Request (400) response code.

Response parameters
Parameter Style Type Description
interfaceAttachment plain xsd:string

Specify the interfaceAttachment action in the response body.

fixed_ips plain xsd:list

Fixed IP addresses with subnet IDs.

mac_addr plain xsd:string

The MAC address.

net_id plain csapi:UUID

The network ID.

port_id plain csapi:UUID

The port ID.

port_state plain xsd:string

The port state.

{
    "interfaceAttachment": {
        "port_id": "ce531f90-199f-48c0-816c-13e38010b442"
    }
}
{
    "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
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-interface
List port interfaces

Lists port interfaces that are attached to a server.

 
Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

Response parameters
Parameter Style Type Description
interfaceAttachment plain xsd:string

Specify the interfaceAttachment action in the response body.

port_state plain xsd:string

The port state.

fixed_ips plain xsd:list

Fixed IP addresses with subnet IDs.

mac_addr plain xsd:string

The MAC address.

net_id plain csapi:UUID

The network ID.

port_id plain csapi:UUID

The port ID.

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

This operation does not accept a request body.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-interface/​{port_id}​
Show port interface details

Shows details for a port interface that is attached to a server.

 
Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

port_id URI csapi:UUID

The UUID of the port.

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

This operation does not accept a request body.

DELETE
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-interface/​{port_id}​
Detach interface

Detaches a port interface.

 
Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), badMediaType (415), NetworkNotFound (400)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

port_id URI csapi:UUID

The UUID of the port.

This operation does not accept a request body and does not return a response body.

Servers password (servers, os-server-password)

Shows the encrypted administrative password. Also, clears the encrypted administrative password for a server, which removes it from the metadata server.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-server-password
Show server password

Shows the administrative password for a server.

 

This operation calls the metadata service to query metadata information and does not read password information from the server itself.

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
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

{
    "password": "xlozO3wLCBRWAa2yDjCCVx8vwNPypxnypmRYDa/zErlQ+EzPe1S/Gz6nfmC52mOlOSCRuUOmG7kqqgejPof6M7bOezS387zjq4LSvvwp28zUknzy4YzfFGhnHAdai3TxUJ26pfQCYrq8UTzmKF2Bq8ioSEtVVzM0A96pDh8W2i7BOz6MdoiVyiev/I1K2LsuipfxSJR7Wdke4zNXJjHHP2RfYsVbZ/k9ANu+Nz4iIH8/7Cacud/pphH7EjrY6a4RZNrjQskrhKYed0YERpotyjYk1eDtRe72GrSiXteqCM4biaQ5w3ruS+AcX//PXk3uJ5kC7d67fPXaVz4WaQRYMg=="
}

This operation does not accept a request body.

DELETE
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-server-password
Clear admin password

Clears the encrypted administrative password for a server, which removes it from the metadata server.

 

This action does not actually change the instance server password.

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

Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

This operation does not accept a request body and does not return a response body.

Servers virtual interfaces (servers, os-virtual-interfaces)

Lists virtual interfaces for a server instance.

GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-virtual-interfaces
List virtual interfaces

Lists the virtual interfaces for an instance.

 

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

The API v2 returns the network ID in the OS-EXT-VIF-NET:net_id response attribute.

The API v2.1 base version does not return the network ID.

The API v2.12 microversion returns the network ID in the net_id response attribute.

Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

Response parameters
Parameter Style Type Description
virtual_interfaces plain xsd:list

A virtual_interfaces object.

id plain csapi:UUID

The UUID of the virtual interface.

mac_address plain xsd:string

The MAC address.

{
    "virtual_interfaces": [
        {
            "id": "cec8b9bb-5d22-4104-b3c8-4c35db3210a6",
            "mac_address": "fa:16:3e:3c:ce:6f"
        }
    ]
}

This operation does not accept a request body.

Servers with volume attachments (servers, os-volume_attachments)

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

POST
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-volume_attachments
Attach volume to server

Attaches a volume to a server.

 

Preconditions

  • You can attach a volume to a server with an ACTIVE, PAUSED, SHUTOFF, VERIFY_RESIZE, or SOFT_DELETED status.

  • You can attach a volume to a server with a status that is not locked.

  • You can attach a volume with a available status.

  • You can attach a volume when its volume type supports volume attaching.

Asynchronous Postconditions

  • After successfully attaching a volume to a server, the volume status changes to in-use.

  • You can see the attached volume when you log in to the server.

Troubleshooting

  • If the volume status remains in available state, the request failed. Ensure that you meet the preconditions and run the request again. If the request fails again, investigate the server and the volume status.

Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

volumeAttachment (Optional) plain xsd:dict

A dictionary representation of a volume attachment.

volumeId (Optional) plain csapi:UUID

The UUID of the volume to attach.

device (Optional) plain xsd: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.

{
    "volumeAttachment": {
        "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "device": "/dev/vdd"
    }
}
{
    "volumeAttachment": {
        "device": "/dev/vdd",
        "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "serverId": "0c92f3f6-c253-4c9b-bd43-e880a8d2eb0a",
        "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
    }
}
GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-volume_attachments
List volume attachments

Lists the volume attachments for a server.

 
Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

{
    "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"
        }
    ]
}
GET
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-volume_attachments/​{attachment_id}​
Show volume attachment details

Shows details for a volume attachment.

 

Preconditions

  • The volume must be attached to the server.

Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

attachment_id URI csapi:UUID

The UUID of the attachment.

{
    "volumeAttachment": {
        "device": "/dev/sdd",
        "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803",
        "serverId": "2390fb4d-1693-45d7-b309-e29c4af16538",
        "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803"
    }
}
DELETE
/v2.1/​{tenant_id}​/servers/​{server_id}​/os-volume_attachments/​{attachment_id}​
Detach volume

Detaches a volume from a server.

 

Preconditions

  • The volume must be attached to the server.

  • You can detach a volume when the server status is ACTIVE, PAUSED, SHUTOFF, VERIFY_RESIZE, or SOFT_DELETED.

  • You can detach a volume when its status is in-use.

  • You can detach a volume from a server with a status that is not locked.

  • You cannot detach a root device volume.

Asynchronous Postconditions

  • After successfully detaching a volume, its status changes to available.

  • The detached volume is no longer visible on the server.

Troubleshooting

  • If the volume status remains in in-use state, the request 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.

  • If you attempt to detach a root device volume, this operation returns the Forbidden (403) response code.

Normal response codes
202
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), badMediaType (415), NetworkNotFound (400), buildInProgress (409)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

server_id URI csapi:UUID

The UUID of the server.

attachment_id URI csapi:UUID

The UUID of the attachment.

This operation does not return a response body.

Flavors with extended attributes (flavors)

Shows information about flavors.

GET
/v2.1/​{tenant_id}​/flavors
List flavors

Lists flavors.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

minDisk (Optional) query xsd:int

Filters the response by a minimum disk space, in GB.

minRam (Optional) query xsd:int

Filters the response by a minimum RAM, in MB.

sort_key (Optional) query xsd:string

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

sort_dir (Optional) query xsd: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.

limit (Optional) query xsd:int

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 xsd: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 parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "flavors": [
        {
            "id": "1",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/openstack/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/1",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.tiny"
        },
        {
            "id": "2",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/openstack/flavors/2",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/2",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.small"
        },
        {
            "id": "3",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/openstack/flavors/3",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/3",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.medium"
        },
        {
            "id": "4",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/openstack/flavors/4",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/4",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.large"
        },
        {
            "id": "5",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/openstack/flavors/5",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/5",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.xlarge"
        }
    ]
}
POST
/v2.1/​{tenant_id}​/flavors
Create flavor

Creates a flavor.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

{
    "flavor": {
        "name": "test_flavor",
        "ram": 1024,
        "vcpus": 2,
        "disk": 10,
        "id": "10"
    }
}
{
    "flavor": {
        "OS-FLV-DISABLED:disabled": false,
        "disk": 10,
        "OS-FLV-EXT-DATA:ephemeral": 0,
        "os-flavor-access:is_public": true,
        "id": "10",
        "links": [
            {
                "href": "http://openstack.example.com/v2.1/flavors/10",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/flavors/10",
                "rel": "bookmark"
            }
        ],
        "name": "test_flavor",
        "ram": 1024,
        "swap": "",
        "vcpus": 2
    }
}
GET
/v2.1/​{tenant_id}​/flavors/​{flavor_id}​
Show flavor details

Shows details for a flavor.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "flavor": {
        "OS-FLV-DISABLED:disabled": false,
        "disk": 1,
        "OS-FLV-EXT-DATA:ephemeral": 0,
        "os-flavor-access:is_public": true,
        "id": "1",
        "links": [
            {
                "href": "http://openstack.example.com/v2.1/openstack/flavors/1",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/openstack/flavors/1",
                "rel": "bookmark"
            }
        ],
        "name": "m1.tiny",
        "ram": 512,
        "swap": "",
        "vcpus": 1
    }
}
DELETE
/v2.1/​{tenant_id}​/flavors/​{flavor_id}​
Delete flavor

Deletes a flavor.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

This operation does not accept a request body and does not return a response body.

GET
/v2.1/​{tenant_id}​/flavors/detail
List flavors with details

Lists flavors with details.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

minDisk (Optional) query xsd:int

Filters the response by a minimum disk space, in GB.

minRam (Optional) query xsd:int

Filters the response by a minimum RAM, in MB.

sort_key (Optional) query xsd:string

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

sort_dir (Optional) query xsd: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.

limit (Optional) query xsd:int

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 xsd: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 parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "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.1/openstack/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/1",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.tiny",
            "ram": 512,
            "swap": "",
            "vcpus": 1
        },
        {
            "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.1/openstack/flavors/2",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/2",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.small",
            "ram": 2048,
            "swap": "",
            "vcpus": 1
        },
        {
            "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.1/openstack/flavors/3",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/3",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.medium",
            "ram": 4096,
            "swap": "",
            "vcpus": 2
        },
        {
            "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.1/openstack/flavors/4",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/4",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.large",
            "ram": 8192,
            "swap": "",
            "vcpus": 4
        },
        {
            "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.1/openstack/flavors/5",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/openstack/flavors/5",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.xlarge",
            "ram": 16384,
            "swap": "",
            "vcpus": 8
        }
    ]
}

Flavors access (flavors, os-flavor-access, action)

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

GET
/v2.1/​{tenant_id}​/flavors/os-flavor-access
List flavor access information for given flavor

Lists flavor access information.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "flavor_access": [
        {
            "flavor_id": "10",
            "tenant_id": "fake_tenant"
        }
    ]
}

This operation does not accept a request body.

POST
/v2.1/​{tenant_id}​/flavors/os-flavor-access/​{flavor_id}​/action
Add flavor access to tenant

Adds flavor access to a tenant and flavor.

 

Specify the addTenantAccess action and the tenant_id in the request body.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

{
    "addTenantAccess": {
        "tenant": "fake_tenant"
    }
}
{
    "flavor_access": [
        {
            "flavor_id": "10",
            "tenant_id": "fake_tenant"
        }
    ]
}
POST
/v2.1/​{tenant_id}​/flavors/os-flavor-access/​{flavor_id}​/action
Remove flavor access from tenant

Removes flavor access from a tenant and flavor.

 

Specify the removeTenantAccess action and the tenant_id in the request body.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

{
    "removeTenantAccess": {
        "tenant": "fake_tenant"
    }
}
{
    "flavor_access": []
}

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

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

POST
/v2.1/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs
Create extra specs for a flavor

Creates extra specs for a flavor, by ID.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

{
    "extra_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
{
    "extra_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
GET
/v2.1/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs
List extra specs for a flavor

Lists all extra specs for a flavor, by ID.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "extra_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
{
    "extra_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
GET
/v2.1/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs/​{flavor_extra_spec_key}​
Show an extra spec for a flavor

Shows an extra spec, by key, for a flavor, by ID.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

flavor_extra_spec_key URI xsd:string

The extra spec key for the flavor.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "key1": "value1"
}

This operation does not accept a request body.

PUT
/v2.1/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs/​{flavor_extra_spec_key}​
Update an extra spec for a flavor

Updates an extra spec, by key, for a flavor, by ID.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

flavor_extra_spec_key URI xsd:string

The extra spec key for the flavor.

{
    "key1": "new_value1"
}
{
    "key1": "new_value1"
}
DELETE
/v2.1/​{tenant_id}​/flavors/​{flavor_id}​/os-extra_specs/​{flavor_extra_spec_key}​
Delete an extra spec for a flavor

Deletes an extra spec, by key, for a flavor, by ID.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

flavor_id URI csapi:UUID

The ID of the flavor.

flavor_extra_spec_key URI xsd:string

The extra spec key for the flavor.

This operation does not accept a request body and does not return a response body.

Keypairs (keypairs)

Generates, imports, and deletes SSH keys.

GET
/v2.1/​{tenant_id}​/os-keypairs
List keypairs

Lists keypairs that are associated with the account.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

{
    "keypairs": [
        {
            "keypair": {
                "fingerprint": "7e:eb:ab:24:ba:d1:e1:88:ae:9a:fb:66:53:df:d3:bd",
                "name": "keypair-50ca852e-273f-4cdc-8949-45feba200837",
                "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCkF3MX59OrlBs3dH5CU7lNmvpbrgZxSpyGjlnE8Flkirnc/Up22lpjznoxqeoTAwTW034k7Dz6aYIrZGmQwe2TkE084yqvlj45Dkyoj95fW/sZacm0cZNuL69EObEGHdprfGJQajrpz22NQoCD8TFB8Wv+8om9NH9Le6s+WPe98WC77KLw8qgfQsbIey+JawPWl4O67ZdL5xrypuRjfIPWjgy/VH85IXg/Z/GONZ2nxHgSShMkwqSFECAC5L3PHB+0+/12M/iikdatFSVGjpuHvkLOs3oe7m6HlOfluSJ85BzLWBbvva93qkGmLg4ZAc8rPh2O+YIsBUHNLLMM/oQp Generated-by-Nova\n"
            }
        }
    ]
}

This operation does not accept a request body.

POST
/v2.1/​{tenant_id}​/os-keypairs
Create or import keypair

Generates or imports a keypair.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

name plain xsd:string

The name to associate with the keypair.

public_key (Optional) plain xsd:string

The public ssh key to import. If you omit this value, a key is generated.

{
    "keypair": {
        "name": "keypair-d20a3d59-9433-4b79-8726-20b431d89c78",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova"
    }
}
{
    "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",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated-by-Nova",
        "user_id": "fake"
    }
}
DELETE
/v2.1/​{tenant_id}​/os-keypairs/​{keypair_name}​
Delete keypair

Deletes a keypair.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

keypair_name URI xsd:string

The keypair name.

This operation does not accept a request body and does not return a response body.

GET
/v2.1/​{tenant_id}​/os-keypairs/​{keypair_name}​
Show keypair details

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

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

keypair_name URI xsd:string

The keypair name.

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

This operation does not accept a request body.

Limits (limits)

Shows rate and absolute limits for the tenant.

GET
/v2.1/​{tenant_id}​/limits
Show rate and absolute limits

Shows rate and absolute limits for the tenant.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

{
    "limits": {
        "rate": [],
        "absolute": {
            "maxServerMeta": 128,
            "maxPersonality": 5,
            "totalServerGroupsUsed": 0,
            "maxImageMeta": 128,
            "maxPersonalitySize": 10240,
            "maxTotalKeypairs": 100,
            "maxSecurityGroupRules": 20,
            "maxServerGroups": 10,
            "totalCoresUsed": 1,
            "totalRAMUsed": 2048,
            "totalInstancesUsed": 1,
            "maxSecurityGroups": 10,
            "totalFloatingIpsUsed": 0,
            "maxTotalCores": 20,
            "maxServerGroupMembers": 10,
            "maxTotalFloatingIps": 10,
            "totalSecurityGroupsUsed": 1,
            "maxTotalInstances": 10,
            "maxTotalRAMSize": 51200
        }
    }
}

This operation does not accept a request body.

Extensions (extensions)

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

OpenStack Compute API v2.0 supports extensions. However, extensions are deprecated in Compute API v2.1. For information about extensions, see Extensions.

GET
/v2.1/​{tenant_id}​/extensions
List extensions

Lists available extensions.

 

Extensions introduce features and vendor-specific functionality to the API without requiring a version change.

The response shows the extension name and its alias. To show details for an extension, you specify the alias.

Normal response codes
200 203
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

Response parameters
Parameter Style Type Description
next (Optional) plain xsd:anyURI

Moves to the next metadata item.

previous (Optional) plain xsd:anyURI

Moves to the previous metadata item.

x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

extensions plain xsd:list

List of extension objects.

name plain xsd:string

Name of the extension.

alias plain xsd:string

A short name by which this extension is also known.

links plain xsd:list

Links pertaining to this extension. This is a list of dictionaries, each including keys href and rel.

namespace plain xsd:string

A URL pointing to the namespace for this extension.

description plain xsd:string

Text describing this extension’s purpose.

updated plain xsd:dateTime

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

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

{
    "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": "",
            "links": [],
            "name": "ExtendedIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-IPS-MAC",
            "description": "",
            "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": "",
            "links": [],
            "name": "ExtendedStatus",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-EXT-VIF-NET",
            "description": "",
            "links": [],
            "name": "ExtendedVIFNet",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-FLV-DISABLED",
            "description": "",
            "links": [],
            "name": "FlavorDisabled",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "OS-FLV-EXT-DATA",
            "description": "",
            "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": "",
            "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": "",
            "links": [],
            "name": "BlockDeviceMappingV2Boot",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-cell-capacities",
            "description": "",
            "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": "",
            "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": "",
            "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": "",
            "links": [],
            "name": "ExtendedEvacuateFindHost",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-floating-ips",
            "description": "",
            "links": [],
            "name": "ExtendedFloatingIps",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-hypervisors",
            "description": "",
            "links": [],
            "name": "ExtendedHypervisors",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-networks",
            "description": "",
            "links": [],
            "name": "ExtendedNetworks",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-quotas",
            "description": "",
            "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": "",
            "links": [],
            "name": "ExtendedRescueWithImage",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-services",
            "description": "",
            "links": [],
            "name": "ExtendedServices",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-extended-services-delete",
            "description": "",
            "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": "",
            "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": "",
            "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": "",
            "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": "",
            "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": "",
            "links": [],
            "name": "ServerSortKeys",
            "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
            "updated": "2014-12-03T00:00:00Z"
        },
        {
            "alias": "os-server-start-stop",
            "description": "",
            "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": "",
            "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": "",
            "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": "",
            "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"
        }
    ]
}

This operation does not accept a request body.

GET
/v2.1/​{tenant_id}​/extensions/​{alias}​
Show extension details

Shows details for an extension, by alias.

 
Normal response codes
200 203
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

alias URI xsd:string

An alias for the extension name. For example, os-server-external-events.

Response parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique request ID that provides tracking for the request. Provider must configure middleware to return a request ID header in a response.

extension plain xsd:dict

An extension object.

name plain xsd:string

Name of the extension.

alias plain xsd:string

A short name by which this extension is also known.

links plain xsd:list

Links pertaining to this extension. This is a list of dictionaries, each including keys href and rel.

namespace plain xsd:string

A URL pointing to the namespace for this extension.

description plain xsd:string

Text describing this extension’s purpose.

updated plain xsd:dateTime

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

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

{
    "extension": {
        "updated": "2014-12-03T00:00:00Z",
        "name": "ServerExternalEvents",
        "links": [],
        "namespace": "http://docs.openstack.org/compute/ext/fake_xml",
        "alias": "os-server-external-events",
        "description": "Server External Event Triggers."
    }
}

This operation does not accept a request body.

Images

Lists, shows details for, and deletes images. Also sets, lists, shows details for, 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 Compute server actions.

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

GET
/v2.1/​{tenant_id}​/images
List images

Lists IDs, names, and links for available images.

 
Normal response codes
200 203
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

changes-since (Optional) query xsd:dateTime

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 xsd:anyURI

Filters the response by a server, as a URL.

name (Optional) query xsd:string

Filters the response by an image name, as a string.

status (Optional) query csapi:ImageStatus

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

minDisk (Optional) query xsd:int

Filters the response by a minimum disk size. For example, 100.

minRam (Optional) query xsd:int

Filters the response by a minimum RAM size. For example, 512.

type (Optional) query xsd:string

Filters the response by an image type. For example, snapshot or backup.

limit (Optional) query xsd:int

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 xsd: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 parameters
Parameter Style Type Description
x-openstack-request-id (Optional) header csapi:UUID

A unique ID for tracking the request. The request ID associated with the request appears in the log lines for that request. By default, the middleware configuration ensures that the request ID appears in the log files.

images plain csapi:ImagesWithOnlyIDsNamesLinks

Image information.

next (Optional) plain xsd:anyURI

Moves to the next metadata item.

previous (Optional) plain xsd:anyURI

Moves to the previous metadata item.

{
    "images": [
        {
            "id": "70a599e0-31e7-49b7-b260-868f441e862b",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/images/70a599e0-31e7-49b7-b260-868f441e862b",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/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.1/images/155d900f-4e14-4e4c-a73d-069cbf4541e6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/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.1/images/a2459075-d96c-40d5-893e-577ff92e721c",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/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.1/images/a440c04b-79fa-479c-bed1-0b816eaec379",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/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.1/images/c905cedb-7281-47e4-8a62-f26bc5fc4c77",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/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.1/images/cedef40a-ed67-4d10-800e-17455edce175",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/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.1/images/76fa36fc-c930-4bf3-8c8a-ea2a2420deb6",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/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
/v2.1/​{tenant_id}​/images/detail
List images details

Lists all details for available images.

 
Normal response codes
200 203
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

changes-since (Optional) query xsd:dateTime

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.