Rook CephObjectStore CRD 完全指南:在 Kubernetes 上配置 Ceph 对象存储(RGW)
Rook CephObjectStore CRD 完全指南:在 Kubernetes 上配置 Ceph 对象存储(RGW)
本篇指南以 Rook 仓库中的 CephObjectStore CRD 文档 为骨架,系统讲解如何通过 CephObjectStore 自定义资源在 Kubernetes 集群中创建与定制 Ceph 对象存储(RGW)服务。你将掌握从基础示例、池与网关配置,到 Keystone/Swift 认证、多站点(Multisite)、TLS/安全(KMS 加密)、运行期调参与删除保护在内的完整 CRD 字段语义与实战用法,并结合 Rook 源码理解各参数在 operator 中的实际生效路径。
概述:通过 CRD 管理对象存储
Rook 允许通过自定义资源定义(CRD)创建和定制对象存储。CephObjectStore 资源(API 组 ceph.rook.io/v1)描述了一个 Ceph RGW(RADOS Gateway)实例集群的期望状态,包括其元数据池、数据池、网关副本数、认证协议、TLS 安全选项与健康检查策略。Rook operator 监听该资源,负责创建 RGW Deployment、Service、ConfigMap、keyring 与相关池,并在资源被更新时进行滚动升级(升级策略为 RollingUpdate,MaxUnavailable: 1、MaxSurge: 0,见 spec.go)。
在深入各字段之前,建议先阅读 对象存储使用文档 了解创建对象存储用户、bucket 与访问端点的方式;本文聚焦 CRD 本身的全部可配置项。
示例:一个完整的 CephObjectStore 定义
以下 YAML 是官方文档给出的完整示例,同时使用了复制池与纠删码池:
apiVersion: ceph.rook.io/v1
kind: CephObjectStore
metadata:
name: my-store
namespace: rook-ceph
spec:
metadataPool:
failureDomain: host
replicated:
size: 3
dataPool:
failureDomain: host
erasureCoded:
dataChunks: 2
codingChunks: 1
parameters:
# Ceph Tentacle v20 的优化需要显式开启
# allow_ec_optimizations: "true"
preservePoolsOnDelete: true
gateway:
# sslCertificateRef:
# caBundleRef:
port: 80
# securePort: 443
instances: 1
# 注解的键值对列表
annotations:
# key: value
placement:
# nodeAffinity:
# requiredDuringSchedulingIgnoredDuringExecution:
# nodeSelectorTerms:
# - matchExpressions:
# - key: role
# operator: In
# values:
# - rgw-node
# tolerations:
# - key: rgw-node
# operator: Exists
# podAffinity:
# podAntiAffinity:
# topologySpreadConstraints:
resources:
# limits:
# memory: "1024Mi"
# requests:
# cpu: "500m"
# memory: "1024Mi"
#zone:
#name: zone-a
#hosting:
# advertiseEndpoint:
# dnsName: "mystore.example.com"
# port: 80
# useTls: false
# dnsNames:
# - "mystore.example.org"
纠删码使用要点
纠删码池只能用于 dataPools;metadataPool 必须使用复制池。示例要求至少 3 个 bluestore OSD,且每个 OSD 位于不同节点——这是因为 failureDomain 设置为 host,而 erasureCoded 的分块设置需要至少 3 个不同的 OSD(2 个 dataChunks + 1 个 codingChunks)。
示例中的注释提及了 Ceph Tentacle v20 的
allow_ec_optimizations参数,该参数需要显式设置为"true"才能启用针对纠删码池的优化。
对象存储设置(Object Store Settings)
Metadata 元数据
name:要创建的对象存储名称,会体现在池名及其他资源名称中。需要注意 Rook 对名称长度有限制:由于资源名总长不能超过 Kubernetes 的 63 字符限制,而 Rook 会额外创建一个名为rook-ceph-rgw-<STORE-NAME>-mime-types的 ConfigMap,因此在非外部集群场景下对象存储名称最长 38 个字符。这一校验在 object.go 的ValidateObjectSpec中实现(objectStoreNameMaxLen = 38);对外部集群(external模式)则不校验名称长度,以兼容历史遗留的外部集群名称。namespace:对象存储所在 Rook 集群的命名空间。
Pools 池设置
池允许使用 Block Pool CRD spec 中定义的全部设置。示例中要求集群至少有 3 个主机(size 3)和至少 3 个设备(2 数据块 + 1 编码块)。
从源码看,Rook 为对象存储维护两类池:metadata 池(rgw.control、rgw.meta、rgw.log、rgw.buckets.index、rgw.buckets.non-ec、rgw.otp,再加上 root pool .rgw.root)以及数据池 rgw.buckets.data,定义见 objectstore.go。当设置了 zone 段时,Rook 不会创建以对象存储名称命名的池,因为此时对象存储将使用由 CephObjectZone 创建的池(对应源码中的 zonePoolNSSuffix 映射,覆盖 .meta.root、.control、.log.gc、.log.lc、.log、.meta.users.* 等 zone 专属池,见 objectstore.go)。
各字段说明:
metadataPool:用于创建对象存储全部元数据池的设置,必须使用复制。dataPool:用于创建对象存储数据池的设置,可以使用复制或纠删码。preservePoolsOnDelete:设为true时,对象存储被删除后其支撑池会保留,这是避免数据意外丢失的安全措施。默认false(未指定也视为false)。源码中在 objectstore.go 有对应逻辑:删除时若该标志为false则删除池,否则跳过并打印日志。allowUsersInNamespaces:当CephObjectStoreUser在 Rook 集群命名空间之外创建时,必须把该命名空间加入此列表(或使用"*"允许所有命名空间)。这对需要在自身命名空间内创建对象存储凭据、且未使用 OBC 或 COSI 的应用很有用。默认值为空列表。该字段定义于 types.go,并在 user/controller.go 中通过userInNamespaceAllowed校验,未授权会返回"object store ... does not allow creating users namespace ..."错误。
Realm 领域设置
defaultRealm:设为true时,Rook 会将此对象存储所属 realm 标记为 Ceph 集群中的默认 realm。同一时刻只能有一个 realm 被标记为默认;Ceph 不允许在赋值后取消默认标记,但可以将另一个 realm 标记为默认来替换它。
认证设置(Auth Settings)
auth 段允许在常规认证机制之外配置额外的认证提供方。目前仅支持 OpenStack Keystone。
Keystone 设置
Keystone 认证在 spec.auth.keystone 段配置:
spec:
[...]
auth:
keystone:
acceptedRoles:
- admin
- member
- service
implicitTenants: "swift"
revocationInterval: 1200
serviceUserSecretName: usersecret
tokenCacheSize: 1000
url: https://keystone.example-namespace.svc/
protocols:
swift:
accountInUrl: true
urlPrefix: swift
[...]
注意:使用此示例配置时,即使
protocols段未显式启用 S3,S3 也是被隐式启用的(S3 默认开启)。
可配置项说明:
acceptedRoles:RGW 向 Keystone 认证时接受的 OpenStack Keystone 角色列表(如admin、member、service)。implicitTenants:是否使用隐式租户,取值可为true、false、swift和s3。更多细节参见 Ceph RadosGW 的多租户文档。revocationInterval:两次 token 吊销检查之间的间隔秒数。serviceUserSecretName:包含 rgw 与 Keystone 通信时使用的 admin 用户凭据的 Kubernetes Secret 名称。关于 Secret 必须包含的内容,参见 Object Store with Keystone and Swift。tokenCacheSize:每个 Keystone token 缓存的最大条目数。url:要使用的 Keystone API 端点 URL。
Protocols 协议设置
protocols 段分为三部分:
enableAPIs:要在 RGW 实例中启用的 API 列表。如果不设置,将启用全部 API。可选值:s3, s3website, swift, swift_auth, admin, sts, iam, notifications。对应 Ceph 的rgw_enable_apis配置参数。在 Rook 源码中,非 S3 的 API 列表被单独维护为rgwAPIwithoutS3 = <a href="https://link.gitcode.com/i/d82affc91506b595adc8d7d61c0c73bb" target="_blank">]string{"s3website", "swift", "swift_auth", "admin", "sts", "iam", "notifications"}(见 [spec.go),用于在禁用 S3 时正确组装rgw_enable_apis。- 一个配置 S3 的段。
- 一个配置 Swift 的段。
spec:
[...]
protocols:
enableAPIs: []
swift:
# 配置 swift 的段
s3:
# 配置 s3 的段
[...]
protocols/s3 设置
authUseKeystone:S3 是否也使用 Keystone 认证(true)或否(false)。设为false时使用默认的 S3 认证。enabled:是否启用 S3(true)或否(false)。默认是true,即使完全不写该段也默认启用。请注意,在 Ceph Multi Site 配置中不应禁用 S3。
protocols/swift 设置
accountInUrl:Swift API URL 中是否包含 Swift 账号名。设为false(默认值)时,Swift API 监听在形如http://host:port/<rgw_swift_url_prefix>/v1的 URL 上;设为true时,URL 形如http://host:port/<rgw_swift_url_prefix>/v1/AUTH_<account_name>。若 radosgw 需要支持公开可读容器和临时 URL,此选项必须设为true。urlPrefix:Swift API 的 URL 前缀,用于与 S3 API 端点区分。默认swift,即 Swift API 位于http://host:port/swift/v1(若启用 account-in-url 则为http://host:port/swift/v1/AUTH_%(tenant_id)s)。警告:如果将此选项设为/,S3 API 会被自动禁用,无法在 urlPrefix 为/时同时支持 S3 与 Swift 两种 API。versioningEnabled:设为true时启用 OpenStack Object Storage API 的对象版本化,允许客户端在需要版本化的容器上设置X-Versions-Location属性。
网关设置(Gateway Settings)
网关设置对应 RGW daemon 的配置。
-
type:目前支持S3。 -
sslCertificateRef:指定时,为包含 TLS 证书的 Kubernetes Secret 名称(opaque或tls类型),用于对象存储的安全连接。若为 opaque 类型 Secret,Rook 会在cert键名下查找证书;cert键的值必须是 RGW beast frontend 所期望的格式。若证书由内部 CA 签发,可将完整证书链按"叶子证书在前、中间证书随后、根证书最后"的顺序拼接。beast frontend 只使用链中的第一张证书,但 Rook operator 在连接 RGW 做管理操作时会使用整个证书链。如果证书的 DNS 只针对特定域名设置(不含本地 Kubernetes DNS,即对象存储的 Service DNS 端点),且不想把 Service DNS 名加进证书,可以在 Secret 的 data 中额外指定
insecureSkipVerify: true跳过证书校验。不建议启用该选项,因为除非使用自定义校验,否则 TLS 易受中间人攻击。 -
caBundleRef:指定时,为包含附加自定义 ca-bundle 的 Kubernetes Secret 名称(opaque类型),且必须与 Rook 集群同命名空间。Rook 会在cabundle键名下查找。该 bundle 供 RGW 验证其连接的外部应用(例如 LDAP 服务器,或多站点连接中的其他 RGW realm)。该 bundle 不用于 Rook operator 连接 RGW——若需要 operator 使用完整证书链,请按上面sslCertificateRef的说明把整个链加载到cert中。从源码看,caBundle 的键名常量caBundleKeyName = "cabundle"、挂载路径/etc/ceph/rgw-ca-bundle/定义于 config.go。 -
hostNetwork:是否对 rgw daemon 启用主机网络。未设置时,应用 Cluster CR 中的网络设置。对应的判定逻辑见 object.go 的IsHostNetwork。 -
port:Object 服务可达的端口。启用主机网络时 RGW daemon 也监听该端口;运行在 SDN 上时,RGW daemon 内部监听端口固定为 8080(源码常量rgwPortInternalPort = 8080,见 config.go)。 -
securePort:RGW pod 监听的 TLS 端口。必须通过sslCertificateRef或service.annotations指定 TLS 证书。启用 TLS 的细节参见 enabling TLS。注意校验规则:port与securePort不能同时为 0,securePort必须在 0~65535 之间(见 object.go)。 -
instances:为对象存储负载均衡而启动的 pod 数量。源码中该值作为 Deployment 的Replicas(见 spec.go)。 -
externalRgwEndpoints:要连接的外部现有 Rados Gateway 的 IP 地址列表(用于 external 模式)。如果CephCluster未启用externalspec,此设置会被忽略。可给出多个端点,但为了 ObjectBucketClaims 的稳定性,强烈建议只给出一个指向多个 RGW 的负载均衡器作为唯一外部端点。更多细节参见 external cluster 文档。外部 RGW 端点示例:
gateway: port: 80 externalRgwEndpoints: - ip: 192.168.39.182 # hostname: example.com -
annotations:要添加的注解键值对列表。 -
labels:要添加的标签键值对列表。 -
placement:决定 RGW pod 在集群中启动位置的 Kubernetes placement 设置(nodeAffinity、tolerations、podAffinity、podAntiAffinity、topologySpreadConstraints 等)。 -
resources:为 Gateway Pod 设置资源 requests/limits,参见 Resource Requirements/Limits。 -
priorityClassName:为 Gateway Pod 设置优先级类名。 -
additionalVolumeMounts:要挂载到 RGW pod 的附加卷。每个附加卷挂载的根目录是/var/rgw,每个卷挂载通过subPath定义文件挂载的子目录。Rook 支持多种标准 Kubernetes 卷类型。例如:挂载 subPath 为ldap、来自含bindpass.secret键的 Secret 时,文件将位于/var/rgw/ldap/bindpass.secret。这与后文 advanced configuration 中rgw_ldap_secret的用法形成配套。 -
service:设置到 RGW 的 Kubernetes Service 上的注解。例如启用 OpenShift 的 service serving cert 功能:gateway: service: annotations: service.beta.openshift.io/serving-cert-secret-name: <name of TLS secret for automatic generation>源码常量
ServiceServingCertKey = "service.beta.openshift.io/serving-cert-secret-name"定义于 object.go;IsTLSEnabled()会在securePort非 0 且(sslCertificateRef或 serving-cert 注解)存在时判定 TLS 已启用(object.go)。 -
opsLogSidecar:默认情况下所有 RGW 日志都包含在主 RGW 容器日志中。为增强可观测性,可通过启用 sidecar 将 RGW operations log 与主容器日志分离(对应 Cephrgw_enable_ops_log配置)。启用方式:gateway: opsLogSidecar: resources: requests: {} limits: {}启用后,可通过 RGW pod 的
ops-logsidecar 容器查看日志:kubectl --namespace rook-ceph logs rook-ceph-rgw-my-store-a-59d48474d8-jv7ps --container ops-log从源码看,ops 日志文件名格式为
ops-log.$(POD_NS).$(POD_NAME).log(依赖注入的POD_NS/POD_NAME环境变量),存放在/var/log/ceph/下(见 spec.go)。
Zone 设置(Zone Settings)
Zone 设置允许对象存储加入自定义创建的 ceph-object-zone。
name:对象存储所属的 ceph-object-zone 名称。
设置 zone.name 后,ObjectStoreSpec.IsMultisite() 返回 true(见 object.go),Rook 将不再为本 store 创建默认池,而是复用 zone 的池(多站点相关逻辑见 objectstore.go 与 controller.go)。
Hosting 设置(Hosting Settings)
hosting 设置允许指定对象存储的端点配置。这些设置仅支持 Ceph v18 及以上版本。
一个常见的需要配置 hosting 的场景是允许 virtual host-style。
-
advertiseEndpoint:默认情况下,Rook 会向 CephObjectStoreUsers 和 ObjectBucketClaims 等依赖资源通告到 RGW 的最直接连接。要通告其他地址(例如支持通配符的 ingress),可在此定义首选端点。默认行为详见 object-store endpoint。dnsName:端点的合法 RFC-1123(子)域名。port:端点的非零端口。useTls:端点使用 HTTPS 则为true,HTTP 则为false。
源码中端点通告逻辑:默认通告地址为 Service 域名
<service-name>.<namespace>.svc,外部集群则取第一个外部端点;用户显式设置advertiseEndpoint后优先使用用户值,并同时返回协议(http/https)、端口(见 object.go 的AdvertiseEndpointIsSet、GetAdvertiseEndpoint、GetAdvertiseEndpointUrl)。 -
dnsNames:设置本项或advertiseEndpoint时,Ceph RGW 会拒绝通过任何未指定 DNS 名称访问对象存储的 S3 客户端连接。应在此添加对象存储需要接受的所有 DNS 名称,它们必须是合法的 RFC-1123(子)域名。Rook 会自动将已知的 CephObjectStore Service DNS 名,以及对应的 CephObjectZonecustomEndpoints(如适用)加入此列表。
注意:对于支持通配符的 DNS 名称,不要包含通配符。例如使用
mystore.example.com而非*.mystore.example.com。
从源码看,hosting 段会在 CRD 校验时逐一验证 dnsName/dnsNames 是否为合法的 DNS-1123 子域名、端口是否在 1~65535 之间(见 object.go)。
运行期设置(Runtime settings)
MIME 类型
Rook 为每个 Ceph 对象存储提供默认的 mime.types 文件,存放在名为 rook-ceph-rgw-<STORE-NAME>-mime-types 的 Kubernetes ConfigMap 中。对大多数用户而言默认文件即可满足需求,但用户也可以按需编辑 ConfigMap 中的 mime.types 文件——例如添加自有特殊文件类型;注重安全的用户可能希望精简该文件,降低文件类型执行攻击的风险。
Rook 不会覆盖已存在的 mime.types ConfigMap,因此用户修改不会被破坏。如果对象存储被销毁并重建,ConfigMap 也会随之销毁并重新创建。
从源码看,mime.types 以 Go embed 方式内嵌(//go:embed 之外通过常量 mimeTypes 定义,见 mime.go),ConfigMap 创建逻辑 generateMimeTypes() 会先检查 ConfigMap 是否已存在,存在则跳过不覆盖(mime.go);卷挂载路径为 /etc/ceph/rgw/mime.types 且只读(mimeTypesVolumeMount,防止恶意修改引入文件类型执行漏洞,见 mime.go)。默认 mime.types 覆盖了 application/*、audio/*、chemical/*、image/*、message/*、model/*、multipart/*、text/*、video/*、x-conference/*、x-epoc/*、x-world/* 等大类,其中 PHP、eruby 等易被滥用的类型被注释掉。
健康设置(Health settings)
Rook 默认会监控对象存储端点的状态。可用的 CRD 设置:
healthCheck:对象存储健康监控的主段。startupProbe:禁用或覆盖对象网关 startup probe 的时机与阈值。readinessProbe:禁用或覆盖对象网关 readiness probe 的时机与阈值。
完整示例:
healthCheck:
startupProbe:
disabled: false
readinessProbe:
disabled: false
periodSeconds: 5
failureThreshold: 2
从源码看,probe 类型有 startup 与 readiness 两种(StartupProbeType/ReadinessProbeType,见 spec.go),probe 会根据是否启用 TLS 选择 HTTP 或 HTTPS 协议对 RGW 端口做健康探测。
你可以通过监控对象存储创建的网关 Deployment 来监控其健康状态。主 Deployment 命名为 rook-ceph-rgw-<store-name>-a,其中 store-name 是 CephObjectStore 的名称(别忘了末尾的 -a)。
安全设置(Security settings)
Ceph RGW 支持 AWS S3 协议 定义的服务器端加密(SSE),共有三种模式:AWS-SSE:C、AWS-SSE:KMS 和 AWS-SSE:S3。后两种模式需要密钥管理系统(KMS),如 HashiCorp Vault。目前 Vault 是 CephObjectStore 唯一支持的 KMS 后端。
关于 Vault 的详细说明参见 Vault KMS 文档。若定义了这些设置,则当 S3 客户端发送带服务器端加密的请求时,RGW 会在 Vault 与自身之间建立连接。
security 段包含 RGW 的 KMS 加密设置以及 RGW beast frontend 的 TLS 选项。
Beast frontend TLS 选项
网关启用 TLS 时,Rook 使用 security 段中的可选 TLS 设置配置 Ceph RGW beast frontend,这些设置直接映射到 beast frontend 选项:
sslOptions:SSL 上下文选项(协议版本、workarounds 等)。ciphers:ssl_ciphers(TLS v1.2 及以下)的密码字符串。要求sslOptions中至少启用tlsv1_2、tlsv1_1、tlsv1_0之一。cipherSuites:ssl_ciphersuites(TLS v1.3)的密码字符串。要将网关限制为仅 TLS 1.3,需在sslOptions中将tlsv1_2、tlsv1_1、tlsv1_0均设为false。tlsGroups:tls_groups的冒号分隔 TLS 组名。
TLS 1.2 密码控制示例:
security:
ciphers:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
tlsGroups:
- X25519
- P-256
TLS 1.3 密码套件控制示例:
security:
sslOptions:
tlsv1_2: false
tlsv1_1: false
tlsv1_0: false
cipherSuites:
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
tlsGroups:
- X25519
- P-256
TLS 1.2 与 TLS 1.3 密码控制示例:
security:
ciphers:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
cipherSuites:
- TLS_AES_256_GCM_SHA384
tlsGroups:
- X25519
- P-256
从源码看,这些选项被拼接到 beast frontend 字符串(如 beast port=... ssl_port=... ssl_certificate=... ssl_options=... ssl_ciphers=... ssl_ciphersuites=... tls_groups=...),具体逻辑见 config.go 的 rgwFrontendStr 与 buildSSLOptions(后者会为每个未启用的旧版协议追加 no_sslv2、no_sslv3、no_tlsv1、no_tlsv1_1、no_tlsv1_2 选项)。校验逻辑 validateObjectStoreSecurity 要求设置 ciphers 时至少启用一个 TLS v1.2 及以下的版本(object.go)。
KMS 加密
security:
kms:
connectionDetails:
KMS_PROVIDER: vault
VAULT_ADDR: http://vault.default.svc.cluster.local:8200
VAULT_BACKEND_PATH: rgw
VAULT_SECRET_ENGINE: kv
VAULT_BACKEND: v2
# 包含 kms 认证 token 的 k8s secret 名称
tokenSecretName: rgw-vault-kms-token
s3:
connectionDetails:
KMS_PROVIDER: vault
VAULT_ADDR: http://vault.default.svc.cluster.local:8200
VAULT_BACKEND_PATH: rgw
VAULT_SECRET_ENGINE: transit
# 包含 kms 认证 token 的 k8s secret 名称
tokenSecretName: rgw-vault-s3-token
针对 RGW 请注意以下几点:
-
VAULT_SECRET_ENGINE:Vault 使用的 secret engine,目前支持kv和transit。AWS-SSE:KMS 支持transitengine 和kvengine 版本 2;AWS-SSE:S3 仅支持transitengine。 -
Storage 管理员需要在 Vault 服务器中创建 Secret,以便 S3 客户端在 AWS-SSE:KMS 场景下使用该密钥加密:
vault kv put rook/<mybucketkey> key=$(openssl rand -base64 32) # kv engine vault write -f transit/keys/<mybucketkey> exportable=true # transit engine -
tokenSecretName对于 kms 和 s3 配置可以相同(也经常相同)。
SSE-S3 与 Vault Agent
除了为 SSE-S3 使用静态 token,还可以使用以 sidecar 形式运行在 RGW pod 中的 Vault Agent。Agent 使用 pod 的 Kubernetes service account 向 Vault 认证(通过 Vault 的 Kubernetes auth method),并作为本地代理运行,从而无需管理静态 token。
该方案使用 Vault Agent Injector(一个 mutating admission webhook)自动将 Vault Agent sidecar 注入 RGW pod。
前置条件
-
在集群中部署 Vault Agent Injector:
helm repo add hashicorp https://helm.releases.hashicorp.com helm install vault hashicorp/vault \ --set "injector.enabled=true" \ --set "server.enabled=false" # 如果使用外部 Vault 服务器 -
为 Vault 配置 Kubernetes auth 方法、策略与角色:
# 启用 Kubernetes auth 方法 vault auth enable kubernetes # 配置 Kubernetes auth vault write auth/kubernetes/config \ kubernetes_host="https://$KUBERNETES_HOST:443" # 创建授予 transit engine 访问权限的策略 vault policy write rgw-sse-s3 - <<EOF path "transit/keys/*" { capabilities = ["create", "read", "update", "delete"] } path "transit/keys/+/rotate" { capabilities = ["update"] } path "transit/datakey/plaintext/*" { capabilities = ["update"] } path "transit/decrypt/*" { capabilities = ["update"] } path "transit/export/encryption-key/*" { capabilities = ["read"] } EOF # 创建绑定到 RGW service account 的角色 vault write auth/kubernetes/role/rook-ceph-rgw \ bound_service_account_names=rook-ceph-rgw \ bound_service_account_namespaces=rook-ceph \ policies=rgw-sse-s3 \ ttl=1h
配置
在 s3 connection details 中设置 VAULT_AUTH_METHOD: agent,并在 gateway spec 中添加 Vault Agent Injector 注解。VAULT_ADDR 应指向本地 Vault Agent 代理(通常为 http://127.0.0.1:8100)。由于注入的 agent 负责认证,无需 tokenSecretName。
apiVersion: ceph.rook.io/v1
kind: CephObjectStore
metadata:
name: my-store
namespace: rook-ceph
spec:
gateway:
annotations:
vault.hashicorp.com/agent-inject: "true"
vault.hashicorp.com/role: "rook-ceph-rgw"
vault.hashicorp.com/agent-cache-enable: "true"
vault.hashicorp.com/agent-cache-listener-port: "8100"
# 如需 TLS 连接 Vault 服务器:
# vault.hashicorp.com/ca-cert: "/vault/tls/ca.crt"
# vault.hashicorp.com/client-cert: "/vault/tls/tls.crt"
# vault.hashicorp.com/client-key: "/vault/tls/tls.key"
security:
s3:
connectionDetails:
KMS_PROVIDER: vault
VAULT_ADDR: http://127.0.0.1:8100
VAULT_SECRET_ENGINE: transit
VAULT_AUTH_METHOD: agent
高级配置(Advanced configuration)
警告:此功能面向高级用户,允许轻松应用可能破坏集群的配置。请谨慎使用。
CephObjectStore 允许向服务该对象存储的 RGW daemon 应用任意的 Ceph 配置。配置会应用到服务该 CephObjectStore 的所有 RGW 上,值必须是字符串。以下示例仅用于展示不同值的数据类型(不代表官方推荐配置):
# 本示例不构成推荐
# ...
spec:
gateway:
# ...
rgwConfig:
debug_rgw: "10" # int
# debug-rgw: "20" # 等价的配置键可用短横线或下划线
rgw_s3_auth_use_ldap: "true" # bool
rgwConfigFromSecret:
rgw_keystone_barbican_password: # 值为 secret 的 rgw 选项名
name: "barbican-secret" # K8s secret 名称
key: "password" # secret 值在 K8s secret.Data map[string]string 中的键
rgwCommandFlags:
rgw_dmclock_auth_res: "100.0" # float
rgw_d4n_l1_datacache_persistent_path: /var/log/rook/rgwd4ncache # string
rgw_d4n_address: "127.0.0.1:6379" # IP string
三种配置方式的区别:
rgwConfig:这些配置在运行时被应用和修改,无需重启 RGW。rgwConfigFromSecret:与rgwConfig相同,但配置值从 Kubernetes Secret 引用。源码中 operator 会先校验 Secret 的name/key组合,再从 Secret 取值并覆盖rgwConfig中同名选项(见 config.go)。rgwCommandFlags:这些配置作为 CLI 参数应用,更新会导致 RGW daemon 重启。对于某些 RGW 配置,重启正是期望的行为。
注意:一旦设置了
rgwConfig或rgwConfigFromSecret,当从 spec 中移除时,它不会从 Ceph 的中央配置存储中删除。请务必在完成后将值显式设回默认值。鉴于此,对于调试级别这类临时配置值,rgwCommandFlags可能是更好的选择。
示例 - 调试
排查复杂问题时,用户经常需要提供高日志级别的 RGW 日志。使用 rgwCommandFlags 可以轻松为 RGW 应用日志级别。
以下 spec 会以最高级别的调试重启 RGW:
# ...
spec:
gateway:
# ...
rgwCommandFlags:
debug_ms: "20"
debug_rgw: "20"
不再需要 RGW 调试日志时,直接从 spec 中移除这些值即可。
示例 - 与 additionalVolumeMounts 配合使用
以下示例展示了高级配置如何与 additionalVolumeMounts 配合:一个包含 LDAP 密钥的 Kubernetes Secret 被挂载到 RGW pod,同时 RGW 被配置为引用挂载的密钥文件:
# ...
gateway:
# ...
rgwConfig:
rgw_ldap_secret: /var/rgw/ldap/bindpass.secret
additionalVolumeMounts:
- subPath: ldap
volumeSource:
secret:
secretName: rgw-ldap
defaultMode: 0600
---
apiVersion: v1
kind: Secret
metadata:
name: rgw-ldap
namespace: rook-ceph
type: Opaque
data:
"bindpass.secret": aGVsbG8ud29ybGQK # hello.world
示例 - 与 rgwConfigFromSecret 配合使用
以下示例展示了在为 RGW 配置 Barbican 集成时,如何安全地处理秘密配置参数:
# ...
gateway:
# ...
rgwConfig:
rgw_barbican_url: "http://barbican.example.com:9311"
rgw_keystone_barbican_domain: "domain"
rgw_keystone_barbican_project: "project"
rgw_keystone_barbican_user: "user"
rgwConfigFromSecret:
rgw_keystone_barbican_password:
name: "barbican-secret"
key: "password"
---
apiVersion: v1
kind: Secret
metadata:
name: barbican-secret
namespace: rook-ceph
type: Opaque
data:
"password": aGVsbG8ud29ybGQK # hello.world
删除 CephObjectStore(Deleting a CephObjectStore)
删除 CephObjectStore 资源时,Rook 通过阻止删除来保护用户数据免遭意外或过早破坏:只要被删除的对象存储中还存在任何对象 bucket(可能由用户创建,也可能由 ObjectBucketClaims 创建),删除就会被阻塞。
删除成功的前提是对象存储中的所有 bucket 都必须被移除,这可能涉及手动删除或移除所有 ObjectBucketClaims。另一种方式是移除 CephObjectStore 上的 cephobjectstore.ceph.rook.io finalizer 来删除 Kubernetes 自定义资源,但这种情况下存储数据的 Ceph 池不会被删除。
Rook 会通过三种方式警告哪些 bucket 阻塞了删除:
- 在 CephObjectStore 资源上注册一个 Event(事件)。
- 在 CephObjectStore 资源上添加一个 status condition(状态条件)。
- 在 Rook Ceph Operator 日志中添加一条错误。
如果 CephObjectStore 配置在 multisite 设置 中,上述条件仅适用于属于单个 master zone 的存储;否则这些条件会被忽略。即使存储被移除,用户仍可从对端对象存储访问数据。
从源码结构看,Rook 通过 CephObjectStore 的 finalizer 与删除前检查逻辑(涉及 bucket 依赖检查)实现该保护;相关依赖跟踪代码位于 dependents.go 与 controller.go,删除时池的处理逻辑见 objectstore.go。
总结
CephObjectStore CRD 是 Rook 在 Kubernetes 上交付 Ceph 对象存储的核心接口。通过本文可以掌握:使用复制/纠删码池组织元数据与数据、配置 S3/Swift 与 Keystone 认证协议、通过 gateway 段控制端口/TLS/副本/调度/资源、接入 Multisite zone、借助 hosting 支持 virtual-host-style 访问、以 security 段启用 Vault KMS 加密与 beast TLS 加固、用 healthCheck 调整探测策略、以及通过 rgwConfig/rgwConfigFromSecret/rgwCommandFlags 精细化调参。需要进一步理解各字段在 operator 内部的实现细节时,可深入阅读 pkg/apis/ceph.rook.io/v1/object.go、pkg/operator/ceph/object/config.go 与 pkg/operator/ceph/object/spec.go 等源码文件。