openstack/python-cinderclient
Code Issues Proposed changes

Docs in cinderlcient were never actually updated.

Browse Source 
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
This commit is contained in:
john-griffith
2013-03-19 00:24:32 -06:00
parent f2ac10f282
commit 020778ddd9
11 changed files with 46 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
doc/source/api.rst
View File

@@ -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

70
doc/source/index.rst
View File

@@ -1,34 +1,52 @@
Python bindings to the OpenStack Cinder API
==================================================
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::
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.
>>> 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
Contents:
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::
.. toctree::
:maxdepth: 2
export OS_USERNAME=user
export OS_PASSWORD=pass
export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
export OS_AUTH_URL=http://auth.example.com:5000/v2.0
shell
api
ref/index
releases
Once you've configured your authentication parameters, you can run ``cinder help`` to see a complete listing of available commands.
Contributing
============
Development takes place `on GitHub`__; please file bugs/pull requests there.
Release Notes
=============
__ https://github.com/openstack/python-cinderclient
Run tests with ``python setup.py test``.
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
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

60
doc/source/ref/backup_schedules.rst
View File

@@ -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

14
doc/source/ref/exceptions.rst
View File

@@ -1,14 +0,0 @@
Exceptions
==========
.. currentmodule:: cinderclient
Exceptions
----------
Exceptions that the API might throw:
.. automodule:: cinderclient
:members: OpenStackException, BadRequest, Unauthorized, Forbidden,
NotFound, OverLimit

35
doc/source/ref/flavors.rst
View File

@@ -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

54
doc/source/ref/images.rst
View File

@@ -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.

12
doc/source/ref/index.rst
View File

@@ -1,12 +0,0 @@
API Reference
=============
.. toctree::
:maxdepth: 1
backup_schedules
exceptions
flavors
images
ipgroups
servers

46
doc/source/ref/ipgroups.rst
View File

@@ -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.

73
doc/source/ref/servers.rst
View File

@@ -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

99
doc/source/releases.rst
View File

@@ -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.

4
doc/source/shell.rst
View File

@@ -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,