【免费下载链接】rook
Storage Orchestration for Kubernetes
RBD 块存储的 QoS（Quality of Service）允许管理员为每个 RBD 块卷单独设置 IOPS 与带宽上限，从而在多租户集群中有效抑制"吵闹邻居"（noisy-neighbor）问题，防止单个工作负载占满整个存储集群的 I/O 能力。本文以 Rook Ceph 当前仓库为基准，完整讲解其工作原理、参数含义、全新集群与存量集群的两种启用路径，以及常见故障排查方法，读完即可在自己的 Kubernetes 集群中为 RBD 卷实施动态可调的 QoS 策略。
RBD QoS 的工作原理
在 Rook Ceph 中，RBD QoS 通过 Kubernetes 的 VolumeAttributesClass 资源来配置。这一机制允许对已存在的卷动态修改 QoS 限制，而无需重新创建卷，底层依赖 CSI 的 ControllerModifyVolume 操作完成热调整。
整体数据流如下：
- 管理员创建一个
VolumeAttributesClass，在其中声明针对某个 CSI 驱动（Rook 中为rook-ceph.rbd.csi.ceph.com）的 QoS 参数（如maxReadIops、maxWriteBps等）。 - PVC 通过
spec.volumeAttributesClassName字段引用该VolumeAttributesClass。 - 当 PVC 的引用被创建或更新时，CSI 控制器插件调用
ControllerModifyVolume，把新的 QoS 参数下发到卷。 - 在节点侧，krbd（kernel RBD）挂载器通过 Linux cgroup v2 的
io.max控制器在容器级别执行限速。
仓库中 PVC 的 API 定义已包含 volumeAttributesClassName 字段，例如 deploy/examples/crds.yaml 中对 PersistentVolumeClaim 的描述明确指出："volumeAttributesClassName may be used to set the VolumeAttributesClass used by this claim ... in the corresponding VolumeAttributesClass"，并且当引用的 VolumeAttributesClass 不存在时 PVC 会进入不可用状态。
支持的挂载器：krbd（cgroup v2）
当前 QoS 方案面向默认的 krbd（kernel RBD）挂载器，通过 cgroup v2 的 io.max 控制器在容器级别实施限额。启用前必须满足以下前提：
- Kubernetes >= v1.34：
VolumeAttributesClass自 v1.34 起 GA（正式发布）； - 节点启用 cgroup v2：现代主流 Linux 发行版默认开启；
- Linux 内核 >= 5.8：较老的内核不支持
io.max所需的 cgroup v2 能力。
QoS 参数参考
以下参数都可以设置在 VolumeAttributesClass 资源上。所有参数均为可选——只需设置你需要的限制项，未设置的维度不加以限制。
| 参数 | 描述 | 示例 |
|---|---|---|
maxReadIops | 最大读 IOPS 限制 | "1000" |
maxWriteIops | 最大写 IOPS 限制 | "2000" |
maxReadBps | 最大读带宽（字节/秒） | "104857600"（即 100 MiB/s） |
maxWriteBps | 最大写带宽（字节/秒） | "209715200"（即 200 MiB/s） |
仓库中完整的参考示例位于 deploy/examples/csi/rbd/volumeattributesclass-cgroup.yaml，其内容如下：
apiVersion: storage.k8s.io/v1
kind: VolumeAttributesClass
metadata:
name: rook-ceph-rbd-cgroup-qos
driverName: rook-ceph.rbd.csi.ceph.com # csi-provisioner-name
parameters:
# Maximum read IOPS limit enforced via cgroup v2 io.max
maxReadIops: "1000"
# Maximum write IOPS limit enforced via cgroup v2 io.max
maxWriteIops: "2000"
# Maximum read bandwidth in bytes per second (104857600 = 100 MiB/s)
maxReadBps: "104857600"
# Maximum write bandwidth in bytes per second (209715200 = 200 MiB/s)
maxWriteBps: "209715200"
注意 driverName 必须与 StorageClass 的 provisioner 一致（即 rook-ceph.rbd.csi.ceph.com），否则该 QoS 类无法作用于对应的卷。
全新集群启用 QoS
对于新建的 Rook Ceph 部署，按以下步骤启用 QoS。
1. 确认 StorageClass 包含必需的 secret 引用
StorageClass 需要同时具备"修改"（modify）与"发布"（publish）两类操作的 secret 引用。默认的 deploy/examples/csi/rbd/storageclass.yaml 已经包含这些配置：
parameters:
# ... existing parameters ...
# Required for VolumeAttributesClass (dynamic QoS modification)
csi.storage.k8s.io/controller-modify-secret-name: rook-csi-rbd-provisioner
csi.storage.k8s.io/controller-modify-secret-namespace: rook-ceph # namespace:cluster
# Required for krbd QoS (cgroup v2)
csi.storage.k8s.io/node-publish-secret-name: rook-csi-rbd-node
csi.storage.k8s.io/node-publish-secret-namespace: rook-ceph # namespace:cluster
其中：
controller-modify-secret-*供 CSI 控制器执行ControllerModifyVolume（即动态修改 QoS）时使用 Ceph 管理员凭据；node-publish-secret-*供节点上的 CSI 插件在发布卷（NodePublishVolume）时获取凭据，以落实 cgroup v2 限速。
仓库中的另外两个 StorageClass 示例 storageclass-ec.yaml（纠删码池）与 storageclass-test.yaml（单副本测试）同样内置了上述两组 secret 参数，说明这是所有 RBD StorageClass 的统一要求。
2. 创建 VolumeAttributesClass
kubectl create -f deploy/examples/csi/rbd/volumeattributesclass-cgroup.yaml
该文件同时包含了全部可用参数，可在此基础上按需调整或新增多个 QoS 类。
3. 创建引用 QoS 类的 PVC
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: rbd-pvc-qos
spec:
accessModes:
- ReadWriteOnce
volumeAttributesClassName: rook-ceph-rbd-cgroup-qos
resources:
requests:
storage: 10Gi
storageClassName: rook-ceph-block
对比仓库自带的普通 PVC 示例 deploy/examples/csi/rbd/pvc.yaml（仅声明 storageClassName: rook-ceph-block 与容量），关键差异在于多出的 volumeAttributesClassName 字段——它把该 PVC 与 rook-ceph-rbd-cgroup-qos 这一 QoS 类绑定在一起。
4. 动态调整已有卷的 QoS
对已存在的卷，直接更新 PVC 的 volumeAttributesClassName 即可：
kubectl patch pvc rbd-pvc-qos -p '{"spec":{"volumeAttributesClassName":"rook-ceph-rbd-cgroup-qos"}}'
这一操作会触发 CSI 的 ControllerModifyVolume，无需卸载卷或重启 Pod。
提示：单个 Pod 可以同时挂载多个拥有不同 QoS 限制的卷——只需为每个 PVC 分别指定不同的
VolumeAttributesClass即可。
存量集群升级启用 QoS
VolumeAttributesClass 允许在不迁移数据的前提下，把 QoS 应用到存量卷上。存量集群按以下步骤操作。
1. 更新已有 StorageClass（需删除重建）
StorageClass 的 parameters 字段是不可变的（immutable），因此必须删除后重建：
警告：删除 StorageClass 不会影响已有的 PV/PVC。但在 StorageClass 重建完成之前，新建 PVC 会失败。
kubectl get storageclass rook-ceph-block -o yaml > storageclass-backup.yaml
kubectl delete storageclass rook-ceph-block
编辑 storageclass-backup.yaml，参照上文"全新集群启用 QoS"第 1 步，把 controller-modify-secret-* 与 node-publish-secret-* 四组参数加入 parameters，然后重新创建：
kubectl create -f storageclass-backup.yaml
2. 创建 VolumeAttributesClass
kubectl create -f deploy/examples/csi/rbd/volumeattributesclass-cgroup.yaml
3. 为存量 PVC 应用 QoS
通过 patch 为已有 PVC 打上 QoS 类：
kubectl patch pvc <pvc-name> -p '{"spec":{"volumeAttributesClassName":"rook-ceph-rbd-cgroup-qos"}}'
4. 验证 QoS 已生效
检查 PVC 的状态字段，确认当前生效的类与所应用的一致：
kubectl get pvc <pvc-name> -o jsonpath='{.status.currentVolumeAttributesClassName}'
输出应为 rook-ceph-rbd-cgroup-qos。这一字段由 CSI 控制器在成功执行 ControllerModifyVolume 后回写，可作为 QoS 是否真正下发的依据。
故障排查
QoS 限制未生效
-
确认 VolumeAttributesClass 存在且被 PVC 正确引用：
kubectl get volumeattributesclass kubectl get pvc <pvc-name> -o jsonpath='{.spec.volumeAttributesClassName}'检查输出是否为期望的类名。若 PVC 引用了不存在的类，卷可能无法正常使用（对应 deploy/examples/crds.yaml 中关于 PVC 引用无效
volumeAttributesClass会失败的行为描述）。 -
检查 CSI 驱动日志：在 CSI 节点插件日志中检索 QoS 相关错误：
kubectl logs -n rook-ceph -l app=csi-rbdplugin -c csi-rbdplugin --tail=100 | grep -i qos
cgroup v2 QoS 不工作
-
确认节点处于 cgroup v2 模式：
kubectl debug node/<node-name> -it --image=busybox -- cat /host/sys/fs/cgroup/cgroup.controllers如果该文件存在且输出列表包含
io，说明 cgroup v2 已激活且io控制器可用（io.max依赖它）。 -
检查 Kubernetes 版本：
VolumeAttributesClass要求 Kubernetes >= v1.34：kubectl version --short -
核对内核版本：请确保节点内核 >= 5.8，否则 cgroup v2 的
io.max无法正确执行限速。
小结
Rook Ceph 的 RBD QoS 是一条从 CSI 到内核的完整链路：管理员通过 VolumeAttributesClass 声明限额，CSI 用 ControllerModifyVolume 实现热更新，节点侧则由 cgroup v2 io.max 在容器级别强制执行。它既适用于全新集群的"开箱即用"，也支持存量集群通过"备份 StorageClass → 删除重建 → patch PVC"三步平滑接入，是治理多租户存储 I/O 争用的直接手段。相关配套文档与示例还可参考 Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-drivers.md（其中概述了 RBD QoS 能力）以及 deploy/examples/csi/rbd/ 下的全部示例清单。
【免费下载链接】rook
Storage Orchestration for Kubernetes
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
