The rbd python module provides file-like access to RBD images.
To use rbd, you must first connect to RADOS and open an IO context:
cluster = rados.Rados(conffile='my_ceph.conf')
cluster.connect()
ioctx = cluster.open_ioctx('mypool')
Then you instantiate an :class:rbd.RBD object, which you use to create the image:
rbd_inst = rbd.RBD()
size = 4 * 1024**3 # 4 GiB
rbd_inst.create(ioctx, 'myimage', size)
To perform I/O on the image, you instantiate an :class:rbd.Image object:
image = rbd.Image(ioctx, 'myimage')
data = 'foo' * 200
image.write(data, 0)
This writes ‘foo’ to the first 600 bytes of the image. Note that data cannot be :type:unicode - Librbd does not know how to deal with characters wider than a :c:type:char.
In the end, you’ll want to close the image, the IO context and the connection to RADOS:
image.close()
ioctx.close()
cluster.shutdown()
To be safe, each of these calls would need to be in a separate :finally block:
cluster = rados.Rados(conffile='my_ceph_conf')
try:
ioctx = cluster.open_ioctx('my_pool')
try:
rbd_inst = rbd.RBD()
size = 4 * 1024**3 # 4 GiB
rbd_inst.create(ioctx, 'myimage', size)
image = rbd.Image(ioctx, 'myimage')
try:
data = 'foo' * 200
image.write(data, 0)
finally:
image.close()
finally:
ioctx.close()
finally:
cluster.shutdown()
This can be cumbersome, so the Rados, Ioctx, and Image classes can be used as context managers that close/shutdown automatically (see PEP 343). Using them as context managers, the above example becomes:
with rados.Rados(conffile='my_ceph.conf') as cluster:
with cluster.open_ioctx('mypool') as ioctx:
rbd_inst = rbd.RBD()
size = 4 * 1024**3 # 4 GiB
rbd_inst.create(ioctx, 'myimage', size)
with rbd.Image(ioctx, 'myimage') as image:
data = 'foo' * 200
image.write(data, 0)
This module is a thin wrapper around librbd.
It currently provides all the synchronous methods of librbd that do not use callbacks.
Error codes from librbd are turned into exceptions that subclass Error. Almost all methods may raise Error (the base class of all rbd exceptions), PermissionError and IOError, in addition to those documented for the method.
A number of methods have string arguments, which must not be unicode to interact correctly with librbd. If unicode is passed to these methods, a TypeError will be raised.
This class wraps librbd CRUD functions.
Clone a parent rbd snapshot into a COW sparse child.
Parameters: |
|
---|---|
Raises : | TypeError |
Raises : | InvalidArgument |
Raises : | ImageExists |
Raises : | FunctionNotSupported |
Raises : | ArgumentOutOfRange |
Create an rbd image.
Parameters: |
|
---|---|
Raises : | ImageExists |
Raises : | TypeError |
Raises : | InvalidArgument |
Raises : | FunctionNotSupported |
List image names.
Parameters: | ioctx (rados.Ioctx) – determines which RADOS pool is read |
---|---|
Returns: | list – a list of image names |
Delete an RBD image. This may take a long time, since it does not return until every object that comprises the image has been deleted. Note that all snapshots must be deleted before the image can be removed. If there are snapshots left, ImageHasSnapshots is raised. If the image is still open, or the watch from a crashed client has not expired, ImageBusy is raised.
Parameters: |
|
---|---|
Raises : | ImageNotFound, ImageBusy, ImageHasSnapshots |
Rename an RBD image.
Parameters: |
|
---|---|
Raises : | ImageNotFound, ImageExists |
Get the version number of the librbd C library.
Returns: | a tuple of (major, minor, extra) components of the librbd version |
---|
This class represents an RBD image. It is used to perform I/O on the image and interact with snapshots.
Note: Any method of this class may raise ImageNotFound if the image has been deleted.
Release a lock held by another rados client.
Release the resources used by this image object.
After this is called, this object should not be used.
Copy the image to another location.
Parameters: |
|
---|---|
Raises : | ImageExists |
Create a snapshot of the image.
Parameters: | name (str) – the name of the snapshot |
---|---|
Raises : | ImageExists |
Iterate over the changed extents of an image.
This will call iterate_cb with three arguments:
(offset, length, exists)
where the changed extent starts at offset bytes, continues for length bytes, and is full of data (if exists is True) or zeroes (if exists is False).
If from_snapshot is None, it is interpreted as the beginning of time and this generates all allocated extents.
The end version is whatever is currently selected (via set_snap) for the image.
Raises InvalidArgument if from_snapshot is after the currently set snapshot.
Raises ImageNotFound if from_snapshot is not the name of a snapshot of the image.
Parameters: |
|
---|---|
Raises : | InvalidArgument, IOError, ImageNotFound |
Trim the range from the image. It will be logically filled with zeroes.
Flatten clone image (copy all blocks from parent to child)
Block until all writes are fully flushed if caching is enabled.
Find out whether a snapshot is protected from deletion.
Parameters: | name (str) – the snapshot to check |
---|---|
Returns: | bool - whether the snapshot is protected |
Raises : | IOError, ImageNotFound |
List children of the currently set snapshot (set via set_snap()).
Returns: | list - a list of (pool name, image name) tuples |
---|
List clients that have locked the image and information about the lock.
Returns: | dict - contains the following keys:
|
---|
Iterate over the snapshots of an image.
Returns: | SnapIterator |
---|
Take an exclusive lock on the image.
Raises : | ImageBusy if a different client or cookie locked it ImageExists if the same client and cookie locked it |
---|
Take a shared lock on the image. The tag must match that of the existing lockers, if any.
Raises : | ImageBusy if a different client or cookie locked it ImageExists if the same client and cookie locked it |
---|
Mark a snapshot as protected. This means it can’t be deleted until it is unprotected.
Parameters: | name (str) – the snapshot to protect |
---|---|
Raises : | IOError, ImageNotFound |
Read data from the image. Raises InvalidArgument if part of the range specified is outside the image.
Parameters: |
|
---|---|
Returns: | str - the data read |
Raises : | InvalidArgument, IOError |
Delete a snapshot of the image.
Parameters: | name (str) – the name of the snapshot |
---|---|
Raises : | IOError, ImageBusy |
Change the size of the image.
Parameters: | size (int) – the new size of the image |
---|
Revert the image to its contents at a snapshot. This is a potentially expensive operation, since it rolls back each object individually.
Parameters: | name (str) – the snapshot to rollback to |
---|---|
Raises : | IOError |
Set the snapshot to read from. Writes will raise ReadOnlyImage while a snapshot is set. Pass None to unset the snapshot (reads come from the current image) , and allow writing again.
Parameters: | name (str or None) – the snapshot to read from, or None to unset the snapshot |
---|
Get the size of the image. If open to a snapshot, returns the size of that snapshot.
Returns: | the size of the image in bytes |
---|
Get information about the image. Currently parent pool and parent name are always -1 and ‘’.
Returns: | dict - contains the following keys:
See also format() and features(). |
---|
Returns the stripe count used for the image.
Returns the stripe unit used for the image.
Release a lock on the image that was locked by this rados client.
Mark a snapshot unprotected. This allows it to be deleted if it was protected.
Parameters: | name (str) – the snapshot to unprotect |
---|---|
Raises : | IOError, ImageNotFound |
Write data to the image. Raises InvalidArgument if part of the write would fall outside the image.
Parameters: |
|
---|---|
Returns: | int - the number of bytes written |
Raises : | IncompleteWriteError, LogicError, InvalidArgument, IOError |
Iterator over snapshot info for an image.
Yields a dictionary containing information about a snapshot.
Keys are: