Skip to content

Commit 038269c

Browse files
author
Dean Troyer
committed
Update release notes for 0.3.1
* update README * update man page * fix doc errors Change-Id: I5682654bf482289879c8ba9016e348f2b2782971
1 parent 2cae50c commit 038269c

4 files changed

Lines changed: 147 additions & 53 deletions

File tree

‎README.rst‎

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22
OpenStack Client
33
================
44

5-
python-openstackclient is a unified command-line client for the OpenStack APIs.
6-
It is a thin wrapper to the stock python-*client modules that implement the
5+
OpenStackclient (aka ``python-openstackclient``) is a command-line client for
6+
the OpenStack APIs.
7+
It is primarily a wrapper to the stock python-*client modules that implement the
78
actual REST API client actions.
89
910
This is an implementation of the design goals shown in
@@ -14,8 +15,7 @@ operations in OpenStack. The master repository is on GitHub_.
1415
.. _OpenStack Client Wiki: https://wiki.openstack.org/wiki/OpenStackClient
1516
.. _GitHub: https://github.com/openstack/python-openstackclient
1617

17-
python-openstackclient is designed to add support for API extensions via a
18-
plugin mechanism.
18+
OpenStackclient has a plugin mechanism to add support for API extensions.
1919

2020
* `Release management`_
2121
* `Blueprints and feature specifications`_
@@ -32,32 +32,41 @@ plugin mechanism.
3232
Note
3333
====
3434

35-
OpenStackClient is considered to be alpha release quality as of the 0.2 release;
35+
OpenStackClient is considered to be beta release quality as of the 0.3 release;
3636
no assurances are made at this point for ongoing compatibility in command forms
3737
or output. We do not, however, expect any major changes at this point.
3838

3939
Getting Started
4040
===============
4141

42-
We recommend using a virtualenv to install the client. This description
43-
uses the `install virtualenv`_ script to create the virtualenv::
42+
OpenStackclient can be installed from PyPI using pip::
43+
44+
pip install python-openstackclient
45+
46+
Developers can use the `install virtualenv`_ script to create the virtualenv::
4447

4548
python tools/install_venv.py
4649
source .venv/bin/activate
4750
python setup.py develop
4851

49-
Unit tests can be ran simply by running::
50-
51-
run_tests.sh
52+
Unit tests are now run using tox. The ``run_test.sh`` script provides compatability
53+
but is generally considered deprecated.
5254

5355
The client can be called interactively by simply typing::
5456

5557
openstack
5658

57-
Alternatively command line parameters can be called non-interactively::
59+
There are a few variants on getting help. A list of global options and supported
60+
commands is shown with ``--help``::
5861

5962
openstack --help
6063

64+
There is also a ``help`` command that can be used to get help text for a specific
65+
command::
66+
67+
openstack help
68+
openstack help server create
69+
6170
Configuration
6271
=============
6372

@@ -116,10 +125,9 @@ The source is maintained in the ``doc/source`` folder using
116125
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
117126
.. _Sphinx: http://sphinx.pocoo.org/
118127

119-
* Building Manually::
128+
Building Manually::
120129

121-
$ export DJANGO_SETTINGS_MODULE=local.local_settings
122-
$ python doc/generate_autodoc_index.py
123-
$ sphinx-build -b html doc/source build/sphinx/html
130+
cd doc
131+
make html
124132

125-
Results are in the `build/sphinx/html` directory.
133+
Results are in the ``build/html`` directory.

‎doc/source/commands.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,36 @@ They follow the same style as the global options and always appear between
6161
the command and any positional arguments the command requires.
6262

6363

64+
Actions
65+
-------
66+
67+
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.
68+
69+
* authorize - authorize a token (used in OAuth)
70+
* 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
71+
* attach (detach) - deprecated; use add/remove
72+
* create (delete) - create a new occurrance of the specified object
73+
* delete (create) - delete a specific occurrance of the specified object
74+
* detach (attach) - deprecated; use add/remove
75+
* list - display summary information about multiple objects
76+
* lock (unlock)
77+
* migrate - move a server to a different host; --live performs a live migration if possible
78+
* pause (unpause) - stop a server and leave it in memory
79+
* reboot - forcibly reboot a server
80+
* rebuild - rebuild a server using (most of) the same arguments as in the original create
81+
* remove (add) - remove an object from a group of objects
82+
* rescue (unrescue) - reboot a server in a special rescue mode allowing access to the original disks
83+
* resize - change a server's flavor
84+
* resume (suspend) - return a suspended server to running state
85+
* save - download an object locally
86+
* set (unset) - set a property on the object, formerly called metadata
87+
* show - display detailed information about the specific object
88+
* suspend (resume) - stop a server and save to disk freeing memory
89+
* unlock (lock)
90+
* unpause (pause) - return a paused server to running state
91+
* unrescue (rescue) - return a server to normal boot mode
92+
* unset (set) - remove an attribute of the object
93+
6494
Implementation
6595
==============
6696

