K8S CSI Driver

Prerequisite: curvine cluster installed via Helm in namespace curvine.

Chart: curvine/curvine-csi, version 0.5.2-alpha. Release namespace: curvine-system.

Architecture

Component	Type	Description
CSI Controller	Deployment	Volume create and delete
CSI Node	DaemonSet	Node mount

Default node.mountMode=embedded. In standalone mode, FUSE runs in a separate pod.

Deployment

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 mount mode:

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

Example 1: Dynamic PV

master-addrs below is for a single-replica curvine cluster. For three replicas:

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

Example 2: Static PV

1. StorageClass

Same as Example 1. Use the three-replica master-addrs when applicable.

2. PV and 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

Configuration Reference

Chart version 0.5.2-alpha. Defaults below match helm show values curvine/curvine-csi --version 0.5.2-alpha.

Image

Parameter	Default	Description
`image.repository`	`ghcr.io/curvineio/curvine-csi`	CSI image repository
`image.tag`	`""`	Empty uses `v{Chart.AppVersion}`
`image.pullPolicy`	`Always`	Image pull policy

CSI driver

Parameter	Default	Description
`csiDriver.name`	`curvine`	CSI driver name
`csiDriver.attachRequired`	`false`	Attach operation not required
`csiDriver.podInfoOnMount`	`false`	Pod info not required on mount

Controller

Parameter	Default	Description
`controller.name`	`curvine-csi-controller`	Deployment name
`controller.replicas`	`1`	Controller replicas
`controller.priorityClassName`	`system-cluster-critical`	Priority class
`controller.container.name`	`csi-plugin`	Main container name
`controller.container.env.CSI_ENDPOINT`	`unix:///csi/csi.sock`	CSI socket
`controller.container.ports.healthz`	`9909`	Health check port
`controller.container.securityContext.privileged`	`true`	Privileged mode
`controller.sidecars.provisioner.image`	`registry.k8s.io/sig-storage/csi-provisioner:v5.0.1`	Provisioner sidecar
`controller.sidecars.attacher.image`	`registry.k8s.io/sig-storage/csi-attacher:v4.5.0`	Attacher sidecar
`controller.sidecars.livenessProbe.image`	`registry.k8s.io/sig-storage/livenessprobe:v2.11.0`	Liveness probe sidecar

Node

Parameter	Default	Description
`node.name`	`curvine-csi-node`	DaemonSet name
`node.priorityClassName`	`system-node-critical`	Priority class
`node.dnsPolicy`	`ClusterFirstWithHostNet`	DNS policy
`node.fuseDebugEnabled`	`false`	FUSE debug logging
`node.mountMode`	`embedded`	`embedded` or `standalone`
`node.container.name`	`csi-plugin`	Main container name
`node.container.env.CSI_ENDPOINT`	`unix:///csi/csi.sock`	CSI socket
`node.container.ports.healthz`	`9909`	Health check port
`node.container.ports.metrics`	`9002`	Metrics port
`node.container.securityContext.privileged`	`true`	Privileged mode
`node.container.resources.requests.cpu`	`500m`	CPU request (`embedded` mode)
`node.container.resources.requests.memory`	`512Mi`	Memory request (`embedded` mode)
`node.container.resources.limits.cpu`	`2`	CPU limit (`embedded` mode)
`node.container.resources.limits.memory`	`2Gi`	Memory limit (`embedded` mode)
`node.sidecars.nodeDriverRegistrar.image`	`registry.k8s.io/sig-storage/csi-node-driver-registrar:v2.13.0`	Registrar sidecar
`node.sidecars.livenessProbe.image`	`registry.k8s.io/sig-storage/livenessprobe:v2.11.0`	Liveness probe sidecar
`node.hostPaths.pluginDir.path`	`/var/lib/kubelet/csi-plugins/csi.curvine.io/`	CSI plugin directory
`node.hostPaths.kubeletDir.path`	`/var/lib/kubelet`	Kubelet directory
`node.hostPaths.registrationDir.path`	`/var/lib/kubelet/plugins_registry/`	Plugin registration directory

Standalone mount mode (`node.mountMode=standalone`)

FUSE runs in a separate pod. Use when FUSE must survive CSI node pod restarts.

Parameter	Default	Description
`node.standalone.image`	`""`	Standalone pod image; empty uses CSI image
`node.standalone.resources.requests.cpu`	`500m`	CPU request
`node.standalone.resources.requests.memory`	`512Mi`	Memory request
`node.standalone.resources.limits.cpu`	`2`	CPU limit
`node.standalone.resources.limits.memory`	`2Gi`	Memory limit

Service account and RBAC

Parameter	Default	Description
`serviceAccount.controller.name`	`""`	Auto-derived from release name when empty
`serviceAccount.node.name`	`""`	Auto-derived from release name when empty
`rbac.create`	`true`	Create RBAC resources

Curvine volume parameters

Used in StorageClass parameters (dynamic PV) or PV csi.volumeAttributes (static PV).

Parameter	Required	Default	Description
`master-addrs`	Yes	—	Curvine master addresses, `host:port` comma-separated
`fs-path`	Dynamic PV	`/`	Path prefix; actual path is `fs-path` + `/` + pv-name
`curvine-path`	Static PV	—	Full path in Curvine filesystem
`path-type`	No	`Directory`	`Directory` or `DirectoryOrCreate`

Additional keys (for example io-threads, worker-threads) are forwarded to curvine-fuse as CLI flags. The following keys are reserved and must not be set manually: master-addrs, fs-path, path-type, curvine-path, mnt-path.

Examples

Override embedded mode resources:

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

Full parameter list:

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

Troubleshooting

Symptom	Action
CSI pod unhealthy	`kubectl logs -n curvine-system -l app=curvine-csi-node -c csi-plugin`
Sidecar ImagePullBackOff	Override sidecar images; see Configuration Reference
`master-addrs` unreachable	`kubectl get pods -n curvine`
Mount disconnected	Restart the application pod

ArchitectureCopy Anchor Link

DeploymentCopy Anchor Link

Example 1: Dynamic PVCopy Anchor Link

1. StorageClassCopy Anchor Link

2. PVCCopy Anchor Link

3. PodCopy Anchor Link

Example 2: Static PVCopy Anchor Link

1. StorageClassCopy Anchor Link

2. PV and PVCCopy Anchor Link

3. PodCopy Anchor Link

Configuration ReferenceCopy Anchor Link

ImageCopy Anchor Link

CSI driverCopy Anchor Link

ControllerCopy Anchor Link

NodeCopy Anchor Link

Standalone mount mode (node.mountMode=standalone)Copy Anchor Link

Service account and RBACCopy Anchor Link

Curvine volume parametersCopy Anchor Link

ExamplesCopy Anchor Link

TroubleshootingCopy Anchor Link

On this page

Architecture

Deployment

Example 1: Dynamic PV

1. StorageClass

2. PVC

3. Pod

Example 2: Static PV

1. StorageClass

2. PV and PVC

3. Pod

Configuration Reference

Image

CSI driver

Controller

Node

Standalone mount mode (`node.mountMode=standalone`)

Service account and RBAC

Curvine volume parameters

Examples

Troubleshooting