FSX 客户端是对接弹性文件存储（EFS）的高可用 POSIX 文件系统客户端，可将 EFS 挂载到 Linux 系统并作为本地文件系统使用。本文介绍如何通过 FSX 客户端创建、挂载并验证 EFS 动态存储卷。 ## 前提条件 * 已安装 csi\-fsx 组件，并升级至 v1.1.0 及以上版本。详情请参见 [csi-fsx](https://www.volcengine.com/docs/6460/2276735)。 * 已安装 fsxset\-controller 组件。详情请参见 [fsxset-controller](https://www.volcengine.com/docs/6460/2309812)。 * 已创建 EFS 文件系统和接入点，详情请参见 [创建文件系统](https://www.volcengine.com/docs/6453/1655296)、[管理接入点](https://www.volcengine.com/docs/6453/1783362)。 * （可选）已在本地安装 kubectl 工具，并通过 kubectl 连接目标集群。详情请参见 [连接集群](https://www.volcengine.com/docs/6460/100942)。 ## 使用限制 * 有状态负载需要独占一个卷，暂不支持使用手动创建的存储卷声明。 * EFS 存储卷仅支持部分地域。详情请参见 [地域和可用区](https://www.volcengine.com/docs/6453/1785202)。 * FSX 客户端当前仅支持 x86_64 的体系结构，暂不支持在 Windows 和 macOS 环境使用。详情请参见 [运行环境](https://www.volcengine.com/docs/6349/1404012)。 * 暂不支持 Kubernetes v1.20 及以下版本的集群使用。 * 若使用 Kubernetes v1.26.x 版本集群，禁止使用名称中带符号`.`的 Secret 密钥，否则会导致 PV 创建失败。 ## 通过控制台配置 ### 步骤一：创建存储类（StorageClass） 1. 登录 [容器服务控制台](https://console.volcengine.com/vke)。 2. 在左侧导航栏中，选择 **集群**。单击目标集群名称，进入集群管理页面。 3. 在集群管理页面左侧导航栏中，选择 **存储管理 \> 存储类**。 4. 单击 **创建存储类**，在弹出的配置页面中，完成参数配置。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ff3ed1c76c5d026368bab16476f5ea57.png) |**配置项** |**说明** | |---|---| |名称 |自定义存储类名称，需确保存储类名称在集群内唯一。 | |存储类型 |选择存储类型，本场景选择 **弹性文件存储**。 | |访问类型 |存储卷的访问类型，本场景选择 **FSX**。 | |可用区 |可用区是同一地域下电力、网络隔离的物理区域，可用区之间内网互通，不同可用区之间物理隔离。 | |计费类型 |选择资源计费类型，目前支持 **按量计费**。 | |项目 |为存储类指定所属项目，从项目维度管理集群资源的运维、授权等操作。默认选择 **default（默认项目）** 。详情请参见 [项目管理](https://www.volcengine.com/docs/6460/661241)。 | |接入点 |选择已创建的 EFS 文件系统和接入点。 | |挂载路径 |配置文件系统挂载路径，系统会在该目录下，创建动态卷的子目录。需要保证输入待挂载路径已存在。默认为根目录`/`。 | |存储卷模式绑定 |存储卷绑定模式。包括：

* **Immediate**：存储卷声明创建完成后，直接完成存储卷的绑定和分配，无需等待 Pod 调度。该模式下存储资源可提前就绪，能够提高业务的启动速度。但若存储卷制备的可用区与 Pod 最终调度节点所在的可用区不一致，将导致挂载失败。

