📚 课程目录第4章 CSI驱动安装

4. CSI 驱动安装：以 Ceph-CSI 为例

本章以 Ceph-CSI 为例，完整演示从 Rook/Ceph 集群部署到 CSI 驱动安装与状态验证的全流程。Ceph 是生产环境最常用的分布式存储后端之一，Rook 则将其 Operator 模式引入 Kubernetes，大幅简化了部署与运维。

4.1 部署架构概览

Rook 将 Ceph 集群以 Kubernetes 原生资源的形式管理，整体架构分为三层：

Rook Operator：负责管理 CephCluster、CephBlockPool、CephFilesystem 等 CRD 资源。
Ceph 守护进程：以 StatefulSet/Deployment 形式运行 MON、OSD、MGR、MDS 等组件。
CSI 驱动：通过 Rook 自动部署的 Ceph-CSI 插件，提供 RBD（块）与 CephFS（文件）的存储接口。

4.2 环境准备

组件	版本要求	说明
Kubernetes	≥ 1.21	建议使用 1.24+ 以获得最佳 CSI 支持
Rook	v1.12+	稳定版，支持 Ceph Quincy 及以上
Ceph	Quincy (17.2.x) 或 Reef (18.2.x)	推荐 Reef 以获得最新性能优化
节点磁盘	至少 1 块裸盘（无分区）	用于 OSD 存储，建议 SSD/NVMe
内核	≥ 5.4	支持 rbd 模块与 blk-mq 多队列

提示：如果使用云虚拟机，请确保附加的磁盘未格式化且未被挂载。Rook 要求 OSD 使用原始块设备。

4.3 部署 Rook/Ceph 集群

步骤 1：克隆 Rook 仓库并部署 Operator

git clone --single-branch --branch v1.12.6 https://github.com/rook/rook.git
cd rook/deploy/examples
kubectl create -f crds.yaml
kubectl create -f common.yaml
kubectl create -f operator.yaml

步骤 2：验证 Operator 运行状态

kubectl -n rook-ceph get pod
# 预期输出：rook-ceph-operator-xxxxx-xxxxx   1/1   Running

步骤 3：创建 CephCluster CR

编辑 cluster.yaml，根据节点磁盘情况调整 storage.nodes 配置：

apiVersion: ceph.rook.io/v1
kind: CephCluster
metadata:
  name: rook-ceph
  namespace: rook-ceph
spec:
  cephVersion:
    image: quay.io/ceph/ceph:v18.2.0
  dataDirHostPath: /var/lib/rook
  mon:
    count: 3
    allowMultiplePerNode: false
  storage:
    useAllNodes: true
    useAllDevices: false
    nodes:
    - name: "k8s-node-1"
      devices:
      - name: "sdb"
    - name: "k8s-node-2"
      devices:
      - name: "sdb"
    - name: "k8s-node-3"
      devices:
      - name: "sdb"

kubectl create -f cluster.yaml

步骤 4：等待集群就绪

kubectl -n rook-ceph wait --for=condition=Ready cephcluster/rook-ceph --timeout=600s
kubectl -n rook-ceph get pod
# 预期输出：mon、mgr、osd 等 Pod 均为 Running 状态

  关键检查点：OSD Pod 数量应与节点上可用的裸盘数量一致。如果 OSD 未启动，请检查 kubectl -n rook-ceph logs deploy/rook-ceph-osd-0 查看错误日志。

4.4 安装 CSI 驱动

Rook 在部署 CephCluster 后，会自动部署 Ceph-CSI 驱动。但需要显式创建 StorageClass 和 CephBlockPool / CephFilesystem 资源来激活 CSI 插件。

步骤 1：创建 CephBlockPool（RBD 块存储池）

apiVersion: ceph.rook.io/v1
kind: CephBlockPool
metadata:
  name: replicapool
  namespace: rook-ceph
