Curvine CSI Architecture

curvine-csi is based on FUSE implementation, establishing connection with Curvine cluster through FUSE mount in csi-node.

Architecture

If you only need to use CSI, you can skip this chapter and refer to K8S CSI Driver directly.

Curvine-csi mainly consists of the following components:

Component	Responsibility
CSI Node	Handle CSI gRPC calls, manage volume mounts
CSI Controller	Create/Delete/Monitor PVs
Standalone POD	In standalone mode, independently manages FUSE processes

Mount Modes

Most CSI implementations manage mounts directly in csi-node by mounting remote storage to hosts and finally bind mounting to pod containers. Curvine-csi is based on FUSE. When the CSI component restarts, the FUSE process will be interrupted. To avoid FUSE interruption caused by CSI driver upgrades or restarts, curvine-csi supports two mount modes: standalone and embedded.

• Standalone: Decouple the FUSE process from the csi-node pod and run it in an independent Pod
• Embedded: FUSE process runs in the csi-node plugin pod

Standalone Mode (Recommended)

Default mode. Install with Helm:

helm install curvine-csi ./curvine-csi \
  --set mountMode=standalone

Resource Configuration

Configure Standalone Pod resource limits via Helm values:

helm install curvine-csi ./curvine-csi \
  --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

Or use a values file:

node:
  mountMode: standalone
  standalone:
    image: ""  # Empty uses CSI image
    resources:
      requests:
        cpu: "500m"
        memory: "512Mi"
      limits:
        cpu: "2"
        memory: "2Gi"

Default configuration:

• CPU: requests 500m, limits 2
• Memory: requests 512Mi, limits 2Gi

Architecture diagram:

Embedded Mode

Install with Helm:

helm install curvine-csi ./curvine-csi \
  --set node.mountMode=embedded \
  --set node.resources.requests.memory=2Gi \
  --set node.resources.requests.cpu=1000m \
  --set node.resources.limits.memory=4Gi \
  --set node.resources.limits.cpu=2000m

Architecture diagram:

warning

In Embedded mode, if curvine-csi restarts or upgrades, the FUSE process will be interrupted, causing Pods to be unable to use Curvine normally. Please choose carefully based on your scenario.

FUSE Process Reuse and Lifecycle Management

Overview

Curvine CSI implements intelligent FUSE process reuse mechanism. Using ClusterID as a unique identifier, multiple PVs can share the same FUSE process (Standalone Pod). This design significantly improves resource utilization and system performance.

Core Concepts

ClusterID Generation

ClusterID is generated from the first 8 characters of the SHA256 hash of master-addrs:

// Example: Generate ClusterID from master-addrs
masterAddrs := "10.0.0.1:8995,10.0.0.2:8995,10.0.0.3:8995"
clusterID := SHA256(masterAddrs)[:8]  // e.g., 0893a5f6

Key Features:

• Same master-addrs → Same ClusterID → Shared Standalone Pod
• Different master-addrs → Different ClusterID → Independent Standalone Pod
• Multi-cluster support: Same node can run multiple Standalone Pods for different Curvine clusters

Standalone Pod Naming

curvine-standalone-{clusterID}-{randomSuffix}
# Example: curvine-standalone-0893a5f6-aefd8804

FUSE Process Reuse Mechanism

Reuse Scenario Example

Explanation:

• PV-1, PV-2, PV-3 use the same master-addrs, sharing Standalone-0893a5f6
• PV-4 uses different master-addrs, using independent Standalone-1a2b3c4d
• Standalone-0893a5f6 has a reference count of 3 (three PVs sharing)
• Standalone-1a2b3c4d has a reference count of 1

Automatic Cleanup Mechanism:

• Trigger Condition: RefCount drops to 0 (no PV references)
• Graceful Shutdown: 30-second grace period to ensure FUSE unmounts correctly
• preStop Hook: 5-second wait to allow ongoing I/O to complete
• State Persistence: Reference counts stored in ConfigMap, state restored after node restarts

RBAC Requirements

Standalone mode requires the following permissions:

Resource	Permissions	Purpose
pods	create, delete, get, list, watch	Manage Standalone Pods
configmaps	create, delete, get, list, update, watch	State persistence
persistentvolumes	get, list, watch	PV Watch fallback cleanup
events	create, patch	Event logging and debugging

Best Practices

1. Use Standalone Mode (default, recommended)

   • Independent FUSE process, CSI upgrades don't affect business
   • Resource isolation, clear problem domain

2. Use consistent master-addrs for same cluster

   • Ensure PV's master-addrs format is consistent
   • Maximize FUSE process reuse

3. Monitor Standalone Pods

   # View all Standalone Pods
   kubectl get pods -n curvine-system -l app=curvine-standalone
   
   # View reference count state
   kubectl get configmap -n curvine-system -l app=curvine-standalone-state

4. Check logs for lifecycle events

   # Creation
   I1222 10:00:00 Creating Standalone for cluster 0893a5f6
   
   # Reference addition
   I1222 10:01:00 Added volume ref, refCount=2
   
   # Automatic cleanup
   I1222 10:15:00 Removed volume ref, refCount=0
   I1222 10:15:00 No more refs, deleting Standalone