ceph-csi

 

---

📘 Ceph-CSI RBD 完整技术文档（含 CSI、VolumeAttachment 机制、详细逻辑与时序图）

---

一、Ceph-CSI RBD 总体逻辑（完整流程）

Ceph-CSI（RBD 模式）是 Kubernetes 与 Ceph RBD 存储系统的集成实现，将 Kubernetes PersistentVolume（PV）映射到 Ceph RBD 镜像对象。
它将 Kubernetes 的控制面与数据面操作统一到 CSI（Container Storage Interface）标准接口，保证扩展性和兼容性。

---

📊 1️⃣ 文本结构总览图（完整数据与控制面 ASCII 图）

╔══════════════════════════════════════════════════════════════╗
║                     Kubernetes API 层                        ║
╠══════════════════════════════════════════════════════════════╣
║  [PersistentVolumeClaim] ──┐                                 ║
║                            │                                 ║
║  [PersistentVolume] <──────┤ 由 external-provisioner 创建    ║
║                            │                                 ║
║  [VolumeAttachment] <──────┤ 由 external-attacher 管理       ║
║                            │                                 ║
║  [Pod + kubelet] ──────────┘                                 ║
╚══════════════════════════════════════════════════════════════╝│▼
╔══════════════════════════════════════════════════════════════╗
║          csi-rbdplugin-provisioner (Deployment)              ║
║ ┌──────────────────────────────────────────────────────────┐ ║
║ │ csi-provisioner  →  调用 CreateVolume/DeleteVolume       │ ║
║ │ csi-attacher     →  调用 ControllerPublish/Unpublish     │ ║
║ │ csi-resizer      →  调用 ControllerExpandVolume          │ ║
║ │ csi-snapshotter  →  调用 CreateSnapshot/DeleteSnapshot   │ ║
║ │ csi-rbdplugin    →  实际与 Ceph 通信                    │ ║
║ └──────────────────────────────────────────────────────────┘ ║
╚══════════════════════════════════════════════════════════════╝│▼
╔══════════════════════════════════════════════════════════════╗
║          csi-rbdplugin (DaemonSet, 每节点一份)              ║
║ ┌──────────────────────────────────────────────────────────┐ ║
║ │ node-driver-registrar  →  注册驱动到 kubelet             │ ║
║ │ csi-rbdplugin          →  NodeStage/Publish/Unstage等接口 │ ║
║ │ liveness-prometheus    →  提供健康检查                   │ ║
║ └──────────────────────────────────────────────────────────┘ ║
╚══════════════════════════════════════════════════════════════╝│▼
╔══════════════════════════════════════════════════════════════╗
║                      Ceph 集群（存储后端）                    ║
║ ┌───────────┬──────────┬────────────┬──────────────┐         ║
║ │ MON (监控)│ MGR (管理)│ OSD (数据) │ RBD (镜像服务) │         ║
║ └───────────┴──────────┴────────────┴──────────────┘         ║
║     ↑  librados / rbd CLI / cephx 通信                      ║
╚══════════════════════════════════════════════════════════════╝

---

二、Ceph-CSI RBD 各阶段详细说明

🧩 阶段 1：PVC 创建与 PV 绑定（CreateVolume）

1. 用户提交 PVC：

kind: PersistentVolumeClaim
metadata:name: data-pvc
spec:storageClassName: rook-ceph-blockaccessModes: [ReadWriteOnce]resources:requests:storage: 10Gi

2. external-provisioner 监听 PVC；

3. 调用 CSI 接口 CreateVolume，传递 StorageClass 参数、PVC 名称和大小；

4. csi-rbdplugin 调用 Ceph 创建 RBD 镜像：

rbd create <pool>/<image> --size 10G

5. 返回 volumeHandle（pool/image）；

6. 创建 PV，并绑定 PVC。

---

🧩 阶段 2：Pod 调度与卷附加（ControllerPublishVolume）

1. Pod 调度到节点后，kube-controller-manager 创建 VolumeAttachment 对象；

2. external-attacher 监听该对象，并调用 CSI 接口 ControllerPublishVolume；

3. 执行生成 CephX 临时密钥、验证 RBD 镜像，返回 PublishContext（monitors、pool、image、user、secretRef）；

4. 说明 CSI 与 VolumeAttachment 的关系：

   • VolumeAttachment 是 Kubernetes 中表示卷与节点绑定状态的对象

   • CSI 插件通过 ControllerPublishVolume 对卷进行 attach，并由 VolumeAttachment 同步状态到 Kubernetes API

   • kubelet 数据面操作（NodeStage/PublishVolume）读取 VolumeAttachment 提供的信息完成实际挂载

---

🧩 阶段 3：节点挂载（NodeStageVolume + NodePublishVolume）

