Rook CephObjectRealm CRD 完全指南:在 Kubernetes 中创建与拉取 Ceph 对象多站点 Realm

原创2026-09-21 20:21:041,398 阅读
文章标签:云原生存储容器编排运维

Rook CephObjectRealm CRD 完全指南:在 Kubernetes 中创建与拉取 Ceph 对象多站点 Realm

CephObjectRealm 是 Rook 提供的自定义资源(CRD),用于在 Kubernetes 中以声明式方式管理 Ceph RGW(RADOS Gateway)多站点(Multisite)架构中的 realm——即对象数据复制与隔离的最高层级逻辑单元。本指南以 ceph-object-realm-crd.md 为核心,结合仓库源码与示例清单,完整讲解该 CRD 的配置字段、底层执行流程、跨集群拉取(pull)realm 的实战步骤,以及与其他多站点 CRD(ZoneGroup、Zone、ObjectStore)的协作关系。阅读完本文,你将能够独立编写 CephObjectRealm 清单、理解其调谐(Reconcile)行为,并完成跨 Ceph 集群的对象数据同步初始化。

背景:Realm 在 Ceph 多站点架构中的位置

Ceph 对象存储多站点(Multisite)允许对象存储在多个 Ceph 集群之间复制数据,也允许同一集群内的多个对象存储相互独立、隔离。RGW 多站点的层级结构自上而下为:

  • Realm(领域):命名空间,包含一个或多个 Zone Group,是数据隔离与复制的顶层单元;
  • Zone Group(区域组):包含一个或多个 Zone,跨集群复制以 Zone Group 为单位;
  • Zone(区域):对应一个 RGW 实例及一组存储池,是实际对外提供 S3 服务的单元。

在 Rook 中,若要搭建多站点,需要依次创建四种资源(详见 ceph-object-multisite.md):

  1. 一个 Realm;
  2. 一个 Zone Group;
  3. 一个 Zone;
  4. 一个带 zone 字段的 CephObjectStore。

当 ceph-object-store 未指定 zone 时,Rook 会创建一个与该 store 同名的 realm、zone group 和 zone,使该 store 的数据保持独立隔离;而当指定了 zone 时,store 会加入自定义的 realm/zonegroup/zone,从而支持跨集群复制。CephObjectRealm 正是这一链路的第一环。

CephObjectRealm 完整示例

官方示例清单位于 deploy/examples/object-multisite.yaml,其中 realm 部分如下:

apiVersion: ceph.rook.io/v1
kind: CephObjectRealm
metadata:
  name: realm-a
  namespace: rook-ceph # namespace:cluster

在 ceph-object-realm-crd.md 中还给出了带 pull 与 defaultRealm 字段的完整形态:

apiVersion: ceph.rook.io/v1
kind: CephObjectRealm
metadata:
  name: realm-a
  namespace: rook-ceph
# 该 endpoint 必须是 realm-a 的 master zone group 中 master zone 的 endpoint。
# 更多细节参见 object-multisite.md。
spec:
  pull:
    endpoint: http://10.2.105.133:80
  defaultRealm: true

将其保存为清单后执行:

kubectl create -f object-realm.yaml

配置参数详解

Metadata 字段

字段 类型 必填 说明
name string 是 要创建的 Ceph realm 名称。该名称同时是底层 radosgw-admin realm 的名称;若用于拉取(pull),名称必须与源集群中被拉取的 realm 一致。
namespace string 是 Rook Ceph 集群所在的命名空间,realm 资源在其中创建。

在控制器源码中,validateRealmCR 会强制校验这两个字段不能为空,否则拒绝调谐(见 pkg/operator/ceph/object/realm/controller.go)。

Spec 字段

spec 由 ObjectRealmSpec 定义,包含以下两个可选字段:

字段 类型 默认值 说明
pull.endpoint string 空 可选。用于从另一个 Ceph 集群拉取 realm。必须是源 realm 的 master zone group 中 master zone 的 endpoint。格式需匹配正则 ^https*://(见下方说明)。
defaultRealm bool false 设为 true 时,Rook 将该 realm 标记为 Ceph 集群中的默认 realm。同一集群中只能有一个 realm 被标记为默认。

关于 pull.endpoint 的校验,CRD 的 OpenAPI Schema 中为其声明了模式约束 ^https*://(见 deploy/examples/crds.yaml),即必须以 http:// 或 https:// 开头;同时 IsPullRealm() 以 pull.endpoint 是否非空来区分“拉取模式”与“本地创建模式”(见 pkg/apis/ceph.rook.io/v1/object.go)。

Status 与观测列

CephObjectRealm 拥有 status 子资源(+kubebuilder:subresource:status),并声明了两个打印列:

  • Phase(对应 .status.phase):展示资源当前调谐阶段;
  • Age(对应 .metadata.creationTimestamp):资源创建时长。

同时 CRD 注册了短名 cephor(+kubebuilder:resource:shortName=cephor),因此可以直接用以下命令观测:

