openstack/python-cinderclient
Code Issues Proposed changes

Fixed documentation of the cinder shell command.

Browse Source 
Updated README.rst and shell.rst to match changes
in the cinder command and novaclient README.rst.

Change-Id: Ifaa53d5c06e6d7d8e3d4d858672717954303bea7
Fixes: bug #1074125
This commit is contained in:
Frederic Lepied 2013-01-11 21:39:11 +01:00
parent 55ae2c1cd5
commit 33c897d87e
5 changed files with 49 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.rst
View File

@ -1,20 +1,16 @@
Python bindings to the OpenStack Volume API Python bindings to the OpenStack Cinder API
=========================================== ===========================================
This is a client for the OpenStack Volume API. There's a Python API (the This is a client for the OpenStack Cinder API. There's a Python API (the
``cinderclient`` module), and a command-line script (``cinder``). Each ``cinderclient`` module), and a command-line script (``cinder``). Each
implements 100% of the OpenStack Volume API. implements 100% of the OpenStack Cinder API.
[PENDING] `Full documentation is available`__. See the `OpenStack CLI guide`_ for information on how to use the ``cinder``
command-line tool. You may also want to look at the
`OpenStack API documentation`_.
__ http://packages.python.org/python-cinderclient/ .. _OpenStack CLI Guide: http://docs.openstack.org/cli/quick-start/content/
.. _OpenStack API documentation: http://docs.openstack.org/api/
You'll also probably want to read `OpenStack Compute Developer Guide API`__ --
the first bit, at least -- to get an idea of the concepts. Rackspace is doing
the cloud hosting thing a bit differently from Amazon, and if you get the
concepts this library should make more sense.
__ http://docs.openstack.org/api/
The project is hosted on `Launchpad`_, where bugs can be filed. The code is The project is hosted on `Launchpad`_, where bugs can be filed. The code is
hosted on `Github`_. Patches must be submitted using `Gerrit`_, *not* Github hosted on `Github`_. Patches must be submitted using `Gerrit`_, *not* Github
@ -26,7 +22,7 @@ pull requests.
This code a fork of `Jacobian's python-cloudservers`__ If you need API support This code a fork of `Jacobian's python-cloudservers`__ If you need API support
for the Rackspace API solely or the BSD license, you should use that repository. for the Rackspace API solely or the BSD license, you should use that repository.
python-client is licensed under the Apache License like the rest of OpenStack. python-cinderclient is licensed under the Apache License like the rest of OpenStack.
__ http://github.com/jacobian/python-cloudservers __ http://github.com/jacobian/python-cloudservers
@ -52,7 +48,7 @@ and the version of the API with ``--version``. Or set them as an environment
variables as well:: variables as well::
export OS_AUTH_URL=http://example.com:8774/v1.1/ export OS_AUTH_URL=http://example.com:8774/v1.1/
export OS_COMPUTE_API_VERSION=1.1 export OS_VOLUME_API_VERSION=1
If you are using Keystone, you need to set the CINDER_URL to the keystone If you are using Keystone, you need to set the CINDER_URL to the keystone
endpoint:: endpoint::
@ -74,9 +70,10 @@ You'll find complete documentation on the shell by running
[--volume-service-name <volume-service-name>] [--volume-service-name <volume-service-name>]
[--endpoint-type <endpoint-type>] [--endpoint-type <endpoint-type>]
[--os-volume-api-version <compute-api-ver>] [--os-volume-api-version <compute-api-ver>]
[--os-cacert <ca-certificate>] [--retries <retries>]
<subcommand> ... <subcommand> ...
Command-line interface to the OpenStack Nova API. Command-line interface to the OpenStack Cinder API.
Positional arguments: Positional arguments:
<subcommand> <subcommand>
@ -86,20 +83,31 @@ You'll find complete documentation on the shell by running
delete Remove a volume. delete Remove a volume.
endpoints Discover endpoints that get returned from the endpoints Discover endpoints that get returned from the
authenticate services authenticate services
extra-specs-list Print a list of current 'volume types and extra specs'
(Admin Only).
list List all the volumes. list List all the volumes.
quota-class-show List the quotas for a quota class.
quota-class-update Update the quotas for a quota class.
quota-defaults List the default quotas for a tenant.
quota-show List the quotas for a tenant.
quota-update Update the quotas for a tenant.
rate-limits Print a list of rate limits for a user rate-limits Print a list of rate limits for a user
rename Rename a volume.
show Show details about a volume. show Show details about a volume.
snapshot-create Add a new snapshot. snapshot-create Add a new snapshot.
snapshot-delete Remove a snapshot. snapshot-delete Remove a snapshot.
snapshot-list List all the snapshots. snapshot-list List all the snapshots.
snapshot-rename Rename a snapshot.
snapshot-show Show details about a snapshot. snapshot-show Show details about a snapshot.
type-create Create a new volume type. type-create Create a new volume type.
type-delete Delete a specific flavor type-delete Delete a specific volume type
type-key Set or unset extra_spec for a volume type.
type-list Print a list of available 'volume types'. type-list Print a list of available 'volume types'.
bash-completion Prints all of the commands and options to stdout so bash-completion Prints all of the commands and options to stdout so
that the that the
help Display help about this program or one of its help Display help about this program or one of its
subcommands. subcommands.
list-extensions List all the os-api extensions that are available.
Optional arguments: Optional arguments:
--debug Print debugging output --debug Print debugging output
@ -122,30 +130,21 @@ You'll find complete documentation on the shell by running
--endpoint-type <endpoint-type> --endpoint-type <endpoint-type>
Defaults to env[CINDER_ENDPOINT_TYPE] or publicURL. Defaults to env[CINDER_ENDPOINT_TYPE] or publicURL.
--os-volume-api-version <compute-api-ver> --os-volume-api-version <compute-api-ver>
Accepts 1, defaults to env[OS_VOLUME_API_VERSION]. Accepts 1,defaults to env[OS_VOLUME_API_VERSION].
--os-cacert <ca-certificate>
See "cinder help COMMAND" for help on a specific command. Specify a CA bundle file to use in verifying a TLS
(https) server certificate. Defaults to env[OS_CACERT]
--retries <retries> Number of retries.
Python API Python API
---------- ----------
[PENDING] There's also a `complete Python API`__. There's also a complete Python API, but it has not yet been documented.
__ http://packages.python.org/python-cinderclient/
Quick-start using keystone:: Quick-start using keystone::
# use v2.0 auth with http://example.com:5000/v2.0/") # use v2.0 auth with http://example.com:5000/v2.0/")
>>> from cinderclient.v1 import client >>> from cinderclient.v1 import client
>>> nt = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="compute") >>> nt = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="volume")
>>> nt.flavors.list() >>> nt.volumes.list()
[...] [...]
>>> nt.servers.list()
[...]
>>> nt.keypairs.list()
[...]
What's new?
-----------
[PENDING] See `the release notes <http://packages.python.org/python-cinderclient/releases.html>`_.