NodeStageVolume

1. kubelet 调用 NodeStageVolume：

rbd map <pool>/<image> --id <user> --keyfile=/etc/ceph/keyring

2. 如果未格式化，执行：

mkfs.ext4 /dev/rbd0

3. 挂载到 staging 目录：

/var/lib/kubelet/plugins/kubernetes.io/csi/pv/<vol-id>/globalmount

NodePublishVolume

4. bind-mount 到 Pod 的卷目录：

/var/lib/kubelet/pods/<pod-id>/volumes/kubernetes.io~csi/<vol-name>/mount

---

🧩 阶段 4：卸载与清理

NodeUnpublishVolume：卸载 Pod bind mount
NodeUnstageVolume：卸载 staging，rbd unmap /dev/rbd0
ControllerUnpublishVolume：删除临时 CephX key
DeleteVolume：PVC 删除时，删除 Ceph 镜像

---

三、CSI 机制详解

1️⃣ CSI 设计目标

• 容器存储访问标准接口

• Kubernetes 仅通过 CSI 与存储交互

• 分离控制面与数据面，支持扩展、多插件共存

• 提供统一的卷生命周期管理，包括创建、挂载、卸载、删除

---

2️⃣ CSI 主要接口分类

分类	接口名	功能
控制面	CreateVolume	创建卷
控制面	DeleteVolume	删除卷
控制面	ControllerPublishVolume	将卷绑定到节点
控制面	ControllerUnpublishVolume	解除卷绑定
控制面	ControllerExpandVolume	扩容
节点面	NodeStageVolume	将卷映射到节点
节点面	NodeUnstageVolume	从节点解除映射
节点面	NodePublishVolume	将卷挂载到 Pod 路径
节点面	NodeUnpublishVolume	卸载卷
监控面	NodeGetVolumeStats	卷状态监控

---

3️⃣ CSI 调用顺序图（核心阶段）

[PVC 创建] ↓
CreateVolume (Controller)↓
[PV 生成 + 绑定]↓
ControllerPublishVolume (attach)  <─ VolumeAttachment 同步 attach 状态↓
NodeStageVolume (map + mount)↓
NodePublishVolume (bind mount)↓
[Pod 使用阶段]↓
NodeUnpublishVolume → NodeUnstageVolume → ControllerUnpublishVolume → DeleteVolume

---

四、VolumeAttachment 深度解析

1️⃣ VolumeAttachment 对象结构

apiVersion: storage.k8s.io/v1
kind: VolumeAttachment
metadata:name: csi-9f7b2e23
spec:attacher: rbd.csi.ceph.comnodeName: worker-01source:persistentVolumeName: pvc-xxxx
status:attached: trueattachmentMetadata:devicePath: /dev/rbd0

2️⃣ VolumeAttachment 逻辑说明

• 作用：表示 PV 是否已绑定到特定节点；是 CSI 控制面与 kubelet 数据面的桥梁

• 控制面：由 external-attacher 管理，更新 status.attached、attachmentMetadata

• 数据面：kubelet 读取 VolumeAttachment 信息，完成

NodeStage/PublishVolume

• 核心字段：

  • spec.attacher：CSI 插件名

  • spec.nodeName：目标节点

  • spec.source.persistentVolumeName：绑定 PV

  • status.attached：节点是否已挂载

  • status.attachmentMetadata.devicePath：映射设备路径

---

3️⃣ CSI 与 VolumeAttachment 的关系

1. VolumeAttachment 由 Kubernetes API 存储卷附加状态

2. CSI 控制面（ControllerPublishVolume / ControllerUnpublishVolume）更新 VolumeAttachment 状态

3. Kubelet 数据面（NodeStage/Publish/Unstage/Unpublish）读取 VolumeAttachment，实现实际设备映射和挂载

4. 核心逻辑：

   • VolumeAttachment = 控制面 attach 状态 + 节点信息

   • CSI 插件通过它保证卷挂载状态与 Kubernetes 状态同步

---

4️⃣ 生命周期与状态变化

阶段	状态变化	操作方	动作
Pod 调度	VolumeAttachment 创建	kube-controller-manager	请求 attach
attach 成功	status.attached: true	external-attacher	更新状态
kubelet 挂载卷	读取 VolumeAttachment	kubelet	NodeStage/Publish
Pod 删除	VolumeAttachment 删除	kube-controller-manager	触发 detach
detach 成功	对象删除	external-attacher	调用 ControllerUnpublishVolume

---

5️⃣ VolumeAttachment 在数据路径中的位置