kubectl -n rook-ceph get cephor
kubectl -n rook-ceph get cephobjectrealms.ceph.rook.io -o yaml

以上定义可在 pkg/apis/ceph.rook.io/v1/types.go 与 deploy/examples/crds.yaml 中核实。

控制器调谐流程:Reconcile 深度解析

CephObjectRealm 由名为 ceph-object-realm-controller 的控制器管理(见 pkg/operator/ceph/object/realm/controller.go)。当 CR 被创建、更新或删除时,控制器通过 ReconcileObjectRealm.Reconcile 驱动以下流程(对应 controller.go):

  1. 读取 CR:从 API Server 获取 CephObjectRealm 实例;若不存在则忽略(视为已删除)。
  2. 前置条件检查:确认集群中存在 CephCluster(IsReadyToReconcile),否则不执行调谐并等待。
  3. 删除处理:若 CR 带删除时间戳,记录事件后直接返回(注意:删除 CR 并不会删除底层 Ceph realm,见下文“清理注意事项”)。
  4. 参数校验:调用 validateRealmCR,校验 name 与 namespace 非空。
  5. 分支执行:
    • 若 IsPullRealm() 为真 → 调用 pullCephRealm 执行拉取;
    • 否则 → 依次调用 createRealmKeys(生成并保存访问密钥)与 createCephRealm(创建底层 realm)。
  6. 默认 realm 处理:若 spec.defaultRealm 为 true,调用 SetDefaultRealm 标记默认。
  7. 状态更新:调谐成功后把 status.phase 更新为 Ready 并记录 observedGeneration;失败则更新为失败状态并返回错误触发重试。

控制器还通过 WaitForRequeueIfRealmNotReady 以 10 秒为间隔自动重新入队(见 controller.go),从而保证“依赖尚不满足”时能持续重试直至成功。

本地创建 Realm:底层 radosgw-admin 调用链

当 CR 不包含 pull 字段时,Rook 在集群内“就地”创建一个全新 realm,过程分两步:

1. 生成 Realm 访问密钥并保存为 Kubernetes Secret

createRealmKeys(见 controller.go)会随机生成一对密钥:

  • access key:长度 14 字符;
  • secret key:长度 28 字符;

两者均经 base64 URL-safe 编码后,以 access-key 与 secret-key 两个键存入名为 <realm名称>-keys 的 Kubernetes Secret(例如 realm 名为 realm-a,则 Secret 名为 realm-a-keys),命名空间与 CR 相同,并设置了所有者引用(owner reference),随 CR 生命周期管理。该 Secret 就是 RGW 内部用于数据复制、以及其它集群拉取该 realm 时所需的凭据来源(详见 ceph-object-multisite.md)。

2. 调用 radosgw-admin 创建 Realm

createCephRealm(见 controller.go)先执行 radosgw-admin realm get --rgw-realm=<name> 检查 realm 是否已存在;若命令返回“未找到”(对应 syscall.ENOENT),则执行:

radosgw-admin realm create --rgw-realm=<name>

若 realm 已存在则直接跳过,保证操作幂等。所有命令通过 RunAdminCommandNoMultisite(见 pkg/operator/ceph/object/admin.go)执行——该函数专门用于“对象存储尚未创建”或“作用于 realm/zonegroup 级别”的命令场景,并带有固定超时。

创建完成后,Rook 会为 realm 自动创建一个系统用户,用户名为 <realm名称>-system-user(如 realm-a-system-user),RGW 内部的数据复制即使用该用户的密钥(见 ceph-object-multisite.md)。

跨集群拉取 Realm:Pull 模式实战

当需要把另一个 Ceph 集群(Rook 或非 Rook)中的 realm 数据同步到本集群时,使用 pull 模式。控制器对应实现为 pullCephRealm(见 controller.go),其核心是执行:

radosgw-admin realm pull --rgw-realm=<name> --url=<endpoint> --access-key=<ak> --secret-key=<sk>

若拉取所需的密钥 Secret 尚不存在,控制器会记录错误并在 10 秒后重新入队重试。执行前需要准备两部分信息(详见 ceph-object-multisite.md)。

第一步:获取拉取 Endpoint

该 endpoint 必须是源 realm 的 master zone group 中 master zone 的 endpoint。若不知道,可在源集群(Rook 集群通过 toolbox)中查询:

radosgw-admin zonegroup get --rgw-realm=$REALM_NAME --rgw-zonegroup=$MASTER_ZONEGROUP_NAME

输出 JSON 的 endpoints 数组中即包含可用 endpoint,例如:

