openstack
/
nova
Code Issues Proposed changes

Fix API Guide doc 

* typos
* reduntant words
* reworded sentences for clarity

Closes-bug: #1545748

Change-Id: I0700d04de38b34cf13988490873b8c34dad1005b
This commit is contained in:
Waldemar Znoinski 2016-02-15 14:42:02 +00:00
parent c20fbc44a9
commit fdd8f0f91e
10 changed files with 97 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
api-guide/source/faults.rst
View File

@ -2,16 +2,16 @@
Faults
======
This doc looks at how to understand what has happened to your API request.
This doc explains how to understand what has happened to your API request.
Every HTTP request has a status code. 2xx codes signify the API was a success.
However, that is often not the end of the story. That generally only means the
request to start the operation has been accepted, it does not mean the action
request to start the operation has been accepted. It does not mean the action
you requested has successfully completed.
Tracking Errors by Request ID
==============================
=============================
Every request made has a unique Request ID.
This is returned in a response header.
@ -70,15 +70,15 @@ information about the fault in the body of the response.
}
}
The error code is returned in the body of the response for convenience.
The message section returns a human-readable message that is appropriate
for display to the end user. The details section is optional and may
The error ``code`` is returned in the body of the response for convenience.
The ``message`` section returns a human-readable message that is appropriate
for display to the end user. The ``details`` section is optional and may
contain information—for example, a stack trace—to assist in tracking
down an error. The detail section might or might not be appropriate for
down an error. The ``details`` section might or might not be appropriate for
display to an end user.
The root element of the fault (such as, computeFault) might change
depending on the type of error. The following is a list of possible
depending on the type of error. The following link contains a list of possible
elements along with their associated error codes.
For more information on possible error code, please see:
@ -100,7 +100,7 @@ When a server is placed into an ``ERROR`` state, a fault is embedded in the
offending server. Note that these asynchronous faults follow the same format
as the synchronous ones. The fault contains an error code, a human readable
message, and optional details about the error. Additionally, asynchronous
faults may also contain a created timestamp that specifies when the fault
faults may also contain a ``created`` timestamp that specifies when the fault
occurred.

67
api-guide/source/general_info.rst
View File

