Rook CephObjectStoreUser CRD 完整指南:在 Kubernetes 上以声明式方式管理 RGW 对象存储用户
Rook CephObjectStoreUser CRD 完整指南:在 Kubernetes 上以声明式方式管理 RGW 对象存储用户
本文是 Rook 项目中 CephObjectStoreUser 自定义资源(CRD)的技术指南,围绕其核心配置骨架(示例 YAML、Metadata、Spec 下的 store/displayName/clusterNamespace/quotas/capabilities/opMask)展开,并辅以仓库源码(API 类型定义、object-user 控制器、opmask 实现)进行原理级剖析。读完本文,你将掌握如何在 Rook 管理的 Ceph 集群中创建、配额限制、授权、审计和删除 S3 对象存储用户,理解 RGW 用户能力(capabilities)与操作掩码(opMask)的真实语义,并能够把用户凭据以 Kubernetes Secret 的形式安全地交付给工作负载。
CephObjectStoreUser:Rook 管理 RGW 用户的声明式入口
Rook 通过自定义资源定义(CRDs)将 Kubernetes 的声明式管理模型延伸到 Ceph 对象存储网关(RGW / RADOS Gateway)的用户体系上。CephObjectStoreUser 正是这一能力的核心:它允许你通过一段 YAML 描述"在哪个对象存储里创建谁、分配多少配额、授予哪些权限",而无需手动登录 Ceph 节点执行 radosgw-admin user create 之类的命令。
该资源由独立的控制器 ceph-object-store-user-controller 负责调谐(reconcile),控制器源码位于 pkg/operator/ceph/object/user/controller.go。调谐流程大致如下(对应 Reconcile 与 reconcile 函数):
- 读取
CephObjectStoreUser实例并添加 finalizer,确保删除资源时同步清理 RGW 侧的用户; - 定位所属
CephCluster与CephObjectStore(支持跨命名空间定位); - 通过 go-ceph 的 admin ops API 调用 RGW:用户不存在则
CreateUser,存在则按需ModifyUser、增删能力(AddUserCap/RemoveUserCap)、设置配额(SetUserQuota); - 在 Kubernetes 中生成/更新存放凭据的 Secret(命名规则为
rook-ceph-object-user-<store>-<user>); - 更新资源
.status(Phase、Info、Keys、ObservedGeneration)。
控制器同时监听 CephObjectStoreUser 与相关 Secret 的变化(含 spec.keys 引用的 Secret),因此凭据轮换、CR 增删改都会触发重新调谐。
快速上手:完整示例
原文档给出的示例几乎覆盖了全部核心字段,下面给出经过注释增强、可直接复制的完整版本(与 deploy/examples/object-user.yaml 示例一致并做了补充说明):
apiVersion: ceph.rook.io/v1
kind: CephObjectStoreUser
metadata:
name: my-user
namespace: rook-ceph
spec:
# 用户将被创建到哪个对象存储中,必须与 CephObjectStore CR 的 name 一致
store: my-store
# 显示名称,会原样传给 radosgw-admin user create 的 display-name 参数
displayName: my-display-name
# 配额限制(可选)
quotas:
maxBuckets: 100 # 最大桶数量
maxSize: 10G # 所有桶内对象的总大小上限,使用 Kubernetes resource.Quantity 格式
maxObjects: 10000 # 所有桶内对象的总数量上限
# 额外的管理能力(可选,详见下文)
capabilities:
user: "*"
bucket: "*"
# 操作掩码:允许的操作类型集合(可选,默认 read、write、delete)
opMask:
- read
- write
- delete
应用方式:
kubectl create -f deploy/examples/object-user.yaml
成功后,控制器会在 RGW 中创建同名用户,并在 rook-ceph 命名空间生成名为 rook-ceph-object-user-my-store-my-user 的 Secret(参见 controller.go 中 generateCephUserSecretName 与 generateCephUserSecret),Secret 内包含 AccessKey、SecretKey、Endpoint 三个键,若对象存储网关配置了 TLS 证书(spec.gateway.sslCertificateRef),还会额外写入 SSLCertSecretName。应用可以用标准的 Secret 挂载方式消费这些凭据来访问 S3 端点。
字段详解:Metadata 与 Spec
Metadata
name:要创建的对象存储用户名称。它不仅对应 RGW 中的用户 ID,还会反映到 Secret 等关联资源的命名上(如rook-ceph-object-user-<store>-<name>),因此应遵循 DNS 子域名命名规范。namespace:Rook 集群所在的命名空间(通常为rook-ceph),用户默认创建于该命名空间。若配合下文clusterNamespace使用,也可以是其他命名空间。
Spec 核心字段
store:用户将归属的对象存储,取值必须与CephObjectStoreCR 的name一致。控制器在调谐时会校验该对象存储是否存在,否则报错并重试(见 controller.go 的getObjectStore)。displayName:传递给radosgw-admin user create命令的显示名称。从源码generateUserConfig看,若未设置则默认回退为用户名(controller.go)。clusterNamespace:父级CephCluster与CephObjectStore所在的命名空间。如果用户与集群/对象存储不在同一命名空间,必须显式指定;同时父对象存储的spec.allowUsersInNamespaces必须包含该用户所在的命名空间,否则控制器会拒绝创建(返回"object store ... does not allow creating users namespace ..."错误)。具体实现见 controller.go 的initializeObjectStoreContext与userInNamespaceAllowed,以及 types.go 中ObjectStoreSpec.AllowUsersInNamespaces的字段说明(支持"*"通配全部命名空间,默认为空)。
从 API 类型定义(types.go 的 ObjectStoreUserSpec)看,Spec 实际还支持 keys 与 accountRef 两个进阶字段,详见下文"进阶能力"一节。
配额管理:quotas
quotas 用于对用户设置资源使用上限,对应 RGW 的配额管理(quota management)能力。三个子字段:
| 字段 | 类型 | 含义 | 说明 |
|---|---|---|---|
maxBuckets |
int | 用户可创建的桶数量上限 | 源码中默认值为 1000(见 controller.go);显式设置后覆盖默认值 |
maxSize |
string | 所有桶中对象的总容量上限 | 使用 Kubernetes resource.Quantity 格式,如 10G、500M;API 类型定义见 types.go |
maxObjects |
int64 | 所有桶中对象的总数量上限 | 未设置时底层按 -1(不限)处理 |
调谐时,控制器会把配额组装为 admin.QuotaSpec(包含 Enabled、MaxSize、MaxObjects)并调用 SetUserQuota 应用到 RGW(见 controller.go)。只要 maxSize 或 maxObjects 任一被设置,配额开关(Enabled)即被打开。
管理能力:capabilities
Ceph 允许为 RGW 用户授予额外的管理权限(admin capabilities)。Rook 支持对以下资源授予 read、write、read, write 或 * 权限,完整字段定义见 types.go 的 ObjectUserCapSpec:
| 资源 | YAML 字段 | 说明 |
|---|---|---|
| user / users | user、users |
管理对象存储用户的权限 |
| buckets | bucket、buckets |
管理桶的权限 |
| usage | usage |
读取使用量统计 |
| metadata | metadata |
管理元数据 |
| zone | zone |
管理 zone |
| roles | roles |
管理角色 |
| info | info |
读取用户信息 |
| amz-cache | amz-cache |
使用 RGW Cache API 请求头 |
| bilog | bilog |
修改桶索引日志 |
| mdlog | mdlog |
修改元数据日志 |
| datalog | datalog |
修改数据日志 |
| user-policy | user-policy |
修改用户策略 |
| oidc-provider | oidc-provider |
修改 OIDC Provider(原文档中写作 odic-provider,实际字段为 oidc-provider) |
| ratelimit | ratelimit |
为用户和桶设置速率限制 |
| userInfoWithoutKeys | userInfoWithoutKeys |
获取不含密钥的用户信息,要求 Ceph ≥ 19.2.0 |
| accounts | accounts |
管理账户(accounts),要求 Ceph ≥ 19.2.3 |
后两个能力存在版本门槛:控制器在 generateUserConfig 中会检查运行中的 Ceph 版本(最低版本常量定义于 controller.go),版本不足时仅记录告警日志而不会注入该能力(见 controller.go)。
关于更新限制:原文档指出,由于 go-ceph 缺少更新用户能力的 API,capabilities 目前只能在用户创建时生效;如需修改,必须删除并重建用户。不过从当前仓库的控制器源码看(controller.go),调谐逻辑已经实现了能力差异检测——先通过 RemoveUserCap 移除现有能力,再通过 AddUserCap 设置目标能力,因此较新版本中修改 capabilities 也会在下次调谐时被同步到 RGW。若你依赖"仅创建时生效"的旧行为,建议以所部署版本的发布说明为准。
操作掩码:opMask
opMask 是最容易与 IAM 策略混淆、但语义截然不同的一个字段。RGW 内部把对持久化状态的操作标记为三类:
RGW_OP_TYPE_READ(read)RGW_OP_TYPE_WRITE(write)RGW_OP_TYPE_DELETE(delete)
每个 RGW 用户都有一个"操作掩码"。需要特别强调:它并不是通常意义上的位掩码/过滤器,而是用户被允许执行的"操作类型"的集合,并且无论桶策略或 IAM 策略如何配置,该掩码都会生效。举例来说,一个 RGW 用户要读取桶中的对象,必须同时满足两个条件:
- 拥有
read的 opMask 位; - IAM/桶策略允许
s3:GetObject。
opMask 与策略是"与"的关系,二者缺一不可。
关键行为(与文档及源码一致):
- 默认值:未显式设置时,默认允许
read、write、delete三个操作(controller.go); - 空序列
<a href="https://link.gitcode.com/i/5460e7ad1779337e9104c0c2f37840b0" target="_blank">]:将掩码中所有操作移除,用户将无法执行任何操作。从实现看,此时生成的掩码字符串为<none>(见 [pkg/operator/ceph/object/user/opmask/opmask.go 的String()方法,<none>也是 admin api 与radosgw-admin返回的等价表示); - 支持的取值:仅
read、write、delete三种。API 类型通过 kubebuilder 校验约束为Enum=read;write;delete、MaxItems=3、MinItems=0且listType=set(types.go)。
掩码到字符串的归一化(按 read, write, delete 顺序输出,与 admin api/radosgw-admin 返回顺序一致)由 opmask.go 的 FromSlice 与 String 完成,并配有单元测试 opmask_test.go。
跨命名空间创建用户
默认情况下,CephObjectStoreUser 必须与 CephCluster/CephObjectStore 位于同一命名空间。若希望把用户创建到应用所在的独立命名空间(例如既不用 OBC 也不用 COSI 的场景),需要两步配合:
- 在父对象存储 CR 中放行该命名空间:
apiVersion: ceph.rook.io/v1
kind: CephObjectStore
metadata:
name: my-store
namespace: rook-ceph
spec:
# ...其他对象存储配置...
allowUsersInNamespaces:
- my-app-namespace # 或 "*" 放行所有命名空间
- 在用户 CR 中指定集群所在命名空间:
apiVersion: ceph.rook.io/v1
kind: CephObjectStoreUser
metadata:
name: my-user
namespace: my-app-namespace
spec:
store: my-store
displayName: my-display-name
clusterNamespace: rook-ceph # 集群与对象存储所在命名空间
allowUsersInNamespaces 的定义与语义见 types.go,放行校验逻辑见 controller.go。
进阶能力:自定义凭据与账户关联
原文档未展开、但源码已实现的两个进阶字段:
spec.keys:自定义访问凭据
默认情况下控制器会为 RGW 用户自动生成密钥对。若需要将预先存在的密钥对(如企业密钥管理系统生成的凭据)注入用户,可以通过 spec.keys 引用存有 accessKey/secretKey 的 Kubernetes Secret(类型定义见 types.go):
apiVersion: ceph.rook.io/v1
kind: CephObjectStoreUser
metadata:
name: my-user
namespace: rook-ceph
spec:
store: my-store
displayName: my-display-name
keys:
- accessKeyRef:
name: my-creds-secret
key: accessKey
secretKeyRef:
name: my-creds-secret
key: secretKey
控制器会通过字段索引监听这些 Secret 的变化(controller.go),并调用 CreateKey/RemoveKey 把 RGW 侧密钥集合收敛到与 spec.keys 完全一致(reconcileUserKeys,controller.go);用户侧不存在的多余密钥会被清理。
accountRef:关联对象存储账户
通过 accountRef 可将用户关联到一个 CephObjectStoreAccount,此时用户以"账户用户"身份创建且默认无任何权限,其创建的资源归属于该账户。控制器会校验账户的 store 与用户一致、等待账户 Ready 后解析 accountID(controller.go)。由于账户用户在 IAM 策略 ARN 中通过 displayName 引用,关联账户时 displayName 必须匹配 IAM 兼容模式 ^<a href="https://link.gitcode.com/i/330b9df1616175e725eeb2e3eacfde7b" target="_blank">\w+=,.@-]+$([controller.go、validateUser)。字段定义见 types.go,并带有"accountRef 不可变"的 CEL 校验。
状态与密钥产出
CephObjectStoreUser 通过 .status 暴露调谐结果(类型定义见 types.go):
status.phase:Ready/Progressing/Failed等阶段;status.info.secretName:凭据 Secret 的名称(rook-ceph-object-user-<store>-<user>);status.keys:spec.keys引用 Secret 的引用列表(Name、Namespace、UID、ResourceVersion);status.observedGeneration:最近一次成功调谐对应的 generation。
CRD 同时注册了短名 rcou、objectuser、cephosu 以及 Phase、Age 两个打印列(见 types.go 的 kubebuilder marker)。
常用运维命令
# 创建用户
kubectl create -f deploy/examples/object-user.yaml
# 查看用户列表(短名 cephosu 亦可)
kubectl -n rook-ceph get cephobjectstoreuser
kubectl -n rook-ceph get cephosu
# 查看用户详情与状态
kubectl -n rook-ceph describe cephobjectstoreuser my-user
# 查看生成的凭据 Secret
kubectl -n rook-ceph get secret rook-ceph-object-user-my-store-my-user -o yaml
# 删除用户(控制器会同步删除 RGW 用户并移除 finalizer)
kubectl -n rook-ceph delete cephobjectstoreuser my-user
注意:删除用户会级联移除其 RGW 账户与凭据 Secret,请确保该用户不再承载任何业务流量。更多对象存储的整体使用方式可参考 Documentation/Storage-Configuration/Object-Storage-RGW/object-storage.md,对象存储 CR 的完整字段见 Documentation/CRDs/Object-Storage/ceph-object-store-crd.md。
相关源码导航
- API 类型定义(
CephObjectStoreUser、ObjectStoreUserSpec、ObjectUserCapSpec、ObjectUserQuotaSpec、ObjectUserOpMask、ObjectUserKey):pkg/apis/ceph.rook.io/v1/types.go - 控制器实现(调谐主流程、用户创建/更新/删除、Secret 生成、配额与能力同步):pkg/operator/ceph/object/user/controller.go
- opMask 归一化实现与单元测试:pkg/operator/ceph/object/user/opmask/opmask.go、pkg/operator/ceph/object/user/opmask/opmask_test.go
- 控制器测试:pkg/operator/ceph/object/user/controller_test.go
- 可直接套用的示例清单:deploy/examples/object-user.yaml