All Products
Search
Document Center

File Storage NAS:Mount a static persistent NAS volume using NFS

Last Updated:Aug 27, 2026

NAS volumes provide data persistence, preventing data loss when a pod is recreated, and data sharing, enabling simultaneous read and write access by multiple pods. Container Service for Kubernetes (ACK) lets you mount existing NAS file systems to workloads as static persistent volumes.

  • Static volume: You must create a PV in advance to represent an existing storage resource, such as a NAS file system. An application creates a PVC to request storage, and the system then binds this PVC to a suitable pre-provisioned PV. This is a common method for managing existing storage resources. However, the bound PVC does not support online expansion by default.

    To use automatic volume expansion, see Use dynamic NAS volumes or Use CNFS to automatically expand NAS volumes.
  • Dynamic volume: You do not need to create a PV in advance. When an application creates a PVC, the system automatically provisions a new volume and a corresponding PV on demand, based on the StorageClass specified in the PVC. This approach is more flexible and supports volume expansion.

Workflow

This diagram shows the workflow for mounting a static NAS storage volume in an ACK cluster.

image
  1. Create a PV: Register an existing NAS file system with the cluster by declaring its mount point (the root directory or a specific subdirectory), capacity, access mode, and other properties.

  2. Create a PVC: An application uses a PVC to claim registered storage resources. Kubernetes then automatically binds the PVC to a matching PV.

  3. Create an application: Mount the bound PVC to an application pod as a persistent directory within the container.

Prerequisites

  • The csi-plugin and csi-provisioner components are installed.

    CSI components are installed by default. Verify that they remain installed. You can check the installation status on the Add-ons page. We recommend upgrading the CSI components to the latest version.
  • Your NAS file system must meet the following conditions. Otherwise, create a file system or use a dynamically provisioned NAS volume.

    NAS has limitations on mount connectivity, the number of file systems, and protocol types.
    • Protocol Type: Must be NFS.

    • VPC: The NAS file system must be in the same VPC as the cluster. NAS supports cross-availability zone mounting, but does not support cross-VPC mounting.

    • Mount Target: Add a mount target in the same VPC as the cluster. Its status must be Available. For details, see Manage mount targets. Record the mount target address.

    • (Optional) Encryption Type: To encrypt volume data, configure the encryption type when you create the NAS file system.

Usage notes

  • Do not delete mount targets: To prevent node I/O errors, do not delete a mount target in the NAS console while its corresponding volume is in use.

  • Concurrent writes: NAS provides shared storage. When multiple Pods mount the same volume, your application must handle potential data consistency issues from concurrent writes.

    For more information about limitations on concurrent writes to NAS, see Multiple processes writing to the same log file and Latency in reading updated file content across ECS instances.
  • Mount performance: If you configure the securityContext.fsgroup parameter in your application, kubelet recursively runs chmod or chown after the volume is mounted, significantly increasing Pod startup time.

    To optimize mount performance, see NAS volume FAQ.

Step 1: Create a PersistentVolume

Create a PersistentVolume (PV) to make an existing NAS file system available in your cluster.