‎doc/source/man/openstack.rst‎

Lines changed: 74 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ DESCRIPTION
1818
===========
1919

2020
:program:`openstack` provides a common command-line interface to OpenStack APIs. It is generally
21-
equivalent to the CLIs provided by the OpenStack project client librariess, but with
21+
equivalent to the CLIs provided by the OpenStack project client libraries, but with
2222
a distinct and consistent command structure.
2323

2424
:program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with
@@ -37,57 +37,59 @@ command line. The primary difference is the use of 'project' in the name of the
3737
OPTIONS
3838
=======
3939

40+
: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.
41+
4042
:program:`openstack` recognizes the following global topions:
4143

42-
:option:`--os-auth-url <auth-url>`
44+
:option:`--os-auth-url` <auth-url>
4345
Authentication URL
4446

45-
:option:`--os-project-name <auth-project-name>`
46-
Authentication project name (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
47+
:option:`--os-domain-name` <auth-domain-name> | :option:`--os-domain-id` <auth-domain-id>
48+
Domain-level authorization scope (name or ID)
49+
50+
:option:`--os-project-name` <auth-project-name> | :option:`--os-project-id` <auth-project-id>
51+
Project-level authentication scope (name or ID)
4752

48-
:option:`--os-project-id <auth-project-id>`
49-
Authentication tenant ID (only one of :option:`--os-project-name` or :option:`--os-project-id` need be supplied)
53+
:option:`--os-project-domain-name` <auth-project-domain-name> | :option:`--os-project-domain-id` <auth-project-domain-id>
54+
Domain name or id containing project
5055

51-
:option:`--os-username <auth-username>`
56+
:option:`--os-username` <auth-username>
5257
Authentication username
5358

54-
:option:`--os-password <auth-password>`
59+
:option:`--os-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
60+
Domain name or id containing user
61+
62+
:option:`--os-password` <auth-password>
5563
Authentication password
5664

57-
:option:`--os-region-name <auth-region-name>`
65+
:option:`--os-region-name` <auth-region-name>
5866
Authentication region name
5967

60-
:option:`--os-default-domain <auth-domain>`
68+
:option:`--os-default-domain` <auth-domain>
6169
Default domain ID (Default: 'default')
6270

63-
:options:`--os-use-keyring`
71+
:option:`--os-use-keyring`
6472
Use keyring to store password (default: False)
6573

66-
:option:`--os-cacert <ca-bundle-file>`
74+
:option:`--os-cacert` <ca-bundle-file>
6775
CA certificate bundle file
6876

69-
:option:`--verify|--insecure`
77+
:option:`--verify` | :option:`--insecure`
7078
Verify or ignore server certificate (default: verify)
7179

72-
:option:`--os-identity-api-version <identity-api-version>`
80+
:option:`--os-identity-api-version` <identity-api-version>
7381
Identity API version (Default: 2.0)
7482

75-
:option:`--os-XXXX-api-version <XXXX-api-version>`
76-
Additional API version options will be presend depending on the installed API libraries.
77-
78-
79-
NOTES
80-
=====
81-
82-
[This section intentionally left blank. So there.]
83+
:option:`--os-XXXX-api-version` <XXXX-api-version>
84+
Additional API version options will be available depending on the installed API libraries.
8385

8486

8587
COMMANDS
8688
========
8789

8890
To get a list of the available commands::
8991

90-
openstack -h
92+
openstack --help
9193

9294
To get a description of a specific command::
9395

@@ -101,12 +103,23 @@ To get a description of a specific command::
101103
Print help for an individual command
102104

103105

106+
NOTES
107+
=====
108+
109+
The command list displayed in help output reflects the API versions selected. For
110+
example, to see Identity v3 commands ``OS_IDENTITY_API_VERSION`` must be set to ``3``.
111+
112+
104113
EXAMPLES
105114
========
106115

107116
Show the detailed information for server ``appweb01``::
108117

109-
openstack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 server show appweb01
118+
openstack \
119+
--os-project-name ExampleCo \
120+
--os-username demo --os-password secrete \
121+
--os-auth-url http://localhost:5000:/v2.0 \
122+
server show appweb01
110123

111124
The same command if the auth environment variables (:envvar:`OS_AUTH_URL`, :envvar:`OS_PROJECT_NAME`,
112125
:envvar:`OS_USERNAME`, :envvar:`OS_PASSWORD`) are set::
@@ -126,25 +139,53 @@ Create a new image::
126139
FILES
127140
=====
128141

129-
:file:`~/.openstack`
142+
:file:`~/.openstack`
143+
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.
130144

131145

132146
ENVIRONMENT VARIABLES
133147
=====================
134148

135-
The following environment variables can be set to alter the behaviour of :program:`openstack`
149+
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.
150+
151+
:envvar:`OS_AUTH_URL`
152+
Authentication URL
153+
154+
:envvar:`OS_DOMAIN_NAME`
155+
Domain-level authorization scope (name or ID)
156+
157+
:envvar:`OS_PROJECT_NAME`
158+
Project-level authentication scope (name or ID)
159+
160+
:envvar:`OS_PROJECT_DOMAIN_NAME`
161+
Domain name or id containing project
136162

137163
:envvar:`OS_USERNAME`
138-
Set the username
164+
Authentication username
165+
166+
:envvar:`OS_USER_DOMAIN_NAME`
167+
Domain name or id containing user
139168

140169
:envvar:`OS_PASSWORD`
141-
Set the password
170+
Authentication password
142171

143-
:envvar:`OS_PROJECT_NAME`
144-
Set the project name
172+
:envvar:`OS_REGION_NAME`
173+
Authentication region name
145174

146-
:envvar:`OS_AUTH_URL`
147-
Set the authentication URL
175+
:envvar:`OS_DEFAULT_DOMAIN`
176+
Default domain ID (Default: ‘default’)
177+
178+
:envvar:`OS_USE_KEYRING`
179+
Use keyring to store password (default: False)
180+
181+
:envvar:`OS_CACERT`
182+
CA certificate bundle file
183+
184+
:envvar:`OS_IDENTITY_API_VERISON`
185+
Identity API version (Default: 2.0)
186+
187+
:envvar:`OS_XXXX_API_VERISON`
188+
Additional API version options will be available depending on the installed API libraries.
148189

149190

150191
BUGS
@@ -163,7 +204,7 @@ Please refer to the AUTHORS file distributed with OpenStackClient.
163204
COPYRIGHT
164205
=========
165206

166-
Copyright 2011-2013 OpenStack Foundation and the authors listed in the AUTHORS file.
207+
Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file.
167208

168209

169210
LICENSE

‎doc/source/releases.rst‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,25 @@
22
Release Notes
33
=============
44

5+
0.3.1 (28 Feb 2014)
6+
===================
7+
8+
* add ``token create`` command
9+
* internal changes for Python 3.3 compatability
10+
* Bug 1100116_: Prompt interactive user for passwords in ``user create`` and ``user set``
11+
* Bug 1198171_: add domain support options for Identity v3
12+
* Bug 1241177_: Fix region handling in volume commands
13+
* Bug 1256935_: Clean up ``security group rule list`` output format
14+
* Bug 1269821_: Fix for unreleased Glance client change in internal class structure
15+
* Bug 1284957_: Correctly pass ``--cacert`` and ``--insecure`` to Identity client in token flow auth
16+
17+
.. _1100116: https://bugs.launchpad.net/ubuntu/+source/python-keystoneclient/+bug/1100116
18+
.. _1198171: https://bugs.launchpad.net/keystone/+bug/1198171
19+
.. _1241177: https://bugs.launchpad.net/python-openstackclient/+bug/1241177
20+
.. _1256935: https://bugs.launchpad.net/python-openstackclient/+bug/1256935
21+
.. _1269821: https://bugs.launchpad.net/python-openstackclient/+bug/1269821
22+
.. _1284957: https://bugs.launchpad.net/python-openstackclient/+bug/1284957
23+
524
0.3.0 (17 Dec 2013)
625
===================
726

@@ -10,10 +29,6 @@ Release Notes
1029
* add options to support TLS cetificate verification
1130
* add object-store show commands for container and object
1231

13-
.. commented to save format of bug fix
14-
.. * 1254168_: OS_REGION_NAME is not used
15-
.. _1254168: https://bugs.launchpad.net/python-openstackclient/+bug/1254168
16-
1732
0.2.2 (20 Sep 2013)
1833
===================
1934

0 commit comments

Comments
 (0)