K8S CSI 驱动

前提:已通过 Helm 部署 curvine cluster(namespace curvine)。

Chart:curvine/curvine-csi,版本 0.5.2-alpha。Release namespace:curvine-system。

架构说明

组件类型说明
CSI ControllerDeployment卷创建、删除
CSI NodeDaemonSet节点挂载

默认 node.mountMode=embedded。standalone 模式下 FUSE 运行于独立 Pod。

部署

helm repo add curvine https://curvineio.github.io/helm-charts
helm repo update

helm upgrade --install curvine-csi curvine/curvine-csi \
  --version 0.5.2-alpha \
  -n curvine-system \
  --create-namespace \
  --wait --timeout 8m

kubectl get csidriver curvine
kubectl get pods -n curvine-system

standalone 挂载模式:

helm upgrade --install curvine-csi curvine/curvine-csi \
  --version 0.5.2-alpha \
  -n curvine-system \
  --create-namespace \
  --set node.mountMode=standalone \
  --set node.standalone.resources.requests.cpu=500m \
  --set node.standalone.resources.requests.memory=512Mi \
  --set node.standalone.resources.limits.cpu=2 \
  --set node.standalone.resources.limits.memory=2Gi \
  --wait --timeout 8m

示例一:动态 PV

以下 master-addrs 按单副本 curvine cluster 编写。三副本时改为:

curvine-master-0.curvine-master.curvine.svc.cluster.local:8995,curvine-master-1.curvine-master.curvine.svc.cluster.local:8995,curvine-master-2.curvine-master.curvine.svc.cluster.local:8995

1. StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: curvine-sc
provisioner: curvine
reclaimPolicy: Delete
volumeBindingMode: Immediate
allowVolumeExpansion: true
parameters:
  master-addrs: "curvine-master.curvine.svc.cluster.local:8995"
  fs-path: "/k8s-volumes"
  path-type: "DirectoryOrCreate"
kubectl apply -f storageclass.yaml

2. PVC

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data
  namespace: curvine
spec:
  storageClassName: curvine-sc
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi
kubectl apply -f pvc.yaml
kubectl wait --for=condition=Bound pvc/app-data -n curvine --timeout=120s

3. Pod

apiVersion: v1
kind: Pod
metadata:
  name: app-pod
  namespace: curvine
spec:
  containers:
    - name: app
      image: busybox:1.36
      command: ["sh", "-c", "echo test > /data/test.txt && cat /data/test.txt && sleep 3600"]
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: app-data
kubectl apply -f pod.yaml
kubectl logs app-pod -n curvine

示例二:静态 PV

1. StorageClass

同示例一。三副本时 master-addrs 同上。

2. PV 与 PVC

apiVersion: v1
kind: PersistentVolume
metadata:
  name: curvine-existing
spec:
  storageClassName: curvine-sc
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: curvine
    volumeHandle: "existing-data-001"
    volumeAttributes:
      master-addrs: "curvine-master.curvine.svc.cluster.local:8995"
      curvine-path: "/existing-data"
      path-type: "Directory"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data
  namespace: curvine
spec:
  storageClassName: curvine-sc
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi
  volumeName: curvine-existing
kubectl apply -f pv-pvc.yaml
kubectl wait --for=condition=Bound pvc/app-data -n curvine --timeout=120s

3. Pod

apiVersion: v1
kind: Pod
metadata:
  name: app-pod
  namespace: curvine
spec:
  containers:
    - name: app
      image: busybox:1.36
      command: ["sh", "-c", "echo test > /data/test.txt && cat /data/test.txt && sleep 3600"]
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: app-data
kubectl apply -f pod.yaml
kubectl logs app-pod -n curvine

配置参考

Chart 版本 0.5.2-alpha。下表默认值与 helm show values curvine/curvine-csi --version 0.5.2-alpha 一致。

镜像

参数默认值说明
image.repositoryghcr.io/curvineio/curvine-csiCSI 镜像仓库
image.tag""空值使用 v{Chart.AppVersion}
image.pullPolicyAlways镜像拉取策略

CSI 驱动

参数默认值说明
csiDriver.namecurvineCSI 驱动名称
csiDriver.attachRequiredfalse不需要 attach 操作
csiDriver.podInfoOnMountfalse挂载时不需要 Pod 信息

Controller

