Example: Creating and writing to an image

To userbd, you must first connect to RADOS and open an IOcontext:

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 theimage:

rbd_inst=rbd.RBD()size=4*1024**3# 4 GiBrbd_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=b'foo'*200image.write(data,0)

This writes ‘foo’ to the first 600 bytes of the image. Note that datacannot be :type:unicode -Librbd does not know how to deal withcharacters wider than a :c:type:char.

In the end, you will 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 :finallyblock:

cluster=rados.Rados(conffile='my_ceph_conf')try:cluster.connect()ioctx=cluster.open_ioctx('my_pool')try:rbd_inst=rbd.RBD()size=4*1024**3# 4 GiBrbd_inst.create(ioctx,'myimage',size)image=rbd.Image(ioctx,'myimage')try:data=b'foo'*200image.write(data,0)finally:image.close()finally:ioctx.close()finally:cluster.shutdown()

This can be cumbersome, so theRados,Ioctx, andImage classes can be used as context managers that close/shutdownautomatically (seePEP 343). Using them as context managers, theabove example becomes:

withrados.Rados(conffile='my_ceph.conf')ascluster:withcluster.open_ioctx('mypool')asioctx:rbd_inst=rbd.RBD()size=4*1024**3# 4 GiBrbd_inst.create(ioctx,'myimage',size)withrbd.Image(ioctx,'myimage')asimage:data=b'foo'*200image.write(data,0)

API Reference

This module is a thin wrapper around librbd.

It currently provides all the synchronous methods of librbd that donot use callbacks.

Error codes from librbd are turned into exceptions that subclassError. Almost all methods may raiseError(the base class of all rbd exceptions),PermissionErrorandIOError, in addition to those documented for themethod.

classrbd.Image(ioctx,name=None,snapshot=None,read_only=False,image_id=None,_oncomplete=None)

This class represents an RBD image. It is used to perform I/O onthe image and interact with snapshots.

Note: Any method of this class may raiseImageNotFoundif the image has been deleted.

close(self)

Release the resources used by this image object.

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

require_not_closed(self)

Checks if the Image is not closed

Raises:

InvalidArgument

classrbd.RBD

This class wraps librbd CRUD functions.

aio_open_image(self,oncomplete,ioctx,name=None,snapshot=None,read_only=False,image_id=None)

Asynchronously open the image at the given snapshot.Specify either name or id, otherwiseInvalidArgument is raised.

oncomplete will be called with the created Image object aswell as the completion:

oncomplete(completion, image)

If a snapshot is specified, the image will be read-only, unlessImage.set_snap() is called later.

If read-only mode is used, metadata for theImageobject (such as which snapshots exist) may become obsolete. Seethe C api for more details.

To clean up from opening the image,Image.close() orImage.aio_close() should be called.

Parameters:

• oncomplete (completion) -- what to do when open is complete

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• name (str) -- the name of the image

• snapshot (str) -- which snapshot to read from

• read_only (bool) -- whether to open the image in read-only mode

• image_id (str) -- the id of the image

Returns:

Completion - the completion object

clone(self,p_ioctx,p_name,p_snapshot,c_ioctx,c_name,features=None,order=None,stripe_unit=None,stripe_count=None,data_pool=None,clone_format=None)

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_snapshot -- the parent image snapshot name or id

• 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 None to let librbd decide)

• stripe_count (int) -- objects to stripe over before looping

• data_pool (str) -- optional separate pool for data blocks

• clone_format (int) -- 1 (requires a protected snapshot), 2 (requires mimic+ clients)

Raises:

TypeError

Raises:

InvalidArgument

Raises:

ImageExists

Raises:

FunctionNotSupported

Raises:

ArgumentOutOfRange

config_get(self,ioctx,key)

Get a pool-level configuration override.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is read

• key (str) -- key

Returns:

str - value

config_list(self,ioctx)

List pool-level config overrides.

Returns:

ConfigPoolIterator

config_remove(self,ioctx,key)

Remove a pool-level configuration override.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is read

• key (str) -- key

Returns:

str - value

config_set(self,ioctx,key,value)

Get a pool-level configuration override.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is read

• key (str) -- key

• value (str) -- value