Kubectl

  1. Create a file named pv-nas.yaml with the following content.

    apiVersion: v1
    kind: PersistentVolume
    metadata:
      # The name of the PV, which must be unique in the cluster.
      name: pv-nas  
      # The label of the PV, used for matching with a PVC.
      labels:  
        alicloud-pvname: pv-nas
    spec:
      capacity:
        # This capacity is for matching purposes only. The actual capacity is determined by the NAS file system.
        storage: 5Gi  
      accessModes:
        - ReadWriteMany
      # The reclaim policy for the PV.
      persistentVolumeReclaimPolicy: Retain
      csi:
        # The driver. This value is fixed when you use a NAS volume.
        driver: nasplugin.csi.alibabacloud.com  
        # Must be the same as metadata.name.
        volumeHandle: pv-nas   
        volumeAttributes:
          server: "0c47****-mpk25.cn-shenzhen.nas.aliyuncs.com"  # Replace this value with the address of your NAS mount target.
          # The NAS subdirectory to mount. If the subdirectory does not exist, it is automatically created.
          path: "/csi"
      mountOptions:
      - nolock,tcp,noresvport
      - vers=3

    Parameter

    Description

    storage

    The capacity of the PV. This value is used only for matching with a PersistentVolumeClaim (PVC) and does not limit the actual available capacity. Your application's available storage capacity is limited by the total capacity of the NAS file system.

    The maximum capacity of a NAS file system is determined by its specifications. For more information, see General-purpose NAS and Extreme NAS.

    accessModes

    The access mode. Valid values:

    • ReadWriteMany (default): The volume can be mounted as read-write by many nodes.

    • ReadWriteOnce: The volume can be mounted as read-write by a single node.

    • ReadOnlyMany: The volume can be mounted as read-only by many nodes.

    persistentVolumeReclaimPolicy

    The reclaim policy for the PV. This policy defines what happens to the PV and the backend NAS data when the bound PersistentVolumeClaim (PVC) is deleted.

    • Retain (Recommended): After the PVC is deleted, the PV enters the Released state. The backend NAS data is retained and must be manually deleted.

    • Delete: Deletes the PV when the associated PVC is deleted. This policy requires archiveOnDelete. However, static PVs do not support archiveOnDelete. Therefore, when this policy is set to Delete, deleting the PVC does not delete the PV or the files on the NAS file system.

      To configure archiveOnDelete, see Use dynamically provisioned NAS volumes.

    driver

    The driver. Set this parameter to nasplugin.csi.alibabacloud.com when you use the Alibaba Cloud NAS CSI plug-in.

    volumeHandle

    A unique identifier for the volume in the backend storage system. This must be the same as the PV name (metadata.name). If you use multiple PVs, this value must be unique for each PV.

    server

    The address of the NAS mount target.

    To find the mount target address, see Manage mount targets.

    path

    The NAS subdirectory to mount. If this parameter is not specified, the root directory is mounted by default.

    If the directory does not exist in the NAS file system, it is automatically created and then mounted.
    • General-purpose NAS: The root directory is /.

    • Extreme NAS: The root directory is /share. When you mount a subdirectory, the path must start with /share, such as /share/data.

    mountOptions

    The mount options for NAS, including the NFS protocol version. By default, volumes are mounted using NFSv3. You can specify a different version with an option such as vers=4.0. For information about the NFS protocols supported by different NAS types, see NFS protocols.

  2. Create the PV.

    kubectl create -f pv-nas.yaml
  3. Check the status and properties of the PV.

    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 output shows that the PV was successfully created with a capacity of 5 Gi and has a status of Available, meaning it is not yet bound to a PersistentVolumeClaim (PVC).

Console

  1. Log on to the ACK console. In the left navigation pane, click Clusters.

  2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Volumes > Persistent Volumes.

  3. On the Persistent Volumes page, click Create. In the dialog box that appears, configure the parameters and then click Create.

    Parameter

    Description

    PV Type

    Select NAS.

    Volume Name:

    The name of the PV, which must be unique in the cluster.

    Capacity

    The capacity of the PV. This value is used only for matching with a PersistentVolumeClaim (PVC) and does not limit the actual available capacity. Your application's available storage capacity is limited by the total capacity of the NAS file system.

    The maximum capacity of a NAS file system is determined by its specifications. For more information, see General-purpose NAS and Extreme NAS.

    Access Mode

    Configure the access mode. Valid values:

    • ReadWriteMany: The volume can be mounted as read-write by multiple nodes.

    • ReadWriteOnce: The volume can be mounted as read-write by a single node.

    Enable CNFS

    Specifies whether to use Container Network File System (CNFS) to use its features for automated O&M, cache acceleration, and performance monitoring.

    To use CNFS to manage an existing NAS file system, see Create a CNFS-managed NAS file system (Recommended).

    Mount Target Domain Name:

    This parameter is displayed only when CNFS is disabled.

    The address of the NAS mount target.

    To obtain the address, see Manage mount targets.
    • Select Mount Target: Select the address of a previously added mount target.

    • Custom: Use a custom domain name as the mount address. Ensure that the custom domain name resolves to the target NAS mount target.

    Advanced Options (Optional)

    Mount Path

    The NAS subdirectory to mount. If this parameter is not specified, the root directory is mounted by default.

    If the directory does not exist in the NAS file system, it is automatically created and then mounted.
    • General-purpose NAS: The root directory is /.

    • Extreme NAS: The root directory is /share. When you mount a subdirectory, the path must start with /share, such as /share/data.

    Reclaim Policy

    • Retain (default): When the PVC is deleted, the PV and NAS files are not deleted. You must manually delete them.

    • Delete: Deletes the PV when the associated PVC is deleted. This policy requires archiveOnDelete. However, static PVs do not support archiveOnDelete. Therefore, when this policy is set to Delete, deleting the PVC does not delete the PV or the files on the NAS file system.

      To configure archiveOnDelete, see Use dynamically provisioned NAS volumes.

    Mount Options

    The mount options for NAS, including the NFS protocol version. By default, volumes are mounted using NFSv3. You can specify a different version with an option such as vers=4.0. For information about the NFS protocols supported by different NAS types, see NFS protocols.

    Labels

    Labels to apply to the PV.

    After the PV is created, you can view it on the Persistent Volumes page.

