注意

本文档适用于 Ceph 的开发版本。

报告文档错误

Librbd (Python)

rbd python 模块提供了对 RBD 镜像的文件式访问。

示例: 创建镜像并写入数据

要使用 rbd，您必须首先连接到 RADOS 并打开一个 IO context

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 = b'foo' * 200
image.write(data, 0)

这会将“foo”写入镜像的前 600 个字节。请注意，数据不能是 :type:unicode - Librbd 不知道如何处理宽度大于 :c:type:char 的字符。

最后，您需要关闭镜像、IO context 和到 RADOS 的连接

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

为了安全起见，每个这些调用都需要放在单独的 :finally 块中

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 GiB
        rbd_inst.create(ioctx, 'myimage', size)
        image = rbd.Image(ioctx, 'myimage')
        try:
            data = b'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 = b'foo' * 200
            image.write(data, 0)

API 参考

此模块是 librbd 的一个简单包装。

它目前提供了 librbd 中所有不使用回调的同步方法。

来自 librbd 的错误代码被转换为继承自 Error 的异常。几乎所有方法都可能引发 Error（所有 rbd 异常的基类）、PermissionError 和 IOError，以及针对该方法记录的其他异常。

class rbd.Image(ioctx, name=None, snapshot=None, read_only=False, image_id=None, _oncomplete=None)

此类表示一个 RBD 镜像。它用于对镜像执行 I/O 操作并与快照交互。

注意: 如果镜像已被删除，此类的任何方法都可能引发 ImageNotFound。

close(self)

释放此镜像对象使用的资源。

调用此方法后，不应再使用此对象。

require_not_closed(self)

检查镜像是否未关闭

引发:

InvalidArgument

class rbd.RBD

此类包装了 librbd CRUD 函数。

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

异步打开给定快照处的镜像。指定名称或 ID，否则会引发 InvalidArgument。

oncomplete 将使用创建的 Image 对象和完成状态调用

oncomplete(completion, image)

如果指定了快照，镜像将是只读的，除非稍后调用 Image.set_snap()。

如果使用只读模式，Image 对象的元数据（例如存在哪些快照）可能会过时。有关更多详细信息，请参阅 C API。

要清理打开的镜像，应调用 Image.close() 或 Image.aio_close()。

参数:

• oncomplete (completion) -- 打开完成后执行的操作

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• name (str) -- 镜像的名称

• snapshot (str) -- 从哪个快照读取

• read_only (bool) -- 是否以只读模式打开镜像

• image_id (str) -- 镜像的 ID

返回:

Completion - 完成对象

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)

将父 RBD 快照克隆为 COW 稀疏子镜像。

参数:

• p_ioctx -- 表示父快照的父上下文

• p_name -- 父镜像名称

• p_snapshot -- 父镜像快照名称或 ID

• c_ioctx -- 表示新克隆的子上下文

• c_name -- 克隆（子）名称

• features (int) -- 要启用的功能位掩码；如果设置，必须包含分层

• order (int) -- 镜像被分成 (2**order) 字节对象

• stripe_unit (int) -- 条带单位（字节）（默认 None 让 librbd 决定）

• stripe_count (int) -- 在循环之前条带化的对象数

• data_pool (str) -- 可选的单独数据块池

• clone_format (int) -- 1（需要受保护的快照），2（需要 mimic+ 客户端）

引发:

TypeError

引发:

InvalidArgument

引发:

ImageExists

引发:

FunctionNotSupported

引发:

ArgumentOutOfRange

config_get(self, ioctx, key)

获取池级别的配置覆盖。

参数:

• ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

• key (str) -- 键

返回:

str - 值

config_list(self, ioctx)

列出池级别的配置覆盖。

返回:

ConfigPoolIterator

config_remove(self, ioctx, key)

删除池级别的配置覆盖。

参数:

• ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

• key (str) -- 键

返回:

str - 值

config_set(self, ioctx, key, value)

获取池级别的配置覆盖。

参数:

• ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

• key (str) -- 键

• value (str) -- 值

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

创建一个 rbd 镜像。

参数:

• ioctx (rados.Ioctx) -- 在其中创建镜像的上下文

• name (str) -- 镜像的名称

• size (int) -- 镜像的大小（字节）

• order (int) -- 镜像被分成 (2**order) 字节对象

• old_format (bool) -- 是否创建旧格式镜像，旧客户端可访问，但不能使用分层等高级功能。

• features (int) -- 要启用的功能位掩码

• stripe_unit (int) -- 条带单位（字节）（默认 None 让 librbd 决定）

• stripe_count (int) -- 在循环之前条带化的对象数

• data_pool (str) -- 可选的单独数据块池

引发:

ImageExists

引发:

TypeError

引发:

InvalidArgument

引发:

FunctionNotSupported

features_from_string(self, str_features)

从 str 获取功能位掩码，如果 str_features 为空，则返回 RBD_FEATURES_DEFAULT。

参数:

str_features (str) -- 功能字符串

返回:

int - 镜像的功能位掩码

引发:

InvalidArgument

features_to_string(self, features)

将功能位掩码转换为 str。

参数:

features (int) -- 功能位掩码

返回:

str - 镜像的功能字符串

引发:

InvalidArgument

group_create(self, ioctx, name)

创建一个组。

参数:

• ioctx (rados.Ioctx) -- 确定使用哪个 RADOS 池

• name (str) -- 组的名称

引发:

ObjectExists

引发:

InvalidArgument

引发:

FunctionNotSupported

group_list(self, ioctx)

列出组。

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

list -- 组名称列表

引发:

FunctionNotSupported

group_remove(self, ioctx, name)

删除 RBD 组。这可能需要很长时间，因为它直到组中的每个镜像都被移除后才会返回。t

参数:

• ioctx (rados.Ioctx) -- 确定组所在的 RADOS 池

• name (str) -- 要删除的组的名称

引发:

ObjectNotFound

引发:

InvalidArgument

引发:

FunctionNotSupported

group_rename(self, ioctx, src, dest)

重命名 RBD 组。

参数:

• ioctx (rados.Ioctx) -- 确定组所在的 RADOS 池

• src (str) -- 组的当前名称

• dest (str) -- 组的新名称

引发:

ObjectExists

引发:

ObjectNotFound

引发:

InvalidArgument

引发:

FunctionNotSupported

list(self, ioctx)

列出镜像名称。

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

list -- 镜像名称列表

list2(self, ioctx)

迭代池中的镜像。

参数:

ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

返回:

ImageIterator

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

取消先前已开始但中断的迁移。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_name (str) -- 镜像的名称

• on_progress (callback function) -- 可选的进度回调函数

引发:

ImageNotFound

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

提交已执行的 RBD 镜像迁移。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_name (str) -- 镜像的名称

• on_progress (callback function) -- 可选的进度回调函数

引发:

ImageNotFound

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

执行已准备好的 RBD 镜像迁移。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_name (str) -- 镜像的名称

• on_progress (callback function) -- 可选的进度回调函数

引发:

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)

准备 RBD 镜像迁移。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_name -- 镜像的当前名称

• dest_ioctx (rados.Ioctx) -- 确定迁移到的池

• dest_image_name (str) -- 目标镜像的名称（可能与源镜像相同）

• features (int) -- 要启用的功能位掩码；如果设置，必须包含分层

• order (int) -- 镜像被分成 (2**order) 字节对象

• stripe_unit (int) -- 条带单位（字节）（默认 None 让 librbd 决定）

• stripe_count (int) -- 在循环之前条带化的对象数

• data_pool (str) -- 可选的单独数据块池

• clone_format (int) -- 如果源镜像是克隆，用于目标镜像的克隆格式

• flatten (bool) -- 如果源镜像是克隆，是否展平目标镜像或使其成为同一父镜像的克隆

引发:

TypeError

引发:

InvalidArgument

引发:

ImageExists

引发:

FunctionNotSupported

引发:

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)

准备 RBD 镜像迁移。

参数:

• source_spec (str) -- JSON 编码的 source-spec

• dest_ioctx (rados.Ioctx) -- 确定迁移到的池

• dest_image_name (str) -- 目标镜像的名称（可能与源镜像相同）

• features (int) -- 要启用的功能位掩码；如果设置，必须包含分层

• order (int) -- 镜像被分成 (2**order) 字节对象

• stripe_unit (int) -- 条带单位（字节）（默认 None 让 librbd 决定）

• stripe_count (int) -- 在循环之前条带化的对象数

• data_pool (str) -- 可选的单独数据块池

引发:

TypeError

引发:

InvalidArgument

引发:

ImageExists

引发:

FunctionNotSupported

引发:

ArgumentOutOfRange

migration_status(self, ioctx, image_name)

返回 RBD 镜像迁移状态。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_name (str) -- 镜像的名称

返回:

dict - 包含以下键

• source_pool_id (int) - 源镜像池 ID

• source_pool_namespace (str) - 源镜像池命名空间

• source_image_name (str) - 源镜像名称

• source_image_id (str) - 源镜像 ID

• dest_pool_id (int) - 目标镜像池 ID

• dest_pool_namespace (str) - 目标镜像池命名空间

• dest_image_name (str) - 目标镜像名称

• dest_image_id (str) - 目标镜像 ID

• state (int) - 当前迁移状态

• state_description (str) - 迁移状态描述

引发:

ImageNotFound

mirror_image_info_list(self, ioctx, mode_filter=None)