create(self,ioctx,name,size,order=None,old_format=False,features=None,stripe_unit=None,stripe_count=None,data_pool=None)

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 thatis accessible by old clients, but can’tuse more advanced features like layering.

• features (int) -- bitmask of features to enable

• stripe_unit (int) -- stripe unit in bytes (default None to let librbd decide)

• stripe_count (int) -- objects to stripe over before looping

• data_pool (str) -- optional separate pool for data blocks

Raises:

ImageExists

Raises:

TypeError

Raises:

InvalidArgument

Raises:

FunctionNotSupported

features_from_string(self,str_features)

Get features bitmask from str, if str_features is empty, it will returnRBD_FEATURES_DEFAULT.

Parameters:

str_features (str) -- feature str

Returns:

int - the features bitmask of the image

Raises:

InvalidArgument

features_to_string(self,features)

Convert features bitmask to str.

Parameters:

features (int) -- feature bitmask

Returns:

str - the features str of the image

Raises:

InvalidArgument

group_create(self,ioctx,name)

Create a group.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is used

• name (str) -- the name of the group

Raises:

ObjectExists

Raises:

InvalidArgument

Raises:

FunctionNotSupported

group_list(self,ioctx)

List groups.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

list -- a list of groups names

Raises:

FunctionNotSupported

group_remove(self,ioctx,name)

Delete an RBD group. This may take a long time, since it doesnot return until every image in the group has been removedfrom the group.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the group is in

• name (str) -- the name of the group to remove

Raises:

ObjectNotFound

Raises:

InvalidArgument

Raises:

FunctionNotSupported

group_rename(self,ioctx,src,dest)

Rename an RBD group.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the group is in

• src (str) -- the current name of the group

• dest (str) -- the new name of the group

Raises:

ObjectExists

Raises:

ObjectNotFound

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

list2(self,ioctx)

Iterate over the images in the pool.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

Returns:

ImageIterator

migration_abort(self,ioctx,image_name,on_progress=None)

Cancel a previously started but interrupted migration.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_name (str) -- the name of the image

• on_progress (callback function) -- optional progress callback function

Raises:

ImageNotFound

migration_commit(self,ioctx,image_name,on_progress=None)

Commit an executed RBD image migration.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_name (str) -- the name of the image

• on_progress (callback function) -- optional progress callback function

Raises:

ImageNotFound

migration_execute(self,ioctx,image_name,on_progress=None)

Execute a prepared RBD image migration.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_name (str) -- the name of the image

• on_progress (callback function) -- optional progress callback function

Raises:

ImageNotFound

migration_prepare(self,ioctx,image_name,dest_ioctx,dest_image_name,features=None,order=None,stripe_unit=None,stripe_count=None,data_pool=None,clone_format=None,flatten=False)

Prepare an RBD image migration.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_name -- the current name of the image

• dest_ioctx (rados.Ioctx) -- determines which pool to migration into

• dest_image_name (str) -- the name of the destination image (may be the same image)

• 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 None to let librbd decide)

• stripe_count (int) -- objects to stripe over before looping

• data_pool (str) -- optional separate pool for data blocks

• clone_format (int) -- if the source image is a clone, which clone formatto use for the destination image

• flatten (bool) -- if the source image is a clone, whether to flatten thedestination image or make it a clone of the same parent

Raises:

TypeError

Raises:

InvalidArgument

Raises:

ImageExists

Raises:

FunctionNotSupported

Raises:

ArgumentOutOfRange

migration_prepare_import(self,source_spec,dest_ioctx,dest_image_name,features=None,order=None,stripe_unit=None,stripe_count=None,data_pool=None)

Prepare an RBD image migration.

Parameters:

• source_spec (str) -- JSON-encoded source-spec

• dest_ioctx (rados.Ioctx) -- determines which pool to migration into

• dest_image_name (str) -- the name of the destination image (may be the same image)

• 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 None to let librbd decide)

• stripe_count (int) -- objects to stripe over before looping

• data_pool (str) -- optional separate pool for data blocks

Raises:

TypeError

Raises:

InvalidArgument

Raises:

ImageExists

Raises:

FunctionNotSupported

Raises:

ArgumentOutOfRange

migration_status(self,ioctx,image_name)

