Mount CPFS Volumes on ACS for Persistent GPU Storage - Container Compute Service

Mount a statically provisioned CPFS volume

Cloud Parallel File Storage (CPFS) is a fully managed, expandable parallel file system for high-performance computing scenarios. CPFS allows concurrent access from thousands of servers, provides tens of GB/s of throughput and millions of input/output operations per second, all at sub-millisecond latency. AI and HPC workloads running in Alibaba Cloud Container Service (ACS) often require this kind of shared, high-throughput storage accessible by multiple pods simultaneously. This topic explains how to mount a statically provisioned CPFS volume to an ACS application and verify that the volume supports shared and persistent storage.

Before you begin

CPFS for LINGJUN is designed for intelligent computing scenarios such as AIGC and autonomous driving. Note the following constraints before you proceed:

CPFS for LINGJUN supports end-to-end RDMA networks and is currently in invitational preview. Support is limited to certain regions and zones.
When accessing CPFS for LINGJUN over RDMA, the hpn-zone of the pod must match the hpn-zone of the CPFS for LINGJUN file system.
CPFS is a shared file system. You can mount a CPFS volume to multiple pods simultaneously.
CPFS volumes can be mounted to any CPU-accelerated ACS pod. For GPU-accelerated pods, only specific GPU models are supported. To check eligibility, submit a ticket.

Prerequisites

Before you begin, ensure that you have:

The managed-csiprovisioner add-on installed in your ACS cluster

To verify the installation, go to the ACS cluster management page, choose Operations > Add-ons in the left-side navigation pane, and check the Storage tab.

How static provisioning works

Static provisioning requires three steps:

Create a CPFS file system in the CPFS console and record its file system ID.
Create a PersistentVolume (PV) and a PersistentVolumeClaim (PVC) in your ACS cluster that reference the file system.
Create a Deployment that references the PVC. Kubernetes binds the PVC to the PV and mounts the file system into your pods.

Choose your access method

The PV configuration depends on your pod type and network access method. Determine which scenario applies before proceeding to Step 1.

Scenario	Pod type	Network	CSI driver
CPFS for LINGJUN via RDMA	GPU (specific models only)	Direct RDMA	`povplugin.csi.alibabacloud.com`
CPFS for LINGJUN via VPC	CPU pods or GPU pods without RDMA support	VPC mount target	`nasplugin.csi.alibabacloud.com`

Step 1: Create a CPFS file system

Create a CPFS for LINGJUN file system and record the file system ID.
(Optional) Create a VPC mount target. Create a VPC mount target if your pods do not support RDMA — for example, CPU pods or GPU pods without RDMA support. Use the VPC and vSwitch of your ACS cluster when creating the mount target. Record the mount target domain name, which follows the format cpfs-*-vpc-*.<Region>.cpfs.aliyuncs.com.

Step 2: Create a PV and a PVC

kubectl

Create a file named cpfs-pv-pvc.yaml. Select the YAML that matches your access method from the "Choose your access method" table. CPFS for LINGJUN — RDMA network

Important

Only pods with specific GPU models support RDMA. For supported models, see GPU models supported by ACS.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: cpfs-test
  labels:
    alicloud-pvname: cpfs-test        # Used by the PVC selector to bind to this PV
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 10Ti                     # Declared capacity; must be >= the PVC request
  csi:
    driver: povplugin.csi.alibabacloud.com
    volumeAttributes:
      filesystemId: bmcpfs-*****      # Replace with your CPFS for LINGJUN file system ID
      path: /                         # Mount path in the file system; subdirectories are auto-created
    volumeHandle: bmcpfs-*****        # Same as filesystemId
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cpfs-test
spec:
  accessModes:
  - ReadWriteMany
  selector:
    matchLabels:
      alicloud-pvname: cpfs-test      # Must match the label on the PV above
  resources:
    requests:
      storage: 10Ti                   # Must not exceed the PV capacity

CPFS for LINGJUN — VPC network

apiVersion: v1
kind: PersistentVolume
metadata:
  name: cpfs-test
  labels:
    alicloud-pvname: cpfs-test        # Used by the PVC selector to bind to this PV
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 10Ti                     # Declared capacity; must be >= the PVC request
  csi:
    driver: nasplugin.csi.alibabacloud.com
    volumeAttributes:
      mountProtocol: efc             # Protocol for VPC-based CPFS access
      server: cpfs-***-vpc-***.cn-wulanchabu.cpfs.aliyuncs.com  # Replace with your VPC mount target domain name
      path: /                        # Mount path in the file system; subdirectories are auto-created
    volumeHandle: bmcpfs-*****       # Replace with your CPFS for LINGJUN file system ID
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cpfs-test
spec:
  accessModes:
  - ReadWriteMany
  selector:
    matchLabels:
      alicloud-pvname: cpfs-test     # Must match the label on the PV above
  resources:
    requests:
      storage: 10Ti                  # Must not exceed the PV capacity

Create the PV and PVC.
```
kubectl create -f cpfs-pv-pvc.yaml
```

Confirm the PVC is bound to the PV.

kubectl get pvc cpfs-test

Expected output:

NAME        STATUS   VOLUME      CAPACITY   ACCESS MODES   STORAGECLASS    VOLUMEATTRIBUTESCLASS   AGE
cpfs-test   Bound    cpfs-test   10Ti       RWX            <unset>         <unset>                 10s

Console

Mounting CPFS for LINGJUN to CPU applications through VPC mount targets is not currently supported in the console. Use kubectl for this scenario.

