Limit the capacity of subdirectories in dynamically provisioned NAS volumes - Container Service for Kubernetes

The Container Storage Interface (CSI) plug-in supports directory quotas on subdirectories of General-purpose NAS volumes. When you mount NAS subdirectories using the subPath method, directory quotas cap each subdirectory's capacity independently so one application cannot consume storage allocated to another. When a subdirectory reaches its quota limit, expand it online by updating the PVC — no restarts or service interruptions required.

If you use CNFS to manage NAS, the directory quota feature is enabled by default. For more information, see Use CNFS to automatically expand NAS volumes.

Limitations

Directory quotas are supported only for dynamically provisioned NAS volumes that meet all of the following conditions:

Protocol: NFS
NAS type: General-purpose NAS
Mount method: subPath

Statically provisioned NAS volumes and dynamically provisioned NAS volumes mounted using the sharepath or filesystem method do not support directory quotas.

For the full list of directory quota limitations, see Directory quotas.

Use cases

By default, when you mount a NAS volume in an ACK cluster, the storage value declared in the persistent volume claim (PVC) has no effect — the pod can access the full capacity of the NAS file system. If the NAS file system is shared across multiple applications, use directory quotas to:

Set a capacity limit per application subdirectory
Expand a subdirectory's quota online without interrupting running services
Improve resource utilization and control storage costs

Different NAS types have different capacity limits. For more information, see General-purpose NAS and Extreme NAS.

Prerequisites

Before you begin, ensure that you have:

The CSI plug-in installed in your cluster at version v1.18.8.45 or later. To upgrade, see Update csi-plugin and csi-provisioner
A General-purpose NAS file system with an NFS mount target. If not, create a General-purpose NAS file system
A mount target in the same VPC as your cluster nodes, with Status set to Active. If not, create a new mount target. For more information, see Manage mount targets

Use dynamically provisioned NAS volumes with directory quotas

Step 1: Create a StorageClass with directory quotas enabled

Save the following YAML as alicloud-nas-quota-sc.yaml. Replace the server value with the mount target address of your NAS file system.

To enable the directory quota feature, set allowVolumeExpansion or volumeCapacity to true. If allowVolumeExpansion is set to true, the volumeCapacity parameter does not take effect, and the directory quota feature remains enabled.

Parameter	Description
`volumeAs`	Must be `subpath`. Mounts a NAS subdirectory as a PV.
`server`	Mount target address of the NAS file system. See Manage mount targets.
`path`	NAS subdirectory to mount. Defaults to `/`. For Extreme NAS, must start with `/share`.
`volumeCapacity`	Set to `"true"` to enable directory quotas. If `allowVolumeExpansion` is `true`, this parameter has no effect but the quota remains enabled.
`allowVolumeExpansion`	Set to `true` to enable directory quotas and allow online PVC expansion. Available for General-purpose NAS only.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: alicloud-nas-quota-sc
mountOptions:
  - nolock,tcp,noresvport
  - vers=3
parameters:
  volumeAs: subpath         # Mount a subdirectory as a persistent volume (PV). Required for directory quotas.
  server: "0cd8b4a576-g****.cn-hangzhou.nas.aliyuncs.com"  # Mount target address
  archiveOnDelete: "false"
  path: "/test"             # Root subdirectory. Default: /. For Extreme NAS, must start with /share.
  volumeCapacity: "true"    # Enables the directory quota feature.
provisioner: nasplugin.csi.alibabacloud.com
reclaimPolicy: Delete
allowVolumeExpansion: true  # Allows online PVC expansion. When set to true, volumeCapacity has no effect but directory quotas remain enabled.

Key parameters: For all parameters, see Use dynamically provisioned NAS volumes.

Create the StorageClass.

kubectl apply -f alicloud-nas-quota-sc.yaml

Step 2: Deploy an application with a NAS volume

Save the following YAML as nas-sts.yaml. The StatefulSet below creates one pod with a dynamically provisioned NAS volume of 20 GiB, backed by the StorageClass with directory quotas enabled.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nas-sts
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        volumeMounts:
        - name: nas-pvc
          mountPath: /data
  volumeClaimTemplates:
  - metadata:
      name: nas-pvc
    spec:
      accessModes: [ "ReadWriteMany" ]
      storageClassName: "alicloud-nas-quota-sc"
      resources:
        requests:
          storage: 20Gi