迭代池的镜像实例 ID。

参数:

• ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

• mode_filter -- 在此镜像模式下过滤镜像

返回:

MirrorImageInfoIterator

mirror_image_instance_id_list(self, ioctx)

迭代池的镜像实例 ID。

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

MirrorImageInstanceIdIterator

mirror_image_status_list(self, ioctx)

迭代池的镜像状态。

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

MirrorImageStatusIterator

mirror_image_status_summary(self, ioctx)

获取池的镜像状态摘要。

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

list - (state, count) 元组列表

mirror_mode_get(self, ioctx)

获取池镜像模式。

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

int - 池镜像模式

mirror_mode_set(self, ioctx, mirror_mode)

设置池镜像模式。

参数:

• ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

• mirror_mode (int) -- 要设置的镜像模式

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

添加镜像对等体。

参数:

• ioctx (rados.Ioctx) -- 确定使用哪个 RADOS 池

• site_name (str) -- 镜像对等站点名称

• client_name (str) -- 镜像对等客户端名称

• direction (int) -- 镜像方向

返回:

str - 对等体 uuid

mirror_peer_bootstrap_create(self, ioctx)

为外部集群创建新的 RBD 镜像引导令牌。

参数:

ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

返回:

str - 引导令牌

mirror_peer_bootstrap_import(self, ioctx, direction, token)

从外部集群导入引导令牌以自动配置镜像对等体。

参数:

• ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

• direction (int) -- 镜像对等方向

• token (str) -- 引导令牌

mirror_peer_get_attributes(self, ioctx, uuid)

获取可选的镜像对等体属性

参数:

• ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

• uuid (str) -- 镜像对等体的 uuid

返回:

dict - 包含以下键

• mon_host (str) - monitor 地址

• key (str) - CephX 密钥

mirror_peer_list(self, ioctx)

迭代池的对等体。

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

MirrorPeerIterator

mirror_peer_remove(self, ioctx, uuid)

移除镜像对等体。

参数:

• ioctx (rados.Ioctx) -- 确定使用哪个 RADOS 池

• uuid (str) -- 对等体 uuid

mirror_peer_set_attributes(self, ioctx, uuid, attributes)

设置可选的镜像对等体属性

参数:

• ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

• uuid (str) -- 镜像对等体的 uuid

• attributes (dict) -- 'mon_host' 和 'key' 属性

mirror_peer_set_client(self, ioctx, uuid, client_name)

设置镜像对等客户端名称

参数:

• ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

• uuid (str) -- 镜像对等体的 uuid

• client_name (str) -- 要设置的镜像对等客户端名称

mirror_peer_set_cluster(self, ioctx, uuid, cluster_name)

mirror_peer_set_name(self, ioctx, uuid, site_name)

设置镜像对等站点名称

参数:

• ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

• uuid (str) -- 镜像对等体的 uuid

• site_name (str) -- 要设置的镜像对等站点名称

mirror_remote_namespace_get(self, ioctx)

获取镜像远程命名空间

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

str - 镜像远程命名空间

mirror_remote_namespace_set(self, ioctx, remote_namespace)

设置镜像远程命名空间

参数:

• ioctx (rados.Ioctx) -- 确定写入哪个 RADOS 池

• remote_namespace -- 要镜像到的远程集群命名空间

mirror_site_name_get(self, rados)

获取本地集群的友好站点名称

参数:

rados -- 集群连接

返回:

str - 本地站点名称

mirror_site_name_set(self, rados, site_name)

设置本地集群的友好站点名称

参数:

• rados -- 集群连接

• site_name -- 友好站点名称

mirror_uuid_get(self, ioctx)

获取池镜像 uuid

参数:

ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

返回:

ste - 池镜像 uuid

namespace_create(self, ioctx, name)

在池中创建 RBD 命名空间

参数:

• ioctx (rados.Ioctx) -- 确定哪个 RADOS 池

• name (str) -- 命名空间名称

namespace_exists(self, ioctx, name)

验证池中是否存在命名空间

参数:

• ioctx (rados.Ioctx) -- 确定哪个 RADOS 池

• name (str) -- 命名空间名称

返回:

bool - 如果命名空间存在，则为 true

namespace_list(self, ioctx)

列出池中的所有命名空间

参数:

ioctx (rados.Ioctx) -- 确定哪个 RADOS 池

返回:

list - 命名空间名称集合

namespace_remove(self, ioctx, name)

从池中移除 RBD 命名空间

参数:

• ioctx (rados.Ioctx) -- 确定哪个 RADOS 池

• name (str) -- 命名空间名称

pool_init(self, ioctx, force)

初始化 RBD 池 :param ioctx: 确定哪个 RADOS 池 :type ioctx: rados.Ioctx :param force: 强制初始化 :type force: bool