Return RBD image migration status.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_name (str) -- the name of the image

Returns:

dict - contains the following keys:

• source_pool_id (int) - source image pool id

• source_pool_namespace (str) - source image pool namespace

• source_image_name (str) - source image name

• source_image_id (str) - source image id

• dest_pool_id (int) - destination image pool id

• dest_pool_namespace (str) - destination image pool namespace

• dest_image_name (str) - destination image name

• dest_image_id (str) - destination image id

• state (int) - current migration state

• state_description (str) - migration state description

Raises:

ImageNotFound

mirror_image_info_list(self,ioctx,mode_filter=None)

Iterate over the mirror image instance ids of a pool.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is read

• mode_filter -- list images in this image mirror mode

Returns:

MirrorImageInfoIterator

mirror_image_instance_id_list(self,ioctx)

Iterate over the mirror image instance ids of a pool.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

MirrorImageInstanceIdIterator

mirror_image_status_list(self,ioctx)

Iterate over the mirror image statuses of a pool.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

MirrorImageStatusIterator

mirror_image_status_summary(self,ioctx)

Get mirror image status summary of a pool.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

list - a list of (state, count) tuples

mirror_mode_get(self,ioctx)

Get pool mirror mode.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

int - pool mirror mode

mirror_mode_set(self,ioctx,mirror_mode)

Set pool mirror mode.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is written

• mirror_mode (int) -- mirror mode to set

mirror_peer_add(self,ioctx,site_name,client_name,direction=RBD_MIRROR_PEER_DIRECTION_RX_TX)

Add mirror peer.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is used

• site_name (str) -- mirror peer site name

• client_name (str) -- mirror peer client name

• direction (int) -- the direction of the mirroring

Returns:

str - peer uuid

mirror_peer_bootstrap_create(self,ioctx)

Creates a new RBD mirroring bootstrap token for anexternal cluster.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is written

Returns:

str - bootstrap token

mirror_peer_bootstrap_import(self,ioctx,direction,token)

Import a bootstrap token from an external cluster toauto-configure the mirror peer.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is written

• direction (int) -- mirror peer direction

• token (str) -- bootstrap token

mirror_peer_get_attributes(self,ioctx,uuid)

Get optional mirror peer attributes

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is written

• uuid (str) -- uuid of the mirror peer

Returns:

dict - contains the following keys:

• mon_host (str) - monitor addresses

• key (str) - CephX key

mirror_peer_list(self,ioctx)

Iterate over the peers of a pool.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

MirrorPeerIterator

mirror_peer_remove(self,ioctx,uuid)

Remove mirror peer.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is used

• uuid (str) -- peer uuid

mirror_peer_set_attributes(self,ioctx,uuid,attributes)

Set optional mirror peer attributes

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is written

• uuid (str) -- uuid of the mirror peer

• attributes (dict) -- ‘mon_host’ and ‘key’ attributes

mirror_peer_set_client(self,ioctx,uuid,client_name)

Set mirror peer client name

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is written

• uuid (str) -- uuid of the mirror peer

• client_name (str) -- client name of the mirror peer to set

mirror_peer_set_cluster(self,ioctx,uuid,cluster_name)

mirror_peer_set_name(self,ioctx,uuid,site_name)

Set mirror peer site name

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is written

• uuid (str) -- uuid of the mirror peer

• site_name (str) -- site name of the mirror peer to set

mirror_remote_namespace_get(self,ioctx)

Get mirror remote namespace

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

str - mirror remote namespace

mirror_remote_namespace_set(self,ioctx,remote_namespace)

Set mirror remote namespace

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is written

• remote_namespace -- the remote cluster namespace to mirror to

mirror_site_name_get(self,rados)

Get the local cluster’s friendly site name

Parameters:

rados -- cluster connection

Returns:

str - local site name

mirror_site_name_set(self,rados,site_name)

Set the local cluster’s friendly site name

Parameters:

• rados -- cluster connection

• site_name -- friendly site name

mirror_uuid_get(self,ioctx)

Get pool mirror uuid

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool is read

Returns:

ste - pool mirror uuid

namespace_create(self,ioctx,name)

Create an RBD namespace within a pool

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool

• name (str) -- namespace name

namespace_exists(self,ioctx,name)

