openstack/python-openstackclient
Code Issues Proposed changes

Update docs and release notes for 0.4.1 release

Browse Source 
Closes-Bug: 1365505
Change-Id: I027d263ba9980715454b034a37733c5ff23fd169
This commit is contained in:
Dean Troyer 2014-09-06 14:32:47 -05:00
parent b7816f3997
commit f7357b7fe7
5 changed files with 194 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
doc/source/commands.rst
View File

@ -62,6 +62,54 @@ They follow the same style as the global options and always appear between
the command and any positional arguments the command requires.
Objects
-------
The objects consist of one or more words to compose a unique name.
Occasionally when multiple APIs have a common name with common
overlapping purposes there will be options to select which object to use, or
the API resources will be merged, as in the ``quota`` object that has options
referring to both Compute and Volume quotas.
* ``access token``: Identity - long-lived OAuth-based token
* ``aggregate``: Compute - a grouping of servers
* ``backup``: Volume - a volume copy
* ``console log``: Compute - a text dump of a server's console
* ``console url``: Compute - a URL to a server's remote console
* ``consumer``: Identity - OAuth-based delegatee
* ``container``: Object Store - a grouping of objects
* ``credential``: Identity - specific to identity providers
* ``domain``: Identity - a grouping of projects
* ``endpoint``: Identity - the base URL used to contact a specific service
* ``extension``: Compute, Identity, Volume - additional APIs available
* ``flavor``: Compute - pre-defined configurations of servers: ram, root disk, etc
* ``group``: Identity - a grouping of users
* ``host``: Compute - the physical computer running a hypervisor
* ``hypervisor``: Compute - the virtual machine manager
* ``identity provider``: Identity - a source of users and authentication
* ``image``: Image - a disk image
* ``ip fixed``: Compute, Network - an internal IP address assigned to a server
* ``ip floating``: Compute, Network - a public IP address that can be mapped to a server
* ``keypair``: Compute - an SSH public key
* ``limits``: Compute, Volume - resource usage limits
* ``module``: internal - installed Python modules in the OSC process
* ``network``: Network - a virtual network for connecting servers and other resources
* ``object``: Object Store - a single file in the Object Store
* ``policy``: Identity - determines authorization
* ``project``: Identity - the owner of a group of resources
* ``quota``: Compute, Volume - limit on resource usage
* ``request token``: Identity - temporary OAuth-based token
* ``role``: Identity - a policy object used to determine authorization
* ``security group``: Compute, Network - groups of network access rules
* ``security group rule``: Compute, Network - the individual rules that define protocol/IP/port access
* ``server``: Compute - a virtual machine instance
* ``service``: Identity - a cloud service
* ``snapshot``: Volume - a point-in-time copy of a volume
* ``token``: Identity - the magic text used to determine access
* ``user``: Identity - individuals using cloud resources
* ``volume``: Volume - block volumes
* ``volume type``: Volume - deployment-specific types of volumes available
Actions
-------
@ -103,7 +151,7 @@ Implementation
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. See :doc:`plugins` for
be subclasses of Cliff's ``command.Command`` object. See :doc:`plugins` for
more information.
@ -117,7 +165,7 @@ supported. For example, to support Identity API v3 there is a group called
``openstack.identity.v3`` that contains the individual commands. The command
entry points have the form::
verb_object = fully.qualified.module.vXX.object:VerbObject
action_object = fully.qualified.module.vXX.object:ActionObject
For example, the ``list user`` command for the Identity API is identified in
``setup.cfg`` with::

5
doc/source/index.rst
View File

@ -3,9 +3,8 @@ OpenStackClient
===============
OpenStackClient (aka OSC) is a command-line client for OpenStack that
unifies the operation
of python-keystoneclient, python-novaclient, python-glanceclient and
python-cinderclient in a single shell with a uniform command structure.
brings the command set for Compute, Identity, Image, Object Store and Volume
APIs together in a single shell with a uniform command structure.
Contents:

68
doc/source/man/openstack.rst
View File

