FSX can be integrated with Elastic File Storage (EFS) and serves as a high-availability, POSIX-compliant file system client for EFS. Through this client, EFS storage can be mounted to a Linux system, enabling the storage to function as a local file system on the Linux system for data storage and management. This topic introduces how to use static EFS PersistentVolumes (PV) by using the FSX client.

Prerequisites

The csi-fsx and fsx-service add-ons have been installed and upgraded to the latest version. For details, see Upgrading add-ons.

An EFS filesystem and mount point have been created. For details, see Creating an EFS filesystem and Managing mount points.

(Optional) You have obtained the AK/SK required for creating a key. This key will be used to mount EFS storage. For information about how to get the AK and SK, see Obtaining API access keys. To use a temporary token for authentication, you need to implement the logic for refreshing tokens.

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

Usage limits

To use a temporary token for authentication, you need to implement the logic for refreshing tokens.

StatefulSets require exclusive access to a volume, and do not support a manually created PersistentVolumeClaim (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.

Creating through the console

Step 1: Create a PV

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 > PersistentVolume.

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

Parameter	Description
How to create	Select a method for creating the PV. Currently, you can select Static creation.
Name	Specify a name for the PV. The name must be unique within the cluster.
StorageClass type	Select a PV type. In this scenario, select EFS.
Access type	Select an access type for the PV. Valid values: FSX and NFS. In this scenario, select FSX. warning FSX-based access currently supports only Elastic Compute Service (ECS). It does not support VCI. FSX-based access delivers better performance and higher availability, and will gradually replace NFS.
Access mode	Select a PV access mode. Currently, you can select ReadWriteMany, which enables read and write access by multiple nodes.
Project	Assign the PV 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 an access point that exists under a created EFS file system and is in the same VPC as the cluster.
Mount path	Enter a valid subdirectory that complies with the on-screen rules. The default directory is the root directory, which is represented by /. tip Ensure that the subdirectory already exists in EFS.

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 the 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.
Billing type	Select a resource billing type as needed. Currently, only Pay-as-you-go is supported.
How to create	Configure the method for creating a PVC. In this scenario, select Use an existing PersistentVolume.
PersistentVolume	Select the created PV for binding.

Click Confirm.

Step 3: Create an application and mount the PV

After the EFS PV is created, add the PV to a workload that will use the PV. 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

If you connect to the cluster, you can use a static EFS PV by using 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 Secret

Create a YAML document for the Secret. The following vke-efs-fsx-secret.yaml file serves as an example:

apiVersion: v1
data:
AccessKeyId: ${ak} # The Base64-encoded account AK. Replace the value with your actual information.
SecretAccessKey: ${sk} # The Base64-encoded SK that matches with the AK. Replace the value with your actual information.
ExpiredTime: ${Temporary Token expiration time} # The Base64-encoded expiration time of the temporary token. If you use an AK and SK, do not specify this field.
SessionToken: ${Temporary Token content} # The Base64-encoded content of the temporary token. If you use an AK and SK, do not specify this field.
kind: Secret
metadata:
name: efs-fsx-key # The name of the Secret. If the cluster version is 1.26.x, the name cannot contain the . character. Other cluster versions do not have this limit.
namespace: default
type: Opaque

Run the following command to create the Secret.

kubectl create -f vke-efs-fsx-secret.yaml

Step 3: Create a PV

Create a YAML document for the PV. The following vke-efs-fsx-static-pv.yaml file serves as an example:

apiVersion: v1
kind: PersistentVolume
metadata:
name: vke-efs-static-pv
spec:
capacity:
storage: 20Gi # The PV capacity, which is only used for validation.
accessModes:
- ReadWriteMany
csi:
driver: fsx.csi.volcengine.com # The driver type. This example uses fsx.csi.volcengine.com, which indicates the csi-fsx add-on.
volumeHandle: vke-efs-static-pv # The unique identifier of the PV. Keep it consistent with the PV name. To use multiple PVs simultaneously, the value for each PV must be different.
volumeAttributes:
type: efs # The PV type, which needs to be set to efs.
server: ap-684b1***.cnshbe27***.3qda7dutskr***.cn-shanghai.efs.ivolces.com # The domain name of the access point for the EFS file system.
path: / # The subdirectory of the file system for mounting.
secretName: efs-fsx-key # The Secret. It is required if the IAM policy is enabled.
secretNamespace: default # Namespace of the Secret. It is required if the IAM policy is enabled.

Run the following command to create the PV.

kubectl create -f vke-efs-fsx-static-pv.yaml

Step 4: Create a PVC

Create a YAML document for the PVC. The following vke-efs-fsx-static-pvc.yaml file serves as an example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: vke-efs-static-pvc # The name of the PVC.
namespace: default
spec:
accessModes:
- ReadWriteMany # PVC access mode. Currently, only ReadWriteMany is supported. ReadWriteMany allows read and write access from multiple nodes.
resources:
requests:
storage: 20Gi # The declared storage usage, which needs to be consistent with the specified capacity of the PV and only used for verification.
volumeMode: Filesystem # The PV type. In this example, enter Filesystem, which indicates file storage.
volumeName: vke-efs-static-pv # The name of the PV bound to this PVC.

Run the following command to create the PVC.

kubectl create -f vke-efs-fsx-static-pvc.yaml

Run the following command to view the result of the static association between the PVC and PV.

kubectl get pvc

If the response is similar to the following one, the binding is successful.

NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
vke-efs-fsx-static-pvc Bound vke-efs-fsx-static-pv 20Gi RWX 33s

Step 5: Create an application and mount the PV

Create a YAML document for the Deployment. The following vke-efs-fsx-static-deployment.yaml file serves as an example:

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

Run the following command to create the Deployment.

kubectl create -f vke-efs-fsx-static-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 vke-efs-static-deployment-xxx -- df | grep tmp

The expected response is as follows.

cnshbe27***.3qda7dutskr***.efs.ivolces.com:/ 10995116277760 0 10995116277760 0% /tmp

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

kubectl exec vke-nas-static-deployment-xxx -- ls /tmp

The expected response is as follows.

lost+found

Write a file to the PV.

kubectl exec vke-nas-static-deployment-xxx -- touch /tmp/test

Delete the pod.

kubectl delete pod vke-nas-static-deployment-xxx

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

kubectl exec vke-nas-static-deployment-xxx -- 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