@ -1,6 +1,6 @@
=========================
========================
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,
@ -10,7 +10,7 @@ connections, and content compression among others.
Providers can return information identifying requests in HTTP response
headers, for example, to facilitate communication between the provider
and client users.
and client applications.
OpenStack Compute is a compute service that provides server capacity in
the cloud. Compute Servers come in different flavors of memory, cores,
@ -19,23 +19,23 @@ with Compute Servers can happen programmatically with the OpenStack
Compute API.
User Concepts
==============
=============
To use the OpenStack Compute API effectively, you should understand
several key concepts:
- **Server**
A virtual machine (VM) instance in the compute system. Flavor and
image are requisite elements when creating a server. A name for the server
is also required.
A virtual machine (VM) instance, physical machine or a container in the
compute system. Flavor and 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:`server_concepts`
- **Flavor**
An available hardware configuration for a server. Each flavor has a
Virtual hardware configuration for the requested server. Each flavor has a
unique combination of disk space, memory capacity and priority for
CPU time.
@ -60,10 +60,11 @@ several key concepts:
- **Key Pair**
An ssh or x509 keypair that can be injected into a server. This allows you
to connect to your server once it 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.
An ssh or x509 keypair that can be injected into a server at it's boot time.
This allows you to connect to your server once it 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.
- **Volume**
@ -76,7 +77,7 @@ several key concepts:
- **Quotas**
An upper bound on the amount of resources any individual tenant may consume.
An upper limit 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
@ -123,14 +124,14 @@ In this section we focus on this related to networking.
Administrator Concepts
=======================
======================
Some APIs are largely focused on administration of Nova, and generally focus
on compute hosts rather than servers.
- **Services**
Services are provide by Nova components. Normally, the Nova component runs
Services are provided by Nova components. Normally, the Nova component runs
as a process on the controller/compute node to provide the service. These
services may be end-user facing, such as the the OpenStack Compute REST API
service, but most just work with other Nova services. The status of each
@ -141,7 +142,8 @@ on compute hosts rather than servers.
- **nova-osapi_compute**
This service provides the OpenStack Compute REST API to end users.
This service provides the OpenStack Compute REST API to end users and
application clients.
- **nova-metadata**
@ -155,10 +157,10 @@ on compute hosts rather than servers.
- **nova-conductor**
This service provides database access for the other services, and handles
internal version compatibility when different services are running
different versions of code. The conductor service also handles
long-running requests.
This service provides database access for Nova and the other OpenStack
services, and handles internal version compatibility when different
services are running different versions of code. The conductor service
also handles long-running requests.
- **nova-compute**
@ -176,7 +178,7 @@ on compute hosts rather than servers.
- **nova-consoleauth**
This service provides authorization for consoles.
This service provides authorization for compute instances consoles.
- **nova-cert**
@ -186,9 +188,8 @@ on compute hosts rather than servers.
- **enable, disable, disable-log-reason**
The service can be disabled to indicate the service didn't provided
service anymore. This is used by administrator to stop service for
maintenance.
The service can be disabled to indicate the service is not available anymore.
This is used by administrator to stop service for maintenance.
For example, when Administrator wants to maintain a specific compute node,
Administrator can disable nova-compute service on that compute node. Then
nova won't dispatch any new compute request to that compute node anymore.
@ -199,9 +200,9 @@ on compute hosts rather than servers.
This action allows you set the state of service down immediately. Actually
Nova only provides the health monitor of service status, there isn't any
guarantee about health status of other parts of infrastructure, like the
health status of data network, storage network and other hardwares. The
health status of data network, storage network and other components. The
more complete health monitor of infrastructure is provided by external
system normally. An external health monitor system can marks the service
system normally. An external health monitor system can mark the service
down for notifying the fault.
`(This action is enabled in Microversion 2.11)`
@ -243,7 +244,7 @@ on compute hosts rather than servers.
currently running, as well as detailed info about the hypervisor, such as
CPU, memory, or disk related configuration.
Currently nova-compute also support Ironic and LXC, but they don't have
Currently nova-compute also supports Ironic and LXC, but they don't have
a hypervisor running.
- **Aggregates**
@ -266,16 +267,16 @@ on compute hosts rather than servers.
are used to generate certificates for euca-bundle-image.
Relationship with Volume API
=============================
============================
Here we discuss about Cinder's API and how Nova users volume uuids.
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.
Here we discuss about Glance's API and how Nova uses image UUIDs.
We also discuss how Nova proxies setting image metadata.
TODO - add more details.
@ -283,9 +284,9 @@ TODO - add more details.
Interactions with Neutron and Nova-Network
==========================================
We talk about how networking can be provided be either by Nova or Neutron.
We talk about how networking can be provided be either Nova or Neutron.
Here we discuss about Neutron's API an how Nova users port uuids.
Here we discuss about Neutron's API and 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.

2
api-guide/source/index.rst
View File

@ -50,7 +50,7 @@ The Compute API includes all end user and operator API calls.
The API works with keystone and oslo.policy to deliver RBAC (Role-based access
control).
The default policy file gives suggestions on what APIs should not
be made available to most end users, but this is fully configurable.
be made available to most end users but this is fully configurable.
API Versions
============

4
api-guide/source/limits.rst
View File

@ -8,7 +8,7 @@ two kinds of limits: *rate limits* and *absolute limits*. Rate limits
are thresholds that are reset after a certain amount of time passes.
Absolute limits are fixed. Limits are configured by operators and may
differ from one deployment of the OpenStack Compute service to
another. Please contact your provider to determine the limits that
another. Please contact your provider to determine the limits that
apply to your account. Your provider may be able to adjust your
account's limits if they are too low. Also see the API Reference for
`*Limits* <http://developer.openstack.org/api-ref-compute-v2.html#compute_limits>`__.
@ -58,7 +58,7 @@ Absolute limits
Absolute limits are specified as name/value pairs. The name of the
absolute limit uniquely identifies the limit within a deployment. Please
consult your provider for an exhaustive list of absolute value names. An
consult your provider for an exhaustive list of absolute limits names. An
absolute limit value is always specified as an integer. The name of the
absolute limit determines the unit type of the integer value. For
example, the name maxServerMeta implies that the value is in terms of