参数默认值说明
controller.namecurvine-csi-controllerDeployment 名称
controller.replicas1Controller 副本数
controller.priorityClassNamesystem-cluster-critical优先级类
controller.container.namecsi-plugin主容器名称
controller.container.env.CSI_ENDPOINTunix:///csi/csi.sockCSI 套接字
controller.container.ports.healthz9909健康检查端口
controller.container.securityContext.privilegedtrue特权模式
controller.sidecars.provisioner.imageregistry.k8s.io/sig-storage/csi-provisioner:v5.0.1Provisioner sidecar
controller.sidecars.attacher.imageregistry.k8s.io/sig-storage/csi-attacher:v4.5.0Attacher sidecar
controller.sidecars.livenessProbe.imageregistry.k8s.io/sig-storage/livenessprobe:v2.11.0存活探针 sidecar

Node

参数默认值说明
node.namecurvine-csi-nodeDaemonSet 名称
node.priorityClassNamesystem-node-critical优先级类
node.dnsPolicyClusterFirstWithHostNetDNS 策略
node.fuseDebugEnabledfalseFUSE 调试日志
node.mountModeembeddedembedded 或 standalone
node.container.namecsi-pluginMain container name
node.container.env.CSI_ENDPOINTunix:///csi/csi.sockCSI socket
node.container.ports.healthz9909健康检查端口
node.container.ports.metrics9002指标端口
node.container.securityContext.privilegedtrue特权模式
node.container.resources.requests.cpu500mCPU request(embedded 模式)
node.container.resources.requests.memory512Mi内存 request(embedded 模式)
node.container.resources.limits.cpu2CPU limit(embedded 模式)
node.container.resources.limits.memory2Gi内存 limit(embedded 模式)
node.sidecars.nodeDriverRegistrar.imageregistry.k8s.io/sig-storage/csi-node-driver-registrar:v2.13.0Registrar sidecar
node.sidecars.livenessProbe.imageregistry.k8s.io/sig-storage/livenessprobe:v2.11.0存活探针 sidecar
node.hostPaths.pluginDir.path/var/lib/kubelet/csi-plugins/csi.curvine.io/CSI 插件目录
node.hostPaths.kubeletDir.path/var/lib/kubeletKubelet 目录
node.hostPaths.registrationDir.path/var/lib/kubelet/plugins_registry/插件注册目录

Standalone 挂载模式(node.mountMode=standalone)

FUSE 运行在独立 Pod 中。适用于 CSI node Pod 重启后仍需保持 FUSE 挂载的场景。

参数默认值说明
node.standalone.image""Standalone Pod 镜像,空值使用 CSI 镜像
node.standalone.resources.requests.cpu500mCPU request
node.standalone.resources.requests.memory512Mi内存 request
node.standalone.resources.limits.cpu2CPU limit
node.standalone.resources.limits.memory2Gi内存 limit

ServiceAccount 与 RBAC

参数默认值说明
serviceAccount.controller.name""空值由 release 名称派生
serviceAccount.node.name""空值由 release 名称派生
rbac.createtrue创建 RBAC 资源

Curvine 卷参数

用于 StorageClass parameters(动态 PV)或 PV csi.volumeAttributes(静态 PV)。

参数必填默认值说明
master-addrs是—Curvine master 地址,host:port 逗号分隔
fs-path动态 PV/路径前缀;实际路径为 fs-path + / + pv-name
curvine-path静态 PV—Curvine 文件系统中的完整路径
path-type否DirectoryDirectory 或 DirectoryOrCreate

其他所有键都会透传给 curvine-fuse 作为 CLI 参数,例如 io-threads=4、worker-threads=8。以下三类不会透传:

  • csi.storage.k8s.io/* 属于 CSI 内部键,会被丢弃。
  • mnt-path 在创建卷时直接报错;宿主机挂载路径由驱动自己计算(/var/lib/kubelet/plugins/kubernetes.io/csi/curvine/<mount-key>/fuse-mount)。
  • curvine-path、author、volume-handle 由控制器写入 PV 的 volumeAttributes,不要在 StorageClass 上手动设置。

fs-path 省略时默认为 /,但随附的示例显式写了 /test-data,这是更安全的做法:该 StorageClass 创建的所有卷都落在同一个目录下,便于整体检查、配额或删除。

示例

覆盖 embedded 模式资源:

helm upgrade curvine-csi curvine/curvine-csi -n curvine-system --reuse-values \
  --set node.container.resources.requests.cpu=200m \
  --set node.container.resources.requests.memory=256Mi

完整参数:

helm show values curvine/curvine-csi --version 0.5.2-alpha

故障排查

现象处理
CSI Pod 异常kubectl logs -n curvine-system -l app=curvine-csi-node -c csi-plugin
Sidecar ImagePullBackOff覆盖 sidecar 镜像,见「配置参考」
master-addrs 不可达kubectl get pods -n curvine
挂载断开重启应用 Pod