You can create your own Ceph client using Python. The following tutorial will
show you how to import the Ceph Python module, connect to a Ceph cluster, and
-perform object operations as a ``client.admin`` user.
+perform object operations as a ``client.admin`` user.
-.. note:: To use the Ceph Python bindings, you must have access to a
+.. note:: To use the Ceph Python bindings, you must have access to a
running Ceph cluster. To set one up quickly, see `Getting Started`_.
First, create a Python source file for your Ceph client. ::
:linenos:
-
+
sudo vim client.py
:linenos:
import rados, sys
-
+
#Create Handle Examples.
cluster = rados.Rados(conffile='ceph.conf')
cluster = rados.Rados(conffile=sys.argv[1])
Ensure that the ``conffile`` argument provides the path and file name of your
Ceph configuration file. You may use the ``sys`` module to avoid hard-coding the
-Ceph configuration path and file name.
+Ceph configuration path and file name.
Your Python client also requires a client keyring. For this example, we use the
``client.admin`` key by default. If you would like to specify the keyring when
creating the cluster handle, you may use the ``conf`` argument. Alternatively,
-you may specify the keyring path in your Ceph configuration file. For example,
-you may add something like the following line to you Ceph configuration file::
+you may specify the keyring path in your Ceph configuration file. For example,
+you may add something like the following line to you Ceph configuration file::
keyring = /path/to/ceph.client.admin.keyring
Connect to the Cluster
----------------------
-Once you have a cluster handle configured, you may connect to the cluster.
+Once you have a cluster handle configured, you may connect to the cluster.
With a connection to the cluster, you may execute methods that return
information about the cluster.
:emphasize-lines: 7
import rados, sys
-
+
cluster = rados.Rados(conffile='ceph.conf')
print "\nlibrados version: " + str(cluster.version())
- print "Will attempt to connect to: " + str(cluster.conf_get('mon initial members'))
-
+ print "Will attempt to connect to: " + str(cluster.conf_get('mon initial members'))
+
cluster.connect()
print "\nCluster ID: " + cluster.get_fsid()
.. code-block:: ini
:linenos:
-
+
[global]
- ...
+ # ... elided configuration
keyring=/path/to/keyring/ceph.client.admin.keyring
When connected to the cluster, the ``Rados`` API allows you to manage pools. You
can list pools, check for the existence of a pool, create a pool and delete a
-pool.
+pool.
.. code-block:: python
:linenos:
--------------------
Reading from and writing to the Ceph Storage Cluster requires an input/output
-context (ioctx). You can create an ioctx with the ``open_ioctx()`` method of the
-``Rados`` class. The ``ioctx_name`` parameter is the name of the pool you wish
-to use.
+context (ioctx). You can create an ioctx with the ``open_ioctx()`` or
+``open_ioctx2()`` method of the ``Rados`` class. The ``ioctx_name`` parameter
+is the name of the pool and ``pool_id`` is the ID of the pool you wish to use.
.. code-block:: python
:linenos:
ioctx = cluster.open_ioctx('data')
+or
+
+.. code-block:: python
+ :linenos:
+
+ ioctx = cluster.open_ioctx2(pool_id)
+
+
Once you have an I/O context, you can read/write objects, extended attributes,
and perform a number of other operations. After you complete operations, ensure
-that you close the connection. For example:
+that you close the connection. For example:
.. code-block:: python
:linenos:
write to an object that doesn't exist, Ceph creates it. If you write to an
object that exists, Ceph overwrites it (except when you specify a range, and
then it only overwrites the range). You may read objects (and object ranges)
-from the cluster. You may also remove objects from the cluster. For example:
+from the cluster. You may also remove objects from the cluster. For example:
.. code-block:: python
:linenos:
:emphasize-lines: 2, 5, 8
-
+
print "\nWriting object 'hw' with contents 'Hello World!' to pool 'data'."
ioctx.write_full("hw", "Hello World!")
print "\n\nContents of object 'hw'\n------------------------\n"
print ioctx.read("hw")
-
+
print "\nRemoving object 'hw'"
ioctx.remove_object("hw")
--------------------------
Once you create an object, you can write extended attributes (XATTRs) to
-the object and read XATTRs from the object. For example:
+the object and read XATTRs from the object. For example:
.. code-block:: python
:linenos:
Listing Objects
---------------
-If you want to examine the list of objects in a pool, you may
+If you want to examine the list of objects in a pool, you may
retrieve the list of objects and iterate over them with the object iterator.
For example:
object_iterator = ioctx.list_objects()
- while True :
-
- try :
+ while True :
+
+ try :
rados_object = object_iterator.next()
print "Object contents = " + rados_object.read()
-
+
except StopIteration :
break
-------------
The ``Rados`` class provides methods for getting and setting configuration
-values, reading the Ceph configuration file, and parsing arguments. You
+values, reading the Ceph configuration file, and parsing arguments. You
do not need to be connected to the Ceph Storage Cluster to invoke the following
methods. See `Storage Cluster Configuration`_ for details on settings.
.. automethod:: Rados.conf_set(option, val)
.. automethod:: Rados.conf_read_file(path=None)
.. automethod:: Rados.conf_parse_argv(args)
-.. automethod:: Rados.version()
+.. automethod:: Rados.version()
Connection Management
from the cluster. You may also assert that the cluster handle is in a particular
state (e.g., "configuring", "connecting", etc.).
-
.. automethod:: Rados.connect(timeout=0)
.. automethod:: Rados.shutdown()
.. automethod:: Rados.get_fsid()
.. automethod:: Rados.get_cluster_stats()
-.. automethod:: Rados.require_state(*args)
+
+.. documented manually because it raises warnings because of *args usage in the
+.. signature
+
+.. py:class:: Rados
+
+ .. py:method:: require_state(*args)
+
+ Checks if the Rados object is in a special state
+
+ :param args: Any number of states to check as separate arguments
+ :raises: :class:`RadosStateError`
Pool Operations
exists, and delete a pool.
.. automethod:: Rados.list_pools()
-.. automethod:: Rados.create_pool(pool_name, auid=None, crush_rule=None)
+.. automethod:: Rados.create_pool(pool_name, crush_rule=None)
.. automethod:: Rados.pool_exists()
.. automethod:: Rados.delete_pool(pool_name)
========================
To write data to and read data from the Ceph Object Store, you must create
-an Input/Output context (ioctx). The `Rados` class provides a `open_ioctx()`
-method. The remaining ``ioctx`` operations involve invoking methods of the
-`Ioctx` and other classes.
+an Input/Output context (ioctx). The `Rados` class provides `open_ioctx()`
+and `open_ioctx2()` methods. The remaining ``ioctx`` operations involve
+invoking methods of the `Ioctx` and other classes.
.. automethod:: Rados.open_ioctx(ioctx_name)
.. automethod:: Ioctx.require_ioctx_open()
.. automethod:: Ioctx.get_stats()
-.. automethod:: Ioctx.change_auid(auid)
.. automethod:: Ioctx.get_last_version()
.. automethod:: Ioctx.close()
.. --------------
.. The Ceph Storage Cluster allows you to make a snapshot of a pool's state.
-.. Whereas, basic pool operations only require a connection to the cluster,
+.. Whereas, basic pool operations only require a connection to the cluster,
.. snapshots require an I/O context.
.. Ioctx.create_snap(self, snap_name)
.. automethod:: Ioctx.set_xattr(key, xattr_name, xattr_value)
.. automethod:: Ioctx.get_xattrs(oid)
-.. automethod:: XattrIterator.next()
+.. automethod:: XattrIterator.__next__()
.. automethod:: Ioctx.get_xattr(key, xattr_name)
.. automethod:: Ioctx.rm_xattr(key, xattr_name)
operations, you should use the I/O context methods.
.. automethod:: Ioctx.list_objects()
-.. automethod:: ObjectIterator.next()
+.. automethod:: ObjectIterator.__next__()
.. automethod:: Object.read(length = 1024*1024)
.. automethod:: Object.write(string_to_write)
.. automethod:: Object.get_xattrs()
projects / ceph.git / blobdiff