Docs

Volcengine Kubernetes Engine

NFS access methods

Using dynamic FileNAS PVs

This topic describes how to create a dynamic PersistentVolume (PV) and PersistentVolumeClaim (PVC) based on FileNAS storage, and how a workload uses the PV.

Prerequisites

The csi-nas add-on has been installed. For details, see Installing add-ons.

A FileNAS file system and mount point have been created. For details, see Creating file systems and Managing mount points.

(Optional) The kubectl tool has already been installed locally, and the target cluster has been connected by using kubectl. For details, see Connecting to clusters.

Usage limits

StatefulSets require exclusive access to a volume and do not currently support manually created PVCs.

Creating through the console

Step 1: Create an SC

In the left navigation bar, click Cluster. Click the name of the target cluster to go to the cluster management page.

In the left navigation bar on the cluster management page, click Storage > StorageClass.

Click Create StorageClass and configure parameters on the page that appears.

Parameter	Description
Name	Specify a name for the StorageClass. The name must be unique within the cluster.
StorageClass type	Select a storage type. In this scenario, select FileNAS.
Availability zone	Availability Zones (AZs) are physically isolated infrastructure units within a single region, featuring independent power and networking systems. AZs communicate with each other over internal networks.
Billing type	Select a resource billing type as needed. Currently, pay-as-you-go is supported.
File system type	Choose a file system type. Extreme speed: This type is applicable to latency-sensitive Linux applications, for example, AI for small and medium-sized scenarios, file sharing, and DevOps code storage. Capacity type: This type is applicable to storage of frequently accessed data, for example, database backups, log storage, primary directories, and other general file sharing services. Cache type: [Beta] This type is applicable to scenarios where workloads use high-speed filesystem interfaces for data access, such as machine learning and high-performance computing (HPC). tip Cache-type FileNAS storage supported by VKE is a beta feature that does not require additional permissions for use. On the FileNAS side, cache-type storage is a beta feature that requires a trial application. To use this type of file system, you need to request permission to use FileNAS.
Project	Assign the StorageClass to a project so that you can perform operations such as maintenance and authorization at the project level. By default, the default project is selected. For details, see Project management.
Mount point	Select an existing mount point in the FileNAS file system.
Subdirectory	Enter a valid subdirectory that complies with the on-screen rules. By default, the root directory (/) is used. tip Ensure that the subdirectory already exists in FileNAS.
NFS version	Select an NFS version for the PV. If the file system type is Extreme speed, only the NFSv3 version is supported. If the file system type is Capacity, only the NFSv3 version is supported. If the file system type is Cache, only the NFSv4.1 version is supported.
Reclaim policy	The reclaim policy. Available options include: Delete: When you delete the PVC, the specified Delete policy applies. When the Delete policy is set to Delayed deletion, the PV and FileNAS data will be archived and will not be permanently deleted. When Delete policy is set to Delete now, the PV and FileNAS data will be actually deleted. Retain: When you delete the PVC, the PV and FileNAS data will not be deleted. If necessary, you can manually delete them. tip We recommend that you select Retain to prevent accidental data deletions.
PersistentVolume binding mode	The binding mode. The following information is included: Immediate: Performs PV binding and allocation when the PVC is created. WaitForFirstConsumer: Delays PV binding and allocation until a pod that uses the PVC is created.

Click Confirm.

Step 2: Create a PVC

In the left navigation bar on the cluster management page, click Storage > PersistentVolumeClaim.

Click Create PersistentVolumeClaim and configure parameters on the page that appears.

Parameter	Description
Namespace	Select the namespace to which the PVC belongs. We recommend selecting a custom namespace or the system-created default namespace. For details about namespaces, see Namespace overview.
Name	Specify a name for the PVC. The name must be unique within the cluster.
StorageClass type	Select a storage type. In this scenario, select FileNAS.
Access mode	Select a PVC access mode. Currently, you can select ReadWriteMany, which enables read and write access by multiple nodes.
Billing type	Select a resource billing type as needed. Currently, pay-as-you-go is supported.
File system type	Select the same file system type as the one configured in the StorageClass. Extreme speed: This type is applicable to latency-sensitive Linux applications, for example, AI for small and medium-sized scenarios, file sharing, and DevOps code storage. Capacity type: This type is applicable to storage of frequently accessed data, for example, database backups, log storage, primary directories, and other general file sharing services. Cache type: [Beta] This type is applicable to scenarios where workloads use high-speed filesystem interfaces for data access, such as machine learning and high-performance computing (HPC). tip Cache-type FileNAS storage supported by VKE is a beta feature that does not require additional permissions for use. On the FileNAS side, cache-type storage is a beta feature that requires a trial application. To use this type of file system, you need to request permission to use FileNAS.
How to create	The method of creating a PVC. Available methods include Create based on StorageClass and Use an existing PersistentVolume. For this example, select Create based on StorageClass.
StorageClass	Select a StorageClass. The system automatically binds a PV that has the same StorageClass and a capacity greater than or equal to the capacity size defined in the PVC.
Capacity	Configure the capacity of the PV. tip This is a required field in Kubernetes. However, the capacity value set here does not limit the actual usage by the application. The actual capacity depends only on the filesystem capacity.

