Merge "Usage docs and initial release note for osc-placement"

This commit is contained in:
Zuul 2018-01-24 19:27:08 +00:00 committed by Gerrit Code Review
commit c486b1fea9
6 changed files with 150 additions and 8 deletions

5
doc/source/cli/index.rst Normal file
View File

@ -0,0 +1,5 @@
======================
Command Line Reference
======================
.. autoprogram-cliff:: openstack.placement.v1

View File

@ -23,7 +23,8 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx',
'oslosphinx'
'oslosphinx',
'cliff.sphinxext'
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
@ -73,3 +74,6 @@ latex_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
# See: https://docs.openstack.org/cliff/2.6.0/sphinxext.html
autoprogram_cliff_application = 'openstack'

View File

@ -6,20 +6,22 @@
Welcome to osc-placement's documentation!
=========================================
Contents:
.. include:: ../../README.rst
Contents
--------
.. toctree::
:maxdepth: 2
readme
installation
usage
contributing
cli/index
user/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -1,3 +0,0 @@
========
Usage
========

98
doc/source/user/index.rst Normal file
View File

@ -0,0 +1,98 @@
==================
User Documentation
==================
This document describes various usage aspects of the *osc-placement* plugin
including but not limited to command line examples and explanations, references
and microversion usage.
The full Placement API reference can be found here:
https://developer.openstack.org/api-ref/placement/
Microversion usage
------------------
By default, all commands are run with the 1.0 Placement API version. One can
specify a different microversion using the ``--os-placement-api-version``
option, for example::
$ openstack resource provider aggregate list --os-placement-api-version 1.1 dc43b86a-1261-4f8b-8330-28289fe754e3
+--------------------------------------+
| uuid |
+--------------------------------------+
| 42896e0d-205d-4fe3-bd1e-100924931787 |
| 42896e0d-205d-4fe3-bd1e-100924931788 |
+--------------------------------------+
Alternatively, the ``OS_PLACEMENT_API_VERSION`` environment variable can be
set, for example::
$ export OS_PLACEMENT_API_VERSION=1.1
$ openstack resource provider aggregate list dc43b86a-1261-4f8b-8330-28289fe754e3
+--------------------------------------+
| uuid |
+--------------------------------------+
| 42896e0d-205d-4fe3-bd1e-100924931787 |
| 42896e0d-205d-4fe3-bd1e-100924931788 |
+--------------------------------------+
The Placement API version history can be found here:
https://docs.openstack.org/nova/latest/user/placement.html#rest-api-version-history
Examples
--------
This section provides some common examples for command line usage.
To see the list of available commands for resource providers, run::
$ openstack resource -h
Allocations
~~~~~~~~~~~
One can set allocations against a resource provider for a given consumer
multiple ways.
When setting allocations against a single resource provider, it is generally
easiest to use something like::
$ openstack resource provider allocation set 45f4ccf9-36e3-4d13-8c6b-80fd6c66a195 --allocation rp=dc43b86a-1261-4f8b-8330-28289fe754e3,DISK_GB=10,VCPU=1,MEMORY_MB=512
+--------------------------------------+------------+-------------------------------------------------+
| resource_provider | generation | resources |
+--------------------------------------+------------+-------------------------------------------------+
| dc43b86a-1261-4f8b-8330-28289fe754e3 | 9 | {u'VCPU': 1, u'MEMORY_MB': 512, u'DISK_GB': 10} |
+--------------------------------------+------------+-------------------------------------------------+
Alternatively one can set resource allocations against separate providers::
$ openstack resource provider allocation set 45f4ccf9-36e3-4d13-8c6b-80fd6c66a195 --allocation rp=dc43b86a-1261-4f8b-8330-28289fe754e3,VCPU=1,MEMORY_MB=512 --allocation rp=762746bc-de0d-47a7-b47a-a14028643663,DISK_GB=10
+--------------------------------------+------------+---------------------------------+
| resource_provider | generation | resources |
+--------------------------------------+------------+---------------------------------+
| dc43b86a-1261-4f8b-8330-28289fe754e3 | 9 | {u'VCPU': 1, u'MEMORY_MB': 512} |
| 762746bc-de0d-47a7-b47a-a14028643663 | 1 | {u'DISK_GB': 10} |
+--------------------------------------+------------+---------------------------------+
In this scenario, the consumer, 45f4ccf9-36e3-4d13-8c6b-80fd6c66a195, has
VCPU and MEMORY_MB allocations against one provider,
dc43b86a-1261-4f8b-8330-28289fe754e3, and DISK_GB allocations against another
provider, 762746bc-de0d-47a7-b47a-a14028643663.
.. note:: When setting allocations for a consumer, the command overwrites any
existing allocations for that consumer. So if you want to add or
change one resource class allocation but leave other existing
resource class allocations unchanged, you must also specify those
other existing unchanged allocations so they are not removed.
Resource classes
~~~~~~~~~~~~~~~~
There is a standard set of resource classes defined within the Placement
service itself. These standard resource classes cannot be modified.
Users can create and delete *custom* resource classes, which have a name
prefix of ``CUSTOM_``.

View File

@ -0,0 +1,36 @@
---
prelude: |
This is the first major release for the *osc-placement* plugin and includes
a minimal set of command line support for the `Placement API`_.
.. _Placement API: https://docs.openstack.org/nova/latest/user/placement.html
features:
- |
The set of new commands in this release includes::
$ openstack resource -h
Command "resource" matches:
resource class create
resource class delete
resource class list
resource class show
resource provider aggregate list
resource provider aggregate set
resource provider allocation delete
resource provider allocation set
resource provider allocation show
resource provider create
resource provider delete
resource provider inventory class set
resource provider inventory delete
resource provider inventory list
resource provider inventory set
resource provider inventory show
resource provider list
resource provider set
resource provider show
resource provider usage show
See the `Usage`_ documentation for more details and examples.
.. _Usage: https://docs.openstack.org/osc-placement/latest/user/index.html