PVC ─┬─> PV ─┬─> VolumeAttachment ─┬─> NodeStage/Publish ─┬─> Pod│        │                    │                      ││        │                    │                      ▼│        │                    │                  /dev/rbdX│        │                    ││        └── external-attacher ─ 调用 ControllerPublishVolume└────────── external-provisioner ─ 调用 CreateVolume

---

五、Ceph-CSI 关键路径总结

阶段	执行节点	操作	对应 Ceph 命令
CreateVolume	provisioner Pod	创建镜像	rbd create
ControllerPublishVolume	provisioner Pod	授权密钥	ceph auth get-or-create
NodeStageVolume	worker 节点	映射镜像	rbd map
NodePublishVolume	worker 节点	绑定挂载	mount /dev/rbdX
NodeUnpublishVolume	worker 节点	卸载	umount
NodeUnstageVolume	worker 节点	解除映射	rbd unmap
DeleteVolume	provisioner Pod	删除镜像	rbd rm

---

六、Ceph 交互原理

1. 通过 monitors + keyring 与 Ceph 集群通信

2. 每卷使用临时 CephX 用户

3. 每个卷对应一个 RBD image

4. 元数据保存在 csi-volumes pool

---

七、关键文件路径

文件/目录	说明
/var/lib/kubelet/plugins/rbd.csi.ceph.com	驱动注册目录
/var/lib/kubelet/plugins/kubernetes.io/csi/pv/<volume-id>/globalmount	staging 挂载路径
/var/lib/kubelet/pods/<pod-id>/volumes/.../mount	Pod 卷挂载路径
/etc/ceph/ceph.conf	Ceph 配置
/etc/ceph/keyring	CephX 密钥文件

---

八、整体调用链文字图

用户PVC → external-provisioner → CreateVolume → Ceph创建RBD镜像↓
Pod调度 → VolumeAttachment → external-attacher → ControllerPublishVolume↓
kubelet → NodeStageVolume (rbd map) → NodePublishVolume (mount)↓
Pod启动 → 访问 /dev/rbdX↓
Pod删除 → NodeUnpublish/Unstage → rbd unmap → ControllerUnpublish → DeleteVolume

---

九、Ceph-CSI RBD 生命周期时序图（ASCII 版）

用户PVC│▼
external-provisioner → CreateVolume → csi-rbdplugin-controller → Ceph → volumeHandle│▼
PV绑定│▼
Pod调度 → VolumeAttachment → external-attacher → ControllerPublishVolume│▼
Kubelet → NodeStageVolume → NodePublishVolume → Pod使用│▼
Pod删除 → NodeUnpublishVolume → NodeUnstageVolume → rbd unmap → ControllerUnpublish → DeleteVolume

---

🔟 控制面 + 数据面详细 CSI 时序图（ASCII 版）

用户PVC│▼
[external-provisioner] --CreateVolume--> [csi-rbdplugin-controller]│                                     ││                                     └--> Ceph RBD 创建镜像│                                     ││                                     <-- volumeHandle│▼
[Kubernetes API] PV 创建 + 绑定 PVC│▼
Pod调度 --> [kube-controller-manager] --> VolumeAttachment 对象创建│▼
[external-attacher] --ControllerPublishVolume--> [csi-rbdplugin-controller]│                                     ││                                     └--> 生成 CephX key / 验证 image│                                     ││                                     <-- PublishContext(monitors/pool/image/key)│▼
[Kubelet] --> NodeStageVolume --> [节点 csi-rbdplugin] --> rbd map / mkfs / staging mount│▼
[Kubelet] --> NodePublishVolume --> [节点 csi-rbdplugin] --> bind mount 到 Pod│▼
[Pod 使用阶段] 访问 /dev/rbdX│▼
Pod删除 --> NodeUnpublishVolume --> NodeUnstageVolume --> rbd unmap│▼
ControllerUnpublishVolume / DeleteVolume --> Ceph 删除镜像

---

⑪ 总结

• 控制面：PVC/PV/VolumeAttachment 由 provisioner 和 attacher 管理

• 数据面：节点上由 kubelet 与 csi-rbdplugin 执行挂载/卸载

• Ceph 后端：提供真正的数据存储

• VolumeAttachment：

  • Kubernetes API 中卷绑定状态的存储对象

  • CSI 控制面更新 attach/detach 状态

  • Kubelet 数据面读取信息完成实际挂载

• CSI 机制：标准化卷生命周期管理，保证控制面和数据面解耦

• 详细 CSI 时序图：展示 PVC → Pod → Detach 的所有控制面 + 数据面 RPC 调用

• 适合培训与企业内部文档使用

---

✅ 改进点：

1. 增加了 CSI 与 VolumeAttachment 关系说明

2. 增加 VolumeAttachment 在控制面与数据面中作用的详细解析

3. 强化生命周期与状态变化逻辑

---