Mount NAS Volumes via CSI for Persistent Pod Storage - Container Compute Service

Statically provisioned volume: You create a PV to represent an existing storage resource, such as a NAS file system. An application then creates a PVC to request and bind to this PV. This approach is commonly used to manage existing storage resources. By default, a bound PVC does not support online scaling.
Dynamically provisioned volume: You do not need to create a PV in advance. When an application creates a PVC, the system automatically creates a storage volume and a corresponding PV based on the StorageClass specified in the PVC. This approach is more flexible and supports volume scaling. For details, see Use a dynamically provisioned NAS volume.

Considerations

Before you begin, note the following:

Protocol: Only NFS protocol NAS file systems are supported. You cannot mount NAS file systems that use the SMB protocol.
Network: The mount target and cluster nodes must be in the same VPC. Cross-VPC mounting is not supported. Within the same VPC, you can mount across zones.
Access modes: Access modes (ReadWriteMany, ReadWriteOnce, ReadOnlyMany) define how a volume can be mounted, but they do not enforce OS-level write protection once the storage is mounted. Your application is responsible for ensuring data consistency.
Reclaim policy: The PV uses the Retain reclaim policy. When you delete the PVC, the PV is not automatically deleted and moves to a "Released" state. The underlying NAS file system and its data are preserved. You must manually delete or reclaim the PV before it can be reused.
Concurrent writes: NAS provides shared storage. A single NAS volume can be mounted to multiple Pods simultaneously. If multiple Pods write data concurrently, your application must ensure data consistency. See How do I prevent exceptions when multiple processes or clients write to the same log file concurrently? and How do I resolve data latency issues when writing to an NFS file system?
Mount target deletion: Do not delete the NAS mount target after mounting. Deleting it may cause the system to become unresponsive.
securityContext.fsgroup: If you configure securityContext.fsgroup in the application template, the kubelet runs a chmod or chown operation after the volume mounts, which increases mount time. For details, see Extended mount time for NAS volumes.

Prerequisites

Your existing NAS file system must meet the following conditions. If it does not, you can create a file system.
- The file system uses the NFS protocol.
- The mount target and cluster nodes are in the same VPC, and the mount target Status is Available. To add a mount target, see Manage mount targets.
Note
To encrypt data in the NAS volume, configure the encryption type when you create the NAS file system.
You also need kubectl access to your cluster. See Obtain the cluster kubeconfig and use kubectl to connect to the cluster.

Mount a statically provisioned NAS volume using kubectl

Step 1: Create a PV

Save the following YAML content as pv-nas.yaml.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-nas
  labels:
    alicloud-pvname: pv-nas
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadWriteMany
  csi:
    driver: nasplugin.csi.alibabacloud.com
    volumeHandle: pv-nas   # Must be the same as the PV name.
    volumeAttributes:
      server: "0c47****-mpk25.cn-shenzhen.nas.aliyuncs.com"  # The address of the NAS mount target. The VPC of the mount target must be the same as the VPC of the cluster.
      path: "/csi"  # The subdirectory to mount.
  mountOptions:
  - nolock,tcp,noresvport
  - vers=3

Parameter	Description
`name`	The name of the PV.
`labels`	The labels of the PV. The PVC uses a label selector to bind to this specific PV, rather than any available PV with matching capacity and access mode.
`storage`	The declared capacity of the PV. Important This value does not limit the actual available capacity of the NAS volume. Actual capacity is determined by the NAS file system specifications. See General-purpose NAS file system and Extreme NAS file system for details.
`accessModes`	The access mode. The default value is `ReadWriteMany`. `ReadWriteOnce` and `ReadOnlyMany` are also supported. Note Access modes do not enforce OS-level write protection once the volume is mounted.
`driver`	The CSI driver type. Must be set to `nasplugin.csi.alibabacloud.com`.
`volumeHandle`	A unique identifier for the PV. Must match the PV name. If you use multiple PVs, this value must be unique for each PV.
`server`	The address of the NAS mount target. The mount target's VPC must match the cluster's VPC. For instructions on viewing the mount target address, see Manage mount targets.
`path`	The NAS subdirectory to mount. If not set, the root directory is mounted by default. If the directory does not exist in the NAS file system, it is automatically created before mounting. Note The root directory of a General-purpose NAS file system is `/`. The root directory of an Extreme NAS file system is `/share`. When you mount a subdirectory of an Extreme NAS file system, the `path` must start with `/share`, for example `/share/data`.
`mountOptions`	Mount parameters, including the NFS protocol version. NFS v3 is recommended for better performance and broader compatibility. Extreme NAS file systems only support NFS v3. For more information, see NFS protocol.