Click Confirm.

tip

When the system dynamically creates a PV according to the resource declaration in the PVC, it will create a subdirectory at the associated FileNAS mount point. Subsequently, when a pod uses the PV, it will mount the subdirectory.

Step 3: Create an application and mount the PV

After the PV is created, add it to a workload that will use it. Supported workloads include Deployment, StatefulSet, Job, CronJob, and DaemonSet.

You can add a PV to a workload when creating it or updating it. For details, see Workloads.

Creating through kubectl

Step 1: Create an SC

Create a YAML file for the SC. The following vke-nas-sc.yaml file serves as an example:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: vke-nas-sc # StorageClass name.
provisioner: nas.csi.volcengine.com # (Required) The driver required for volume mounting. In this example, set the value to nas.csi.volcengine.com, which indicates the csi-nas add-on.
parameters:
fsType: Extreme # (Required) Filesystem type. Value: Extreme, Cache, and Capacity.
fsId: enas-cnbj1b9f32****** # (Optional) The ID of the FileNAS filesystem. This parameter is required only if fsType is set to Extreme. For other file system types, it must be left empty or omitted.
volumeAs: subpath # (Required) Subdirectory type. Value: subpath.
server: cnshbb***.3qda7dut***.nas.ivolces.com # (Required) The domain of the FileNAS file system mount point when you create a PV as a subdirectory.
subPath: /tmp # (Required) The subdirectory of the subpath-type FileNAS system after the mount operation. The csi-nas add-on creates directories in the subdirectory as the back-end storage of the dynamic PV.
archiveOnDelete: "true" # (Required) Whether to enable the delayed deletion policy. Valid values include true and false. true indicates that the PV and FileNAS data will be archived and not deleted. false indicates that the PV and FileNAS data will be deleted.
mountOptions:
- nolock,proto=tcp,noresvport
- vers=3 # Protocol version for mounting the data volume. Valid values include 3 and 4.1. The value 3 indicates NFSv3, which is applicable to the Extreme speed and Capacity types. The value 4.1 indicates NFSv4.1, which is the only version supported by the Cache type.
reclaimPolicy: Delete # PV reclaim policy. Value: Retain or Delete.
volumeBindingMode: Immediate # Volume binding mode. Values include Immediate (indicating immediate binding and allocation) and WaitForFirstConsumer (indicating delayed binding and allocation).

The key parameters are described in the following table.

Parameter	Description
provisioner	The driver for mounting a PV. In this example, you need to set the value to nas.csi.volcengine.com, which indicates the csi-nas add-on.
archiveOnDelete	Whether to synchronously delete PVs when the PVC is deleted. Valid values include: true: Delayed PV deletion. When the PVC is deleted, the FileNAS data will not be deleted synchronously. false: Immediate deletion. When the PVC is deleted, the FileNAS data will be deleted synchronously.
fsId	The ID of the created NFS filesystem. tip You can view the ID of the created filesystem in the console. For details, see Viewing filesystem information.
fsType	NFS filesystem type. Available values include Extreme, Cache, and Capacity. tip For a description of NFS filesystem types, see Product overview.
volumeAs	Specify the subdirectory type for NFS storage, including: subpath.
server	The domain of the FileNAS filesystem mount point. tip When volumeAs is set to subpath (creating a subdirectory in an existing filesystem), this field is required.
subpath	The subdirectory after FileNAS mounting. The system will create directories within this subdirectory as the backend storage for dynamically provisioned volumes.
volumeHandle	The unique identifier of the PV. Keep it consistent with the name of the PV.
mountOptions	Configure PV mount parameters, which support dynamic modification and only take effect on newly mounted PVs instead of those already mounted. You can use the vers parameter to specify the NFS version number for mounting the PV. Valid values: 3: Indicates NFSv3, which applies to the Extreme speed and Capacity. 4.1: Indicates NFSv4.1, which applies only to the Cache type.
reclaimPolicy	The PV reclaim policy. Valid values: Delete: When you delete the PVC, the PV and the data in the PV will be simultaneously deleted. Retain: When you delete the PVC, the PV and the data in the PV will not be simultaneously deleted. You need to manually delete them. warning We recommend that you select Retain to prevent accidental data deletions. Under the Delete policy, deleted data cannot be restored. Proceed with prudence when selecting the Delete policy.
volumeBindingMode	The binding mode of the PV. Values: Immediate: Performs PV binding and allocation when the PVC is created. WaitForFirstConsumer: Delays PV binding and allocation until a pod that uses the PVC is created.

