diff --git a/README.rst b/README.rst index 241f75050..86a8669bf 100644 --- a/README.rst +++ b/README.rst @@ -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 -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/ - -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/ +.. _OpenStack CLI Guide: http://docs.openstack.org/cli/quick-start/content/ +.. _OpenStack API documentation: http://docs.openstack.org/api/ 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 @@ -26,7 +22,7 @@ pull requests. 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. -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 @@ -52,7 +48,7 @@ and the version of the API with ``--version``. Or set them as an environment variables as well:: 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 endpoint:: @@ -74,9 +70,10 @@ You'll find complete documentation on the shell by running [--volume-service-name ] [--endpoint-type ] [--os-volume-api-version ] + [--os-cacert ] [--retries ] ... - Command-line interface to the OpenStack Nova API. + Command-line interface to the OpenStack Cinder API. Positional arguments: @@ -86,20 +83,31 @@ You'll find complete documentation on the shell by running delete Remove a volume. endpoints Discover endpoints that get returned from the authenticate services + extra-specs-list Print a list of current 'volume types and extra specs' + (Admin Only). 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 + rename Rename a volume. show Show details about a volume. snapshot-create Add a new snapshot. snapshot-delete Remove a snapshot. snapshot-list List all the snapshots. + snapshot-rename Rename a snapshot. snapshot-show Show details about a snapshot. 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'. bash-completion Prints all of the commands and options to stdout so that the help Display help about this program or one of its subcommands. + list-extensions List all the os-api extensions that are available. Optional arguments: --debug Print debugging output @@ -122,30 +130,21 @@ You'll find complete documentation on the shell by running --endpoint-type Defaults to env[CINDER_ENDPOINT_TYPE] or publicURL. --os-volume-api-version - Accepts 1, defaults to env[OS_VOLUME_API_VERSION]. - - See "cinder help COMMAND" for help on a specific command. + Accepts 1,defaults to env[OS_VOLUME_API_VERSION]. + --os-cacert + Specify a CA bundle file to use in verifying a TLS + (https) server certificate. Defaults to env[OS_CACERT] + --retries Number of retries. Python API ---------- -[PENDING] There's also a `complete Python API`__. - -__ http://packages.python.org/python-cinderclient/ +There's also a complete Python API, but it has not yet been documented. Quick-start using keystone:: # use v2.0 auth with http://example.com:5000/v2.0/") >>> from cinderclient.v1 import client - >>> nt = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="compute") - >>> nt.flavors.list() + >>> nt = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="volume") + >>> nt.volumes.list() [...] - >>> nt.servers.list() - [...] - >>> nt.keypairs.list() - [...] - -What's new? ------------ - -[PENDING] See `the release notes `_. diff --git a/cinderclient/shell.py b/cinderclient/shell.py index 621de294f..1f174db80 100644 --- a/cinderclient/shell.py +++ b/cinderclient/shell.py @@ -15,7 +15,7 @@ # under the License. """ -Command-line interface to the OpenStack Volume API. +Command-line interface to the OpenStack Cinder API. """ import argparse diff --git a/doc/source/api.rst b/doc/source/api.rst index 1e184bbf4..116fba40e 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -2,7 +2,7 @@ The :mod:`cinderclient` Python API ================================== .. module:: cinderclient - :synopsis: A client for the OpenStack Nova API. + :synopsis: A client for the OpenStack Cinder API. .. currentmodule:: cinderclient diff --git a/doc/source/index.rst b/doc/source/index.rst index d992f7c62..f1996630a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ` (the :mod:`cinderclient` module), and a :doc:`command-line script ` (installed as :program:`cinder`). Each implements the entire -OpenStack Nova 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 +OpenStack Cinder API. Contents: @@ -32,7 +21,7 @@ Contributing 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``. diff --git a/doc/source/shell.rst b/doc/source/shell.rst index 9458ceed9..7ded87fc5 100644 --- a/doc/source/shell.rst +++ b/doc/source/shell.rst @@ -4,36 +4,33 @@ The :program:`cinder` shell utility .. program:: cinder .. highlight:: bash -The :program:`cinder` shell utility interacts with OpenStack Nova API -from the command line. It supports the entirety of the OpenStack Nova 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. +The :program:`cinder` shell utility interacts with the OpenStack Cinder API +from the command line. It supports the entirety of the OpenStack Cinder API. 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` -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: -.. 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. -.. envvar:: OS_TENANT_NAME +.. envvar:: OS_TENANT_NAME or CINDER_PROJECT_ID Project for work. -.. envvar:: OS_AUTH_URL +.. envvar:: OS_AUTH_URL or CINDER_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:: @@ -41,7 +38,7 @@ For example, in Bash you'd use:: export OS_PASSWORD=yadayadayada export OS_TENANT_NAME=myproject 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::