pool_metadata_get(self, ioctx, key)

获取给定键的池元数据。

参数:

• ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

• key (str) -- 元数据键

返回:

str - 元数据值

pool_metadata_list(self, ioctx)

列出池元数据。

返回:

PoolMetadataIterator

pool_metadata_remove(self, ioctx, key)

移除给定键的池元数据。

参数:

• ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

• key (str) -- 元数据键

返回:

str - 元数据值

pool_metadata_set(self, ioctx, key, value)

设置给定键的池元数据。

参数:

• ioctx (rados.Ioctx) -- 确定读取哪个 RADOS 池

• key (str) -- 元数据键

• value (str) -- 元数据值

pool_stats_get(self, ioctx)

返回 RBD 池统计信息

参数:

ioctx (rados.Ioctx) -- 确定哪个 RADOS 池

返回:

dict - 包含以下键

• image_count (int) - 镜像数量

• image_provisioned_bytes (int) - 镜像 HEAD 总分配字节数

• image_max_provisioned_bytes (int) - 镜像总最大分配字节数

• image_snap_count (int) - 镜像快照数量

• trash_count (int) - 垃圾镜像数量

• trash_provisioned_bytes (int) - 垃圾 HEAD 总分配字节数

• trash_max_provisioned_bytes (int) - 垃圾总最大分配字节数

• trash_snap_count (int) - 垃圾快照数量

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

删除 RBD 镜像。这可能需要很长时间，因为它直到构成镜像的每个对象都被删除后才会返回。请注意，必须先删除所有快照才能删除镜像。如果还有快照残留，则会引发 ImageHasSnapshots。如果镜像仍处于打开状态，或者来自崩溃客户端的监视尚未过期，则会引发 ImageBusy。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• name (str) -- 要删除的镜像的名称

• on_progress (callback function) -- 可选的进度回调函数

引发:

ImageNotFound, ImageBusy, ImageHasSnapshots

rename(self, ioctx, src, dest)

重命名 RBD 镜像。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• src (str) -- 镜像的当前名称

• dest (str) -- 镜像的新名称

引发:

ImageNotFound, ImageExists

trash_get(self, ioctx, image_id)

从垃圾箱检索 RBD 镜像信息。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_id (str) -- 要恢复的镜像的 ID

返回:

dict - 包含以下键

• id (str) - 镜像 ID

• name (str) - 镜像名称

• source (str) - 删除来源

• deletion_time (datetime) - 删除时间

• deferment_end_time (datetime) - 允许从垃圾箱中移除镜像的时间

引发:

ImageNotFound

trash_list(self, ioctx)

列出垃圾箱中的所有条目。

参数:

ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

返回:

TrashIterator

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

将 RBD 镜像移动到垃圾箱。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• name (str) -- 要删除的镜像的名称

• delay (int) -- 镜像从垃圾箱删除前的时间延迟（秒）

引发:

ImageNotFound

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

批量删除垃圾箱中的 RBD 镜像。

默认情况下，它会删除延迟结束时间小于当前时间的镜像。

时间戳是可配置的，例如删除一周前过期的镜像。

如果使用了阈值，它会删除镜像直到达到 X% 的池使用率。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• expire_ts (datetime) -- 镜像被视为过期的时间戳（UTC）

• threshold (float) -- 要达到的池使用率百分比（0 到 1）

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

从垃圾箱中删除 RBD 镜像。如果镜像延迟时间尚未过期，则会引发 PermissionError。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_id (str) -- 要删除的镜像的 ID

• force (bool) -- 即使延迟时间未过期也强制删除

• on_progress (callback function) -- 可选的进度回调函数

引发:

ImageNotFound, PermissionError

trash_restore(self, ioctx, image_id, name)

从垃圾箱恢复 RBD 镜像。

参数:

• ioctx (rados.Ioctx) -- 确定镜像所在的 RADOS 池

• image_id (str) -- 要恢复的镜像的 ID

• name (str) -- 恢复后镜像的新名称

引发:

ImageNotFound

version(self)

获取 librbd C 库的版本号。

返回:

一个包含 librbd 版本的 (major, minor, extra) 组件的元组

class rbd.SnapIterator(Image image)

镜像快照信息的迭代器。

生成包含快照信息的字典。

键包括

• id (int) - 快照的数字标识符

• size (int) - 快照时的镜像大小（字节）

• name (str) - 快照的名称

• namespace (int) - 快照命名空间的枚举

• group (dict) - 组命名空间快照可选

• trash (dict) - 垃圾命名空间快照可选

• mirror (dict) - 镜像命名空间快照可选

由 Ceph 基金会为您呈现

Ceph 文档是由非营利性 Ceph 基金会 资助和托管的社区资源。如果您希望支持这项工作和我们的其他努力，请考虑 立即加入。