Rook CephObjectStoreUser CRD 完整指南:在 Kubernetes 上以声明式方式管理 RGW 对象存储用户

原创2026-09-21 22:35:591,648 阅读
文章标签:云原生存储容器编排运维

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 函数):

  1. 读取 CephObjectStoreUser 实例并添加 finalizer,确保删除资源时同步清理 RGW 侧的用户;
  2. 定位所属 CephCluster 与 CephObjectStore(支持跨命名空间定位);
  3. 通过 go-ceph 的 admin ops API 调用 RGW:用户不存在则 CreateUser,存在则按需 ModifyUser、增删能力(AddUserCap/RemoveUserCap)、设置配额(SetUserQuota);
  4. 在 Kubernetes 中生成/更新存放凭据的 Secret(命名规则为 rook-ceph-object-user-<store>-<user>);
  5. 更新资源 .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:用户将归属的对象存储,取值必须与 CephObjectStore CR 的 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 用户要读取桶中的对象,必须同时满足两个条件:

  1. 拥有 read 的 opMask 位;
  2. 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 的场景),需要两步配合:

  1. 在父对象存储 CR 中放行该命名空间:
apiVersion: ceph.rook.io/v1
kind: CephObjectStore
metadata:
  name: my-store
  namespace: rook-ceph
spec:
  # ...其他对象存储配置...
  allowUsersInNamespaces:
    - my-app-namespace   # 或 "*" 放行所有命名空间
  1. 在用户 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。

相关源码导航

登录后查看全文
rook