Cloud Parallel File Storage:Mount CPFS AI Edition file systems on ACK

Before you begin

• An ACK Lingjun managed cluster has been created. The cluster runs Kubernetes 1.26 or later and uses Alibaba Cloud Linux 3 as the node operating system.

• A CPFS AI Edition file system has been created. Record the file system ID. For more information, see Create a CPFS AI Edition file system.

• The following storage components are installed in the ACK cluster. You can check the versions on the Component Management page of the cluster or Manage CSI components:

  Component	Required version
  csi-plugin / csi-provisioner	≥ v1.33.1
  cnfs-nas-daemon	≥ 0.1.2
  bmcpfs-csi-controller / bmcpfs-csi-node	Managed by ACK. Manual installation is not required.

• If a pod is scheduled to a non-Lingjun node or a Lingjun node in a different compute-storage affinity zone, you must create a VPC mount target in advance and record the mount target domain name (in the format of cpfs-***-vpc-***.<Region>.cpfs.aliyuncs.com). The VPC to which the VPC mount target belongs must be the same as the VPC of the ACK cluster. For more information, see Manage VPC mount points.

Considerations

• When you mount a CPFS file system by using VSC, the node on which the pod runs must be in the same compute-storage affinity zone as the CPFS AI Edition file system instance.

• If you use CSI container-based mounting for CPFS, you must select the option to support high-performance file storage access when you create a Lingjun node group.

• Before a Lingjun node is taken offline due to a fault, you must first drain pods from the node. Otherwise, the cluster metadata becomes inconsistent, which causes pod resources to remain and fail to be reclaimed properly.

• Mounting different subdirectories from the same CPFS instance through multiple PVs in a single pod is not supported. Due to underlying driver limitations, this configuration causes the pod to fail to start.

  We recommend that you create only one PV/PVC for the CPFS instance, and then use the subPath field in the pod volumeMounts configuration to mount the required subdirectories separately.

  subPath is implemented based on a lightweight bind mount mechanism and does not introduce additional performance overhead.

Access channels and scheduling

In an ACK Lingjun cluster, the network channel through which a pod accesses CPFS AI Edition is determined by the pod scheduling location. The CSI plug-in automatically selects the optimal channel:

To enable automatic channel switching, you must configure both mountpointAutoSwitch: "true" and vpcMountTarget (VPC mount target domain name) in the volumeAttributes of the PV. For configuration details, see Step 1: Create a PV and PVC below.

To determine whether a Lingjun node and a CPFS file system are in the same compute-storage affinity zone, see Overview of mount access.

Step 1: Create a PV and PVC

1. 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

2. Apply the configuration.

   kubectl apply -f bmcpfs-pv-pvc.yaml

3. 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 2: Create an application and mount CPFS

Step 3: Verify the mount

kubectl exec -it <pod-name> -- mount | grep /data
# Expected output contains fuse.aliyun-alinas-efc, indicating the EFC + FUSE protocol is in use