Log on to the ACS console.
On the Clusters page, click the cluster name.
In the left-side navigation pane, choose Volumes > Persistent Volume Claims.
On the Persistent Volume Claims page, click Create.

Configure the parameters and click Create.

Parameter	Description	Example
PVC type	Select CPFS.	CPFS
Name	A custom name for the PVC.	cpfs-test
Allocation mode	Select Existing Volumes to bind an existing PV, or Create Volume to create a PV and PVC together.	Create Volume
CPFS type	Select CPFS for LINGJUN.	CPFS for LINGJUN
Access mode	Select ReadWriteMany or ReadWriteOnce.	ReadWriteMany
File system ID	The ID of your CPFS for LINGJUN file system.	bmcpfs-0115\\\\\\13q5

On the Persistent Volume Claims page and the Persistent Volumes page, confirm that the newly created PVC and PV appear and their status shows as Bound.

Step 3: Deploy an application with the CPFS volume

kubectl

Create a file named cpfs-test.yaml. Select the template that matches your pod type. The following examples create a Deployment with two replicas. Both pods mount the CPFS file system at /data using the PVC created in Step 2. GPU-accelerated application

For supported GPU models and driver versions, see Specify GPU models and driver versions for ACS GPU-accelerated pods.

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
        alibabacloud.com/compute-class: gpu       # Request GPU compute resources
        alibabacloud.com/gpu-model-series: T4     # Specify the GPU model (e.g., T4); update as needed
        alibabacloud.com/compute-qos: default
    spec:
      containers:
      - name: nginx
        image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginx:latest
        ports:
        - containerPort: 80
        volumeMounts:
          - name: pvc-cpfs
            mountPath: /data                      # Mount path inside the container
      volumes:
        - name: pvc-cpfs
          persistentVolumeClaim:
            claimName: cpfs-test                  # Must match the PVC name from Step 2

CPU-accelerated application

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: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginx:latest
        ports:
        - containerPort: 80
        volumeMounts:
          - name: pvc-cpfs
            mountPath: /data                      # Mount path inside the container
      volumes:
        - name: pvc-cpfs
          persistentVolumeClaim:
            claimName: cpfs-test                  # Must match the PVC name from Step 2

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

Confirm both pods are running.

kubectl get pod | grep cpfs-test

Expected output:

cpfs-test-****-***a   1/1     Running   0          45s
cpfs-test-****-***b   1/1     Running   0          45s

Confirm the CPFS file system is mounted at the expected path.
```
kubectl exec cpfs-test-****-***a -- ls /data
```
The directory is empty by default if no data has been written.

Console

In the left-side navigation pane of the cluster management page, choose Workloads > Deployments.
On the Deployments page, click Create from Image.

Configure the Deployment parameters. For parameters not listed below, keep the defaults. For more information, see Create a stateless application using a Deployment.

GPU-accelerated application

Configuration page	Parameter	Description	Example
Basic information	Name	A custom name for the Deployment.	cpfs-test
	Replicas	Number of pod replicas.	2
	Type	The compute type for the pod. For supported GPU models, see Specify GPU models and driver versions for ACS GPU-accelerated pods.	GPU, T4
Container	Image name	The container image address.	registry.cn-hangzhou.aliyuncs.com/acs-sample/nginx:latest
	Required resources	GPU, vCPU, and memory to allocate.	GPU: 1, CPU: 2 vCPUs, Memory: 2 GiB
	Volume	Click Add PVC and set the mount source and container path.	Mount source: pvc-cpfs, Container path: /data

CPU-accelerated application

Configuration page	Parameter	Description	Example
Basic information	Application name	A custom name for the Deployment.	cpfs-test
	Replicas	Number of pod replicas.	2
	Type	The compute type for the pod.	CPU, general-purpose
Container	Image name	The container image address.	registry.cn-hangzhou.aliyuncs.com/acs-sample/nginx:latest
	Required resources	vCPU and memory to allocate.	CPU: 0.25 vCPUs, Memory: 0.5 GiB
	Volume	Click Add PVC and set the mount source and container path.	Mount source: pvc-cpfs, Container path: /data

Click the Deployment name on the Deployments page. On the Pods tab, confirm that all pods show a Running status.

Verify shared and persistent storage

The Deployment created above has two pods that mount the same CPFS file system. Use the following steps to verify that shared storage and persistent storage work correctly.

Get the pod names.

kubectl get pod | grep cpfs-test

Expected output:

cpfs-test-****-***a   1/1     Running   0          45s
cpfs-test-****-***b   1/1     Running   0          45s

Confirm the mount directory is empty before writing any data.
```
kubectl exec cpfs-test-****-***a -- ls /data
```
If no output is returned, the directory is empty and ready for testing.
Verify shared storage.
1. Create a file in one pod. ``shell kubectl exec cpfs-test-**-*a -- touch /data/test.txt ``
2. Check that the file is visible in the other pod. ``shell kubectl exec cpfs-test-**-*b -- ls /data ` Expected output — the file created in the first pod is visible in the second pod: ` test.txt ``
Verify persistent storage.
1. Restart the Deployment to create new pods. ``shell kubectl rollout restart deploy cpfs-test ``
2. Wait for the new pods to reach Running status. ``shell kubectl get pod | grep cpfs-test ` Expected output: ` cpfs-test-**-*c 1/1 Running 0 78s cpfs-test-**-*d 1/1 Running 0 52s ``
3. Check that the data persists in the new pods. ``shell kubectl exec cpfs-test-**-*c -- ls /data ` Expected output — the file still exists after the pods were recreated: ` test.txt ``