Rook CephObjectRealm CRD 完全指南:在 Kubernetes 中创建与拉取 Ceph 对象多站点 Realm
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):
- 一个 Realm;
- 一个 Zone Group;
- 一个 Zone;
- 一个带
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):
- 读取 CR:从 API Server 获取
CephObjectRealm实例;若不存在则忽略(视为已删除)。 - 前置条件检查:确认集群中存在
CephCluster(IsReadyToReconcile),否则不执行调谐并等待。 - 删除处理:若 CR 带删除时间戳,记录事件后直接返回(注意:删除 CR 并不会删除底层 Ceph realm,见下文“清理注意事项”)。
- 参数校验:调用
validateRealmCR,校验name与namespace非空。 - 分支执行:
- 若
IsPullRealm()为真 → 调用pullCephRealm执行拉取; - 否则 → 依次调用
createRealmKeys(生成并保存访问密钥)与createCephRealm(创建底层 realm)。
- 若
- 默认 realm 处理:若
spec.defaultRealm为true,调用SetDefaultRealm标记默认。 - 状态更新:调谐成功后把
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 的两个约束:
- 同一集群中只能有一个 realm 被标记为默认,请勿在多个 CR 上同时设置
defaultRealm: true; - 默认标记一旦被赋值就不能取消(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):
- 读取 store 的
zone字段,找到CephObjectZone; - 由 zone 的
zoneGroup找到CephObjectZoneGroup; - 由 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 构建或接入多站点对象存储架构。