Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Docs in cinderlcient were never actually updated.

Not only were the docs and release info here not being
maintainted properly, but the examples that were given were
not correct.

This change is an attempt to set us on the right path going
forward and includes info on how to import the API and history
info for the upcoming release/push to PyPi.

Fixes bug: 1156994

Change-Id: I169b1c01380ef653a6a25eb8946b9a06d6419e62
  • Loading branch information...
commit 020778ddd942e762a5e543e41bc3f4d95df3b91e 1 parent f2ac10f
@j-griffith j-griffith authored
View
67 doc/source/api.rst
@@ -1,67 +0,0 @@
-The :mod:`cinderclient` Python API
-==================================
-
-.. module:: cinderclient
- :synopsis: A client for the OpenStack Cinder API.
-
-.. currentmodule:: cinderclient
-
-Usage
------
-
-First create an instance of :class:`OpenStack` with your credentials::
-
- >>> from cinderclient import OpenStack
- >>> cinder = OpenStack(USERNAME, PASSWORD, AUTH_URL)
-
-Then call methods on the :class:`OpenStack` object:
-
-.. class:: OpenStack
-
- .. attribute:: backup_schedules
-
- A :class:`BackupScheduleManager` -- manage automatic backup images.
-
- .. attribute:: flavors
-
- A :class:`FlavorManager` -- query available "flavors" (hardware
- configurations).
-
- .. attribute:: images
-
- An :class:`ImageManager` -- query and create server disk images.
-
- .. attribute:: ipgroups
-
- A :class:`IPGroupManager` -- manage shared public IP addresses.
-
- .. attribute:: servers
-
- A :class:`ServerManager` -- start, stop, and manage virtual machines.
-
- .. automethod:: authenticate
-
-For example::
-
- >>> cinder.servers.list()
- [<Server: buildslave-ubuntu-9.10>]
-
- >>> cinder.flavors.list()
- [<Flavor: 256 server>,
- <Flavor: 512 server>,
- <Flavor: 1GB server>,
- <Flavor: 2GB server>,
- <Flavor: 4GB server>,
- <Flavor: 8GB server>,
- <Flavor: 15.5GB server>]
-
- >>> fl = cinder.flavors.find(ram=512)
- >>> cinder.servers.create("my-server", flavor=fl)
- <Server: my-server>
-
-For more information, see the reference:
-
-.. toctree::
- :maxdepth: 2
-
- ref/index
View
86 doc/source/index.rst
@@ -1,34 +1,52 @@
-Python bindings to the OpenStack Cinder 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
-<shell>` (installed as :program:`cinder`). Each implements the entire
-OpenStack Cinder API.
-
-Contents:
-
-.. toctree::
- :maxdepth: 2
-
- shell
- api
- ref/index
- releases
-
-Contributing
-============
-
-Development takes place `on GitHub`__; please file bugs/pull requests there.
-
-__ https://github.com/openstack/python-cinderclient
-
-Run tests with ``python setup.py test``.
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+Python API
+==========
+In order to use the python api directly, you must first obtain an auth token and identify which endpoint you wish to speak to. Once you have done so, you can use the API like so::
+
+ >>> from cinderclient import client
+ >>> cinder = client.Client('1', $OS_USER_NAME, $OS_PASSWORD, $OS_TENANT_NAME, $OS_AUTH_URL)
+ >>> cinder.volumes.list()
+ []
+ >>> myvol = cinder.volumes.create(display_name="test-vol", size=1)
+ >>> myvol.id
+ ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70
+ >>> cinder.volumes.list()
+ [<Volume: ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70>]
+ >>>myvol.delete
+
+Command-line Tool
+=================
+In order to use the CLI, you must provide your OpenStack username, password, tenant, and auth endpoint. Use the corresponding configuration options (``--os-username``, ``--os-password``, ``--os-tenant-id``, and ``--os-auth-url``) or set them in environment variables::
+
+ export OS_USERNAME=user
+ export OS_PASSWORD=pass
+ export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
+ export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+
+Once you've configured your authentication parameters, you can run ``cinder help`` to see a complete listing of available commands.
+
+
+Release Notes
+=============
+
+1.1.0
+-----
+
+* Added support for V2 Cinder API
+* Corected upload-volume-to-image help messaging
+* Align handling of metadata args for all methods
+* Update OSLO version
+* Correct parsing of volume metadata
+* Enable force delete of volumes and snapshots in error state
+* Implement clone volume API call
+* Add list-extensions call to cinderclient
+* Add bootable column to list output
+* Add retries to cinderclient operations
+* Add Type/Extra-Specs support
+* Add volume and snapshot rename commands
+.. _1155655: http://bugs.launchpad.net/python-cinderclient/+bug/1155655
+.. _1130730: http://bugs.launchpad.net/python-cinderclient/+bug/1130730
+.. _1068521: http://bugs.launchpad.net/python-cinderclient/+bug/1068521
+.. _1052161: http://bugs.launchpad.net/python-cinderclient/+bug/1052161
+.. _1071003: http://bugs.launchpad.net/python-cinderclient/+bug/1071003
+.. _1065275: http://bugs.launchpad.net/python-cinderclient/+bug/1065275
+.. _1053432: http://bugs.launchpad.net/python-cinderclient/+bug/1053432
View
60 doc/source/ref/backup_schedules.rst
@@ -1,60 +0,0 @@
-Backup schedules
-================
-
-.. currentmodule:: cinderclient
-
-Rackspace allows scheduling of weekly and/or daily backups for virtual
-servers. You can access these backup schedules either off the API object as
-:attr:`OpenStack.backup_schedules`, or directly off a particular
-:class:`Server` instance as :attr:`Server.backup_schedule`.
-
-Classes
--------
-
-.. autoclass:: BackupScheduleManager
- :members: create, delete, update, get
-
-.. autoclass:: BackupSchedule
- :members: update, delete
-
- .. attribute:: enabled
-
- Is this backup enabled? (boolean)
-
- .. attribute:: weekly
-
- The day of week upon which to perform a weekly backup.
-
- .. attribute:: daily
-
- The daily time period during which to perform a daily backup.
-
-Constants
----------
-
-Constants for selecting weekly backup days:
-
- .. data:: BACKUP_WEEKLY_DISABLED
- .. data:: BACKUP_WEEKLY_SUNDAY
- .. data:: BACKUP_WEEKLY_MONDAY
- .. data:: BACKUP_WEEKLY_TUESDAY
- .. data:: BACKUP_WEEKLY_WEDNESDA
- .. data:: BACKUP_WEEKLY_THURSDAY
- .. data:: BACKUP_WEEKLY_FRIDAY
- .. data:: BACKUP_WEEKLY_SATURDAY
-
-Constants for selecting hourly backup windows:
-
- .. data:: BACKUP_DAILY_DISABLED
- .. data:: BACKUP_DAILY_H_0000_0200
- .. data:: BACKUP_DAILY_H_0200_0400
- .. data:: BACKUP_DAILY_H_0400_0600
- .. data:: BACKUP_DAILY_H_0600_0800
- .. data:: BACKUP_DAILY_H_0800_1000
- .. data:: BACKUP_DAILY_H_1000_1200
- .. data:: BACKUP_DAILY_H_1200_1400
- .. data:: BACKUP_DAILY_H_1400_1600
- .. data:: BACKUP_DAILY_H_1600_1800
- .. data:: BACKUP_DAILY_H_1800_2000
- .. data:: BACKUP_DAILY_H_2000_2200
- .. data:: BACKUP_DAILY_H_2200_0000
View
14 doc/source/ref/exceptions.rst
@@ -1,14 +0,0 @@
-Exceptions
-==========
-
-.. currentmodule:: cinderclient
-
-Exceptions
-----------
-
-Exceptions that the API might throw:
-
-.. automodule:: cinderclient
- :members: OpenStackException, BadRequest, Unauthorized, Forbidden,
- NotFound, OverLimit
-
View
35 doc/source/ref/flavors.rst
@@ -1,35 +0,0 @@
-Flavors
-=======
-
-From Rackspace's API documentation:
-
- A flavor is an available hardware configuration for a server. Each flavor
- has a unique combination of disk space, memory capacity and priority for
- CPU time.
-
-Classes
--------
-
-.. currentmodule:: cinderclient
-
-.. autoclass:: FlavorManager
- :members: get, list, find, findall
-
-.. autoclass:: Flavor
- :members:
-
- .. attribute:: id
-
- This flavor's ID.
-
- .. attribute:: name
-
- A human-readable name for this flavor.
-
- .. attribute:: ram
-
- The amount of RAM this flavor has, in MB.
-
- .. attribute:: disk
-
- The amount of disk space this flavor has, in MB
View
54 doc/source/ref/images.rst
@@ -1,54 +0,0 @@
-Images
-======
-
-.. currentmodule:: cinderclient
-
-An "image" is a snapshot from which you can create new server instances.
-
-From Rackspace's own API documentation:
-
- An image is a collection of files used to create or rebuild a server.
- Rackspace provides a number of pre-built OS images by default. You may
- also create custom images from cloud servers you have launched. These
- custom images are useful for backup purposes or for producing "gold"
- server images if you plan to deploy a particular server configuration
- frequently.
-
-Classes
--------
-
-.. autoclass:: ImageManager
- :members: get, list, find, findall, create, delete
-
-.. autoclass:: Image
- :members: delete
-
- .. attribute:: id
-
- This image's ID.
-
- .. attribute:: name
-
- This image's name.
-
- .. attribute:: created
-
- The date/time this image was created.
-
- .. attribute:: updated
-
- The date/time this instance was updated.
-
- .. attribute:: status
-
- The status of this image (usually ``"SAVING"`` or ``ACTIVE``).
-
- .. attribute:: progress
-
- During saving of an image this'll be set to something between
- 0 and 100, representing a rough percentage done.
-
- .. attribute:: serverId
-
- If this image was created from a :class:`Server` then this attribute
- will be set to the ID of the server whence this image came.
View
12 doc/source/ref/index.rst
@@ -1,12 +0,0 @@
-API Reference
-=============
-
-.. toctree::
- :maxdepth: 1
-
- backup_schedules
- exceptions
- flavors
- images
- ipgroups
- servers
View
46 doc/source/ref/ipgroups.rst
@@ -1,46 +0,0 @@
-Shared IP addresses
-===================
-
-From the Rackspace API guide:
-
- Public IP addresses can be shared across multiple servers for use in
- various high availability scenarios. When an IP address is shared to
- another server, the cloud network restrictions are modified to allow each
- server to listen to and respond on that IP address (you may optionally
- specify that the target server network configuration be modified). Shared
- IP addresses can be used with many standard heartbeat facilities (e.g.
- ``keepalived``) that monitor for failure and manage IP failover.
-
- A shared IP group is a collection of servers that can share IPs with other
- members of the group. Any server in a group can share one or more public
- IPs with any other server in the group. With the exception of the first
- server in a shared IP group, servers must be launched into shared IP
- groups. A server may only be a member of one shared IP group.
-
-.. seealso::
-
- Use :meth:`Server.share_ip` and `Server.unshare_ip` to share and unshare
- IPs in a group.
-
-Classes
--------
-
-.. currentmodule:: cinderclient
-
-.. autoclass:: IPGroupManager
- :members: get, list, find, findall, create, delete
-
-.. autoclass:: IPGroup
- :members: delete
-
- .. attribute:: id
-
- Shared group ID.
-
- .. attribute:: name
-
- Name of the group.
-
- .. attribute:: servers
-
- A list of server IDs in this group.
View
73 doc/source/ref/servers.rst
@@ -1,73 +0,0 @@
-Servers
-=======
-
-A virtual machine instance.
-
-Classes
--------
-
-.. currentmodule:: cinderclient
-
-.. autoclass:: ServerManager
- :members: get, list, find, findall, create, update, delete, share_ip,
- unshare_ip, reboot, rebuild, resize, confirm_resize,
- revert_resize
-
-.. autoclass:: Server
- :members: update, delete, share_ip, unshare_ip, reboot, rebuild, resize,
- confirm_resize, revert_resize
-
- .. attribute:: id
-
- This server's ID.
-
- .. attribute:: name
-
- The name you gave the server when you booted it.
-
- .. attribute:: imageId
-
- The :class:`Image` this server was booted with.
-
- .. attribute:: flavorId
-
- This server's current :class:`Flavor`.
-
- .. attribute:: hostId
-
- Rackspace doesn't document this value. It appears to be SHA1 hash.
-
- .. attribute:: status
-
- The server's status (``BOOTING``, ``ACTIVE``, etc).
-
- .. attribute:: progress
-
- When booting, resizing, updating, etc., this will be set to a
- value between 0 and 100 giving a rough estimate of the progress
- of the current operation.
-
- .. attribute:: addresses
-
- The public and private IP addresses of this server. This'll be a dict
- of the form::
-
- {
- "public" : ["67.23.10.138"],
- "private" : ["10.176.42.19"]
- }
-
- You *can* get more than one public/private IP provisioned, but not
- directly from the API; you'll need to open a support ticket.
-
- .. attribute:: metadata
-
- The metadata dict you gave when creating the server.
-
-Constants
----------
-
-Reboot types:
-
-.. data:: REBOOT_SOFT
-.. data:: REBOOT_HARD
View
99 doc/source/releases.rst
@@ -1,99 +0,0 @@
-=============
-Release notes
-=============
-
-2.5.8 (July 11, 2011)
-=====================
-* returns all public/private ips, not just first one
-* better 'cinder list' search options
-
-2.5.7 - 2.5.6 = minor tweaks
-
-2.5.5 (June 21, 2011)
-=====================
-* zone-boot min/max instance count added thanks to comstud
-* create for user added thanks to cerberus
-* fixed tests
-
-2.5.3 (June 15, 2011)
-=====================
-* ProjectID can be None for backwards compatability.
-* README/docs updated for projectId thanks to usrleon
-
-2.5.1 (June 10, 2011)
-=====================
-* ProjectID now part of authentication
-
-2.5.0 (June 3, 2011)
-=================
-
-* better logging thanks to GridDynamics
-
-2.4.4 (June 1, 2011)
-=================
-
-* added support for GET /servers with reservation_id (and /servers/detail)
-
-2.4.3 (May 27, 2011)
-=================
-
-* added support for POST /zones/select (client only, not cmdline)
-
-2.4 (March 7, 2011)
-=================
-
-* added Jacob Kaplan-Moss copyright notices to older/untouched files.
-
-
-2.3 (March 2, 2011)
-=================
-
-* package renamed to python-cinderclient. Module to cinderclient
-
-
-2.2 (March 1, 2011)
-=================
-
-* removed some license/copywrite notices from source that wasn't
- significantly changed.
-
-
-2.1 (Feb 28, 2011)
-=================
-
-* shell renamed to cinder from cindertools
-
-* license changed from BSD to Apache
-
-2.0 (Feb 7, 2011)
-=================
-
-* Forked from https://github.com/jacobian/python-cloudservers
-
-* Rebranded to python-cindertools
-
-* Auth URL support
-
-* New OpenStack specific commands added (pause, suspend, etc)
-
-1.2 (August 15, 2010)
-=====================
-
-* Support for Python 2.4 - 2.7.
-
-* Improved output of :program:`cloudservers ipgroup-list`.
-
-* Made ``cloudservers boot --ipgroup <name>`` work (as well as ``--ipgroup
- <id>``).
-
-1.1 (May 6, 2010)
-=================
-
-* Added a ``--files`` option to :program:`cloudservers boot` supporting
- the upload of (up to five) files at boot time.
-
-* Added a ``--key`` option to :program:`cloudservers boot` to key the server
- with an SSH public key at boot time. This is just a shortcut for ``--files``,
- but it's a useful shortcut.
-
-* Changed the default server image to Ubuntu 10.04 LTS.
View
4 doc/source/shell.rst
@@ -39,9 +39,9 @@ For example, in Bash you'd use::
export OS_TENANT_NAME=myproject
export OS_AUTH_URL=http://...
export OS_VOLUME_API_VERSION=1
-
+
From there, all shell commands take the form::
-
+
cinder <command> [arguments...]
Run :program:`cinder help` to get a full list of all possible commands,
Please sign in to comment.
Something went wrong with that request. Please try again.