Update docs and release notes for 0.4.1 release

Dean Troyer · Dean Troyer · commit f7357b7fe78b · 2014-09-08T11:36:33.000-05:00
Closes-Bug: 1365505
Change-Id: I027d263ba9980715454b034a37733c5ff23fd169
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
@@ -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::
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -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:
 
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
@@ -56,18 +56,24 @@ OPTIONS
 :option:`--os-username` <auth-username>
     Authentication username
 
+:option:`--os-password` <auth-password>
+    Authentication password
+
 :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-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
+    Domain name or ID containing user
 
-:option:`--os-region-name` <auth-region-name>
-    Authentication region name
+: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,13 +97,37 @@ 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.
 
 :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
 ====
 
diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
@@ -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
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
@@ -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)
 ===================
 