Create the PV.
```
kubectl create -f pv-nas.yaml
```
Verify the PV was created.
```
kubectl get pv
```
Expected output:
```
NAME     CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM    STORAGECLASS     VOLUMEATTRIBUTESCLASS   REASON   AGE
pv-nas   5Gi        RWX            Retain           Available                             <unset>                          25s
```
The Retain reclaim policy means that when you delete the PVC, the PV is not automatically deleted. The PV moves to a "Released" state, and the underlying NAS data is preserved. You must manually delete or reclaim the PV before reuse.

Step 2: Create a PVC

Save the following YAML as pvc-nas.yaml.

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: pvc-nas
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  selector:
    matchLabels:
      alicloud-pvname: pv-nas

Parameter	Description
`name`	The name of the PVC.
`accessModes`	Must match the PV's access mode. Default: `ReadWriteMany`. You can also set this to `ReadWriteOnce` or `ReadOnlyMany`.
`storage`	The requested storage capacity. Cannot exceed the PV's capacity. Important The actual available capacity is determined by the NAS file system specifications, not this value. See General-purpose NAS file system and Extreme NAS file system for details.
`matchLabels`	Labels used to bind this PVC to the specific PV created in Step 1.

Create the PVC.
```
kubectl create -f pvc-nas.yaml
```

Verify the PVC status.

kubectl get pvc

Expected output:

NAME       STATUS   VOLUME    CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
pvc-nas    Bound    pv-nas    5Gi        RWX                           <unset>                 5s

A Bound status confirms the PVC has successfully bound to the PV.

Step 3: Create an application and mount the NAS volume

Save the following YAML as nas.yaml.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nas-test
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    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-nas
            mountPath: "/data"
      volumes:
        - name: pvc-nas
          persistentVolumeClaim:
            claimName: pvc-nas

Parameter	Description
`mountPath`	The container path where the NAS volume is mounted.
`claimName`	The name of the PVC to bind.

Deploy the application.
```
kubectl create -f nas.yaml
```

Check Pod status.

kubectl get pod -l app=nginx

Expected output:

NAME                  READY   STATUS    RESTARTS   AGE
nas-test-****-***a    1/1     Running   0          32s
nas-test-****-***b    1/1     Running   0          32s

Both Pods show Running status, confirming the NAS volume mounted successfully.

Verify shared storage and persistent storage

The Deployment creates two Pods, both mounting the same NAS file system. You can verify that the volume provides shared and persistent storage.

Verify shared storage: Create a file in one Pod and confirm it is visible from the other Pod.
Verify persistent storage: Recreate the Deployment and confirm the file still exists in the newly created Pods.

View the running Pods.

kubectl get pod | grep nas-test

Sample output:

nas-test-*****a   1/1     Running   0          40s
nas-test-*****b   1/1     Running   0          40s

Verify shared storage.
1. Create a file in one Pod. This example uses nas-test-*****a.
```
kubectl exec nas-test-*****a -- touch /data/test.txt
```
2. Confirm the file is visible from the other Pod. This example uses nas-test-*****b.
```
kubectl exec nas-test-*****b -- ls /data
```
  Expected output:
```
test.txt
```
  The file created in nas-test-*****a is accessible from nas-test-*****b, confirming shared storage.
Verify persistent storage.
1. Recreate the Deployment.
```
kubectl rollout restart deploy nas-test
```
2. Wait for the new Pods to start.
```
kubectl get pod | grep nas-test
```
  Sample output:
```
nas-test-*****c   1/1     Running   0          67s
nas-test-*****d   1/1     Running   0          49s
```
3. Check that the file still exists in a new Pod. This example uses nas-test-*****c.
```
kubectl exec nas-test-*****c -- ls /data
```
  Expected output:
```
test.txt
```
  The file persists in the NAS file system and is accessible from the new Pod.

Cleanup

To remove the application and storage resources, run the following commands in order:

kubectl delete -f nas.yaml
kubectl delete -f pvc-nas.yaml
kubectl delete -f pv-nas.yaml

Because the PV uses the Retain reclaim policy, the underlying NAS file system and its data are not deleted when you delete the PVC or PV. You must manage NAS file system data independently through the NAS console.

FAQ

If you encounter problems when mounting or using a NAS volume, see the following resources for troubleshooting.