From fdd8f0f91ede06814e3537206234224e9f982e35 Mon Sep 17 00:00:00 2001 From: Waldemar Znoinski Date: Mon, 15 Feb 2016 14:42:02 +0000 Subject: [PATCH] Fix API Guide doc * typos * reduntant words * reworded sentences for clarity Closes-bug: #1545748 Change-Id: I0700d04de38b34cf13988490873b8c34dad1005b --- api-guide/source/faults.rst | 18 ++--- api-guide/source/general_info.rst | 67 +++++++-------- api-guide/source/index.rst | 2 +- api-guide/source/limits.rst | 4 +- api-guide/source/links_and_references.rst | 4 +- api-guide/source/paginated_collections.rst | 9 +-- .../polling_changes-since_parameter.rst | 1 - api-guide/source/server_concepts.rst | 81 ++++++++++--------- api-guide/source/users.rst | 4 +- api-guide/source/versions.rst | 3 +- 10 files changed, 97 insertions(+), 96 deletions(-) diff --git a/api-guide/source/faults.rst b/api-guide/source/faults.rst index 0f10fa43509b..29bb677013e6 100644 --- a/api-guide/source/faults.rst +++ b/api-guide/source/faults.rst @@ -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. diff --git a/api-guide/source/general_info.rst b/api-guide/source/general_info.rst index 4593d4e8d40a..2855f261f079 100644 --- a/api-guide/source/general_info.rst +++ b/api-guide/source/general_info.rst @@ -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. diff --git a/api-guide/source/index.rst b/api-guide/source/index.rst index 9e7d2ca4f472..194bdc361c80 100644 --- a/api-guide/source/index.rst +++ b/api-guide/source/index.rst @@ -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 ============ diff --git a/api-guide/source/limits.rst b/api-guide/source/limits.rst index 8229d5ee5b2d..5208892a983d 100644 --- a/api-guide/source/limits.rst +++ b/api-guide/source/limits.rst @@ -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* `__. @@ -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 diff --git a/api-guide/source/links_and_references.rst b/api-guide/source/links_and_references.rst index 20676aac847a..1e57b7dda5cc 100644 --- a/api-guide/source/links_and_references.rst +++ b/api-guide/source/links_and_references.rst @@ -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** diff --git a/api-guide/source/paginated_collections.rst b/api-guide/source/paginated_collections.rst index e72c3ed7ce87..f3c2c78a2d04 100644 --- a/api-guide/source/paginated_collections.rst +++ b/api-guide/source/paginated_collections.rst @@ -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. ] } } - diff --git a/api-guide/source/polling_changes-since_parameter.rst b/api-guide/source/polling_changes-since_parameter.rst index cacf9eecb32c..7354ccf22f91 100644 --- a/api-guide/source/polling_changes-since_parameter.rst +++ b/api-guide/source/polling_changes-since_parameter.rst @@ -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. - diff --git a/api-guide/source/server_concepts.rst b/api-guide/source/server_concepts.rst index d836debd2bfd..521c81e9c4cb 100644 --- a/api-guide/source/server_concepts.rst +++ b/api-guide/source/server_concepts.rst @@ -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 diff --git a/api-guide/source/users.rst b/api-guide/source/users.rst index 2a6ca53506ec..7128a5ac66f0 100644 --- a/api-guide/source/users.rst +++ b/api-guide/source/users.rst @@ -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". diff --git a/api-guide/source/versions.rst b/api-guide/source/versions.rst index 9399044b44c4..2237eb5d7c3f 100644 --- a/api-guide/source/versions.rst +++ b/api-guide/source/versions.rst @@ -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). +