5 The ``rados`` module is a thin Python wrapper for ``librados``.
10 To install Python libraries for Ceph, see `Getting librados for Python`_.
16 You can create your own Ceph client using Python. The following tutorial will
17 show you how to import the Ceph Python module, connect to a Ceph cluster, and
18 perform object operations as a ``client.admin`` user.
20 .. note:: To use the Ceph Python bindings, you must have access to a
21 running Ceph cluster. To set one up quickly, see `Getting Started`_.
23 First, create a Python source file for your Ceph client. ::
32 To use the ``rados`` module, import it into your source file.
34 .. code-block:: python
40 Configure a Cluster Handle
41 --------------------------
43 Before connecting to the Ceph Storage Cluster, create a cluster handle. By
44 default, the cluster handle assumes a cluster named ``ceph`` (i.e., the default
45 for deployment tools, and our Getting Started guides too), and a
46 ``client.admin`` user name. You may change these defaults to suit your needs.
48 To connect to the Ceph Storage Cluster, your application needs to know where to
49 find the Ceph Monitor. Provide this information to your application by
50 specifying the path to your Ceph configuration file, which contains the location
51 of the initial Ceph monitors.
53 .. code-block:: python
58 #Create Handle Examples.
59 cluster = rados.Rados(conffile='ceph.conf')
60 cluster = rados.Rados(conffile=sys.argv[1])
61 cluster = rados.Rados(conffile = 'ceph.conf', conf = dict (keyring = '/path/to/keyring'))
63 Ensure that the ``conffile`` argument provides the path and file name of your
64 Ceph configuration file. You may use the ``sys`` module to avoid hard-coding the
65 Ceph configuration path and file name.
67 Your Python client also requires a client keyring. For this example, we use the
68 ``client.admin`` key by default. If you would like to specify the keyring when
69 creating the cluster handle, you may use the ``conf`` argument. Alternatively,
70 you may specify the keyring path in your Ceph configuration file. For example,
71 you may add something like the following line to you Ceph configuration file::
73 keyring = /path/to/ceph.client.admin.keyring
75 For additional details on modifying your configuration via Python, see `Configuration`_.
78 Connect to the Cluster
79 ----------------------
81 Once you have a cluster handle configured, you may connect to the cluster.
82 With a connection to the cluster, you may execute methods that return
83 information about the cluster.
85 .. code-block:: python
91 cluster = rados.Rados(conffile='ceph.conf')
92 print("\nlibrados version: {}".format(str(cluster.version())))
93 print("Will attempt to connect to: {}".format(str(cluster.conf_get('mon host'))))
96 print("\nCluster ID: {}".format(cluster.get_fsid()))
98 print("\n\nCluster Statistics")
99 print("==================")
100 cluster_stats = cluster.get_cluster_stats()
102 for key, value in cluster_stats.items():
106 By default, Ceph authentication is ``on``. Your application will need to know
107 the location of the keyring. The ``python-ceph`` module doesn't have the default
108 location, so you need to specify the keyring path. The easiest way to specify
109 the keyring is to add it to the Ceph configuration file. The following Ceph
110 configuration file example uses the ``client.admin`` keyring.
116 # ... elided configuration
117 keyring=/path/to/keyring/ceph.client.admin.keyring
123 When connected to the cluster, the ``Rados`` API allows you to manage pools. You
124 can list pools, check for the existence of a pool, create a pool and delete a
127 .. code-block:: python
129 :emphasize-lines: 6, 13, 18, 25
131 print("\n\nPool Operations")
132 print("===============")
134 print("\nAvailable Pools")
135 print("----------------")
136 pools = cluster.list_pools()
141 print("\nCreate 'test' Pool")
142 print("------------------")
143 cluster.create_pool('test')
145 print("\nPool named 'test' exists: {}".format(str(cluster.pool_exists('test'))))
146 print("\nVerify 'test' Pool Exists")
147 print("-------------------------")
148 pools = cluster.list_pools()
153 print("\nDelete 'test' Pool")
154 print("------------------")
155 cluster.delete_pool('test')
156 print("\nPool named 'test' exists: {}".format(str(cluster.pool_exists('test'))))
162 Reading from and writing to the Ceph Storage Cluster requires an input/output
163 context (ioctx). You can create an ioctx with the ``open_ioctx()`` or
164 ``open_ioctx2()`` method of the ``Rados`` class. The ``ioctx_name`` parameter
165 is the name of the pool and ``pool_id`` is the ID of the pool you wish to use.
167 .. code-block:: python
170 ioctx = cluster.open_ioctx('data')
175 .. code-block:: python
178 ioctx = cluster.open_ioctx2(pool_id)
181 Once you have an I/O context, you can read/write objects, extended attributes,
182 and perform a number of other operations. After you complete operations, ensure
183 that you close the connection. For example:
185 .. code-block:: python
188 print("\nClosing the connection.")
192 Writing, Reading and Removing Objects
193 -------------------------------------
195 Once you create an I/O context, you can write objects to the cluster. If you
196 write to an object that doesn't exist, Ceph creates it. If you write to an
197 object that exists, Ceph overwrites it (except when you specify a range, and
198 then it only overwrites the range). You may read objects (and object ranges)
199 from the cluster. You may also remove objects from the cluster. For example:
201 .. code-block:: python
203 :emphasize-lines: 2, 5, 8
205 print("\nWriting object 'hw' with contents 'Hello World!' to pool 'data'.")
206 ioctx.write_full("hw", "Hello World!")
208 print("\n\nContents of object 'hw'\n------------------------\n")
209 print(ioctx.read("hw"))
211 print("\nRemoving object 'hw'")
212 ioctx.remove_object("hw")
215 Writing and Reading XATTRS
216 --------------------------
218 Once you create an object, you can write extended attributes (XATTRs) to
219 the object and read XATTRs from the object. For example:
221 .. code-block:: python
223 :emphasize-lines: 2, 5
225 print("\n\nWriting XATTR 'lang' with value 'en_US' to object 'hw'")
226 ioctx.set_xattr("hw", "lang", "en_US")
228 print("\n\nGetting XATTR 'lang' from object 'hw'\n")
229 print(ioctx.get_xattr("hw", "lang"))
235 If you want to examine the list of objects in a pool, you may
236 retrieve the list of objects and iterate over them with the object iterator.
239 .. code-block:: python
241 :emphasize-lines: 1, 6, 7, 13
243 object_iterator = ioctx.list_objects()
248 rados_object = object_iterator.__next__()
249 print("Object contents = {}".format(rados_object.read()))
251 except StopIteration :
255 [print("Object contents = {}".format(obj.read())) for obj in ioctx.list_objects()]
257 The ``Object`` class provides a file-like interface to an object, allowing
258 you to read and write content and extended attributes. Object operations using
259 the I/O context provide additional functionality and asynchronous capabilities.
265 The ``Rados`` class provides an interface into the Ceph Storage Daemon.
271 The ``Rados`` class provides methods for getting and setting configuration
272 values, reading the Ceph configuration file, and parsing arguments. You
273 do not need to be connected to the Ceph Storage Cluster to invoke the following
274 methods. See `Storage Cluster Configuration`_ for details on settings.
276 .. currentmodule:: rados
277 .. automethod:: Rados.conf_get(option)
278 .. automethod:: Rados.conf_set(option, val)
279 .. automethod:: Rados.conf_read_file(path=None)
280 .. automethod:: Rados.conf_parse_argv(args)
281 .. automethod:: Rados.version()
284 Connection Management
285 ---------------------
287 Once you configure your cluster handle, you may connect to the cluster, check
288 the cluster ``fsid``, retrieve cluster statistics, and disconnect (shutdown)
289 from the cluster. You may also assert that the cluster handle is in a particular
290 state (e.g., "configuring", "connecting", etc.).
292 .. automethod:: Rados.connect(timeout=0)
293 .. automethod:: Rados.shutdown()
294 .. automethod:: Rados.get_fsid()
295 .. automethod:: Rados.get_cluster_stats()
297 .. documented manually because it raises warnings because of *args usage in the
302 .. py:method:: require_state(*args)
304 Checks if the Rados object is in a special state
306 :param args: Any number of states to check as separate arguments
307 :raises: :class:`RadosStateError`
313 To use pool operation methods, you must connect to the Ceph Storage Cluster
314 first. You may list the available pools, create a pool, check to see if a pool
315 exists, and delete a pool.
317 .. automethod:: Rados.list_pools()
318 .. automethod:: Rados.create_pool(pool_name, crush_rule=None)
319 .. automethod:: Rados.pool_exists()
320 .. automethod:: Rados.delete_pool(pool_name)
326 The Ceph CLI command is internally using the following librados Python binding methods.
328 In order to send a command, choose the correct method and choose the correct target.
330 .. automethod:: Rados.mon_command
331 .. automethod:: Rados.osd_command
332 .. automethod:: Rados.mgr_command
333 .. automethod:: Rados.pg_command
336 Input/Output Context API
337 ========================
339 To write data to and read data from the Ceph Object Store, you must create
340 an Input/Output context (ioctx). The `Rados` class provides `open_ioctx()`
341 and `open_ioctx2()` methods. The remaining ``ioctx`` operations involve
342 invoking methods of the `Ioctx` and other classes.
344 .. automethod:: Rados.open_ioctx(ioctx_name)
345 .. automethod:: Ioctx.require_ioctx_open()
346 .. automethod:: Ioctx.get_stats()
347 .. automethod:: Ioctx.get_last_version()
348 .. automethod:: Ioctx.close()
354 .. The Ceph Storage Cluster allows you to make a snapshot of a pool's state.
355 .. Whereas, basic pool operations only require a connection to the cluster,
356 .. snapshots require an I/O context.
358 .. Ioctx.create_snap(self, snap_name)
359 .. Ioctx.list_snaps(self)
360 .. SnapIterator.next(self)
361 .. Snap.get_timestamp(self)
362 .. Ioctx.lookup_snap(self, snap_name)
363 .. Ioctx.remove_snap(self, snap_name)
365 .. not published. This doesn't seem ready yet.
370 The Ceph Storage Cluster stores data as objects. You can read and write objects
371 synchronously or asynchronously. You can read and write from offsets. An object
372 has a name (or key) and data.
375 .. automethod:: Ioctx.aio_write(object_name, to_write, offset=0, oncomplete=None, onsafe=None)
376 .. automethod:: Ioctx.aio_write_full(object_name, to_write, oncomplete=None, onsafe=None)
377 .. automethod:: Ioctx.aio_append(object_name, to_append, oncomplete=None, onsafe=None)
378 .. automethod:: Ioctx.write(key, data, offset=0)
379 .. automethod:: Ioctx.write_full(key, data)
380 .. automethod:: Ioctx.aio_flush()
381 .. automethod:: Ioctx.set_locator_key(loc_key)
382 .. automethod:: Ioctx.aio_read(object_name, length, offset, oncomplete)
383 .. automethod:: Ioctx.read(key, length=8192, offset=0)
384 .. automethod:: Ioctx.stat(key)
385 .. automethod:: Ioctx.trunc(key, size)
386 .. automethod:: Ioctx.remove_object(key)
389 Object Extended Attributes
390 --------------------------
392 You may set extended attributes (XATTRs) on an object. You can retrieve a list
393 of objects or XATTRs and iterate over them.
395 .. automethod:: Ioctx.set_xattr(key, xattr_name, xattr_value)
396 .. automethod:: Ioctx.get_xattrs(oid)
397 .. automethod:: XattrIterator.__next__()
398 .. automethod:: Ioctx.get_xattr(key, xattr_name)
399 .. automethod:: Ioctx.rm_xattr(key, xattr_name)
406 From an I/O context, you can retrieve a list of objects from a pool and iterate
407 over them. The object interface provide makes each object look like a file, and
408 you may perform synchronous operations on the objects. For asynchronous
409 operations, you should use the I/O context methods.
411 .. automethod:: Ioctx.list_objects()
412 .. automethod:: ObjectIterator.__next__()
413 .. automethod:: Object.read(length = 1024*1024)
414 .. automethod:: Object.write(string_to_write)
415 .. automethod:: Object.get_xattrs()
416 .. automethod:: Object.get_xattr(xattr_name)
417 .. automethod:: Object.set_xattr(xattr_name, xattr_value)
418 .. automethod:: Object.rm_xattr(xattr_name)
419 .. automethod:: Object.stat()
420 .. automethod:: Object.remove()
425 .. _Getting Started: ../../../start
426 .. _Storage Cluster Configuration: ../../configuration
427 .. _Getting librados for Python: ../librados-intro#getting-librados-for-python