Librbd 的 Python 接口

rbd 的 python 模块为 RBD 映像提供了类似文件的访问方法。

实例：创建一映像并写入

要使用 rbd ，必须先连接 RADOS 并打开一个 IO 上下文：

cluster = rados.Rados(conffile='my_ceph.conf')
cluster.connect()
ioctx = cluster.open_ioctx('mypool')

然后实例化一个 :class:rbd.RBD 对象，用它来创建映像：

rbd_inst = rbd.RBD()
size = 4 * 1024**3  # 4 GiB
rbd_inst.create(ioctx, 'myimage', size)

要在映像上进行 I/O 操作，需实例化 :class:rbd.Image 对象：

image = rbd.Image(ioctx, 'myimage')
data = 'foo' * 200
image.write(data, 0)

上面的代码向映像前面写入了 600 字节的 foo 字符串。注意数据不能是 :type:unicode ， librbd 不知道如何处理大于 :c:type:char 宽度的字符。

最后，应该要关闭映像、 IO 上下文和 RADOS 的连接。

image.close()
ioctx.close()
cluster.shutdown()

安全起见，每个调用都应该封装到单独的 :finally 块内。

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()

这样做有些繁琐，所以 Rados 、 Ioctx 和 Image 类可以当上下文管理器来用，它能自动关闭（见 PEP 343 ）。作为上下文管理器使用时，上面的例子可以写成：

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)

API 参考

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.

class rbd.RBD

This class wraps librbd CRUD functions.

clone(self, p_ioctx, p_name, p_snapname, c_ioctx, c_name, features=0, order=None, stripe_unit=0, stripe_count=0)

Clone a parent rbd snapshot into a COW sparse child.

Parameters:	p_ioctx – the parent context that represents the parent snap p_name – the parent image name p_snapname – the parent image snapshot name c_ioctx – the child context that represents the new clone c_name – the clone (child) name features (int) – bitmask of features to enable; if set, must include layering order (int) – the image is split into (2**order) byte objects stripe_unit (int) – stripe unit in bytes (default 0 for object size) stripe_count (int) – objects to stripe over before looping
Raises :	TypeError
Raises :	InvalidArgument
Raises :	ImageExists
Raises :	FunctionNotSupported
Raises :	ArgumentOutOfRange

create(self, ioctx, name, size, order=None, old_format=True, features=0, stripe_unit=0, stripe_count=0)

Create an rbd image.

Parameters:	ioctx (rados.Ioctx) – the context in which to create the image name (str) – what the image is called size (int) – how big the image is in bytes order (int) – the image is split into (2**order) byte objects old_format (bool) – whether to create an old-style image that is accessible by old clients, but can’t use more advanced features like layering. features (int) – bitmask of features to enable stripe_unit (int) – stripe unit in bytes (default 0 for object size) stripe_count (int) – objects to stripe over before looping
Raises :	ImageExists
Raises :	TypeError
Raises :	InvalidArgument
Raises :	FunctionNotSupported

list(self, ioctx)

List image names.

Parameters:	ioctx (rados.Ioctx) – determines which RADOS pool is read
Returns:	list – a list of image names

remove(self, ioctx, name)

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:	ioctx (rados.Ioctx) – determines which RADOS pool the image is in name (str) – the name of the image to remove
Raises :	ImageNotFound, ImageBusy, ImageHasSnapshots

rename(self, ioctx, src, dest)

Rename an RBD image.

Parameters:	ioctx (rados.Ioctx) – determines which RADOS pool the image is in src (str) – the current name of the image dest (str) – the new name of the image
Raises :	ImageNotFound, ImageExists

version(self)

Get the version number of the librbd C library.

Returns:	a tuple of (major, minor, extra) components of the librbd version

class rbd.Image

Image(ioctx, name, snapshot=None, read_only=False)

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.

break_lock(self, client, cookie)

Release a lock held by another rados client.

close(self)

Release the resources used by this image object.

After this is called, this object should not be used.

copy(self, dest_ioctx, dest_name, features=0, order=None, stripe_unit=0, stripe_count=0)

Copy the image to another location.

Parameters:	dest_ioctx (rados.Ioctx) – determines which pool to copy into dest_name (str) – the name of the copy features (int) – bitmask of features to enable; if set, must include layering order (int) – the image is split into (2**order) byte objects stripe_unit (int) – stripe unit in bytes (default 0 for object size) stripe_count (int) – objects to stripe over before looping
Raises :	TypeError
Raises :	InvalidArgument
Raises :	ImageExists
Raises :	FunctionNotSupported
Raises :	ArgumentOutOfRange

create_snap(self, name)

Create a snapshot of the image.

Parameters:	name (str) – the name of the snapshot
Raises :	ImageExists

diff_iterate(self, offset, length, from_snapshot, iterate_cb, include_parent=True, whole_object=False)

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.

iterate_cb may raise an exception, which will abort the diff and will be propagated to the caller.

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:

offset (int) – start offset in bytes length (int) – size of region to report on, in bytes from_snapshot (str or None) – starting snapshot name, or None iterate_cb (function acception arguments for offset, length, and exists) – function to call for each extent include_parent (bool) – True if full history diff should include parent whole_object (bool) – True if diff extents should cover whole object

Raises :

InvalidArgument, IOError, ImageNotFound

discard(self, offset, length)

Trim the range from the image. It will be logically filled with zeroes.

features(self)

Gets the features bitmask of the image.

Returns:	int - the features bitmask of the image

flags(self)

Gets the flags bitmask of the image.

Returns:	int - the flags bitmask of the image

flatten(self)

Flatten clone image (copy all blocks from parent to child)

flush(self)

Block until all writes are fully flushed if caching is enabled.

invalidate_cache(self)

Drop any cached data for the image.

is_exclusive_lock_owner(self)

Gets the status of the image exclusive lock.

Returns:	bool - true if the image is exclusively locked

is_protected_snap(self, name)

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(self)

List children of the currently set snapshot (set via set_snap()).

Returns:	list - a list of (pool name, image name) tuples

list_lockers(self)

List clients that have locked the image and information about the lock.

Returns:	dict - contains the following keys: tag - the tag associated with the lock (every additional locker must use the same tag) exclusive - boolean indicating whether the lock is exclusive or shared lockers - a list of (client, cookie, address) tuples

list_snaps(self)

Iterate over the snapshots of an image.

Returns:	SnapIterator

lock_exclusive(self, cookie)

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

lock_shared(self, cookie, tag)

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

old_format(self)

Find out whether the image uses the old RBD format.

Returns:	bool - whether the image uses the old RBD format

overlap(self)

Gets the number of overlapping bytes between the image and its parent image. If open to a snapshot, returns the overlap between the snapshot and the parent image.

Returns:	int - the overlap in bytes
Raises :	ImageNotFound if the image doesn’t have a parent

parent_info(self)

Get information about a cloned image’s parent (if any)

Returns:	tuple - (pool name, image name, snapshot name) components of the parent image
Raises :	ImageNotFound if the image doesn’t have a parent

protect_snap(self, name)

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(self, offset, length, fadvise_flags=0)

Read data from the image. Raises InvalidArgument if part of the range specified is outside the image.

Parameters:	offset (int) – the offset to start reading at length (int) – how many bytes to read fadvise_flags (int) – fadvise flags for this read
Returns:	str - the data read
Raises :	InvalidArgument, IOError

rebuild_object_map(self)

Rebuilds the object map for the image HEAD or currently set snapshot

remove_snap(self, name)

Delete a snapshot of the image.

Parameters:	name (str) – the name of the snapshot
Raises :	IOError, ImageBusy

rename_snap(self, srcname, dstname)

rename a snapshot of the image.

Parameters:	srcname (str) – the src name of the snapshot dstname (str) – the dst name of the snapshot
Raises :	ImageExists

resize(self, size)

Change the size of the image.

Parameters:	size (int) – the new size of the image

rollback_to_snap(self, name)

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_snap(self, name)

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

size(self)

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

stat(self)

Get information about the image. Currently parent pool and parent name are always -1 and ‘’.

Returns:

dict - contains the following keys: size (int) - the size of the image in bytes obj_size (int) - the size of each object that comprises the image num_objs (int) - the number of objects in the image order (int) - log_2(object_size) block_name_prefix (str) - the prefix of the RADOS objects used to store the image parent_pool (int) - deprecated parent_name (str) - deprecated See also format() and features().

stripe_count(self)

Returns the stripe count used for the image.

stripe_unit(self)

Returns the stripe unit used for the image.

unlock(self, cookie)

Release a lock on the image that was locked by this rados client.

unprotect_snap(self, name)

Mark a snapshot unprotected. This allows it to be deleted if it was protected.

Parameters:	name (str) – the snapshot to unprotect
Raises :	IOError, ImageNotFound

update_features(self, features, enabled)

Updates the features bitmask of the image by enabling/disabling a single feature. The feature must support the ability to be dynamically enabled/disabled.

Parameters:	features (int) – feature bitmask to enable/disable enabled (bool) – whether to enable/disable the feature
Raises :	InvalidArgument

write(self, data, offset, fadvise_flags=0)

Write data to the image. Raises InvalidArgument if part of the write would fall outside the image.

Parameters:	data (bytes) – the data to be written offset (int) – where to start writing data fadvise_flags (int) – fadvise flags for this write
Returns:	int - the number of bytes written
Raises :	IncompleteWriteError, LogicError, InvalidArgument, IOError

class rbd.SnapIterator

SnapIterator(Image image)

Iterator over snapshot info for an image.

Yields a dictionary containing information about a snapshot.

Keys are:

• id (int) - numeric identifier of the snapshot
• size (int) - size of the image at the time of snapshot (in bytes)
• name (str) - name of the snapshot