The FSX client is a high‑availability POSIX file system client that is integrated with EFS. It can mount EFS to a Linux system and use it as a local file system. This topic describes how to create, mount, and verify dynamic EFS PVs by using the FSX client.

Prerequisites

The csi-fsx add-on has been installed and upgraded to v1.1.0 or later. For details, see csi-fsx.

The fsxset-controller add-on has been installed. For details, see fsxset-controller.

An EFS file system and access point have been created. For details, see Creating an EFS file system and Managing access 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 a cluster.

Usage limits

StatefulSets require exclusive access to a volume, and do not support a manually created PVC.

EFS PVs are only available in some regions. For details, see Regions and availability zones.

The FSX client currently supports only the x86_64 architecture. The client is currently not available on Windows and macOS. For details about supported environments, see Supported environments.

This feature is unavailable in clusters running on Kubernetes v1.20 and earlier.

If you use clusters running on Kubernetes v1.26.x, you cannot use Secrets whose names contain periods (.). Otherwise, the PV will fail to be created.

Configure through the console

Step 1: Create a StorageClass

Log in to the VKE console.

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 the storage type. In this scenario, select EFS.
Access type	Select an access type for the PV. In this scenario, select FSX.
Availability zone	AZs refer to physical areas isolated from each other in terms of electricity and network in the same region. AZs communicate with each other over internal networks.
Billing type	The billing method for resources. Pay-as-you-go is supported.
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.
Access point	Select the created EFS file system and access point.
Mount path	Configure the file system mount path. The system will create subdirectories for dynamic PVs under this directory. Make sure that the entered mount path already exists. By default, the root directory (/) is used.
PersistentVolume binding mode	Select a PV binding mode. Immediate: The PV is bound and allocated immediately after the PVC is created, without waiting for Pod scheduling. In this mode, storage resources are provisioned in advance, which can accelerate application startup. WaitForFirstConsumer: Delays PV binding and allocation until a pod that uses the PVC is scheduled to the node. The PV is then provisioned and bound in the availability zone of the node.
Advanced settings
Mount parameters	Specify PV mount parameters, which support dynamic modification and only take effect on newly mounted disks instead of those already mounted. For details, see Specifying mount parameters.

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 EFS.
Access mode	Select a PVC access mode. You can select ReadWriteMany, which enables read and write access by multiple nodes.
Creation method	Configure the method for creating a PVC. In this scenario, select Create based on StorageClass.
StorageClass	Select the created SC.
Capacity	Configure the PV capacity in Gi.

Click Confirm.

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.

Use kubectl

Step 1: (Optional) Create a policy

For the steps of creating a policy, see Creating custom policies. An Identity and Access Management (IAM) user must have the required permissions to mount storage. For a list of required permissions, see Configuring access point policies.

The following is a JSON example for creating an EFS policy:

Step 2: Create a StorageClass

Create a YAML file for the SC. The following efs-sc-demo.yaml file functions as an example:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: efs-sc-demo # StorageClass name.
provisioner: fsx.csi.volcengine.com # (Required) The driver required for volume mounting. In this example, set the value to fsx.csi.volcengine.com, which indicates the csi-fsx add-on.
parameters:
type: efs # (Required) The file system type. In this example, set the value to efs to specify EFS.
fsid: efs-cnbja5*** # (Required) The ID of the EFS file system.
server: ap-df81***.cnbja5ef96***.3pspvsoy8hyps***.cn-beijing.efs.ivolces.com # (Required) The ID and domain of the EFS file system access point.
subpath: / # (Required) The mount path of EFS. The system will create subdirectories for dynamic PVs under this directory.
mountOptions: # (Optional) The PV mount parameters.
- enable_xattr=true
reclaimPolicy: Retain # (Optional) The PV reclaim policy. Valid value: Retain.
volumeBindingMode: Immediate # (Optional) The PV 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 required for PV mount. In this topic, you need to set the value to fsx.csi.volcengine.com, which indicates the csi-fsx add-on.
type	The file system type. In this example, set the value to efs to specify EFS.
fsid	The ID of the created EFS file system. tip You can view the ID of the created file system in the console. For details, see Viewing file system information.
server	The ID and domain name of the access point that has been created in the EFS file system, such as ap-df81*.cnbja5ef.3pspvsoy8hy**.cn-beijing.efs.ivolces.com.
subpath	The mount path of EFS. The system will create subdirectories for dynamic PVs under this directory. Make sure that the entered mount path already exists. By default, the root directory (/) is used.
mountOptions	Configure PV mount parameters, which support dynamic modification and only take effect on newly mounted PVs instead of those already mounted. For details, see Specifying mount parameters.
reclaimPolicy	The PV reclaim policy. Only Retain is supported. It indicates that when you delete the PVC, the PV and the data in the PV will not be simultaneously deleted. You need to manually delete them.
volumeBindingMode	The binding mode of the PV. Values: Immediate: (Default) The PV is bound and allocated immediately after the PVC is created, without waiting for Pod scheduling. In this mode, storage resources are provisioned in advance, which can accelerate application startup. WaitForFirstConsumer: Delays PV binding and allocation until a pod that uses the PVC is scheduled to the node. The PV is then provisioned and bound in the availability zone of the node.

Run the following command to create the StorageClass.

kubectl create -f efs-sc-demo.yaml

Step 3: Create a PVC

Create a YAML file for the PVC. The following efs-pvc-demo.yaml file functions as an example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: efs-pvc-demo # 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: efs-sc-demo # 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 in Gi. The value is an integer within the range of 1 to 16384.
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 efs-pvc-demo.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
efs-pvc-demo Bound pvc-6318***-3d355a768220 100Gi RWX vke-efs-sc 5s

Step 4: Create an application and mount the PV

Create a YAML file for the Deployment. The following efs-deployment-demo.yaml file functions as an example:

apiVersion: apps/v1
kind: Deployment
metadata:
name: efs-deployment-demo
spec:
replicas: 1
selector:
matchLabels:
app: efs-deployment-demo
template:
metadata:
labels:
app: efs-deployment-demo
spec:
containers:
- image: doc-cn-beijing.cr.volces.com/vke/nginx-demo:v1.0
name: nginx
volumeMounts:
- mountPath: /tmp # The mount location of the EFS PV in the container.
name: efs-pv
volumes:
- name: efs-pv
persistentVolumeClaim:
claimName: efs-pvc-demo # The name of the created PVC.

Run the following command to create the Deployment.

kubectl create -f efs-deployment-demo.yaml

Validate 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 efs-deployment-demo-665769f*** -- df | grep tmp

The expected response is as follows.

BFBC9***:ap-df81***.cnbja5***.3pspvsoy8hy***.cn-beijing.efs.ivolces.com:/pvc-bde228f9-6*** 10995116277760 0 10995116277760 0% /tmp

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

kubectl exec efs-deployment-demo-665769f*** -- ls /tmp

The expected response is as follows.

lost+found

Write a file to the PV.

kubectl exec efs-deployment-demo-665769f*** -- touch /tmp/test

Delete the pod.

kubectl delete pod efs-deployment-demo-665769f***

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

kubectl exec efs-deployment-demo-665769f*** -- 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

Volcengine Kubernetes Engine