Update docs for plugins and release notes
* Fill out the existing command and man page * Add a plugins page. * Begin the release notes for 0.3.0 Change-Id: I4527fed28a10a9d79fc8f6c1d925a4bf0d0a7a36
This commit is contained in:
Dean Troyer
parent
e06e1a2cce
commit
4f1ebe8069
@ -10,15 +10,24 @@ OpenStackClient has a consistent and predictable format for all of its commands.
|
||||
|
||||
Commands take the form::
|
||||
|
||||
openstack [<global-options>] <object> <action> [<second-object>] [<command-arguments>]
|
||||
openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>]
|
||||
|
||||
* All long options names begin with two dashes ('--') and use a single dash ('-') internally between words (--like-this)
|
||||
* All long options names begin with two dashes ('--') and use a single dash
|
||||
('-') internally between words (--like-this). Underscores ('_') are not used
|
||||
in option names.
|
||||
|
||||
|
||||
Global Options
|
||||
--------------
|
||||
|
||||
Global options are global in the sense that the apply to every command invocation regardless of action to be performed. This includes authentication credentials and API version selection. Most global options have a corresponding environment variable that may also be used to set the value. If both are present, the command-line option takes priority. The environment variable names are derived from the option name by dropping the leading dashes ('--'), converting each embedded dash ('-') to an underscore ('_'), and converting to upper case.
|
||||
Global options are global in the sense that they apply to every command
|
||||
invocation regardless of action to be performed. They include authentication
|
||||
credentials and API version selection. Most global options have a corresponding
|
||||
environment variable that may also be used to set the value. If both are
|
||||
present, the command-line option takes priority. The environment variable
|
||||
names are derived from the option name by dropping the leading dashes ('--'),
|
||||
converting each embedded dash ('-') to an underscore ('_'), and converting
|
||||
to upper case.
|
||||
|
||||
For example, ``--os-username`` can be set from the environment via ``OS_USERNAME``.
|
||||
|
||||
@ -26,9 +35,12 @@ For example, ``--os-username`` can be set from the environment via ``OS_USERNAME
|
||||
Command Object(s) and Action
|
||||
----------------------------
|
||||
|
||||
Commands consist of an object described by one or more words followed by an action.
|
||||
In commands requiring two objects be acted upon, the primary object appears ahead of the action and the secondary object appears after the action.
|
||||
If both objects have cooresponding positional arguments the arguments appear in the same order as the objects. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)."
|
||||
Commands consist of an object described by one or more words followed by
|
||||
an action. Commands that require two objects have the primary object ahead
|
||||
of the action and the secondary object after the action. Any positional
|
||||
arguments identifying the objects shall appear in the same order as the
|
||||
objects. In badly formed English it is expressed as "(Take) object1
|
||||
(and perform) action (using) object2 (to it)."
|
||||
|
||||
::
|
||||
|
||||
@ -44,22 +56,23 @@ Examples::
|
||||
Command Arguments and Options
|
||||
-----------------------------
|
||||
|
||||
Commands have their own set of options distinct from the global options. They follow the
|
||||
same style as the global options and always appear between the command and any positional arguemnts the command may require.
|
||||
Each command may have its own set of options distinct from the global options.
|
||||
They follow the same style as the global options and always appear between
|
||||
the command and any positional arguments the command requires.
|
||||
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
The command structure is designed to support seamless addition of extension
|
||||
command modules via entry points. The extensions are assumed to be subclasses
|
||||
of Cliff's command.Command object.
|
||||
The command structure is designed to support seamless addition of plugin
|
||||
command modules via ``setuptools`` entry points. The plugin commands must
|
||||
be subclasses of Cliff's command.Command object.
|
||||
|
||||
|
||||
Command Entry Points
|
||||
--------------------
|
||||
|
||||
Commands are added to the client using setuptools's entry points in ``setup.cfg``.
|
||||
Commands are added to the client using ``setuptools`` entry points in ``setup.cfg``.
|
||||
There is a single common group ``openstack.cli`` for commands that are not versioned,
|
||||
and a group for each combination of OpenStack API and version that is
|
||||
supported. For example, to support Identity API v3 there is a group called
|
||||
|
||||
@ -12,6 +12,7 @@ Contents:
|
||||
|
||||
releases
|
||||
commands
|
||||
plugins
|
||||
man/openstack
|
||||
|
||||
Getting Started
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
=========
|
||||
====================
|
||||
:program:`openstack`
|
||||
=========
|
||||
====================
|
||||
|
||||
OpenStack Command Line
|
||||
|
||||
SYNOPSIS
|
||||
========
|
||||
@ -10,6 +11,7 @@ SYNOPSIS
|
||||
|
||||
:program:`openstack help` <command>
|
||||
|
||||
:program:`openstack` --help
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
@ -21,9 +23,8 @@ a distinct and consistent command structure.
|
||||
|
||||
:program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with
|
||||
the credential information supplied either as environment variables or as options on the
|
||||
command line. The primary difference is a preference for using
|
||||
``OS_PROJECT_NAME``/``OS_PROJECT_ID`` over the old tenant-based names. The old names work
|
||||
for now though.
|
||||
command line. The primary difference is the use of 'project' in the name of the options
|
||||
``OS_PROJECT_NAME``/``OS_PROJECT_ID`` over the old tenant-based names.
|
||||
|
||||
::
|
||||
|
||||
@ -57,7 +58,22 @@ OPTIONS
|
||||
Authentication region name
|
||||
|
||||
:option:`--os-default-domain <auth-domain>`
|
||||
Default domain ID (defaults to 'default')
|
||||
Default domain ID (Default: 'default')
|
||||
|
||||
:options:`--os-use-keyring`
|
||||
Use keyring to store password (default: False)
|
||||
|
||||
:option:`--os-cacert <ca-bundle-file>`
|
||||
CA certificate bundle file
|
||||
|
||||
:option:`--verify|--insecure`
|
||||
Verify or ignore server certificate (default: verify)
|
||||
|
||||
:option:`--os-identity-api-version <identity-api-version>`
|
||||
Identity API version (Default: 2.0)
|
||||
|
||||
:option:`--os-XXXX-api-version <XXXX-api-version>`
|
||||
Additional API version options will be presend depending on the installed API libraries.
|
||||
|
||||
|
||||
NOTES
|
||||
@ -78,6 +94,35 @@ To get a description of a specific command::
|
||||
openstack help <command>
|
||||
|
||||
|
||||
:option:`complete`
|
||||
Print the bash completion functions for the current command set.
|
||||
|
||||
:option:`help <command>`
|
||||
Print help for an individual command
|
||||
|
||||
|
||||
EXAMPLES
|
||||
========
|
||||
|
||||
Show the detailed information for server ``appweb01``::
|
||||
|
||||
openstack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 server show appweb01
|
||||
|
||||
The same command if the auth environment variables (:envvar:`OS_AUTH_URL`, :envvar:`OS_PROJECT_NAME`,
|
||||
:envvar:`OS_USERNAME`, :envvar:`OS_PASSWORD`) are set::
|
||||
|
||||
openstack server show appweb01
|
||||
|
||||
Create a new image::
|
||||
|
||||
openstack image create \
|
||||
--disk-format=qcow2 \
|
||||
--container-format=bare \
|
||||
--public \
|
||||
--copy-from http://somewhere.net/foo.img \
|
||||
foo
|
||||
|
||||
|
||||
FILES
|
||||
=====
|
||||
|
||||
@ -95,6 +140,12 @@ The following environment variables can be set to alter the behaviour of :progra
|
||||
:envvar:`OS_PASSWORD`
|
||||
Set the password
|
||||
|
||||
:envvar:`OS_PROJECT_NAME`
|
||||
Set the project name
|
||||
|
||||
:envvar:`OS_AUTH_URL`
|
||||
Set the authentication URL
|
||||
|
||||
|
||||
BUGS
|
||||
====
|
||||
@ -124,4 +175,8 @@ http://www.apache.org/licenses/LICENSE-2.0
|
||||
SEE ALSO
|
||||
========
|
||||
|
||||
The OpenStack project CLIs, the OpenStack API references. <links TBD>
|
||||
The `OpenStackClient page <https://wiki.openstack.org/wiki/OpenStackClient>`_
|
||||
in the `OpenStack Wiki <https://wiki.openstack.org/>`_ contains further
|
||||
documentation.
|
||||
|
||||
The individual OpenStack project CLIs, the OpenStack API references.
|
||||
|
||||
46
doc/source/plugins.rst
Normal file
46
doc/source/plugins.rst
Normal file
@ -0,0 +1,46 @@
|
||||
=======
|
||||
Plugins
|
||||
=======
|
||||
|
||||
The OpenStackClient plugin system is designed so that the plugin need only be
|
||||
properly installed for OSC to find and use it. It utilizes the
|
||||
``setuptools`` entry points mechanism to advertise to OSC the
|
||||
plugin module and supported commands.
|
||||
|
||||
Implementation
|
||||
--------------
|
||||
|
||||
Plugins are discovered by enumerating the entry points
|
||||
found under ``openstack.cli.extension`` and initializing the specified
|
||||
client module.
|
||||
|
||||
::
|
||||
|
||||
[entry_points]
|
||||
openstack.cli.extension =
|
||||
oscplugin = oscplugin.client
|
||||
|
||||
The client module must implement the following interface functions:
|
||||
|
||||
* ``API_NAME`` - A string containing the plugin API name; this is
|
||||
the name of the entry point declaring the plugin client module
|
||||
(``oscplugin = ...`` in the example above) and the group name for
|
||||
the plugin commands (``openstack.oscplugin.v1 =`` in the example below)
|
||||
* ``API_VERSION_OPTION`` (optional) - If set, the name of the API
|
||||
version attribute; this must be a valid Python identifier and
|
||||
match the destination set in ``build_option_parser()``.
|
||||
* ``API_VERSIONS`` - A dict mapping a version string to the client class
|
||||
* ``build_option_parser(parser)`` - Hook to add global options to the parser
|
||||
* ``make_client(instance)`` - Hook to create the client object
|
||||
|
||||
OSC enumerates the plugin commands from the entry points in the usual manner
|
||||
defined for the API version:
|
||||
|
||||
::
|
||||
|
||||
openstack.oscplugin.v1 =
|
||||
plugin_list = oscplugin.v1.plugin:ListPlugin
|
||||
plugin_show = oscplugin.v1.plugin:ShowPlugin
|
||||
|
||||
Note that OSC defines the group name as ``openstack.<api-name>.v<version>``
|
||||
so the version should not contain the leading 'v' character.
|
||||
@ -2,6 +2,18 @@
|
||||
Release Notes
|
||||
=============
|
||||
|
||||
0.3.0 (xx Dec 2013)
|
||||
===================
|
||||
|
||||
* add new command plugin structure
|
||||
* complete converting base test classes
|
||||
* add options to support TLS cetificate verification
|
||||
* add object-store show commands for container and object
|
||||
|
||||
.. commented to save format of bug fix
|
||||
.. * 1254168_: OS_REGION_NAME is not used
|
||||
.. _1254168: https://bugs.launchpad.net/python-openstackclient/+bug/1254168
|
||||
|
||||
0.2.2 (20 Sep 2013)
|
||||
===================
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user