Step 2: Create a PVC

Create a Persistent Volume Claim (PVC) to request persistent storage for your application.

kubectl

  1. Create a file named pvc-nas.yaml to bind to the previously created PV.

    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: pvc-nas  # The PVC name, which must be unique within the namespace.
    spec:
      accessModes:
        - ReadWriteMany
      resources:
        requests:
          storage: 5Gi
      selector:
        matchLabels:
          alicloud-pvname: pv-nas   # Matches the PV created earlier by its label.

    Parameter

    Description

    accessModes

    The access mode. Valid values:

    • ReadWriteMany (default): The volume can be mounted as read-write by many nodes.

    • ReadWriteOnce: The volume can be mounted as read-write by a single node.

    • ReadOnlyMany: The volume can be mounted as read-only by many nodes.

    storage

    This value is used to find a matching PV and does not limit the actual storage capacity.

    The maximum capacity of a NAS file system is determined by its specifications. For more information, see General-purpose NAS and Extreme NAS.

    matchLabels

    Specifies the label used to select a PV for binding.

  2. Create the PVC.

    kubectl create -f pvc-nas.yaml
  3. Check the status of the PVC.

    kubectl get pvc

    Expected output:

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

    The output shows that the pvc-nas PVC is Bound to the pv-nas PV and is ready for use by an application.

Console

  1. In the left navigation pane of the cluster management page, choose Storage > PVCs.

  2. On the Persistent Volume Claims page, click Create and configure the parameters as described in the following table.

    Parameter

    Description

    PVC Type

    Select NAS.

    Name

    The PVC name, which must be unique within the namespace.

    Allocation Mode

    Select Existing Persistent Volume.

    This topic uses the PV created in the previous step. If you have not created a PV, you can set the Allocation Mode to Create PV.

    Existing Volumes

    Select the previously created PV.

    Capacity

    This value is used to find a matching PV and does not limit the actual storage capacity.

    The maximum capacity of a NAS file system is determined by its specifications. For more information, see General-purpose NAS and Extreme NAS.

    Access Mode

    The access mode. Valid values:

    • ReadWriteMany (default): The volume can be mounted as read-write by many nodes.

    • ReadWriteOnce: The volume can be mounted as read-write by a single node.

    • ReadOnlyMany: The volume can be mounted as read-only by many nodes.

Step 3: Create application and mount NAS

After you create the PVC, you can mount the bound PV in an application.

kubectl

  1. Create a file named deploy.yaml with the following content. This manifest references the PVC that you created earlier.

    This setup lets you verify the shared storage feature of 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
                # The mount path for the NAS volume.
                mountPath: "/data"  
          volumes:
            # Specify the PVC to use.
            - name: pvc-nas  
              persistentVolumeClaim:
                claimName: pvc-nas
  2. Create the Deployment.

    kubectl create -f deploy.yaml
  3. Check the status of the Pods.

    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

Console

  1. On the Clusters page, click the name of your cluster. In the left navigation pane, click Workloads > Deployments.

  2. On the Deployments page, click Create from Image and configure the application parameters.

    The following table describes the main parameters. You can keep the default values for other parameters. For more information, see Create a stateless workload (Deployment).

    Category

    Parameter

    Description

    Basic Information

    Application Name

    The name of the Deployment.

    Replicas:

    The number of replicas for the Deployment.

    This setup lets you verify the shared storage feature of NAS.

    Container

    Image Name

    The address of the application image.

    Required Resources

    The required vCPU and memory resources.

    Volume

    Click Add PVC and configure the parameters.

    • Mount Source: Select the PVC that you created earlier.

    • Container Path: The path within the container to mount the NAS file system, such as /data.

    When the deployment finishes, go to the Deployments page and click the application's name. On the Pods tab, verify that the Pods are in the Running state.

