diff --git a/api-guide/source/conf.py b/api-guide/source/conf.py index 6b0411a3d4fa..632115b1c292 100644 --- a/api-guide/source/conf.py +++ b/api-guide/source/conf.py @@ -31,7 +31,8 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['openstackdocstheme'] +extensions = ['openstackdocstheme', + 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -39,6 +40,9 @@ templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' +# The 'todo' and 'todolist' directive produce output. +todo_include_todos = True + # The encoding of source files. # source_encoding = 'utf-8-sig' diff --git a/api-guide/source/general_info.rst b/api-guide/source/general_info.rst index a32f62849b48..873c81cd7306 100644 --- a/api-guide/source/general_info.rst +++ b/api-guide/source/general_info.rst @@ -112,19 +112,19 @@ In this section we focus on this related to networking. - **Port** - TODO + .. todo:: Add more details. - **Floating IPs, Pools and DNS** - TODO + .. todo:: Add more details. - **Security Groups** - TODO + .. todo:: Add more details. - **Extended Networks** - TODO + .. todo:: Add more details. Administrator Concepts @@ -222,9 +222,9 @@ on compute hosts rather than servers. - **Hosts** Hosts are the *physical machines* that provide the resources for the virtual - servers created in Nova. They run a ``hypervisor`` (see definition below) + servers created in Nova. They run a **hypervisor** (see definition below) that handles the actual creation and management of the virtual servers. - Hosts also run the ``Nova compute service``, which receives requests from + Hosts also run the **Nova compute service**, which receives requests from Nova to interact with the virtual servers on that machine. When compute service receives a request, it calls the appropriate methods of the driver for that hypervisor in order to carry out the request. The driver acts as @@ -282,7 +282,7 @@ Relationship with Volume API Here we discuss about Cinder's API and how Nova users volume UUIDs. -TODO - add more details. +.. todo:: add more details. Relationship with Image API =========================== @@ -290,7 +290,7 @@ Relationship with Image API 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. +.. todo:: add more details. Interactions with neutron and nova-network (deprecated) ======================================================= @@ -302,4 +302,4 @@ 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. -TODO - add more details. +.. todo:: add more details. diff --git a/api-guide/source/index.rst b/api-guide/source/index.rst index 48b5a4383537..cd6901bd6948 100644 --- a/api-guide/source/index.rst +++ b/api-guide/source/index.rst @@ -60,7 +60,7 @@ the following endpoints: * / - list of available versions * /v2 - the first version of the Compute API, uses extensions - (we call this Compute API v2.0) + (we call this Compute API v2.0) * /v2.1 - same API, except uses microversions While this guide concentrates on documenting the v2.1 API, diff --git a/api-guide/source/microversions.rst b/api-guide/source/microversions.rst index 1b202665edf0..b1590123cbc4 100644 --- a/api-guide/source/microversions.rst +++ b/api-guide/source/microversions.rst @@ -27,24 +27,24 @@ There are multiple cases which you can resolve with microversions: - **Older clients with new cloud** -Before using an old client to talk to a newer cloud, the old client can check -the minimum version of microversions to verify whether the cloud is compatible -with the old API. This prevents the old client from breaking with backwards -incompatible API changes. + Before using an old client to talk to a newer cloud, the old client can check + the minimum version of microversions to verify whether the cloud is + compatible with the old API. This prevents the old client from breaking with + backwards incompatible API changes. -Currently the minimum version of microversions is `2.1`, which is a -microversion compatible with the legacy v2 API. That means the legacy v2 API -user doesn't need to worry that their older client software will be broken when -their cloud is upgraded with new versions. And the cloud operator doesn't need -to worry that upgrading their cloud to newer versions will break any user with -older clients that don't expect these changes. + Currently the minimum version of microversions is `2.1`, which is a + microversion compatible with the legacy v2 API. That means the legacy v2 API + user doesn't need to worry that their older client software will be broken + when their cloud is upgraded with new versions. And the cloud operator + doesn't need to worry that upgrading their cloud to newer versions will + break any user with older clients that don't expect these changes. - **User discovery of available features between clouds** -The new features can be discovered by microversions. The user client should -check the microversions firstly, and new features are only enabled when clouds -support. In this way, the user client can work with clouds that have deployed -different microversions simultaneously. + The new features can be discovered by microversions. The user client should + check the microversions firstly, and new features are only enabled when + clouds support. In this way, the user client can work with clouds that have + deployed different microversions simultaneously. Version Discovery ================= @@ -52,7 +52,7 @@ Version Discovery The Version API will return the minimum and maximum microversions. These values are used by the client to discover the API's supported microversion(s). -Requests to '/' will get version info for all endpoints. A response would look +Requests to `/` will get version info for all endpoints. A response would look as follows:: { @@ -86,12 +86,12 @@ as follows:: ] } -"version" is the maximum microversion, "min_version" is the minimum +``version`` is the maximum microversion, ``min_version`` is the minimum microversion. If the value is the empty string, it means this endpoint doesn't support microversions; it is a legacy v2 API endpoint -- for example, the endpoint `http://openstack.example.com/v2/` in the above sample. The endpoint `http://openstack.example.com/v2.1/` supports microversions; the maximum -microversion is '2.14', and the minimum microversion is '2.1'. The client +microversion is `2.14`, and the minimum microversion is `2.1`. The client should specify a microversion between (and including) the minimum and maximum microversion to access the endpoint. @@ -117,20 +117,20 @@ following header to specify the microversion:: This acts conceptually like the "Accept" header. Semantically this means: -* If neither `X-OpenStack-Nova-API-Version` nor `OpenStack-API-Version` +* If neither ``X-OpenStack-Nova-API-Version`` nor ``OpenStack-API-Version`` (specifying `compute`) is provided, act as if the minimum supported microversion was specified. -* If both headers are provided, `OpenStack-API-Version` will be preferred. +* If both headers are provided, ``OpenStack-API-Version`` will be preferred. -* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` is provided, +* If ``X-OpenStack-Nova-API-Version`` or ``OpenStack-API-Version`` is provided, respond with the API at that microversion. If that's outside of the range of microversions supported, return 406 Not Acceptable. -* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` has a value - of ``latest`` (special keyword), act as if maximum was specified. +* If ``X-OpenStack-Nova-API-Version`` or ``OpenStack-API-Version`` has a value + of `latest` (special keyword), act as if maximum was specified. -.. warning:: The ``latest`` value is mostly meant for integration testing and +.. warning:: The `latest` value is mostly meant for integration testing and would be dangerous to rely on in client code since microversions are not following semver and therefore backward compatibility is not guaranteed. Clients should always require a specific microversion but limit what is @@ -149,7 +149,7 @@ the response:: The first header specifies the microversion number of the API which was executed. -The `Vary` header is used as a hint to caching proxies that the response +The ``Vary`` header is used as a hint to caching proxies that the response is also dependent on the microversion and not just the body and query parameters. See :rfc:`2616` section 14.44 for details. diff --git a/api-guide/source/paginated_collections.rst b/api-guide/source/paginated_collections.rst index 08f7d137be68..e817642bf2d1 100644 --- a/api-guide/source/paginated_collections.rst +++ b/api-guide/source/paginated_collections.rst @@ -4,18 +4,18 @@ Paginated collections To reduce load on the service, list operations return a maximum number of items at a time. The maximum number of items returned is determined -by the compute provider. To navigate the collection, the *``limit``* and -*``marker``* parameters can be set in the URI. For example: +by the compute provider. To navigate the collection, the ``limit`` and +``marker`` parameters can be set in the URI. For example: .. code:: ?limit=100&marker=1234 -The *``marker``* parameter is the ID of the last item in the previous +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 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 one that is supported by the deployment +``limit`` parameter sets the page size. Both parameters are optional. If the +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. @@ -25,11 +25,11 @@ implementation does not contain ``previous`` links. The last page in the list does not contain a link to "next" page. The following examples illustrate three pages in a collection of servers. The first page was retrieved through a **GET** to -``http://servers.api.openstack.org/v2.1/servers?limit=1``. In these +`http://servers.api.openstack.org/v2.1/servers?limit=1`. In these examples, the *``limit``* parameter sets the page size to a single item. Subsequent links honor the initial page size. Thus, a client can follow links to traverse a paginated collection without having to input the -*``marker``* parameter. +``marker`` parameter. **Example: Servers collection: JSON (first page)** diff --git a/api-guide/source/polling_changes.rst b/api-guide/source/polling_changes.rst index bef656d39e5c..671ad8943415 100644 --- a/api-guide/source/polling_changes.rst +++ b/api-guide/source/polling_changes.rst @@ -10,10 +10,10 @@ for changes within a specified time. The ``changes-since`` time or ``changes-before`` time is specified as an `ISO 8601 `__ dateTime -(2011-01-24T17:08Z). The form for the timestamp is **CCYY-MM-DDThh:mm:ss**. +(`2011-01-24T17:08Z`). The form for the timestamp is **CCYY-MM-DDThh:mm:ss**. An optional time zone may be written in by appending the form ±hh:mm which describes the timezone as an offset from UTC. When the timezone is -not specified (2011-01-24T17:08), the UTC timezone is assumed. +not specified (`2011-01-24T17:08`), the UTC timezone is assumed. The following situations need to be considered: diff --git a/api-guide/source/server_concepts.rst b/api-guide/source/server_concepts.rst index c3c0d3b3da51..1ddf557e49c9 100644 --- a/api-guide/source/server_concepts.rst +++ b/api-guide/source/server_concepts.rst @@ -59,9 +59,9 @@ server status is one of the following values: - ``SHUTOFF``: The server was powered down by the user, either through the OpenStack Compute API or from within the server. 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, it transitions the - server to the SHUTOFF status. + issued a :command:`shutdown -h` command from within the server. + If the OpenStack Compute manager detects that the VM was powered down, + it transitions the server to the SHUTOFF status. - ``SOFT_DELETED``: The server is marked as deleted but will remain in the cloud for some configurable amount of time. While soft-deleted, an @@ -93,8 +93,8 @@ are exposed to administrators: Refer to :nova-doc:`VM States `. - task_state represents what is happening to the instance at the - current moment. These tasks can be generic, such as 'spawning', or specific, - such as 'block_device_mapping'. These task states allow for a better view into + current moment. These tasks can be generic, such as `spawning`, or specific, + such as `block_device_mapping`. These task states allow for a better view into what a server is doing. Server creation @@ -102,24 +102,28 @@ Server creation Status Transition: -``BUILD`` +- ``BUILD`` -``ACTIVE`` + .. todo:: Add more details. -``ERROR`` (on error) +- ``ACTIVE`` -When you create a server, the 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 returns a progress -attribute (from 0% to 100% complete). The full URL to the newly created -server is returned through the ``Location`` header and is available as a -``self`` and ``bookmark`` link in the server representation. Note that -when creating a server, only the server ID, its links, and the -administrative password are guaranteed to be returned in the request. -You can retrieve additional attributes by performing subsequent **GET** -operations on the server. + .. todo:: Add more details. + +- ``ERROR`` (on error) + + When you create a server, the 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/*{server_id}*, which returns a progress + attribute (from 0% to 100% complete). The full URL to the newly created + server is returned through the ``Location`` header and is available as a + ``self`` and ``bookmark`` link in the server representation. Note that + when creating a server, only the server ID, its links, and the + administrative password are guaranteed to be returned in the request. + You can retrieve additional attributes by performing subsequent **GET** + operations on the server. Server query ~~~~~~~~~~~~ @@ -144,31 +148,33 @@ For different user roles, the user has different query options set: the query options are different from the attribute naming in the servers API response. -.. code:: - Precondition: - there are 2 servers existing in cloud with following info: +Precondition: there are 2 servers existing in cloud with following info:: - "servers": [ - { - "name": "t1", - "locked": "true", - ... - }, - { - "name": "t2", - "locked": "false", - ... - } - ] + { + "servers": [ + { + "name": "t1", + "locked": "true", + ... + }, + { + "name": "t2", + "locked": "false", + ... + } + ] + } - **Example: General user query server with administrator only options** +**Example: General user query server with administrator only options** - Request with non-administrator context: - GET /servers/detail?locked=1 - Note that 'locked' is not returned through API layer +Request with non-administrator context: ``GET /servers/detail?locked=1`` + +Note that ``locked`` is returned through API layer starting from +microversion 2.9. + +Response:: - Response: { "servers": [ { @@ -182,12 +188,12 @@ For different user roles, the user has different query options set: ] } - **Example: Administrator query server with administrator only options** +**Example: Administrator query server with administrator only options** - Request with administrator context: - GET /servers/detail?locked=1 +Request with administrator context: ``GET /servers/detail?locked=1`` + +Response:: - Response: { "servers": [ { @@ -213,14 +219,13 @@ There are also some special query options: - ``all_tenants`` is an administrator query option, which allows the administrator to query the servers in any tenant. -.. code:: - **Example: User query server with special keys changes-since or changes-before** +**Example: User query server with special keys changes-since or changes-before** - Precondition: - GET /servers/detail +Request: ``GET /servers/detail`` + +Response:: - Response: { "servers": [ { @@ -236,9 +241,10 @@ There are also some special query options: ] } - GET /servers/detail?changes-since='2015-12-16T15:55:52Z' +Request: ``GET /servers/detail?changes-since='2015-12-16T15:55:52Z'`` + +Response:: - Response: { { "name": "t2", @@ -247,9 +253,10 @@ There are also some special query options: } } - GET /servers/detail?changes-before='2015-12-16T15:55:52Z' +Request: ``GET /servers/detail?changes-before='2015-12-16T15:55:52Z'`` + +Response:: - Response: { { "name": "t1", @@ -258,9 +265,11 @@ There are also some special query options: } } - GET /servers/detail?changes-since='2015-12-10T15:55:52Z'&changes-before='2015-12-28T15:55:52Z' +Request: +``GET /servers/detail?changes-since='2015-12-10T15:55:52Z'&changes-before='2015-12-28T15:55:52Z'`` + +Response:: - Response: { "servers": [ { @@ -279,15 +288,11 @@ There are also some special query options: There are two kinds of matching in query options: Exact matching and regex matching. -.. code:: +**Example: User query server using exact matching on host** - **Example: User query server using exact matching on host** +Request with administrator context: ``GET /servers/detail`` - Precondition: - Request with administrator context: - GET /servers/detail - - Response: +Response:: { "servers": [ @@ -304,10 +309,9 @@ regex matching. ] } - Request with administrator context: - GET /servers/detail?host=devstack +Request with administrator context: ``GET /servers/detail?host=devstack`` - Response: +Response:: { "servers": [ @@ -319,13 +323,11 @@ regex matching. ] } - **Example: Query server using regex matching on name** +**Example: Query server using regex matching on name** - Precondition: - Request with administrator context: - GET /servers/detail +Request with administrator context: ``GET /servers/detail`` - Response: +Response:: { "servers": [ @@ -348,10 +350,9 @@ regex matching. ] } - Request with administrator context: - GET /servers/detail?name=t1 +Request with administrator context: ``GET /servers/detail?name=t1`` - Response: +Response:: { "servers": [ @@ -370,14 +371,12 @@ regex matching. ] } - **Example: User query server using exact matching on host and - regex matching on name** +**Example: User query server using exact matching on host and regex +matching on name** - Precondition: - Request with administrator context: - GET /servers/detail +Request with administrator context: ``GET /servers/detail`` - Response: +Response:: { "servers": [ @@ -399,10 +398,10 @@ regex matching. ] } - Request with administrator context: - GET /servers/detail?host=devstack1&name=test +Request with administrator context: +``GET /servers/detail?host=devstack1&name=test`` - Response: +Response:: { "servers": [ @@ -414,16 +413,10 @@ regex matching. ] } - "name": "t2", - "updated": "2015-12-17T15:55:52Z" - ... - } - ] - } +Request: ``GET /servers/detail?changes-since='2015-12-16T15:55:52Z'`` - GET /servers/detail?changes-since='2015-12-16T15:55:52Z' +Response:: - Response: { { "name": "t2", @@ -635,7 +628,7 @@ limit. Block Device Mapping ~~~~~~~~~~~~~~~~~~~~ -TODO: Add some description about BDM. +.. todo:: Add some description about BDM. Scheduler Hints ~~~~~~~~~~~~~~~ @@ -706,7 +699,7 @@ assigned at creation time. **Example: Create server with access IP: JSON request** -.. code:: +.. code-block:: json { "server": { @@ -724,7 +717,7 @@ assigned at creation time. **Example: Create server with multiple access IPs: JSON request** -.. code:: +.. code-block:: json { "server": { @@ -803,7 +796,7 @@ a cloud: This process can be repeated until the whole cloud has been updated, usually using a pool of empty hosts instead of just one. -- **Resource Optimization** +- **Resource Optimization** To reduce energy usage, some cloud operators will try and move servers so they fit into the minimum number of hosts, allowing diff --git a/api-guide/source/users.rst b/api-guide/source/users.rst index 7128a5ac66f0..e09cbb6d1623 100644 --- a/api-guide/source/users.rst +++ b/api-guide/source/users.rst @@ -27,7 +27,7 @@ Keystone middleware is used to authenticate users and identify their roles. The Compute API uses these roles, along with oslo.policy, to decide what the user is authorized to do. -TODO - link to compute admin guide for details. +.. todo:: link to compute admin guide for details. Personas used in this guide =========================== @@ -47,11 +47,15 @@ cloud administrator permissions, such as a read-only role that is able to view 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. +.. note:: -TODO - could assign names to these users, or similar, to make it more "real". + 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. + +.. todo:: + + could assign names to these users, or similar, to make it more "real". Discovering Policy ================== @@ -59,4 +63,4 @@ Discovering Policy An API to discover what actions you are authorized to perform is still a work in progress. Currently this reported by a HTTP 403 error. -TODO - link to the doc on errors. +.. todo:: link to the doc on errors. diff --git a/api-guide/source/versions.rst b/api-guide/source/versions.rst index ee8ce9fed6c7..fdb1ffe217fc 100644 --- a/api-guide/source/versions.rst +++ b/api-guide/source/versions.rst @@ -4,8 +4,8 @@ Versions The OpenStack Compute API uses both a URI and a MIME type versioning scheme. In the URI scheme, the first element of the path contains the -target version identifier (e.g. https://servers.api.openstack.org/ -v2.1/...). The MIME type versioning scheme uses HTTP content negotiation +target version identifier (e.g. `https://servers.api.openstack.org/ +v2.1/`...). The MIME type versioning scheme uses HTTP content negotiation where the ``Accept`` or ``Content-Type`` headers contains a MIME type that identifies the version (application/vnd.openstack.compute.v2.1+json). A version MIME type is always linked to a base MIME type, such as @@ -37,7 +37,7 @@ Permanent Links 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. +`https://api.servers.openstack.org/224532/servers/123`. If a request is made without a version specified in the URI or via HTTP headers, then a multiple-choices response (300) follows that provides @@ -99,12 +99,12 @@ everything following that truncated) returned from the authentication system. You can also obtain additional information about a specific version by performing a **GET** on the base version URL (such as, -``https://servers.api.openstack.org/v2.1/``). Version request URLs must -always end with a trailing slash (``/``). If you omit the slash, the +`https://servers.api.openstack.org/v2.1/`). Version request URLs must +always end with a trailing slash (`/`). If you omit the slash, the server might respond with a 302 redirection request. For examples of the list versions and get version details requests and -responses, see `*API versions* +responses, see `API versions `__. The detailed version response contains pointers to both a human-readable