diff --git a/api-ref/src/docbkx/ch_compute-v2.xml b/api-ref/src/docbkx/ch_compute-v2.xml index c91035d44..b679d507c 100644 --- a/api-ref/src/docbkx/ch_compute-v2.xml +++ b/api-ref/src/docbkx/ch_compute-v2.xml @@ -1,28 +1,26 @@ - + +%common;]> + Compute API v2 (CURRENT) - Launch virtual machines from images or images stored on - persistent volumes. API v1.1 is identical to API v2. - XML support in requests and responses has been - deprecated for the Compute API v2. + Launch virtual machines from images or images stored on persistent volumes. API v1.1 is + identical to API v2. + + XML support in requests and responses has been deprecated for the Compute API + v2. +
API versions - List information for all API versions and show details - about API v2. + List information for all API versions and show details about API v2. - + - + @@ -31,43 +29,139 @@ Limits Get rate and absolute limits. - +
Extensions - List available Compute API v2 extensions and show - details for a specified extension. + List available Compute API v2 extensions and show details for a specified + extension. - + - +
Servers - List, create, get details for, update, and delete - servers. + List, create, get details for, update, and delete servers. + + + Passwords + When you create a server, you can specify a password through the optional adminPass + attribute. The specified 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, a randomly generated password is assigned + and returned in the response object. This password is guaranteed to meet the + security requirements set by the compute provider. For security reasons, the + password is not returned in subsequent &GET; calls. + + + + + 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 maximum number of key-value + pairs that can be supplied per server is determined by the compute provider. You + can query this value through the maxServerMeta absolute + limit. + + + + + Server networks + You can specify networks to which the server connects at launch time. You can + specify one or more networks. 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 + You can customize the personality of a server instance by injecting data into + its file system. For example, you might want to insert ssh keys, set + configuration files, or store data that you want to retrieve from inside the + instance. This feature provides a minimal amount of 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 providers + determines the maximum size of the file contents. This value can vary + based on the image that is used to create the server. + + The maximum limit refers to the number of bytes in the decoded + data and not to the number of characters in the encoded data. + + + + You can inject text files only. You cannot inject binary or ZIP files + into a new build. + + + The maximum number of file path/content pairs that you can supply is + also determined by the compute provider and is defined by the + maxPersonality absolute limit. + + + The absolute limit, maxPersonalitySize, is a byte limit + that is guaranteed to apply to all images in the deployment. Providers + can set additional per-image personality limits. + + + The file injection might not occur until after the server is built and + booted. + During file injection, any existing files that match specified files are + renamed to include the BAK extension appended with a time stamp. For example, if + the /etc/passwd file exists, it is backed up as + /etc/passwd.bak.1246036261.5785. + After file injection, personality files are accessible by only system + administrators. For example, on Linux, all files have root and the root group as + the owner and group owner, respectively, and allow user and group read access + only ( ). + + + + + Server access addresses + In a hybrid environment, the IP address of a server might not be controlled by + the underlying implementation. Instead, the access IP address might be part of + the dedicated hardware; for example, a router/NAT device. In this case, the + addresses provided by the implementation cannot actually be used to access the + server (from outside the local LAN). Here, a separate access + address might be assigned 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. + See . Nonetheless, clients that must + access the server directly are encouraged to do so through an access + address. + + - + - + - + @@ -76,11 +170,9 @@
Server metadata - Show details for, set, update, and delete server - metadata or metadata items. + Show details for, set, update, and delete server metadata or metadata items. - + @@ -95,24 +187,18 @@
Server addresses - List addresses for a specified server or a specified - server and network. + List addresses for a specified server or a specified server and network. - - + +
Server actions - Perform actions for a specified server, including change - administrator password, reboot, rebuild, resize, and - create image from server. + Perform actions for a specified server, including change administrator password, + reboot, rebuild, resize, and create image from server. - + @@ -125,47 +211,36 @@
Flavors - List available flavors and get details for a specified - flavor. A flavor is a hardware configuration for a server. - Each flavor is a unique combination of disk space and - memory capacity. + List available flavors and get details for a specified flavor. A flavor is a hardware + configuration for a server. Each flavor is a unique combination of disk space and memory + capacity. - + - + - +
Images - List available images, get details for a specified - image, and delete an image. - Also, set, list, get details for, and delete image - metadata. - An image is a collection of files that you use to create - or rebuild a server. By default, operators provide - pre-built operating system images. You can also create - custom images: See . + List available images, get details for a specified image, and delete an image. + Also, set, list, get details for, and delete image metadata. + An image is a collection of files that you use to create or rebuild a server. By + default, operators provide pre-built operating system images. You can also create custom + images: See . - + - + - + @@ -173,11 +248,9 @@
Image metadata - Show details for, set, update, and delete image metadata - or metadata items. + Show details for, set, update, and delete image metadata or metadata items. - + diff --git a/api-ref/src/wadls/compute-api/src/v2/wadl/os-compute-2.wadl b/api-ref/src/wadls/compute-api/src/v2/wadl/os-compute-2.wadl index 5fabff4ec..34b7c2fd4 100644 --- a/api-ref/src/wadls/compute-api/src/v2/wadl/os-compute-2.wadl +++ b/api-ref/src/wadls/compute-api/src/v2/wadl/os-compute-2.wadl @@ -11,9 +11,8 @@ %common;]> @@ -23,34 +22,24 @@ - + - - - The tenant ID in a multi-tenancy - cloud. + + + The tenant ID in a multi-tenancy cloud. - + - - - An alias, which is a name for a - pointer to a resource. For example, - a named extension. + + + An alias, which is a name for a pointer to a resource. For + example, a named extension. @@ -59,64 +48,44 @@ - + - + - - + + The UUID for the server. - - - - - A string. Maximum length is - 255 characters. - + + + + + A string. Maximum length is 255 characters. + - + - + - - - - The network label, such as - public or - private. - + + + The network label, such as public + or private. + @@ -132,56 +101,40 @@ - + - - + + The UUID for the image. - - - - - A string. Maximum length is - 255 characters. - + + + + + A string. Maximum length is 255 characters. + - + - - + + - - - UUID for the specific flavor - (combination of memory, disk size, - and CPUs). + + + UUID for the specific flavor (combination of memory, disk + size, and CPUs). @@ -195,82 +148,70 @@ - + Details for a version. - + A list of supported extensions. - + A detailed server list. - - A list of servers. Each server contains IDs, names, - and links. Other attributes are omitted. + + A list of servers. In the list, each server element shows includes its ID, name, + and links attributes. Other attributes are omitted. - + A list of addresses associated with a server. - - A list of addresses associated with a - network. + + A list of addresses associated with a network. - + A detailed image list. - - A list of images. Each image contains IDs, names, - and links. Other attributes are omitted. + + A list of images. Each image contains IDs, names, and links. Other attributes are + omitted. - + A detailed flavor list. - - A list of flavors. Each flavor contains IDs, names, - and links; other attributes are omitted. + + A list of flavors. Each flavor contains IDs, names, and links; other attributes + are omitted. - + Metadata details for a server. @@ -278,8 +219,7 @@ - + Metadata details for an image. @@ -292,147 +232,107 @@ - Lists information about all Compute - API versions. + Lists information about all Compute API versions. - - + + - - + + &commonFaults; &getFaults; - Shows details for Compute API - v2. + Shows details for Compute API v2. - - + + - - - + + + - - Full URL - to a service or server. - + Full URL to a service or server. + &commonFaults; - - Lists the current limits for the - account. + + Lists the current limits for the account. - - + + - - - + + + &commonFaults; - + Lists available extensions. - - + + - - - + + + - Moves to the next metadata - item. + Moves to the + next metadata item. - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + &commonFaults; - - Gets details about the specified - extension. - Extensions introduce features and vendor-specific - functionality to the API without requiring a version - change. + + Gets details about the specified extension. + Extensions introduce features and vendor-specific functionality to the API without + requiring a version change. - + - - + + @@ -440,57 +340,133 @@ &commonFaults; &getFaults; - + Creates a server. + This operation asynchronously provisions a new server. The progress of this + operation depends on several factors including location of the requested image, + network i/o, host load, and the selected flavor. The progress of the request can be + checked by performing a &GET; on /servers/id, which will + return a progress attribute (0-100% completion). The full URL to the newly created + server is returned via the Location header and is available as a + self and bookmark link in the server representation + (See Links and references). + Note that when you create a server, only the server ID, its links, and the admin + password are guaranteed to be returned in the response. You can retrieve additional + attributes through subsequent &GET;s on the server. - &serverCreateParameters; + + &serverCreateParameters; - - + + - - - + + + - - + + - - - + + + &serverCreateParameters; - + - - &commonFaults; &getFaults; &postPutFaults; &buildFaults; + &commonFaults; &getFaults; + &postPutFaults; &buildFaults; - - Lists IDs, names, and links for all - 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 server status is one of the following + values: + + Server status values + + ACTIVE. The server is active. + + + BUILD. The server has not finished the original build + process. + + + DELETED. The server is 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. + + + PASSWORD. The password is being reset on the server. + + + REBOOT. The server is in a soft reboot state. A reboot + command was passed to the operating system. + + + REBUILD. The server is currently being rebuilt from an + image. + + + RESCUE. The server is in rescue mode. + + + RESIZE. Server is performing the differential copy of data + that changed during its initial copy. Server is down for this stage. + + + REVERT_RESIZE. The resize or migration of a server failed for + some reason. The destination server is being cleaned up and the original + source server is restarting. + + + SHUTOFF. The virtual machine (VM) was powered down by the + user, but not through the OpenStack Compute API. For example, the user + issued a shutdown -h command from within the server instance. + If the OpenStack Compute manager detects that the VM was powered down, it + transitions the server instance to the SHUTOFF status. If you use the + OpenStack Compute API to restart the instance, the instance might be deleted + first, depending on the value in the + shutdown_terminate database field on the Instance + model. + + + SUSPENDED. The server is suspended, either by request or + necessity. This status appears for only the following hypervisors: + XenServer/XCP, KVM, and ESXi. Administrative users may 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. + + @@ -498,39 +474,32 @@ - - + + - - + - + List of servers. - Moves to the next metadata - item. + Moves to the + next metadata item. - Moves to the previous - metadata item. + Moves to the + previous metadata item. @@ -539,8 +508,16 @@ - Lists details for all - servers. + Lists details for all servers. + 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. hostId represents + the host your server runs on and can be used to determine this scenario if it is + relevant to your application. + + HostId is unique per account and is + not globally unique. + @@ -548,553 +525,394 @@ - - + + - Moves to the next metadata - item. - + Moves to the + next metadata item. + - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + - - + + - - - + + + &commonFaults; - - Gets details for a specified - server. + + Gets details for a specified server. - - + + - - - + + + &commonFaults; &getFaults; - - Updates the editable attributes of - the specified server. + + Updates the editable attributes of the specified server. - - + - + - - + - + - - - The name of the server. If you edit the - server name, the server host name does not - change. Also, server names are not - guaranteed to be unique. + + + The name of the server. If you edit the server name, the server host + name does not change. Also, server names are not guaranteed to be + unique. - - + The IP version 4 address. - - + The IP version 6 address. - - + - - + - - + - + - - + - + - - + - - + - - &commonFaults; &getFaults; &postPutFaults; &inProgressFault; + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; - + Deletes a specified server. - &commonFaults; - &getFaults; + &commonFaults; &getFaults; - - Changes the password for a server. - Specify the changePassword action in the - request body. + + Changes the password for a server. Specify the + changePassword action in the request body. - - + + - - - + + + - &commonFaults; - &getFaults; &postPutFaults; &inProgressFault; + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; - - Reboots the specified server. - Specify the reboot action in the request - body. - - - - - - - - - - - - - - - &commonFaults; - &getFaults; &postPutFaults; &rebootFaults; &inProgressFault; - - - Rebuilds the specified server. - Specify the rebuild action in the request - body. - - - - - - - - - - - - - - - - - - - - - - - - - - Specific URL of the server you want to - rebuild. - - - - - &commonFaults; &getFaults; &postPutFaults; &buildFaults; - &inProgressFault; - - - Resizes the specified server. - Specify the resize action in the request - body. - - - - - - - - - - - - - - - - &commonFaults; &getFaults; &postPutFaults; &buildFaults; - &inProgressFault; - - - Confirms a pending resize action. - Specify the confirmResize action in the - request body. - - - - - - - - - - - - - - - - &commonFaults; &getFaults; &postPutFaults; &buildFaults; - &inProgressFault; - - - Cancels and reverts a pending - resize action. Specify the revertResize + + Reboots the specified server. Specify the reboot action in the request body. - - + + - - - + + + - - &commonFaults; &getFaults; &postPutFaults; &buildFaults; - &inProgressFault; - - - Creates a new image. Specify the - createImage action in the request - body. + &commonFaults; &getFaults; &postPutFaults; + &rebootFaults; &inProgressFault; + + + Rebuilds the specified server. Specify the rebuild + action in the request body. - - + + - - - + + + - - + + + + + + + + + + + + + + + Specific URL of the server you want to rebuild. + + + + &commonFaults; + &getFaults; &postPutFaults; &buildFaults; &inProgressFault; + + + Resizes the specified server. Specify the resize + action in the request body. + + + + + + + + + + + + + + + &commonFaults; + &getFaults; &postPutFaults; &buildFaults; &inProgressFault; + + + Confirms a pending resize action. Specify the + confirmResize action in the request body. + + + + + + + + + + + + + + + &commonFaults; + &getFaults; &postPutFaults; &buildFaults; &inProgressFault; + + + Cancels and reverts a pending resize action. Specify the + revertResize action in the request body. + + + + + + + + + + + + + + + &commonFaults; + &getFaults; &postPutFaults; &buildFaults; &inProgressFault; + + + Creates a new image. Specify the createImage action + in the request body. + + + + + + + + + + + + + Name of the snapshot. - - - A dictionary representation of a - creation for image. + + A dictionary representation of a creation for image. - - - Metadata key and value pairs. The - maximum size of the metadata key and value - is 255 bytes each. + + + Metadata key and value pairs. The maximum size of the metadata key and + value is 255 bytes each. - + - + - - &commonFaults; &getFaults; &postPutFaults; &buildFaults; - &inProgressFault; + &commonFaults; + &getFaults; &postPutFaults; &buildFaults; &inProgressFault; - - Lists networks and addresses for a - specified tenant and server. - Specify the tenant ID and server ID in the - URI. + + Lists networks and addresses for a specified tenant and + server. + Specify the tenant ID and server ID in the URI. - + - - + + - &commonFaults; - &getFaults; &inProgressFault; + &commonFaults; &getFaults; &inProgressFault; - Lists addresses for a specified - tenant, server, and network. - Specify the tenant ID, server ID, and network label - in the request URI. + Lists addresses for a specified tenant, server, and + network. + Specify the tenant ID, server ID, and network label in the request URI. - + - - + + - &commonFaults; - &getFaults; &inProgressFault; + &commonFaults; &getFaults; &inProgressFault; - - Lists IDs, names, and links for - available flavors. + + Lists IDs, names, and links for available flavors. - - &flavorListQueryParameters; + &flavorListQueryParameters; + - - + + - - - + + + - Flavors are known - combinations of memory, disk space, and - number of CPUs. + type="csapi:FlavorsWithOnlyIDsNamesLinks" path="/csapi:flavors"> + Flavors are + known combinations of memory, disk space, and number of + CPUs. - Moves to the next metadata - item. + Moves to the + next metadata item. - Moves to the previous - metadata item. + Moves to the + previous metadata item. @@ -1103,732 +921,517 @@ - Lists all details for available - flavors. + Lists all details for available flavors. - - &flavorListQueryParameters; + &flavorListQueryParameters; + - - + + - - - + + + - Moves to the next metadata - item. - + Moves to the + next metadata item. + - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + &commonFaults; - - Gets details for a specified - flavor. + + Gets details for a specified flavor. - - + + - - - + + + &commonFaults; &getFaults; - - Lists all details for available - images. + + Lists all details for available images. - - &imageListQueryParameters; + &imageListQueryParameters; + - - + + - - - + + + - Moves to the next metadata - item. - + Moves to the + next metadata item. + - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + &commonFaults; - - Lists IDs, names, and links for - available images. + + Lists IDs, names, and links for available images. - - &imageListQueryParameters; + &imageListQueryParameters; + - - + + - - - + + + - Image - information. + type="csapi:ImagesWithOnlyIDsNamesLinks" path="/csapi:images"> + Image + information. - Moves to the next metadata - item. + Moves to the + next metadata item. - Moves to the previous - metadata item. + Moves to the + previous metadata item. &commonFaults; - - Gets details for a specified - image. + + Gets details for a specified image. - - + + - - - + + + &commonFaults; &getFaults; - + Deletes a specified image. &commonFaults; &getFaults; - - Shows metadata for a specified - server. + + Shows metadata for a specified server. - - + + - - - + + + - Moves to the next metadata - item. - + Moves to the + next metadata item. + - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + - &commonFaults; - &getFaults; + &commonFaults; &getFaults; - - Shows metadata for a specified - image. + + Shows metadata for a specified image. - - - + + + + - - - + + + - Moves to the next metadata - item. - + Moves to the + next metadata item. + - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + - &commonFaults; - &getFaults; + &commonFaults; &getFaults; - Updates metadata items by key for a - specified server. - Replaces items that match the specified keys and - does not modify items not specified in the - request. - An overLimit (413) fault - might be thrown if the operation causes the quota for - metadata items to be exceeded. + Updates metadata items by key for a specified server. + Replaces items that match the specified keys and does not modify items not + specified in the request. + An overLimit (413) fault might be thrown if the operation + causes the quota for metadata items to be exceeded. - - + + - - - + + + - - - + + + + - - - + + + - Moves to the next metadata - item. - + Moves to the + next metadata item. + - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + - - &commonFaults; &getFaults; &postPutFaults; &inProgressFault; + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; - Updates metadata items by key for a - specified image. - Replaces items that match the specified keys and - does not modify items not specified in the - request. - An overLimit (413) fault - might be thrown if the operation causes the quota for - metadata items to be exceeded. + Updates metadata items by key for a specified image. + Replaces items that match the specified keys and does not modify items not + specified in the request. + An overLimit (413) fault might be thrown if the operation + causes the quota for metadata items to be exceeded. - - + + - - - - - - - - - - - - - - - - - Moves to the next metadata - item. - - - - Moves to the previous - metadata item. - - - - - - &commonFaults; &getFaults; &postPutFaults; &inProgressFault; - - - Creates or replaces metadata for a - specified server. - Replaces items that match the specified keys. If you - omit a key that already exists, the key retains its - value. - If the number of metadata items exceeds the quota - for metadata items, an overLimit - (413) fault might be - thrown. - - - - - - - - - - - - - - - - - - - - - - - - Moves to the next metadata - item. - - - - Moves to the previous - metadata item. - - - - - - &commonFaults; &getFaults; &postPutFaults; &inProgressFault; - - - Creates or replaces metadata for a - specified image. - Replaces items that match the specified keys. If you - omit a key that already exists, this key retains its - value. - If the number of metadata items exceeds the quota - for metadata items, an overLimit - (413) fault might be - thrown. - - - - - - - - - - + + + - - + + - - - + + + - Moves to the next metadata - item. - + Moves to the + next metadata item. + - Moves to the previous - metadata item. - + Moves to the + previous metadata item. + - - &commonFaults; &getFaults; &postPutFaults; &inProgressFault; + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; + + + Creates or replaces metadata for a specified server. + Replaces items that match the specified keys. If you omit a key that already + exists, the key retains its value. + If the number of metadata items exceeds the quota for metadata items, an overLimit + (413) fault might be thrown. + + + + + + + + + + + + + + + + + + + + + + + + + Moves to the + next metadata item. + + + + Moves to the + previous metadata item. + + + + + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; + + + Creates or replaces metadata for a specified image. + Replaces items that match the specified keys. If you omit a key that already + exists, this key retains its value. + If the number of metadata items exceeds the quota for metadata items, an overLimit + (413) fault might be thrown. + + + + + + + + + + + + + + + + + + + + + + + + + Moves to the + next metadata item. + + + + Moves to the + previous metadata item. + + + + + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; - Shows details for a metadata item - by key for a specified server. + Shows details for a metadata item by key for a specified + server. - - + + - - - + + + - &commonFaults; - &getFaults; + &commonFaults; &getFaults; - Shows details for a metadata item - by key for a specified image. + Shows details for a metadata item by key for a specified + image. - - + + - - - + + + - &commonFaults; - &getFaults; + &commonFaults; &getFaults; - Sets a metadata item by key for a - specified server. - An overLimit (413) fault - might be thrown if the operation causes the quota for - metadata items to be exceeded. + Sets a metadata item by key for a specified server. + An overLimit (413) fault might be thrown if the operation + causes the quota for metadata items to be exceeded. - - + + - - - + + + - - + + - - - + + + - - &commonFaults; &getFaults; &postPutFaults; &inProgressFault; + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; - Creates or updates a metadata item - by key for a specified image. - An overLimit (413) fault - might be thrown if the operation causes the quota for - metadata items to be exceeded. + Creates or updates a metadata item by key for a specified + image. + An overLimit (413) fault might be thrown if the operation + causes the quota for metadata items to be exceeded. - - + + - - - + + + - - + + - - - + + + - - &commonFaults; &getFaults; &postPutFaults; &inProgressFault; + &commonFaults; &getFaults; &postPutFaults; + &inProgressFault; - Deletes a metadata item by key for - a specified server. + Deletes a metadata item by key for a specified server. - &commonFaults; - &getFaults; &inProgressFault; + &commonFaults; &getFaults; &inProgressFault; - Deletes a metadata item by key for - a specified image. + Deletes a metadata item by key for a specified image. - &commonFaults; - &getFaults; &inProgressFault; + &commonFaults; &getFaults; &inProgressFault; +