{
    "endpoints": [http://10.17.159.77:80]
}

该 endpoint 必须能被目标 Rook 集群解析访问,可用 curl 验证:

curl -L http://10.17.159.77:80

正常响应会返回类似 ListAllMyBucketsResult 的 XML。最后将该 endpoint 填入 CephObjectRealm 的 pull.endpoint:

apiVersion: ceph.rook.io/v1
kind: CephObjectRealm
metadata:
  name: realm-a
  namespace: rook-ceph
spec:
  pull:
    endpoint: http://10.17.159.77:80

注意:拉取模式下,CR 的 name 必须与源 realm 名称一致,控制器才会把数据拉取到同名 realm 下。

第二步:获取并导入 Realm 密钥

realm 的系统用户密钥是其它集群拉取该 realm 的凭证。

从 Rook Ceph 集群获取:realm 密钥以 Kubernetes Secret 形式存在源集群中,导出并导入到目标集群:

kubectl -n $ORIGINAL_CLUSTER_NAMESPACE get secrets realm-a-keys -o yaml > realm-a-keys.yaml

编辑 realm-a-keys.yaml,将 namespace 改为目标 Rook 集群的命名空间,然后创建:

kubectl create -f realm-a-keys.yaml

控制器在拉取时会通过 GetRealmKeyArgs / GetRealmKeyArgsFromSecret(见 pkg/operator/ceph/object/objectstore.go)从该 Secret 解码出 --access-key 与 --secret-key 参数。

从非 Rook Ceph 集群获取:在源集群执行:

radosgw-admin user info --uid="realm-a-system-user"

输出 JSON 的 keys 数组中包含该用户的 access_key 与 secret_key。将两个密钥分别 base64 编码后,按以下模板创建 Secret(只需替换 access-key、secret-key 与 namespace):

apiVersion: v1
data:
  access-key: YVN3NGJsWklLVjluS0VVNVZDMD0=
  secret-key: SlNsRFhGdDVUbGdqU1Y5UU9FOVhVbmRyTGlJNUpFbzlZREJzSmc9PQ==
kind: Secret
metadata:
  name: realm-a-keys
  namespace: $NEW_ROOK_CLUSTER_NAMESPACE

第三步:应用 CR 并验证

kubectl create -f object-realm-pull.yaml

调谐成功后,可在目标集群 toolbox 中确认 realm 已同步:

radosgw-admin realm list
radosgw-admin realm get --rgw-realm=realm-a

defaultRealm:默认 Realm 语义与限制

defaultRealm: true 用于将当前 realm 标记为 Ceph 集群的默认 realm。控制器在创建/拉取完成后调用 SetDefaultRealm(见 pkg/operator/ceph/object/objectstore.go),其底层命令为:

radosgw-admin realm default --rgw-realm=<name>

需要特别留意 Ceph 的两个约束:

  1. 同一集群中只能有一个 realm 被标记为默认,请勿在多个 CR 上同时设置 defaultRealm: true;
  2. 默认标记一旦被赋值就不能取消(unassigned),只能改由另一个 realm 成为默认。

因此该字段适合在只有一个 realm、或明确需要某个 realm 作为默认接入点的场景使用。此外,CephObjectStore 的 spec 中也存在 defaultRealm 字段,用于在创建对象存储时把其所在 realm 标记为默认(见 pkg/operator/ceph/object/controller.go),两者语义一致。

与其他多站点 CRD 的依赖链

CephObjectRealm 并非孤立存在,它通过 CephObjectZoneGroup.spec.realm 字段与 ZoneGroup 关联。当创建带 zone 的 CephObjectStore 时,Rook 会沿着 store → zone → zonegroup → realm 的链逐级查找并校验(见 pkg/operator/ceph/object/controller.go):

  1. 读取 store 的 zone 字段,找到 CephObjectZone;
  2. 由 zone 的 zoneGroup 找到 CephObjectZoneGroup;
  3. 由 zonegroup 的 realm 找到 CephObjectRealm。

任一环缺失或未就绪,store 的调谐都会返回“等待重试”(requeue),直到整个链齐全。完整的多站点创建顺序示例见 object-multisite.yaml(realm-a → zonegroup-a → zone-a),测试用最小清单见 object-multisite-realm-test.yaml(test-realm → test-zonegroup → test-zone)。

清理注意事项

删除 CephObjectRealm CR 时,控制器仅记录删除事件并结束调谐,不会删除底层已创建的 Ceph realm,由 Zone 创建的存储池同样不会被删除(详见 ceph-object-multisite.md 中的清理说明)。如需彻底清理,需在 toolbox 中手动执行 radosgw-admin realm delete 等命令,操作前请确认数据复制关系已解除,避免影响其它集群的数据同步。

测试与实现依据

该 CRD 的行为有完整单元测试覆盖(见 pkg/operator/ceph/object/realm/controller_test.go),测试覆盖了“无 CephCluster 时不就绪”、“创建/拉取 realm 的调谐路径”等场景;CRD 的类型定义、OpenAPI 校验(pull.endpoint 的 ^https*:// 模式、defaultRealm 布尔类型)与状态子资源可分别在 pkg/apis/ceph.rook.io/v1/types.go 和 deploy/examples/crds.yaml 中核实。结合本文内容,你可以放心地在自己的 Rook 集群中通过 CephObjectRealm 构建或接入多站点对象存储架构。

登录后查看全文
rook