Create the StatefulSet.
```
kubectl apply -f nas-sts.yaml
```

Verify that the pod is running.

kubectl get pod -l app=nginx

Expected output:

NAME          READY   STATUS    RESTARTS   AGE
nas-sts-0     1/1     Running   0          24s

Verify that the PV was created and the directory quota is active.
1. Check the PV.
```
kubectl get pv
```
  Expected output (the PV has a capacity of 20 GiB):
```
NAME                             CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                       STORAGECLASS            VOLUMEATTRIBUTESCLASS   REASON   AGE
nas-****-c72c-497f-ab13-******   20Gi       RWX            Delete           Bound    default/nas-pvc-nas-sts-0   alicloud-nas-quota-sc   <unset>                          15m
```
2. Confirm the directory quota in the NAS console. In the NAS console, go to the File System List page. In the Actions column of the target file system, click ![icon](https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/5892161761/p537429.png) > Quota Management. Click Manage Quotas to view the details. The directory quota is set to 20 GiB.

Verify the directory quota limit

Because the volume has a 20 GiB quota, writes beyond 20 GiB to the mounted directory trigger a Disk quota exceeded error.

Write 20,000 MiB (approximately 19.53 GiB) to the mounted directory /data.

kubectl exec -it nas-sts-0 -- dd if=/dev/zero of=/data/20G.txt bs=1M count=20000

Wait 5 to 15 minutes, then check the directory quota in the NAS console. In the NAS console, go to File System List. In the Actions column of the target file system, click ![icon](https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/5892161761/p537429.png) > Quota Management. Click Manage Quotas to view the current usage. The directory now shows approximately 19 GiB used.

Attempt to write another 1 GiB to exceed the quota.

kubectl exec -it nas-sts-0 -- dd if=/dev/zero of=/data/1G.txt bs=1M count=1024

The following error confirms the quota is enforced:

dd: closing output file '/data/1G.txt': Disk quota exceeded

Expand a dynamically provisioned NAS volume with directory quotas

Expand the volume by patching the PVC storage value. This operation does not interrupt running services.

Important

The quota of a NAS directory is measured in GiB. After you modify the PVC, the CSI plug-in adjusts the quota of the mounted NAS directory to the new volume capacity specified by the PVC. During the adjustment, the CSI plug-in rounds up the capacity value to the nearest integer.

Check the current PVC size.

kubectl get pvc

Expected output:

NAME                STATUS   VOLUME                           CAPACITY   ACCESS MODES   STORAGECLASS            VOLUMEATTRIBUTESCLASS   AGE
nas-pvc-nas-sts-0   Bound    nas-****-c72c-497f-ab13-******   20Gi       RWX            alicloud-nas-quota-sc   <unset>                 23m

Expand the PVC from 20 GiB to 30 GiB.

kubectl patch pvc nas-pvc-nas-sts-0 -p '{"spec":{"resources":{"requests":{"storage":"30Gi"}}}}'

Verify the expansion by checking the PV and PVC.

Check the PV.

kubectl get pv

Expected output (capacity is now 30 GiB):

NAME                             CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                       STORAGECLASS            VOLUMEATTRIBUTESCLASS   REASON   AGE
nas-****-c72c-497f-ab13-******   30Gi       RWX            Delete           Bound    default/nas-pvc-nas-sts-0   alicloud-nas-quota-sc   <unset>                          25m

Check the PVC.

kubectl get pvc

Expected output:

NAME                STATUS   VOLUME                           CAPACITY   ACCESS MODES   STORAGECLASS            VOLUMEATTRIBUTESCLASS   AGE
nas-pvc-nas-sts-0   Bound    nas-****-c72c-497f-ab13-******   30Gi       RWX            alicloud-nas-quota-sc   <unset>                 26m

Confirm the updated quota in the NAS console. In the NAS console, go to File System List. In the Actions column of the target file system, click ![icon](https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/5892161761/p537429.png) > Quota Management. Click Manage Quotas to confirm the directory quota is now 30 GiB.

FAQ

If you encounter issues when mounting or using NAS volumes, see:

What's next

For NAS directory quota details, see Directory quotas.
To monitor NAS volume capacity usage, use the node_volume_capacity_bytes_used metric and create an alert rule for a Prometheus instance.