* **WaitForFirstConsumer**：延迟存储卷的绑定和分配，直到使用该存储卷声明的 Pod 被调度到节点后，再在该节点所在可用区完成存储卷的制备和绑定。该模式下可避免跨可用区挂载失败的问题，但业务启动速度稍慢。 | |**高级配置** || |挂载参数 |配置存储卷挂载参数，支持动态修改，仅对新挂载的盘生效，对已挂载的盘不生效。详情请参见 [配置挂载参数](https://www.volcengine.com/docs/6460/2165061)。 | 5. 单击 **确定**，完成配置。 ### 步骤二：创建存储卷声明（PVC） 1. 在集群管理页面左侧导航栏中，选择 **存储管理 \> 存储卷声明**。 2. 单击 **创建存储卷声明**，在弹出的配置页面中，完成参数配置。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d5be02020fe79214456c216764679996.png) |**配置项** |**说明** | |---|---| |命名空间 |选择存储卷声明所属的命名空间。建议选择您自定义的命名空间，或系统默认创建的 **default** 命名空间。命名空间相关介绍，请参见 [命名空间概述](https://www.volcengine.com/docs/6460/100958)。 | |名称 |根据系统提示自定义存储卷声明的名称，需确保存储卷声明名称在集群内唯一。 | |存储类型 |选择存储类型，本场景选择 **弹性文件存储**。 | |访问模式 |选择存储卷声明的访问方式，目前支持 **ReadWriteMany** ，表示多点读写。 | |创建方式 |存储卷声明的创建方式，本场景选择 **基于存储类创建**。 | |存储类 |选择已创建的存储类。 | |容量 |配置存储卷容量，单位为 Gi，取值范围为 1～10485760。

说明

该配置为 Kubernetes 必配字段，但此处设置的容量值不会限制应用实际使用量，实际容量仅跟文件系统容量有关。

| 3. 单击 **确定**，完成配置。 ### 步骤三：创建应用并挂载存储卷文件存储类型的动态存储卷创建完成后，可通过添加卷的方式挂载到工作负载使用，包括：无状态负载、有状态负载、任务、定时任务、守护进程。可通过创建工作负载或更新工作负载操作的容器配置步骤，为工作负载添加卷并挂载卷。详细操作，请参见 [工作负载](https://www.volcengine.com/docs/6460/100965?lang=zh)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_42435ba5f4fcd2e118a3ede715ff8550.png) ## 通过 kubectl 命令行配置 ### 步骤一：（可选）创建策略

说明

若使用主账号 AK/SK，可跳过此步骤。

如需实现动态刷新临时 Token 的逻辑，参考 AssumeRole 接口。

创建策略的操作步骤参见 [新建自定义策略](https://www.volcengine.com/docs/6257/1158323)。其中，使用 IAM 用户挂载存储并执行相应操作时，所需的权限参见 [配置接入点策略](https://www.volcengine.com/docs/6453/1783376)。创建 EFS 策略的 JSON 示例如下： ```JSON { "Statement": [ { "Effect": "Allow", "Action": [ "efs:ClientMount", "efs:ClientWrite", "efs:ClientRootAccess" ], "Resource": ["trn:efs:::filesystem/"], "Condition": { "StringEquals": { "volc:RequestTag/accesspoint": "<接入点 ID>" } } }, { "Effect": "Allow", "Action": [ "efs:VerifyAccessPoint", "efs:DescribeAccessPoints", "efs:CreateAccessPoint", "efs:ModifyAccessPoint", "efs:DeleteAccessPoint" ], "Resource": [ "*" ] } ] } ``` ### 步骤二：创建存储类（StorageClass） 1. 创建 StorageClass 的 YAML 文件。示例文件`efs-sc-demo.yaml`代码如下： ```YAML apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: efs-sc-demo # 存储类名称 provisioner: fsx.csi.volcengine.com # 必填，存储挂载依赖的驱动，本示例为 fsx.csi.volcengine.com，表示 csi-fsx 插件 parameters: type: efs # 必填，文件系统类型，本文中取值为 efs，表示使用弹性文件存储 fsid: efs-cnbja5*** # 必填，EFS 文件系统 ID server: ap-df81***.cnbja5ef96***.3pspvsoy8hyps***.cn-beijing.efs.ivolces.com # 必填，EFS 文件系统的接入点 ID + 接入点域名 subpath: / # 必填，EFS 挂载路径，系统会在该目录下，创建动态卷的子目录 mountOptions: # 非必填，存储卷挂载参数 - enable_xattr=true reclaimPolicy: Retain # 非必填，存储卷回收策略。取值：Retain（保留策略） volumeBindingMode: Immediate # 非必填，存储卷绑定模式，取值：Immediate（立即绑定和分配），WaitForFirstConsumer（延迟存储卷的绑定和分配） ``` 关键参数说明，如下表所示。 |参数 |说明 | |---|---| |provisioner |存储卷挂载依赖的驱动，本文中需要配置为`fsx.csi.volcengine.com`，表示 csi\-fsx 插件。 | |type |文件系统类型，本文中取值为`efs`，表示使用弹性文件存储。 | |fsid |已创建的 EFS 文件系统 ID。

说明

您可以在文件存储控制台，查看已创建的文件系统 ID。详情请参见查看文件系统。

| |server |EFS 文件系统中，已创建的接入点 ID + 接入点域名，例如`ap-df81***.cnbja5ef***.3pspvsoy8hy***.cn-beijing.efs.ivolces.com`。 | |subpath |EFS 挂载路径，系统会在该目录下，创建动态卷的子目录。需要保证输入待挂载路径已存在。默认为根目录`/`。 | |mountOptions |存储卷挂载参数，支持动态修改，仅对新挂载的存储卷生效，对已挂载的存储卷不生效。详情请参见 [配置挂载参数](https://www.volcengine.com/docs/6460/2165061)。 | |reclaimPolicy |存储卷回收策略。仅支持 **Retain**，即删除 PVC 时，不会同步删除 PV 以及 PV 中的数据，需要您手动删除。 | |volumeBindingMode |存储卷的绑定模式。取值：

* **Immediate**：（默认值）存储卷声明创建完成后，直接完成存储卷的绑定和分配，无需等待 Pod 调度。该模式下存储资源可提前就绪，能够提高业务的启动速度。但若存储卷制备的可用区与 Pod 最终调度节点所在的可用区不一致，将导致挂载失败。

* **WaitForFirstConsumer**：延迟存储卷的绑定和分配，直到使用该存储卷声明的 Pod 被调度到节点后，再在该节点所在可用区完成存储卷的制备和绑定。该模式下可避免跨可用区挂载失败的问题，但业务启动速度稍慢。 | 2. 执行以下命令，创建 StorageClass。 ```Bash kubectl create -f efs-sc-demo.yaml ``` ### 步骤三：创建存储卷声明（PVC） 1. 创建 PVC 的 YAML 文件。示例文件`efs-pvc-demo.yaml`代码如下： ```YAML apiVersion: v1 kind: PersistentVolumeClaim metadata: name: efs-pvc-demo # 存储卷声明名称 namespace: default # 存储卷声明所属命名空间 spec: accessModes: # 存储卷声明访问模式。目前仅支持 ReadWriteMany，表示多点读写 - ReadWriteMany resources: requests: storage: 100Gi # 声明的存储使用量，单位为 Gi storageClassName: efs-sc-demo # 已创建的存储类名称 volumeMode: Filesystem # 存储卷类型，取值：Filesystem（将存储卷作为文件系统使用）、Block（将存储卷作为块设备使用） ``` 关键参数说明，如下表所示。 |参数 |说明 | |---|---| |accessModes |存储卷声明的访问方式，仅支持 ReadWriteMany，表示多点读写。 | |storage |存储卷容量，单位为 Gi，整数形式，取值范围为 1～1~10485760。

说明

该字段为 Kubernetes 必填字段，但此处设置的容量值不会限制应用实际使用量，实际容量仅跟文件系统容量有关。

| |storageClassName |已创建的存储类名称。 | |volumeMode |存储卷类型，包括：

* **Filesystem**：（默认值）将存储卷作为文件系统使用。存储卷会被格式化并挂载一个文件系统（如 ext4、xfs），再将该文件系统挂载到容器指定路径。您可以在容器中使用`ls`命令（例如`ls /data`）能查看挂载的目录或文件，并可以直接读写文件。

* **Block**：将卷作为块设备使用。直接暴露给容器，不格式化、不挂载文件系统。您可以通过`/dev/block/xxx `类似的路径操作块设备，应用需支持裸块设备读写。 | 2. 执行以下命令，创建 PVC。 ```Bash kubectl create -f efs-pvc-demo.yaml ``` 3. 执行以下命令，查看 PVC 声明的动态卷是否创建成功。 ```Bash kubectl get pvc ``` 预期输出结果如下： ```Bash NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE efs-pvc-demo Bound pvc-6318***-3d355a768220 100Gi RWX vke-efs-sc 5s ``` ### 步骤四：创建应用并挂载存储卷 1. 创建 Deployment 的 YAML 文件。示例文件`efs-deployment-demo.yaml`代码如下： ```YAML 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 # EFS 存储卷在容器中的挂载位置 name: efs-pv volumes: - name: efs-pv persistentVolumeClaim: claimName: efs-pvc-demo # 已创建的 PVC 名称 ``` 2. 执行以下命令，创建 Deployment。 ```Bash kubectl create -f efs-deployment-demo.yaml ``` ## 结果验证按照上文示例创建工作负载并挂载存储卷后，您可以通过以下方式验证存储卷的挂载和持久化存储。

说明

执行命令时，请注意将下文中的efs-deployment-demo-665769f***替换为为您集群中业务 Pod 的实际值。

1. 执行以下命令，查看存储卷是否正确挂载到 Pod 的指定路径。 ```Bash kubectl exec efs-deployment-demo-665769f*** -- df | grep tmp ``` 预期返回结果如下。 ```Bash BFBC9***:ap-df81***.cnbja5***.3pspvsoy8hy***.cn-beijing.efs.ivolces.com:/pvc-bde228f9-6*** 10995116277760 0 10995116277760 0% /tmp ``` 2. 查看 Pod 中的挂载路径，即查看存储卷中的数据。 ```Bash kubectl exec efs-deployment-demo-665769f*** -- ls /tmp ``` 预期返回结果如下。 ```Bash lost+found ``` 3. 在存储卷中写入文件。 ```Bash kubectl exec efs-deployment-demo-665769f*** -- touch /tmp/test ``` 4. 删除 Pod。 ```Bash kubectl delete pod efs-deployment-demo-665769f*** ``` 5. 查看新创建 Pod 下的存储卷挂载路径。 ```Bash kubectl exec efs-deployment-demo-665769f*** -- ls /tmp ``` 预期返回如下，可以看到存储卷中写入的文件依然存在，未随着 Pod 的删除而被删除，实现了数据的持久化存储。 ```Bash lost+found test ```