Verifies if a namespace exists within a pool

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool

• name (str) -- namespace name

Returns:

bool - true if namespace exists

namespace_list(self,ioctx)

List all namespaces within a pool

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool

Returns:

list - collection of namespace names

namespace_remove(self,ioctx,name)

Remove an RBD namespace from a pool

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool

• name (str) -- namespace name

pool_init(self,ioctx,force)

Initialize an RBD pool:param ioctx: determines which RADOS pool:type ioctx:rados.Ioctx:param force: force init:type force: bool

pool_metadata_get(self,ioctx,key)

Get pool metadata for the given key.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is read

• key (str) -- metadata key

Returns:

str - metadata value

pool_metadata_list(self,ioctx)

List pool metadata.

Returns:

PoolMetadataIterator

pool_metadata_remove(self,ioctx,key)

Remove pool metadata for the given key.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is read

• key (str) -- metadata key

Returns:

str - metadata value

pool_metadata_set(self,ioctx,key,value)

Set pool metadata for the given key.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool is read

• key (str) -- metadata key

• value (str) -- metadata value

pool_stats_get(self,ioctx)

Return RBD pool stats

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool

Returns:

dict - contains the following keys:

• image_count (int) - image count

• image_provisioned_bytes (int) - image total HEAD provisioned bytes

• image_max_provisioned_bytes (int) - image total max provisioned bytes

• image_snap_count (int) - image snap count

• trash_count (int) - trash image count

• trash_provisioned_bytes (int) - trash total HEAD provisioned bytes

• trash_max_provisioned_bytes (int) - trash total max provisioned bytes

• trash_snap_count (int) - trash snap count

remove(self,ioctx,name,on_progress=None)

Delete an RBD image. This may take a long time, since it doesnot return until every object that comprises the image hasbeen deleted. Note that all snapshots must be deleted beforethe image can be removed. If there are snapshots left,ImageHasSnapshots is raised. If the image is stillopen, 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

• on_progress (callback function) -- optional progress callback function

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

trash_get(self,ioctx,image_id)

Retrieve RBD image info from trash.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_id (str) -- the id of the image to restore

Returns:

dict - contains the following keys:

• id (str) - image id

• name (str) - image name

• source (str) - source of deletion

• deletion_time (datetime) - time of deletion

• deferment_end_time (datetime) - time that an image is allowedto be removed from trash

Raises:

ImageNotFound

trash_list(self,ioctx)

List all entries from trash.

Parameters:

ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

Returns:

TrashIterator

trash_move(self,ioctx,name,delay=0)

Move an RBD image to the trash.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• name (str) -- the name of the image to remove

• delay (int) -- time delay in seconds before the image can be deletedfrom trash

Raises:

ImageNotFound

trash_purge(self,ioctx,expire_ts=None,threshold=-1)

Delete RBD images from trash in bulk.

By default it removes images with deferment end time less than now.

The timestamp is configurable, e.g. delete images that have expired aweek ago.

If the threshold is used it deletes images until X% pool usage is met.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• expire_ts (datetime) -- timestamp for images to be considered as expired (UTC)

• threshold (float) -- percentage of pool usage to be met (0 to 1)

trash_remove(self,ioctx,image_id,force=False,on_progress=None)

Delete an RBD image from trash. If image deferment time has notexpiredPermissionError is raised.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_id (str) -- the id of the image to remove

• force (bool) -- force remove even if deferment time has not expired

• on_progress (callback function) -- optional progress callback function

Raises:

ImageNotFound,PermissionError

trash_restore(self,ioctx,image_id,name)

Restore an RBD image from trash.

Parameters:

• ioctx (rados.Ioctx) -- determines which RADOS pool the image is in

• image_id (str) -- the id of the image to restore

• name (str) -- the new name of the restored image

Raises:

ImageNotFound

version(self)

Get the version number of thelibrbd C library.

Returns:

a tuple of(major,minor,extra) components of thelibrbd version

classrbd.SnapIterator(Imageimage)

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

• namespace (int) - enum for snap namespace

• group (dict) - optional for group namespace snapshots

• trash (dict) - optional for trash namespace snapshots

• mirror (dict) - optional for mirror namespace snapshots