2
cinderclient/shell.py
View File

@ -15,7 +15,7 @@
# under the License. # under the License.
""" """
Command-line interface to the OpenStack Volume API. Command-line interface to the OpenStack Cinder API.
""" """
import argparse import argparse

2
doc/source/api.rst
View File

@ -2,7 +2,7 @@ The :mod:`cinderclient` Python API
================================== ==================================
.. module:: cinderclient .. module:: cinderclient
:synopsis: A client for the OpenStack Nova API. :synopsis: A client for the OpenStack Cinder API.
.. currentmodule:: cinderclient .. currentmodule:: cinderclient

19
doc/source/index.rst
View File

@ -1,21 +1,10 @@
Python bindings to the OpenStack Nova API Python bindings to the OpenStack Cinder API
================================================== ==================================================
This is a client for OpenStack Nova API. There's :doc:`a Python API This is a client for OpenStack Cinder API. There's :doc:`a Python API
<api>` (the :mod:`cinderclient` module), and a :doc:`command-line script <api>` (the :mod:`cinderclient` module), and a :doc:`command-line script
<shell>` (installed as :program:`cinder`). Each implements the entire <shell>` (installed as :program:`cinder`). Each implements the entire
OpenStack Nova API. OpenStack Cinder API.
You'll need an `OpenStack Nova` account, which you can get by using `cinder-manage`.
.. seealso::
You may want to read `Rackspace's API guide`__ (PDF) -- the first bit, at
least -- to get an idea of the concepts. Rackspace is doing the cloud
hosting thing a bit differently from Amazon, and if you get the concepts
this library should make more sense.
__ http://docs.rackspacecloud.com/servers/api/cs-devguide-latest.pdf
Contents: Contents:
@ -32,7 +21,7 @@ Contributing
Development takes place `on GitHub`__; please file bugs/pull requests there. Development takes place `on GitHub`__; please file bugs/pull requests there.
__ https://github.com/rackspace/python-cinderclient __ https://github.com/openstack/python-cinderclient
Run tests with ``python setup.py test``. Run tests with ``python setup.py test``.

25
doc/source/shell.rst
View File

@ -4,36 +4,33 @@ The :program:`cinder` shell utility
.. program:: cinder .. program:: cinder
.. highlight:: bash .. highlight:: bash
The :program:`cinder` shell utility interacts with OpenStack Nova API The :program:`cinder` shell utility interacts with the OpenStack Cinder API
from the command line. It supports the entirety of the OpenStack Nova API. from the command line. It supports the entirety of the OpenStack Cinder API.
First, you'll need an OpenStack Nova account and an API key. You get this
by using the `cinder-manage` command in OpenStack Nova.
You'll need to provide :program:`cinder` with your OpenStack username and You'll need to provide :program:`cinder` with your OpenStack username and
API key. You can do this with the :option:`--os-username`, :option:`--os-password` API key. You can do this with the :option:`--os-username`, :option:`--os-password`
and :option:`--os-tenant-id` options, but it's easier to just set them as and :option:`--os-tenant-name` options, but it's easier to just set them as
environment variables by setting two environment variables: environment variables by setting two environment variables:
.. envvar:: OS_USERNAME .. envvar:: OS_USERNAME or CINDER_USERNAME
Your OpenStack Nova username. Your OpenStack Cinder username.
.. envvar:: OS_PASSWORD .. envvar:: OS_PASSWORD or CINDER_PASSWORD
Your password. Your password.
.. envvar:: OS_TENANT_NAME .. envvar:: OS_TENANT_NAME or CINDER_PROJECT_ID
Project for work. Project for work.
.. envvar:: OS_AUTH_URL .. envvar:: OS_AUTH_URL or CINDER_URL
The OpenStack API server URL. The OpenStack API server URL.
.. envvar:: OS_COMPUTE_API_VERSION .. envvar:: OS_VOLUME_API_VERSION
The OpenStack API version. The OpenStack Block Storage API version.
For example, in Bash you'd use:: For example, in Bash you'd use::
@ -41,7 +38,7 @@ For example, in Bash you'd use::
export OS_PASSWORD=yadayadayada export OS_PASSWORD=yadayadayada
export OS_TENANT_NAME=myproject export OS_TENANT_NAME=myproject
export OS_AUTH_URL=http://... export OS_AUTH_URL=http://...
export OS_COMPUTE_API_VERSION=1.1 export OS_VOLUME_API_VERSION=1
From there, all shell commands take the form:: From there, all shell commands take the form::