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 <ed@leafe.com> Change-Id: I2a878586d6a073026d1f997e6f0f7ee87a01f726
This commit is contained in:
John Garbutt
EdLeafe
parent
253cd4bf17
commit
cf44f0ab7d
@ -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 <http://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)* <http://developer.openstack.org/api-ref-compute-v2.html>`__.
|
||||
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)* <http://developer.openstack.org/api-ref-compute-v2-ext.html>`__.
|
||||
- **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.
|
||||
|
||||
@ -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
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@ -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 <http://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)* <http://developer.openstack.org/api-ref-compute-v2.1.html>`__.
|
||||
* `*Compute API v2 reference (SUPPORTED)* <http://developer.openstack.org/api-ref-compute-v2.html>`__.
|
||||
* `*Compute API v2 extensions (SUPPORTED)* <http://developer.openstack.org/api-ref-compute-v2-ext.html>`__.
|
||||
|
||||
21
doc/source/v2/microversions.rst
Normal file
21
doc/source/v2/microversions.rst
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user