From f7357b7fe78b7d7afe099a867d1dca14b19f8bc1 Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Sat, 6 Sep 2014 14:32:47 -0500 Subject: [PATCH] Update docs and release notes for 0.4.1 release Closes-Bug: 1365505 Change-Id: I027d263ba9980715454b034a37733c5ff23fd169 --- doc/source/commands.rst | 52 +++++++++++++++++++++++++-- doc/source/index.rst | 5 ++- doc/source/man/openstack.rst | 68 +++++++++++++++++++++++------------- doc/source/plugins.rst | 55 ++++++++++++++++++++++++++++- doc/source/releases.rst | 45 ++++++++++++++++++++++++ 5 files changed, 194 insertions(+), 31 deletions(-) diff --git a/doc/source/commands.rst b/doc/source/commands.rst index a9d10c96d3..45e73a0594 100644 --- 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 index 2bb8f3868b..569a5aa1b2 100644 --- 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 index 9af1c42513..b8dcbd6b66 100644 --- a/doc/source/man/openstack.rst +++ b/doc/source/man/openstack.rst @@ -56,18 +56,24 @@ OPTIONS :option:`--os-username` Authentication username -:option:`--os-user-domain-name` | :option:`--os-user-domain-id` - Domain name or id containing user - :option:`--os-password` Authentication password -:option:`--os-region-name` - Authentication region name +:option:`--os-user-domain-name` | :option:`--os-user-domain-id` + Domain name or id containing user + +:option:`--os-user-domain-name` | :option:`--os-user-domain-id` + Domain name or ID containing user + +:option:`--os-trust-id` + id of the trust to use as a trustee user :option:`--os-default-domain` Default domain ID (Default: 'default') +:option:`--os-region-name` + Authentication region name + :option:`--os-cacert` CA certificate bundle file @@ -80,9 +86,6 @@ OPTIONS :option:`--os-XXXX-api-version` Additional API version options will be available depending on the installed API libraries. -:option:`--os-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 +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 ` 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 index 690c1269c8..3b35ec08e8 100644 --- 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..v` 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='', + 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 index 9551db2ee0..89b4ad111e 100644 --- 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) ===================