4
api-guide/source/links_and_references.rst
View File

@ -72,8 +72,8 @@ following types of link relations are associated with resources:
resource. For example, an OpenStack Compute image might have an
alternate representation in the OpenStack Image service.
.. note:: The type attribute provides a hint as to the type of representation
to expect when following the link.
.. note:: The ``type`` attribute provides a hint as to the type of
representation to expect when following the link.
**Example: Server with self links: JSON**

9
api-guide/source/paginated_collections.rst
View File

@ -13,16 +13,16 @@ by the compute provider. To navigate the collection, the *``limit``* and
The *``marker``* parameter is the ID of the last item in the previous
list. By default, the service sorts items by create time in descending order.
When the service cannot identify a a create time, it sorts items by ID. The
When the service cannot identify a create time, it sorts items by ID. The
*``limit``* parameter sets the page size. Both parameters are optional. If the
client requests a *``limit``* beyond that which is supported by the deployment
client requests a *``limit``* beyond one that is supported by the deployment
an overLimit (413) fault may be thrown. A marker with an invalid ID returns
a badRequest (400) fault.
For convenience, collections should contain atom ``next``
links. They may optionally also contain ``previous`` links but the current
implementation does not contain ``previous`` links. The last
page in the list does not contain a "next" link. The following examples
page in the list does not contain a link to "next" page. The following examples
illustrate three pages in a collection of images. The first page was
retrieved through a **GET** to
``http://servers.api.openstack.org/v2/1234/servers?limit=1``. In these
@ -73,7 +73,7 @@ JSON. The approach allows for extensibility of paginated collections by
allowing them to be associated with arbitrary properties. It also allows
collections to be embedded in other objects as illustrated below. Here,
a subset of metadata items are presented within the image. Clients must
follow the "next" link to retrieve the full set of metadata.
keep following the ``next`` link to retrieve the full set of metadata.
**Example: Paginated metadata: JSON**
@ -102,4 +102,3 @@ follow the "next" link to retrieve the full set of metadata.
]
}
}

1
api-guide/source/polling_changes-since_parameter.rst
View File

@ -26,4 +26,3 @@ servers contain a ``DELETED`` status that indicates that the resource
has been removed. Implementations are not required to keep track of
deleted resources indefinitely, so sending a changes since time in the
distant past may miss deletions.

81
api-guide/source/server_concepts.rst
View File

