openstack/python-openstackclient
Code Issues Proposed changes

Update release notes for 0.3.1

Browse Source 
* update README
* update man page
* fix doc errors

Change-Id: I5682654bf482289879c8ba9016e348f2b2782971
This commit is contained in:
Dean Troyer 2014-02-21 12:46:07 -06:00
parent 2cae50c442
commit 038269cf7f
4 changed files with 151 additions and 57 deletions

40
README.rst

@ -2,8 +2,9 @@
OpenStack Client
================
python-openstackclient is a unified command-line client for the OpenStack APIs.
It is a thin wrapper to the stock python-*client modules that implement the
OpenStackclient (aka ``python-openstackclient``) is a command-line client for
the OpenStack APIs.
It is primarily a wrapper to the stock python-*client modules that implement the
actual REST API client actions.
This is an implementation of the design goals shown in
@ -14,8 +15,7 @@ operations in OpenStack. The master repository is on GitHub_.
.. _OpenStack Client Wiki: https://wiki.openstack.org/wiki/OpenStackClient
.. _GitHub: https://github.com/openstack/python-openstackclient
python-openstackclient is designed to add support for API extensions via a
plugin mechanism.
OpenStackclient has a plugin mechanism to add support for API extensions.
* `Release management`_
* `Blueprints and feature specifications`_
@ -32,32 +32,41 @@ plugin mechanism.
Note
====
OpenStackClient is considered to be alpha release quality as of the 0.2 release;
OpenStackClient is considered to be beta release quality as of the 0.3 release;
no assurances are made at this point for ongoing compatibility in command forms
or output. We do not, however, expect any major changes at this point.
Getting Started
===============
We recommend using a virtualenv to install the client. This description
uses the `install virtualenv`_ script to create the virtualenv::
OpenStackclient can be installed from PyPI using pip::
pip install python-openstackclient
Developers can use the `install virtualenv`_ script to create the virtualenv::
python tools/install_venv.py
source .venv/bin/activate
python setup.py develop
Unit tests can be ran simply by running::
run_tests.sh
Unit tests are now run using tox. The ``run_test.sh`` script provides compatability
but is generally considered deprecated.
The client can be called interactively by simply typing::
openstack
Alternatively command line parameters can be called non-interactively::
There are a few variants on getting help. A list of global options and supported
commands is shown with ``--help``::
openstack --help
There is also a ``help`` command that can be used to get help text for a specific
command::
openstack help
openstack help server create
Configuration
=============
@ -116,10 +125,9 @@ The source is maintained in the ``doc/source`` folder using
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org/
* Building Manually::
Building Manually::
$ export DJANGO_SETTINGS_MODULE=local.local_settings
$ python doc/generate_autodoc_index.py
$ sphinx-build -b html doc/source build/sphinx/html
cd doc
make html
Results are in the `build/sphinx/html` directory.
Results are in the ``build/html`` directory.

30
doc/source/commands.rst

@ -61,6 +61,36 @@ They follow the same style as the global options and always appear between
the command and any positional arguments the command requires.
Actions
-------
The actions used by OpenStackClient are defined below to provide a consistent meaning to each action. Many of them have logical opposite actions. Those actions with an opposite action are noted in parens if applicable.
* authorize - authorize a token (used in OAuth)
* add (remove) - add some object to a container object; the command is built in the order of "container add object" (<container> <object>), the positional arguments appear in the same order
* attach (detach) - deprecated; use add/remove
* create (delete) - create a new occurrance of the specified object
* delete (create) - delete a specific occurrance of the specified object
* detach (attach) - deprecated; use add/remove
* list - display summary information about multiple objects
* lock (unlock)
* migrate - move a server to a different host; --live performs a live migration if possible
* pause (unpause) - stop a server and leave it in memory
* reboot - forcibly reboot a server
* rebuild - rebuild a server using (most of) the same arguments as in the original create
* remove (add) - remove an object from a group of objects
* rescue (unrescue) - reboot a server in a special rescue mode allowing access to the original disks
* resize - change a server's flavor
* resume (suspend) - return a suspended server to running state
* save - download an object locally
* set (unset) - set a property on the object, formerly called metadata
* show - display detailed information about the specific object
* suspend (resume) - stop a server and save to disk freeing memory
* unlock (lock)
* unpause (pause) - return a paused server to running state
* unrescue (rescue) - return a server to normal boot mode
* unset (set) - remove an attribute of the object
Implementation
==============

115
doc/source/man/openstack.rst