Verify shared and persistent storage

After you deploy the application, verify that the volume works as expected.

Shared storage

Persistent storage

To verify shared storage, create a file in one pod and then check for it in another.

  1. Get the pod names.

    kubectl get pod | grep nas-test

    Expected output:

    nas-test-*****a   1/1     Running   0          40s
    nas-test-*****b   1/1     Running   0          40s
  2. Create a file in one of the pods.

    For example, use the pod named nas-test-*****a:

    kubectl exec nas-test-*****a -- touch /data/test.txt
  3. Check if the file exists in the other pod.

    For example, use the pod named nas-test-*****b:

    kubectl exec nas-test-*****b -- ls /data

    Expected output:

    test.txt

    The output shows the file, confirming that data is shared between pods.

To verify persistent storage, restart the Deployment and check if the data persists in the new pods.

  1. Restart the Deployment to recreate the application pods.

    kubectl rollout restart deploy nas-test
  2. Check the status of the pods and wait for the new pods to start and enter the Running state.

    kubectl get pod | grep nas-test

    Expected output:

    nas-test-*****c   1/1     Running   0          67s
    nas-test-*****d   1/1     Running   0          49s
  3. Check if the previously created file exists in a new pod.

    For example, use the pod named nas-test-*****c:

    kubectl exec nas-test-*****c -- ls /data

    Expected output:

    test.txt

    The output shows the file, confirming that data persists across pod restarts.

Production readiness

  • Security and access management

    • Use permission groups for access control: NAS uses permission groups to manage network access. Follow the principle of least privilege: add only the private IP addresses of cluster nodes or their vSwitch CIDR blocks to the permission group. Avoid overly broad permissions, such as 0.0.0.0/0.

  • Performance and cost optimization

    • Select an appropriate NAS type: Refer to File system selection to choose a NAS type that meets your application's IOPS and throughput requirements.

    • Optimize mount options (mountOptions): Adjust NFS mount parameters based on your workload characteristics. For example, using protocol versions such as vers=4.0 or vers=4.1 can improve performance and file locking capabilities in some scenarios. For workloads with large-scale file I/O, test different rsize and wsize values to optimize read and write throughput.

  • Operations and reliability

    • Configure health checks: Configure a liveness probe for your application pods to verify that the mount point is healthy. If a mount point becomes unresponsive, ACK automatically restarts the pod, triggering a remount of the storage volume.

    • Set up monitoring and alerts: Use container storage monitoring to configure alerts to promptly detect storage volume issues or performance bottlenecks.

    • Use the Retain reclaim policy: For production data, set the persistentVolumeReclaimPolicy for the PV to Retain. This prevents accidental data loss on the backend NAS file system when the corresponding PVC is removed.

Release resources

To avoid unexpected charges, release the resources in the following order when you no longer need the NAS volume.

  1. Delete workloads

    • Delete all applications, such as Deployments and StatefulSets, that use the NAS volume. This action unmounts the volume from the Pods and stops all read and write access.

    • Example command: kubectl delete deployment <your-deployment-name>

  2. Delete the PVC

    • Delete the PVC associated with the application. After the PVC is deleted, what happens to the bound PV depends on its persistentVolumeReclaimPolicy.

    • Reclaim policy:

      • Retain (recommended): After a PVC is deleted, its bound PV enters the Released state. The PV object and the data on the backend NAS file system are retained. You must delete them manually.

      • Delete: After a PVC is deleted, the corresponding PV object is also deleted. Note the following:

        • If the PV points to the root directory of the NAS file system, the data on the file system is retained to prevent accidental deletion.

        • If the volumeHandle of a static PV is a suffix of its path (for example, if volumeHandle is app and path is /exports/app), deleting the PVC triggers the automatic deletion of the subdirectory on the backend NAS file system. Use this feature with caution.

    • Example command: kubectl delete pvc <your-pvc-name>

  3. Delete the PV

    • You can delete a PV when its status is Available or Released. This action only removes the PV definition from the Kubernetes cluster but does not delete the data on the backend NAS file system.

    • Example command: kubectl delete pv <your-pv-name>

  4. Delete the backend NAS file system (optional)

    • See Delete a file system. This action permanently deletes all data on the NAS file system and cannot be undone. Before proceeding, ensure that no workloads depend on the file system.

References