@ -15,7 +15,7 @@ help user to understand the difference.
You can filter the list of servers by image, flavor, name, and status
through the respective query parameters.
Servers contain a status attribute that indicates the current server
Server contains 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:
@ -24,7 +24,7 @@ server status is one of the following values:
- ``ACTIVE``: The server is active.
- ``BUILD``: The server has not finished the original build process.
- ``BUILD``: The server has not yet finished the original build process.
- ``DELETED``: The server is deleted.
@ -34,7 +34,7 @@ server status is one of the following values:
pulling the power plug on a physical server, plugging it back in, and
rebooting it.
- ``MIGRATING``: The server is under migrating. This is caused by a
- ``MIGRATING``: The server is migrating. This is caused by a
live migration (moving a server that is active) action.
- ``PASSWORD``: The password is being reset on the server.
@ -61,7 +61,7 @@ server status is one of the following values:
- ``SHELVED_OFFLOADED``: The shelved server is offloaded (removed from the
compute host) and it needs unshelved action to be used again.
- ``SHUTOFF``: The virtual machine (VM) was powered down by the user,
- ``SHUTOFF``: The server 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. If
the OpenStack Compute manager detects that the VM was powered down,
@ -79,8 +79,8 @@ server status is one of the following values:
necessity. This status appears for only the following hypervisors:
XenServer/XCP, KVM, and ESXi. Administrative users may suspend a
server if it is infrequently used or to perform system maintenance.
When you suspend a server, its VM state is stored on disk, all
memory is written to disk, and the virtual machine is stopped.
When you suspend a server, its state is stored on disk, all
memory is written to disk, and the server is stopped.
Suspending a server is similar to placing a device in hibernation;
memory and vCPUs become available to create other servers.
@ -381,7 +381,7 @@ be used and interpreted by nova.
}
Server actions
~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~
- **Reboot**
@ -405,7 +405,7 @@ Server actions
listed in an 'ACTIVE' state forever.
Evacuate is a work around for this that lets an administrator
forceably rebuild these zombie servers on another node. It makes
forcibly rebuild these servers on another node. It makes
no guarantees that the host was actually down, so fencing is
left as an exercise to the deployer.
@ -421,9 +421,9 @@ Server actions
Confirm resize action will delete the old server in the virt layer.
The spawned server in the virt layer will be used from then on.
on the contrary, Revert resize action will delete the new server
spawned in the virt layer and revert all changes, the original server
will still be used from then on.
On the contrary, Revert resize action will delete the new server
spawned in the virt layer and revert all changes. The original server
will be used from then on.
Also, there is a periodic task configured by configuration option
resize_confirm_window(in seconds), if this value is not 0, nova compute
@ -454,7 +454,7 @@ Server actions
You can store the current state of the server root disk to be saved
and uploaded back into the glance image repository.
Then the server can later be booted again using this saved image.
Then a server can later be booted again using this saved image.
- **Backup**
@ -464,11 +464,11 @@ Server actions
- **Start**
Power on an server.
Power on the server.
- **Stop**
Power off an server.
Power off the server.
- **Delete**, **Restore**
@ -486,7 +486,7 @@ Server actions
- **Shelve**, **Shelve offload**, **Unshelve**
Shelving an server indicates it will not be needed for some time and may be
Shelving a server indicates it will not be needed for some time and may be
temporarily removed from the hypervisors. This allows its resources to
be freed up for use by someone else.
@ -494,14 +494,15 @@ Server actions
server will be removed from the hypervisor immediately after shelve operation;
Otherwise, the resource will be kept for the value of 'shelved_offload_time'
(in seconds) so that during the time period the unshelve action will be faster,
then the periodic task will remove the server from hypervisor. Set the option
'shelved_offload_time' to -1 make it never offload.
then the periodic task will remove the server from hypervisor after
'shelved_offload_time' time passes. Set the option 'shelved_offload_time'
to -1 make it never offload.
Shelve will power off the given server and take a snapshot if it is booted
from image. The server can then be offloaded from the compute host and its
resources deallocated. Offloading is done immediately if booted from volume,
but if booted from image the offload can be delayed for some time or
indefinitely, leaving the image on disk and the resources still allocated.
infinitely, leaving the image on disk and the resources still allocated.
Shelve offload is used to explicitly remove a shelved server that has been
left on a host. This action can only be used on a shelved server and is
@ -525,23 +526,23 @@ Server actions
The rescue operation starts a server in a special configuration whereby
it is booted from a special root disk image. This enables the tenant to try
and restore a broken vitrual machine.
and restore a broken guest system.
Unrescue is the reverse action of Rescue, the server spawned from the special
Unrescue is the reverse action of Rescue. The server spawned from the special
root image will be deleted.
- **Set administrator password**
Set the root/administrator password for the given server, it uses an
optional installed agent to inject the administrator password.
Sets the root/administrator password for the given server. It uses an
optionally installed agent to set the administrator password.
- **Migrate**, **Live migrate**
Migrate is usually utilized by administrator, it will move a server to
another host; it utilize the 'resize' action but with same flavor, so during
migration, the server will be power off and rebuilt on another host.
another host; it utilizes the 'resize' action but with same flavor, so during
migration, the server will be powered off and rebuilt on another host.
Live migrate also moves an server from one host to another, but it won't
Live migrate also moves a server from one host to another, but it won't
power off the server in general so the server will not suffer a down time.
Administrators may use this to evacuate servers from a host that needs to
undergo maintenance tasks.
@ -604,7 +605,7 @@ server interface.
Considerations
~~~~~~~~~~~~~~
The maximum limit refers to the number of bytes in the decoded data
- The maximum limit refers to the number of bytes in the decoded data
and not the number of characters in the encoded data.
- The maximum number of file path/content pairs that you can supply is
@ -615,13 +616,13 @@ Considerations
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.
- The file injection might not occur until after the server is built and
booted.
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 (octal 440).
- 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 (octal 440).
Server access addresses
~~~~~~~~~~~~~~~~~~~~~~~
@ -710,19 +711,19 @@ a cloud:
- **Host maintenance**
If a compute host is to be removed from the cloud all its servers
will need to moved to other hosts. In this case it is normal for
will need to be moved to other hosts. In this case it is normal for
the rest of the cloud to absorb the work load, redistributing
the servers by rescheduling them.
To prepare the host it will be disabled so it does not receive
any further servers. Then each server will be migrated to a new
host by cold or live migration, depending on the state of the
server. When complete, the host is free to be removed.
server. When complete, the host is ready to be removed.
- **Rolling updates**
Often it is necessary to perform an update on all compute hosts
that requires them to be rebooted. In this case it is not
which requires them to be rebooted. In this case it is not
strictly necessary to move inactive servers because they
will be available after the reboot. However, active servers would
be impacted by the reboot. Live migration will allow them to
@ -751,7 +752,7 @@ a cloud:
Migrating a server is not normally a choice that is available to
the cloud user because the user is not normally aware of compute
hosts. Management of the cloud and how servers are provisioned
in it is the sole responsibility of the cloud operator.
in it is the responsibility of the cloud operator.
Recover from a failed compute host
----------------------------------
@ -793,7 +794,7 @@ User resizes server to get more resources
Sometimes a user may want to change the flavor of a server, e.g. change
the quantity of cpus, disk, memory or any other resource. This is done
by rebuilding the server with a new flavor. As the server is being
by restarting the server with a new flavor. As the server is being
moved, it is normal to reschedule the server to another host
(although resize to the same host is an option for the operator).
@ -805,12 +806,12 @@ the server is started again.
After the resize operation, when the user is happy their server is
working correctly after the resize, the user calls Confirm Resize.
This deletes the backup server that was kept on the source host.
This deletes the 'before-the-resize' server that was kept on the source host.
Alternatively, the user can call Revert Resize to delete the new
resized server, and restore the back up that was stored on the source
resized server and restore the old that was stored on the source
host. If the user does not manually confirm the resize within a
configured time period, the resize is automatically confirmed, to
free up the space the backup is using on the source host.
free up the space the old is using on the source host.
As with shelving, resize provides the cloud operator with an
opportunity to redistribute work loads across the cloud according

4
api-guide/source/users.rst
View File

@ -48,8 +48,8 @@ a lists of servers for a specific tenant but is not able to perform any
actions on any of them.
Note: this is not attempting to be an exhaustive set of personas that consider
various facets of the different users, but instead aims to be a minimal set of
users, such that we use a consistent terminology throughout this document.
various facets of the different users but instead aims to be a minimal set of
users such that we use a consistent terminology throughout this document.
TODO - could assign names to these users, or similar, to make it more "real".

3
api-guide/source/versions.rst
View File

@ -35,7 +35,7 @@ header and a URI, the URI takes precedence.
Permanent Links
~~~~~~~~~~~~~~~
The MIME type versioning approach allows for the creating of permanent
The MIME type versioning approach allows for creating of permanent
links, because the version scheme is not specified in the URI path:
https://api.servers.openstack.org/224532/servers/123.
@ -111,3 +111,4 @@ The detailed version response contains pointers to both a human-readable
and a machine-processable description of the API service. The
machine-processable description is written in the Web Application
Description Language (WADL).