@ -18,7 +18,7 @@ DESCRIPTION
===========
:program:`openstack` provides a common command-line interface to OpenStack APIs. It is generally
equivalent to the CLIs provided by the OpenStack project client librariess, but with
equivalent to the CLIs provided by the OpenStack project client libraries, but with
a distinct and consistent command structure.
:program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with
@ -37,49 +37,51 @@ command line. The primary difference is the use of 'project' in the name of the
OPTIONS
=======
:program:`openstack` takes global options that control overall behaviour and command-specific options that control the command operation. 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.
:program:`openstack` recognizes the following global topions:
:option:`--os-auth-url <auth-url>`
:option:`--os-auth-url` <auth-url>
Authentication URL
:option:`--os-project-name <auth-project-name>`
Authentication project name (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
:option:`--os-domain-name` <auth-domain-name> | :option:`--os-domain-id` <auth-domain-id>
Domain-level authorization scope (name or ID)
:option:`--os-project-id <auth-project-id>`
Authentication tenant ID (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
:option:`--os-project-name` <auth-project-name> | :option:`--os-project-id` <auth-project-id>
Project-level authentication scope (name or ID)
:option:`--os-username <auth-username>`
:option:`--os-project-domain-name` <auth-project-domain-name> | :option:`--os-project-domain-id` <auth-project-domain-id>
Domain name or id containing project
:option:`--os-username` <auth-username>
Authentication username
:option:`--os-password <auth-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-region-name <auth-region-name>`
:option:`--os-region-name` <auth-region-name>
Authentication region name
:option:`--os-default-domain <auth-domain>`
:option:`--os-default-domain` <auth-domain>
Default domain ID (Default: 'default')
:options:`--os-use-keyring`
:option:`--os-use-keyring`
Use keyring to store password (default: False)
:option:`--os-cacert <ca-bundle-file>`
:option:`--os-cacert` <ca-bundle-file>
CA certificate bundle file
:option:`--verify|--insecure`
:option:`--verify` | :option:`--insecure`
Verify or ignore server certificate (default: verify)
:option:`--os-identity-api-version <identity-api-version>`
: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
=====
[This section intentionally left blank. So there.]
:option:`--os-XXXX-api-version` <XXXX-api-version>
Additional API version options will be available depending on the installed API libraries.
COMMANDS
@ -87,7 +89,7 @@ COMMANDS
To get a list of the available commands::
openstack -h
openstack --help
To get a description of a specific command::
@ -101,12 +103,23 @@ To get a description of a specific command::
Print help for an individual command
NOTES
=====
The command list displayed in help output reflects the API versions selected. For
example, to see Identity v3 commands ``OS_IDENTITY_API_VERSION`` must be set to ``3``.
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
openstack \
--os-project-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::
@ -126,25 +139,53 @@ Create a new image::
FILES
=====
:file:`~/.openstack`
:file:`~/.openstack`
Placeholder for future local state directory. This directory is intended to be shared among multiple OpenStack-related applications; contents are namespaced with an identifier for the app that owns it. Shared contents (such as :file:`~/.openstack/cache`) have no prefix and the contents must be portable.
ENVIRONMENT VARIABLES
=====================
The following environment variables can be set to alter the behaviour of :program:`openstack`
:envvar:`OS_USERNAME`
Set the username
:envvar:`OS_PASSWORD`
Set the password
:envvar:`OS_PROJECT_NAME`
Set the project name
The following environment variables can be set to alter the behaviour of :program:`openstack`. Most of them have corresponding command-line options that take precedence if set.
:envvar:`OS_AUTH_URL`
Set the authentication URL
Authentication URL
:envvar:`OS_DOMAIN_NAME`
Domain-level authorization scope (name or ID)
:envvar:`OS_PROJECT_NAME`
Project-level authentication scope (name or ID)
:envvar:`OS_PROJECT_DOMAIN_NAME`
Domain name or id containing project
: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_DEFAULT_DOMAIN`
Default domain ID (Default: ‘default’)
:envvar:`OS_USE_KEYRING`
Use keyring to store password (default: False)
:envvar:`OS_CACERT`
CA certificate bundle file
:envvar:`OS_IDENTITY_API_VERISON`
Identity API version (Default: 2.0)
:envvar:`OS_XXXX_API_VERISON`
Additional API version options will be available depending on the installed API libraries.
BUGS
@ -163,7 +204,7 @@ Please refer to the AUTHORS file distributed with OpenStackClient.
COPYRIGHT
=========
Copyright 2011-2013 OpenStack Foundation and the authors listed in the AUTHORS file.
Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file.
LICENSE

23
doc/source/releases.rst

@ -2,6 +2,25 @@
Release Notes
=============
0.3.1 (28 Feb 2014)
===================
* add ``token create`` command
* internal changes for Python 3.3 compatability
* Bug 1100116_: Prompt interactive user for passwords in ``user create`` and ``user set``
* Bug 1198171_: add domain support options for Identity v3
* Bug 1241177_: Fix region handling in volume commands
* Bug 1256935_: Clean up ``security group rule list`` output format
* Bug 1269821_: Fix for unreleased Glance client change in internal class structure
* Bug 1284957_: Correctly pass ``--cacert`` and ``--insecure`` to Identity client in token flow auth
.. _1100116: https://bugs.launchpad.net/ubuntu/+source/python-keystoneclient/+bug/1100116
.. _1198171: https://bugs.launchpad.net/keystone/+bug/1198171
.. _1241177: https://bugs.launchpad.net/python-openstackclient/+bug/1241177
.. _1256935: https://bugs.launchpad.net/python-openstackclient/+bug/1256935
.. _1269821: https://bugs.launchpad.net/python-openstackclient/+bug/1269821
.. _1284957: https://bugs.launchpad.net/python-openstackclient/+bug/1284957
0.3.0 (17 Dec 2013)
===================
@ -10,10 +29,6 @@ Release Notes
* 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)
===================