@ -56,18 +56,24 @@ OPTIONS
:option:`--os-username` <auth-username>
Authentication username
:option:`--os-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
Domain name or id containing user
:option:`--os-password` <auth-password>
Authentication password
:option:`--os-region-name` <auth-region-name>
Authentication region name
:option:`--os-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
Domain name or id containing user
:option:`--os-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
Domain name or ID containing user
:option:`--os-trust-id` <trust-id>
id of the trust to use as a trustee user
:option:`--os-default-domain` <auth-domain>
Default domain ID (Default: 'default')
:option:`--os-region-name` <auth-region-name>
Authentication region name
:option:`--os-cacert` <ca-bundle-file>
CA certificate bundle file
@ -80,9 +86,6 @@ OPTIONS
:option:`--os-XXXX-api-version` <XXXX-api-version>
Additional API version options will be available depending on the installed API libraries.
:option:`--os-trust-id` <trust-id>
id of the trust to use as a trustee user
COMMANDS
========
@ -94,6 +97,11 @@ To get a description of a specific command::
openstack help <command>
Note that the set of commands shown will vary depending on the API versions
that are in effect at that time. For example, to force the display of the
Identity v3 commands:
openstack --os-identity-api-version 3 --help
:option:`complete`
Print the bash completion functions for the current command set.
@ -101,6 +109,25 @@ To get a description of a specific command::
:option:`help <command>`
Print help for an individual command
Additional information on the OpenStackClient command structure and arguments
is available in the `OpenStackClient Commands`_ wiki page.
.. _`OpenStackClient Commands`: https://wiki.openstack.org/wiki/OpenStackClient/Commands
Command Objects
---------------
The list of command objects is growing longer with the addition of OpenStack
project support. The object names may consist of multiple words to compose a
unique name. Occasionally when multiple APIs have a common name with common
overlapping purposes there will be options to select which object to use, or
the API resources will be merged, as in the ``quota`` object that has options
referring to both Compute and Volume quotas.
Command Actions
---------------
The actions used by OpenStackClient are defined with specific meaning to provide a consistent behavior for each object. Some actions have logical opposite actions, and those pairs will always match for any object that uses them.
NOTES
=====
@ -162,39 +189,30 @@ The following environment variables can be set to alter the behaviour of :progra
:envvar:`OS_USERNAME`
Authentication username
:envvar:`OS_USER_DOMAIN_NAME`
Domain name or id containing user
:envvar:`OS_PASSWORD`
Authentication password
:envvar:`OS_REGION_NAME`
Authentication region name
:envvar:`OS_USER_DOMAIN_NAME`
Domain name or id containing user
:envvar:`OS_TRUST_ID`
id of the trust to use as a trustee user
:envvar:`OS_DEFAULT_DOMAIN`
Default domain ID (Default: 'default')
:envvar:`OS_REGION_NAME`
Authentication region name
:envvar:`OS_CACERT`
CA certificate bundle file
:envvar:`OS_COMPUTE_API_VERSION`
Compute API version (Default: 2)
:envvar:`OS_IDENTITY_API_VERSION`
Identity API version (Default: 2.0)
:envvar:`OS_IMAGE_API_VERSION`
Image API version (Default: 1)
:envvar:`OS_VOLUME_API_VERSION`
Volume API version (Default: 1)
:envvar:`OS_XXXX_API_VERSION`
Additional API version options will be available depending on the installed API libraries.
:envvar:`OS_TRUST_ID`
id of the trust to use as a trustee user
BUGS
====

55
doc/source/plugins.rst
View File

@ -20,7 +20,7 @@ client module.
openstack.cli.extension =
oscplugin = oscplugin.client
The client module must implement the following interface functions:
The client module must define the following top-level variables:
* ``API_NAME`` - A string containing the plugin API name; this is
the name of the entry point declaring the plugin client module
@ -30,6 +30,9 @@ The client module must implement the following interface functions:
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
The client module must implement the following interface functions:
* ``build_option_parser(parser)`` - Hook to add global options to the parser
* ``make_client(instance)`` - Hook to create the client object
@ -44,3 +47,53 @@ defined for the API version:
Note that OSC defines the group name as :py:mod:`openstack.<api-name>.v<version>`
so the version should not contain the leading 'v' character.
::
DEFAULT_OSCPLUGIN_API_VERSION = '1'
# Required by the OSC plugin interface
API_NAME = 'oscplugin'
API_VERSION_OPTION = 'os_oscplugin_api_version'
API_VERSIONS = {
'1': 'oscplugin.v1.client.Client',
}
# Required by the OSC plugin interface
def make_client(instance):
"""Returns a client to the ClientManager
Called to instantiate the requested client version. instance has
any available auth info that may be required to prepare the client.
:param ClientManager instance: The ClientManager that owns the new client
"""
plugin_client = utils.get_client_class(
API_NAME,
instance._api_version[API_NAME],
API_VERSIONS)
client = plugin_client()
return client
# Required by the OSC plugin interface
def build_option_parser(parser):
"""Hook to add global options
Called from openstackclient.shell.OpenStackShell.__init__()
after the builtin parser has been initialized. This is
where a plugin can add global options such as an API version setting.
:param argparse.ArgumentParser parser: The parser object that has been
initialized by OpenStackShell.
"""
parser.add_argument(
'--os-oscplugin-api-version',
metavar='<oscplugin-api-version>',
default=utils.env(
'OS_OSCPLUGIN_API_VERSION',
default=DEFAULT_OSCPLUGIN_API_VERSION),
help='OSC Plugin API version, default=' +
DEFAULT_OSCPLUGIN_API_VERSION +
' (Env: OS_OSCPLUGIN_API_VERSION)')
return parser

45
doc/source/releases.rst
View File

@ -2,6 +2,51 @@
Release Notes
=============
0.4.1 (08 Sep 2014)
===================
* Bug 1319381_: remove insecure keyring support
* Bug 1317478_: fix ``project create`` for domain admin
* Bug 1317485_: fix ``project list`` for domain admins
* Bug 1281888_: add region filter to ``endpoint list`` command
* Bug 1337245_: add ``user password set`` command
* Bug 1337684_: add ``extension list --compute``
* Bug 1337687_: add ``extension list --volume``
* Bug 1343658_: fix ``container list`` command
* Bug 1343659_: add network command help text
* Bug 1348475_: add fields to ``image list`` output
* Bug 1351121_: v3 ``endpoint set`` should not require service option
* Bug 1352119_: v2 ``user create`` response error
* Bug 1353788_: test_file_resource() failure
* Bug 1364540_: load_keyring() exception fixed in bug 1319381_
* Bug 1365505_: domain information not in help output
* fix ``security group list`` for non-admin
* fix ``server add security group``
* add ``container create`` and ``container delete`` commands
* add ``object create`` and ``object delete`` commands
* add initial support for global ``--timing`` options (similar to nova CLI)
* complete Python 3 compatibility
* fix ``server resize` command
* add authentication via ``--os-trust-id`` for Identity v3
* Add initial support for Network API, ``network create|delete|list|show``
.. _1319381: https://bugs.launchpad.net/bugs/1319381
.. _1317478: https://bugs.launchpad.net/bugs/1317478
.. _1317485: https://bugs.launchpad.net/bugs/1317485
.. _1281888: https://bugs.launchpad.net/bugs/1281888
.. _1337245: https://bugs.launchpad.net/bugs/1337245
.. _1337684: https://bugs.launchpad.net/bugs/1337684
.. _1337687: https://bugs.launchpad.net/bugs/1337687
.. _1343658: https://bugs.launchpad.net/bugs/1343658
.. _1343659: https://bugs.launchpad.net/bugs/1343659
.. _1348475: https://bugs.launchpad.net/bugs/1348475
.. _1351121: https://bugs.launchpad.net/bugs/1351121
.. _1352119: https://bugs.launchpad.net/bugs/1352119
.. _1353788: https://bugs.launchpad.net/bugs/1353788
.. _1364540: https://bugs.launchpad.net/bugs/1364540
.. _1365505: https://bugs.launchpad.net/bugs/1365505
0.4.0 (20 Jun 2014)
===================