Run the following command to create the StorageClass.

kubectl create -f vke-nas-sc.yaml

Step 2: Create a PVC

Create a YAML file for the PVC. The following vke-nas-pvc.yaml file serves as an example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: vke-nas-pvc # PVC name.
namespace: default # Namespace to which the PVC belongs.
spec:
accessModes: # PVC access mode. Currently, only ReadWriteMany is supported. ReadWriteMany allows read and write access from multiple nodes.
- ReadWriteMany
resources:
requests:
storage: 100Gi # The declared storage capacity. Unit: Gi.
storageClassName: vke-nas-sc # StorageClass name.
volumeMode: Filesystem # The PV type. Valid values: Filesystem (using the volume as a file system) or Block (using the volume as a block device).

The key parameters are described in the following table.

Parameter	Description
accessModes	The PVC access mode. You can only select ReadWriteMany, which enables read and write access by multiple nodes.
storage	The declared storage capacity. Unit: Gi.
storageClassName	The name of the created SC.
volumeMode	The PV types. Valid values: Filesystem: (Default) Use the PV as a file system. The PV will be formatted and mounted to a file system (such as ext4 and xfs), and the file system will be mounted to a specified path in the container. You can use the ls command (such as ls /data) in the container to view the mounted directories or files, and directly read and write files. Block: Use the volume as a block device. It is directly exposed to the container without being formatted or mounted to a file system. You can perform operations on the block device by using paths such as /dev/block/xxx, and applications must support read and write operations on the raw block device.

Run the following command to create the PVC.

kubectl create -f vke-nas-pvc.yaml

Run the following command to check whether the dynamic volume declared by the PVC has been created.

kubectl get pvc

The expected result is as follows:

NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
vke-nas-pvc Bound pvc-6318***-3d355a768220 100Gi RWX vke-nas-sc 5s

Step 3: Create an application and mount the PV

Create a YAML file for the Deployment. The following vke-dynamic-nas-deployment.yaml file serves as an example:

tip

To use Volcengine Container Instance (VCI), you need to add vke.volcengine.com/burst-to-vci: enforce to spec.template.metadata.annotations. VCI offers advantages including fully managed maintenance-free operation, pay-as-you-go pricing, and secure sandboxed container isolation. For a detailed introduction, see What is VCI?

apiVersion: apps/v1
kind: Deployment
metadata:
name: dynamic-nas-deploy
spec:
replicas: 1
selector:
matchLabels:
app: dynamic-nas-deploy
template:
metadata:
labels:
app: dynamic-nas-deploy
spec:
containers:
- image: doc-cn-beijing.cr.volces.com/vke/nginx-demo:v1.0
name: nginx
volumeMounts:
- mountPath: /tmp # The location where the FileNAS storage is mounted in the container.
name: nas-pv
volumes:
- name: nas-pv
persistentVolumeClaim:
claimName: vke-nas-pvc # The name of the created PVC.

Run the following command to create the Deployment.

kubectl create -f vke-dynamic-nas-deployment.yaml

Validating results

After creating a workload and mounting a PV to it as described in the preceding steps, you can verify the volume mounting status and persistent storage via the following methods.

Run the following command to check whether the PV is mounted to the specified path in the pod.

kubectl exec dynamic-nas-deploy-5fcd*** -- df | grep tmp

The expected response is as follows.

cnshb***.3qda7dut***.nas.ivolces.com:/tmp/pvc-6318d*** 10995116277760 0 10995116277760 0% /tmp

Check the mount path in the pod to view the data in the PV.

kubectl exec dynamic-nas-deploy-5fcd*** -- ls /tmp

The expected response is as follows.

lost+found

Write a file to the PV.

kubectl exec dynamic-nas-deploy-5fcd*** -- touch /tmp/test

Delete the pod.

kubectl delete pod dynamic-nas-deploy-5fcd***

Check the mount path of the PV in the newly created pod.

kubectl exec dynamic-nas-deploy-5fcd*** -- ls /tmp

The expected result is as follows. You can see that the file written to the PV still exists and is not deleted along with the pod. This indicates that persistent storage of data is achieved.

lost+found
test