spec:
  failureDomain: host
  replicated:
    size: 3
    requireSafeReplicaSize: true

kubectl create -f pool.yaml

步骤 2：创建 StorageClass（RBD CSI）

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ceph-rbd-sc
provisioner: rook-ceph.rbd.csi.ceph.com
parameters:
  clusterID: rook-ceph
  pool: replicapool
  imageFeatures: layering
  csi.storage.k8s.io/provisioner-secret-name: rook-csi-rbd-provisioner
  csi.storage.k8s.io/provisioner-secret-namespace: rook-ceph
  csi.storage.k8s.io/controller-expand-secret-name: rook-csi-rbd-provisioner
  csi.storage.k8s.io/controller-expand-secret-namespace: rook-ceph
  csi.storage.k8s.io/node-stage-secret-name: rook-csi-rbd-node
  csi.storage.k8s.io/node-stage-secret-namespace: rook-ceph
reclaimPolicy: Delete
allowVolumeExpansion: true
mountOptions: []

kubectl create -f storageclass-rbd.yaml

步骤 3：创建 CephFilesystem（可选，用于文件存储）

apiVersion: ceph.rook.io/v1
kind: CephFilesystem
metadata:
  name: myfs
  namespace: rook-ceph
spec:
  metadataPool:
    replicated:
      size: 3
  dataPools:
    - replicated:
        size: 3
  preservePoolsOnDelete: true
  metadataServer:
    activeCount: 1
    activeStandby: true

kubectl create -f filesystem.yaml

4.5 验证 CSI 驱动状态

1. 检查 CSI 插件 Pod

kubectl -n rook-ceph get pod -l app=rook-ceph-csi-rbd
# 预期输出：csi-rbdplugin-xxxxx 和 csi-rbdplugin-provisioner-xxxxx 均为 Running

2. 检查 CSIDriver 对象

kubectl get csidriver
# 预期输出包含 rook-ceph.rbd.csi.ceph.com 和 rook-ceph.cephfs.csi.ceph.com

3. 创建测试 PVC 验证端到端

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  storageClassName: ceph-rbd-sc
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

kubectl create -f test-pvc.yaml
kubectl get pvc test-pvc
# 预期输出：Bound 状态

4. 检查 CSI 驱动日志

kubectl -n rook-ceph logs -l app=rook-ceph-csi-rbd --tail=20
# 应无 ERROR 级别日志，常见 INFO 日志包括 "GRPC call" 和 "provision" 操作

4.6 常见问题与排查

现象	可能原因	解决措施
OSD Pod 一直 Pending	节点上没有可用裸盘，或磁盘已被分区/挂载	使用 `lsblk` 检查磁盘状态，确保磁盘为 raw 且无文件系统
PVC 一直 Pending	StorageClass 参数错误，或 CSI 驱动未就绪	检查 `kubectl describe pvc` 事件，确认 provisioner 名称正确
CSI Pod CrashLoopBackOff	Ceph 集群未就绪，或 secret 配置错误	检查 `kubectl -n rook-ceph logs csi-rbdplugin-xxxx` 定位错误
rbd 命令执行失败	内核模块未加载或版本不匹配	执行 `modprobe rbd`，确认内核版本 ≥ 5.4

注意：在生产环境中，建议将 Ceph 集群与 CSI 驱动部署在专用的存储节点上，避免与计算节点争抢 CPU/内存资源。同时，确保 OSD 使用的磁盘为 NVMe SSD 以获得最佳 IOPS 性能。

4.7 本章小结

通过 Rook 部署 Ceph 集群并安装 Ceph-CSI 驱动，我们完成了以下关键步骤：

部署 Rook Operator 与 CephCluster CR，自动拉起 MON、OSD、MGR 等守护进程。
创建 CephBlockPool 与 StorageClass，激活 RBD CSI 驱动。
通过检查 Pod、CSIDriver、PVC 状态和日志，验证 CSI 驱动正常工作。