Use CPFS for Lingjun Statically Provisioned Volumes in ACK Clusters - Container Service for Kubernetes

Choose a mounting method

Based on the Container Storage Interface (CSI), ACK supports mounting CPFS for Lingjun file systems as statically provisioned PVs and persistent volume claims (PVCs). The CSI add-on automatically selects the optimal mounting method based on the pod's node type:

Mounting method	Supported nodes	Requirements
Virtual storage channel (VSC)	Lingjun nodes only	You must submit a ticket to both the CPFS and Lingjun product teams for allowlist access.
VPC	Non-Lingjun nodes	Create a VPC mount target in the same VPC as the cluster nodes.

Before starting, identify which path applies to your cluster:

Pods run on Lingjun nodes—VSC mounting by default. Skip VPC mount target creation.
Pods run on non-Lingjun nodes—VPC mounting required. Create a VPC mount target in Step 1.
Pods run on both node types—Set both vpcMountTarget and mountpointAutoSwitch: "true" in the PV. The CSI add-on switches automatically.

Prerequisites

Before you begin, make sure you have:

Reviewed the limits for CPFS for Lingjun
An ACK cluster running Kubernetes 1.26 or later. Upgrade if needed.
Nodes running Alibaba Cloud Linux 3
The following storage add-ons at the required versions (verify and upgrade on the Add-ons page):
- CSI add-on (csi-plugin and csi-provisioner): v1.33.1 or later (manage CSI add-ons).
- cnfs-nas-daemon: 0.1.2 or later
  Configure cnfs-nas-daemon resources
  The cnfs-nas-daemon add-on manages Elastic File Client (EFC) processes, consumes significant resources, and directly impacts storage performance. Adjust resources on the Add-ons page:
  - CPU: Depends on the node's total bandwidth. Recommended: 0.5 cores per 1 Gbps of bandwidth, plus 1 extra core for metadata management.
    
    Example: For a 100 Gbps node, the CPU request is 100 × 0.5 + 1 = 51 cores.
  - Memory: CPFS for Lingjun uses Filesystem in USErspace (FUSE), so read/write caches and metadata consume memory. Set the request to 15% of the node's total memory.
  Adjust as needed based on your workload.
  Important
  
  Update behavior: cnfs-nas-daemon uses an OnDelete update strategy by default. After adjusting CPU or memory on the Add-ons page, manually delete the cnfs-nas-daemon pods on each node to recreate them with the new configuration. Perform during off-peak hours.
  
  Interruption risk: Deleting or restarting the cnfs-nas-daemon pod temporarily interrupts the CPFS mount service on that node.
  
  For nodes without hot-upgrade support^①: Hard interruption that causes application pods to fail. Manually delete and restart the application pods to restore service.
  
  For nodes with hot-upgrade support^①: Application pods recover automatically after cnfs-nas-daemon restarts.
  
  ①: A node supports hot upgrades if it meets all of the following conditions:
  
  The node's kernel version is 5.10.134-18 or later.
  
  bmcpfs-csi-controller and bmcpfs-csi-plugin are version 1.35.1 or later.
  
  cnfs-nas-daemon is version 0.1.9-compatible.1 or later.
- bmcpfs-csi: includes bmcpfs-csi-controller (control-plane add-on managed by ACK) and bmcpfs-csi-node (node-side DaemonSet)

Usage notes

VSC mounting zone: The node running the pod must be in the same hpn-zone as the CPFS for Lingjun file system instance.
Node initialization: A Lingjun node must be associated with a CPFS for Lingjun file system during initialization. If not, CSI mounting fails.
Node draining: Before decommissioning a faulty Lingjun node, drain all pods from it. Skipping this causes inconsistent cluster metadata and orphaned pod resources that cannot be cleaned up.
Single PV per CPFS instance: Mounting multiple subdirectories from the same CPFS file system as separate PVs to one pod is not supported. Due to driver limitations, this causes pod startup failure. Create one PV/PVC and use volumeMounts.subPath to mount subdirectories. subPath uses a lightweight bind mount with no performance overhead.

Step 1: Create a CPFS file system

Create a CPFS for Lingjun file system and record the file system ID.
(Optional) For non-Lingjun nodes, create a VPC mount target in the same VPC as your cluster nodes and record the mount target domain name. Format: cpfs-*-vpc-*.<Region>.cpfs.aliyuncs.com.

Not required if pods run on Lingjun nodes (VSC mounts by default).

Step 2: Create a PV and PVC

Save the following template as bmcpfs-pv-pvc.yaml, replacing placeholders with your file system ID and (if needed) VPC mount target.

PV parameters

Parameter	Description	Required
`accessModes`	Access mode for the PV.	Yes
`capacity.storage`	Declared storage capacity. Does not affect actual capacity.	Yes
`csi.driver`	Driver type. For CPFS for Lingjun, use `bmcpfsplugin.csi.alibabacloud.com`.	Yes
`csi.volumeHandle`	ID of the CPFS for Lingjun file system.	Yes
`csi.volumeAttributes.vpcMountTarget`	VPC mount target domain name. Required for non-Lingjun nodes; omit if pods schedule only to Lingjun nodes.	Conditional
`csi.volumeAttributes.mountpointAutoSwitch`	Enables automatic switching between VSC and VPC mount points. Use with `vpcMountTarget`.	No
`mountOptions`	Mount options.	No

PVC parameters

Parameter	Description	Required
`accessModes`	Access mode requested by the PVC. Must match the PV.	Yes
`resources.requests.storage`	Storage capacity allocated to the pod. Must not exceed the PV capacity.	Yes
`volumeMode`	Mount mode. Set to `Filesystem`.	Yes
`volumeName`	Name of the PV to bind to this PVC.	Yes

