diff options
| -rw-r--r-- | README.rst | 40 | ||||
| -rw-r--r-- | doc/source/commands.rst | 30 | ||||
| -rw-r--r-- | doc/source/man/openstack.rst | 107 | ||||
| -rw-r--r-- | doc/source/releases.rst | 23 |
4 files changed, 147 insertions, 53 deletions
@@ -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. diff --git a/doc/source/commands.rst b/doc/source/commands.rst index 0b93c64d..31e7c148 100644 --- a/doc/source/commands.rst +++ b/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 ============== diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst index 3a780e24..74db6815 100644 --- a/doc/source/man/openstack.rst +++ b/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-name` <auth-project-name> | :option:`--os-project-id` <auth-project-id> + Project-level authentication 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-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>` +: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` +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` + 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` - Set the username + Authentication username + +:envvar:`OS_USER_DOMAIN_NAME` + Domain name or id containing user :envvar:`OS_PASSWORD` - Set the password + Authentication password -:envvar:`OS_PROJECT_NAME` - Set the project name +:envvar:`OS_REGION_NAME` + Authentication region name -:envvar:`OS_AUTH_URL` - Set the authentication URL +: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 diff --git a/doc/source/releases.rst b/doc/source/releases.rst index 7d74318e..34bdce62 100644 --- a/doc/source/releases.rst +++ b/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) =================== |