This topic describes how to use EFS static volumes via the FSX client in VCI workloads.

Background

VCI supports connecting to Elastic File System (EFS) via the FSX protocol, serving as a high-availability POSIX (Portable Operating System Interface) 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.

For more information about the FSX client, see Introducing FSX clients.

Limits

When mounting EFS via FSX in VCI, please note the following usage restrictions:

Temporary token authentication is not supported.

StatefulSet workloads require a dedicated volume. Manually created PersistentVolumeClaims (PVCs) are currently not supported.

EFS volumes are only supported in certain regions. For details, see EFS regions and availability zones.

The FSX client currently only supports the x86_64 architecture and does not support Windows or macOS environments. For details, see Runtime environment.

Prerequisites

An EFS file system and access point have been created. For details, see Creating an EFS file system and Managing access points.

When operating with IAM identities (users or roles), you need to obtain the AK/SK required for creating keys, which are used for mounting EFS storage. For information on how to obtain account AK/SK, see API keys (access key and API key).

When using the kubectl command line, you need to install the kubectl tool locally in advance and connect to the target cluster via kubectl. For details, see Connecting to clusters using kubectl.

Procedure

Configure through the console

Use kubectl

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
Creation method	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	Access type for the PV. In this scenario, FSX is selected.
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 to finish.

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.
Creation method	Configure the method for creating a PVC. In this scenario, select Use an existing PersistentVolume.
PersistentVolume	Select the created PV for binding.

Click Confirm to finish.

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.

When the cluster is already connected, you can use EFS static PVs via the kubectl command line.

Step 1: (Optional) Create a policy

tip

If you use the AK and SK of the root user, you can skip this step.

For the steps to create a policy, see Creating custom policies. When mounting storage and performing corresponding operations with IAM identities, see Configuring access point policies for parameter configuration instructions and required permissions.

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

Step 2: Create a PV

Create a YAML file for the PV. The code of the example file vci-efs-fsx-static-pv.yaml is shown below.

apiVersion: v1
kind: PersistentVolume
metadata:
name: vci-efs-static-pv # The name of the PV.
spec:
capacity:
storage: 20Gi # PV capacity, used only for validation. This value has no practical significance.
accessModes:
- ReadWriteMany
csi:
driver: fsx.csi.volcengine.com # Driver type. In this example, it is fsx.csi.volcengine.com, indicating the csi-fsx add-on.
volumeHandle: vci-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 # PV type. It must be configured as efs.
server: ap-684b1***.cnshbe27***.3qda7dutskr***.cn-shanghai.efs.ivolces.com # EFS file system access point domain.
path: / # The subdirectory of the mounted file system.
accessKey: xxx # The Base64-encoded account AK. Replace the value with your actual information.
secretKey: xxx # The Base64-encoded SK that matches with the AK. Replace the value with your actual information.
mountOptions: rw # PV mount parameters. Currently supported: rw (default, read-write mount), ro (read-only mount), access_key_id (account AK), secret_access_key (account SK), enable_xattr (extended attributes).

Run the following command to create the PV.

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

Step 3: Create a PVC

Create a YAML file for the PVC. The code of the example file vci-efs-fsx-static-pvc.yaml is shown below.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: vci-efs-static-pvc # The name of the PVC.
namespace: default
spec:
accessModes:
- ReadWriteMany # PVC access mode. Currently, only ReadWriteMany is supported, indicating that it can be read and written by multiple nodes.
resources:
requests:
storage: 20Gi # The declared storage usage. It is only for validation. It must be consistent with the PV capacity configuration.
volumeMode: Filesystem # The PV type. In this example, enter "Filesystem", which indicates file storage.
volumeName: vci-efs-static-pv # The name of the PV bound to this PVC.

Run the following command to create the PVC.

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

Run the following command to view the static binding result of 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
vci-efs-fsx-static-pvc Bound vci-efs-fsx-static-pv 20Gi RWX 33s

Step 4: Create an application and mount the PV

Create a YAML file for the Deployment. The code of the example file vci-efs-fsx-static-deployment.yaml is shown below.

apiVersion: apps/v1
kind: Deployment
metadata:
name: vci-efs-static-deployment # The Deployment name.
namespace: default # The namespace of the Deployment.
labels:
app: nginx
spec:
replicas: 1
selector:
matchLabels:
app: vci-efs-static-deployment
template:
metadata:
labels:
app: vci-efs-static-deployment
spec:
containers:
- image: doc-cn-beijing.cr.volces.com/vke/nginx-demo:v1.0 # The address and version of the container image. Replace the value with your actual information. If you need to use a public image, make sure that the cluster can access the public network.
imagePullPolicy: IfNotPresent
name: nginx
volumeMounts:
- mountPath: /tmp # The mount path of EFS within the container.
name: fsx-pv
volumes:
- name: fsx-pv
persistentVolumeClaim:
claimName: vci-efs-static-pvc # The name of the PVC that has been created.

Run the following command to create the Deployment.

kubectl create -f vci-efs-fsx-static-deployment.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.

The target cluster has been connected by using kubectl. For details, see Connecting to clusters using kubectl.

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

kubectl exec vci-efs-static-deployment-xxx -- df | grep tmp

The expected response is as follows.

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

Execute the following command to view the mount path in the pod, i.e., to view the data in the volume.

kubectl exec vci-fsx-static-deployment-xxx -- ls /tmp

The expected response is as follows.

lost+found

Execute the following command to write a file into the PersistentVolume (PV).

kubectl exec vci-fsx-static-deployment-xxx -- touch /tmp/test

Execute the following command to delete the pod.

kubectl delete pod vci-fsx-static-deployment-xxx

Execute the following command to view the PV mount path under the newly created pod.

kubectl exec vci-fsx-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