Usage docs and initial release note for osc-placement
This adds the initial usage docs and a release note for the first set of commands available in what will be the 1.0.0 release for the osc-placement plugin in the Queens series. There are some other changes to the docs layout: * The cliff.sphinxext is used to get the CLI reference. * The README is inlined to the top docs index page. * The usage doc is changed to the user/index.rst format based on the docs.o.o manuals migration spec. * The ordering of the contents is also changed based on the docs.o.o manuals migration spec. * The modindex is removed since it doesn't exist and since there are no python API bindings in this library, we don't need a module index anyway. Depends-On: Id18aab2a95849bc60769f2f81c363c17d049b21f Part of blueprint placement-osc-plugin Change-Id: I552688b9ee32b719a576a7a9ed5e4d5aa31d7b3f
This commit is contained in:
parent
ecef8f4255
commit
5b39d446be
|
@ -0,0 +1,5 @@
|
|||
======================
|
||||
Command Line Reference
|
||||
======================
|
||||
|
||||
.. autoprogram-cliff:: openstack.placement.v1
|
|
@ -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'
|
||||
|
|
|
@ -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`
|
||||
|
||||
|
|
|
@ -1,3 +0,0 @@
|
|||
========
|
||||
Usage
|
||||
========
|
|
@ -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_``.
|
|
@ -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
|
Loading…
Reference in New Issue