apiVersion: v1
kind: PersistentVolume
metadata:
  name: bmcpfs
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 10Ti
  claimRef:
    name: bmcpfs
    namespace: default
  csi:
    driver: bmcpfsplugin.csi.alibabacloud.com
    volumeAttributes:
      # Required if pods schedule to non-Lingjun nodes or cross-zone automatic VPC switching is enabled.
      # Omit if pods schedule only to Lingjun nodes.
      vpcMountTarget: cpfs-***-vpc-***.<Region>.cpfs.aliyuncs.com
      # Enables automatic switching between VSC and VPC mount points.
      # Use together with vpcMountTarget.
      mountpointAutoSwitch: "true"
    # Replace with your CPFS for Lingjun file system ID.
    volumeHandle: bmcpfs-*****
  mountOptions: []

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: bmcpfs
  namespace: default
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 10Ti
  volumeMode: Filesystem
  volumeName: bmcpfs

Apply the configuration.
```
kubectl apply -f bmcpfs-pv-pvc.yaml
```

Confirm that the PVC is bound to the PV.

kubectl get pvc bmcpfs

Expected output:

NAME     STATUS   VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
bmcpfs   Bound    bmcpfs   10Ti       RWX                           <unset>                 51s

The STATUS is Bound, confirming the PVC is bound to the PV.

Step 3: Deploy a workload

Scenario 1: Mount the entire CPFS file system

Use this approach when all containers need full access to the CPFS file system.

Save the following YAML template as cpfs-test.yaml.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cpfs-test
  labels:
    app: cpfs-test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: cpfs-test
  template:
    metadata:
      labels:
        app: cpfs-test
    spec:
      containers:
      - name: nginx
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        ports:
        - containerPort: 80
        volumeMounts:
          - name: pvc-cpfs
            mountPath: /data
      volumes:
        - name: pvc-cpfs
          persistentVolumeClaim:
            claimName: bmcpfs

Create the Deployment.
```
kubectl create -f cpfs-test.yaml
```

Verify both pods are running.

kubectl get pod -l app=cpfs-test

Expected output:

NAME                         READY   STATUS    RESTARTS   AGE
cpfs-test-76b77d64b5-2hw96   1/1     Running   0          42s
cpfs-test-76b77d64b5-dnwdx   1/1     Running   0          42s

Verify the CPFS volume mount inside a pod.

kubectl exec -it <pod-name> -- mount | grep /data

Expected output:

bindroot-f0a5c-******:cpfs-*******-vpc-****.cn-shanghai.cpfs.aliyuncs.com:/ on /data type fuse.aliyun-alinas-efc (rw,relatime,user_id=0,group_id=0,default_permissions,allow_other,max_read=1048576)

The mount type fuse.aliyun-alinas-efc at /data confirms the CPFS volume is mounted.

Scenario 2: Mount subdirectories for data isolation

In shared storage scenarios such as multi-tenant or multitasking setups, multiple containers can share one CPFS volume while isolating data in separate directories. Use volumeMounts.subPath to mount different subdirectories into different containers from the same PVC.

If a subPath directory (for example, workspace/alpha) does not exist, it is created automatically.

Save the following YAML template as pod.yaml. This pod runs two containers, each mounting a different subdirectory of the same PVC (bmcpfs).

apiVersion: v1
kind: Pod
metadata:
  name: cpfs-subpath-demo-pod
spec:
  containers:
    - name: task-alpha-container
      image: busybox:1.35
      command: ["/bin/sh", "-c", "sleep 3600"]
      volumeMounts:
        - name: cpfs-storage
          mountPath: /data/workspace        # Mount path inside the container
          subPath: workspace/alpha          # Mount the workspace/alpha subdirectory only

    - name: task-beta-container
      image: busybox:1.35
      command: ["/bin/sh", "-c", "sleep 3600"]
      volumeMounts:
        - name: cpfs-storage
          mountPath: /data/workspace        # Mount paths can be identical across containers
          subPath: workspace/beta           # Mount the workspace/beta subdirectory only
  volumes:
    - name: cpfs-storage
      persistentVolumeClaim:
        claimName: bmcpfs                  # Reference the PVC created earlier

Deploy the pod.
```
kubectl apply -f pod.yaml
```

Verify the mount and write permissions for task-alpha-container.

Connect to the container.

kubectl exec -it cpfs-subpath-demo-pod -c task-alpha-container -- /bin/sh

Confirm that the CPFS volume is mounted.
```
df -h
```
Expected output (shared directory mounted at /data/workspace):
```
Filesystem                Size      Used Available Use% Mounted on
...
192.XX.XX.0:/share          10.0T     1.0G     10.0T   0% /data/workspace
...
```
The filesystem entry at /data/workspace confirms the CPFS subdirectory is mounted.

Check the parent directory structure.

ls -l /data/

Expected output:

total 4
drwxr-xr-x    2 root     root          4096 Aug 15 10:00 workspace

Write a test file and exit.

echo "hello from alpha" > /data/workspace/alpha.log
exit

Verify the task-beta-container mount and data isolation.
1. Connect to the container.
```
kubectl exec -it cpfs-subpath-demo-pod -c task-beta-container -- /bin/sh
```
2. Write a test file.
```
echo "hello from beta" > /data/workspace/beta.log
```
3. List files in the mount point.
```
ls -l /data/workspace/
```
  Expected output:
```
total 4
-rw-r--r--    1 root     root            16 Aug 15 10:05 beta.log
```
  beta.log is present but alpha.log is absent, confirming data isolation between containers.