From cf44f0ab7d89784f5ac231b20ec99e3b540b7aa3 Mon Sep 17 00:00:00 2001 From: John Garbutt Date: Tue, 22 Sep 2015 11:59:47 +0100 Subject: [PATCH] docs: re-organise the API concept docs This moves material from 2.0_general_info into the index to make an improved index page. Some details from the general_info have been moved into the server concepts, where that information is a better fit. The general_info page has been expanded with TODOs so we are clear about some the missing details. Co-Authored-By: Ed Leafe Change-Id: I2a878586d6a073026d1f997e6f0f7ee87a01f726 --- doc/source/v2/2.0_general_info.rst | 193 +++++++++++++++++--------- doc/source/v2/2.0_server_concepts.rst | 49 ++++++- doc/source/v2/index.rst | 73 ++++++++-- doc/source/v2/microversions.rst | 21 +++ 4 files changed, 257 insertions(+), 79 deletions(-) create mode 100644 doc/source/v2/microversions.rst diff --git a/doc/source/v2/2.0_general_info.rst b/doc/source/v2/2.0_general_info.rst index e32e3e83ae..7ff6df2b4b 100644 --- a/doc/source/v2/2.0_general_info.rst +++ b/doc/source/v2/2.0_general_info.rst @@ -1,17 +1,12 @@ -==================================== -General Compute API v2.0 information -==================================== +========================= +Key Compute API Concepts +========================= The OpenStack Compute API is defined as a ReSTful HTTP service. The API takes advantage of all aspects of the HTTP protocol (methods, URIs, media types, response codes, etc.) and providers are free to use existing features of the protocol such as caching, persistent -connections, and content compression among others. For example, -providers who employ a caching layer may respond with a 203 when a -request is served from the cache instead of a 200. Additionally, -providers may offer support for conditional **GET** requests using -ETags, or they may send a redirect in response to a **GET** request. -Clients should be written to account for these differences. +connections, and content compression among others. Providers can return information identifying requests in HTTP response headers, for example, to facilitate communication between the provider @@ -23,27 +18,8 @@ disk space, and CPU, and can be provisioned in minutes. Interactions with Compute Servers can happen programmatically with the OpenStack Compute API. -We welcome feedback, comments, and bug reports at -`bugs.launchpad.net/nova `__. - -Intended audience ------------------ - -This guide assists software developers who want to develop applications -using the OpenStack Compute API. To use this information, you should -have access to an account from an OpenStack Compute provider, and you -should also be familiar with the following concepts: - -- OpenStack Compute service - -- ReSTful web services - -- HTTP/1.1 - -- JSON data serialization formats - -Concepts --------- +User Concepts +============== To use the OpenStack Compute API effectively, you should understand several key concepts: @@ -51,7 +27,11 @@ several key concepts: - **Server** A virtual machine (VM) instance in the compute system. Flavor and - image are requisite elements when creating a server. + image are requisite elements when creating a server. A name for the server + is also required. + + For more details, such as server actions and server metadata, + please see: :doc:`2.0_server_concepts` - **Flavor** @@ -68,54 +48,129 @@ several key concepts: server images if you plan to deploy a particular server configuration frequently. -- **Reboot** +- **Key Pair** - Use this function to perform either a soft or hard reboot of a - server. With a soft reboot, the operating system is signaled to - restart, which allows for a graceful shutdown of all processes. A - hard reboot is the equivalent of power cycling the server. The - virtualization platform should ensure that the reboot action has - completed successfully even in cases in which the underlying - domain/VM is paused or halted/stopped. + An ssh or x509 keypair that can be injected into a server. This allows you + to connect to your server once t has been created without having to use a + password. If you don't specify a key pair, Nova will create a root password + for you, and return it in plain text in the server create response. -- **Rebuild** +- **Volume** - Use this function to remove all data on the server and replaces it - with the specified image. Server ID and IP addresses remain the same. + A block storage device that Nova can use as permanent storage. When a server + is created it has some disk storage available, but that is considered + ephemeral, as it is destroyed when the server is destroyed. A volume can be + attached to a server, then later detached and used by another server. + Volumes are created and managed by the Cinder service, though the Nova API + can proxy some of these calls. -- **Resize** +- **Quotas** - Use this function to convert an existing server to a different - flavor, in essence, scaling the server up or down. The original - server is saved for a period of time to allow rollback if there is a - problem. All resizes should be tested and explicitly confirmed, at - which time the original server is removed. All resizes are - automatically confirmed after 24 hours if you do not confirm or - revert them. + An upper bound on the amount of resources any individual tenant may consume. + Quotas can be used to limit the number of servers a tenant creates, or the + amount of disk space consumed, so that no one tenant can overwhelm the + system and prevent normal operation for others. Changing quotas is an + admin-level action. -- **Pause** +- **Rate Limiting** - You can pause a server by making a pause request. This request stores - the state of the VM in RAM. A paused instance continues to run in a - frozen state. + Please see :doc:`limits` -- **Suspend** +- **Availability zone** - Administrative users might want to 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. + A grouping of host machines that can be used to control where a new server + is created. There is some confusion about this, as the name "availability + zone" is used in other clouds, such as Amazon Web Services, to denote a + physical separation of server locations that can be used to distribute cloud + resources for fault tolerance in case one zone is unavailable for any + reason. Such a separation is possible in Nova if an admin carefully sets up + availability zones for that, but it is not the default. -Reference ---------- +Networking Concepts +------------------- -For a reference listing for the Compute API v2, see the `*Compute API v2 -reference -(CURRENT)* `__. +In this section we focus on this related to networking. -For information about Compute API v 2 extensions, see the `*Compute API v2 -extensions -(CURRENT)* `__. +- **Port** + TODO + +- **Floating IPs, Pools and DNS** + + TODO + +- **Security Groups** + + TODO + +- **Cloudpipe** + + TODO + +- **Extended Networks** + + TODO + + +Administrator Concepts +======================= + +Come APIs are largely focused on administration of Nova, and generally focus +on compute hosts rather than servers. + +- **Hosts** + + TODO + +- **Host Actions** + + TODO + +- **Hypervisors** + + TODO + +- **Aggregates** + + TODO + +- **Migrations** + + TODO + +- **Certificates** + + TODO + +Error Handling +============== + +The Compute API follows the standard HTTP error code conventions. + +TODO - add details including: request id, migrations and instance actions. + +Relationship with Volume API +============================= + +Here we discuss about Cinder's API and how Nova users volume uuids. + +TODO - add more details. + +Relationship with Image API +============================= + +Here we discuss about Glance's API and how Nova users image uuids. +We also discuss how Nova proxies setting image metadata. + +TODO - add more details. + +Interactions with Neutron and Nova-Network +========================================== + +We talk about how networking can be provided be either by Nova or Neutron. + +Here we discuss about Neutron's API an how Nova users port uuids. +We also discuss Nova automatically creating ports, proxying security groups, +and proxying floating IPs. Also talk about the APIs we do not proxy. + +TODO - add more details. diff --git a/doc/source/v2/2.0_server_concepts.rst b/doc/source/v2/2.0_server_concepts.rst index b4e3f8d2b0..f8ed4d2dca 100644 --- a/doc/source/v2/2.0_server_concepts.rst +++ b/doc/source/v2/2.0_server_concepts.rst @@ -2,8 +2,8 @@ Server concepts =============== -For the OpenStack Compute API, a server is a virtual machine (VM) instance in -the compute system. +For the OpenStack Compute API, a server is a virtual machine (VM) instance, +a physical machine or a container. Server status ~~~~~~~~~~~~~ @@ -104,6 +104,51 @@ administrative password are guaranteed to be returned in the request. You can retrieve additional attributes by performing subsequent **GET** operations on the server. +Server actions +~~~~~~~~~~~~~~~ + +- **Reboot** + + Use this function to perform either a soft or hard reboot of a + server. With a soft reboot, the operating system is signaled to + restart, which allows for a graceful shutdown of all processes. A + hard reboot is the equivalent of power cycling the server. The + virtualization platform should ensure that the reboot action has + completed successfully even in cases in which the underlying + domain/VM is paused or halted/stopped. + +- **Rebuild** + + Use this function to remove all data on the server and replaces it + with the specified image. Server ID and IP addresses remain the same. + +- **Resize** + + Use this function to convert an existing server to a different + flavor, in essence, scaling the server up or down. The original + server is saved for a period of time to allow rollback if there is a + problem. All resizes should be tested and explicitly confirmed, at + which time the original server is removed. All resizes are + automatically confirmed after 24 hours if you do not confirm or + revert them. + +- **Pause** + + You can pause a server by making a pause request. This request stores + the state of the VM in RAM. A paused instance continues to run in a + frozen state. + +- **Suspend** + + Administrative users might want to 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. + +TODO - need to add many more actions in here + Server passwords ~~~~~~~~~~~~~~~~ diff --git a/doc/source/v2/index.rst b/doc/source/v2/index.rst index 8cc92c5c69..21c722a260 100644 --- a/doc/source/v2/index.rst +++ b/doc/source/v2/index.rst @@ -13,25 +13,82 @@ License for the specific language governing permissions and limitations under the License. -Compute API v2 -============== +=========== +Compute API +=========== -This section describes the Compute API version 2 and is intended for software -developers interested in developing applications using the OpenStack Compute -Application Programming Interface (API). +OpenStack Nova has a ReSTful HTTP service called the OpenStack Compute API. +Through this API, Nova provides massively scalable, on demand, self service +access to compute resources. Depending on the deployment those compute +resources might be Virtual Machines, Physical Machines or Containers. + +We welcome feedback, comments, and bug reports at +`bugs.launchpad.net/nova `__. + + +Intended Audience +================= + +This guide assists software developers who want to develop applications +using the OpenStack Compute API. To use this information, you should +have access to an account from an OpenStack Compute provider, or have +access to your own deployment, and you should also be familiar with the +following concepts: + +* OpenStack Compute service +* ReSTful web services +* HTTP/1.1 +* JSON data serialization formats + + +Versions and Extensions +======================= + +Following the Liberty release, every Nova deployment should have +the following endpoints: + +* / - list of available versions +* /v2.0 - the first version of the Compute API, uses extensions +* /v1.1 - an alias for v2.0 for backwards compatibility +* /v2.1 - same API, except uses microversions + +For more information on how to make use the API, how to get the endpoint +from the keystone service catalog and pick what version of the API to use, +please read: .. toctree:: - :maxdepth: 3 + :maxdepth: 1 + + versions + extensions + microversions + + +Key API Concepts +================ + +The following documents go into more details about the key concepts of the +OpenStack Compute API: + +.. toctree:: + :maxdepth: 2 2.0_general_info 2.0_server_concepts authentication - extensions faults limits links_and_references paginated_collections polling_changes-since_parameter request_and_response_formats - versions + +Full Reference +============== + +For a full reference listing for the OpenStack Compute API, please see: + +* `*Compute API v2.1 extensions (CURRENT)* `__. +* `*Compute API v2 reference (SUPPORTED)* `__. +* `*Compute API v2 extensions (SUPPORTED)* `__. diff --git a/doc/source/v2/microversions.rst b/doc/source/v2/microversions.rst new file mode 100644 index 0000000000..8b31cb7574 --- /dev/null +++ b/doc/source/v2/microversions.rst @@ -0,0 +1,21 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============== +Microversions +============== + +API v2.1 users micro versions, instead of extensions, to allow for the API +to slowly evolve over time, without breaking any existing users. + +TODO - add more information.