容器服务支持通过 CSI 使用 vePFS 文件存储，本文为您介绍如何创建 vePFS 文件存储类型的存储卷和存储卷声明，以及工作负载如何使用 vePFS 文件存储动态存储卷。 > **说明** > 【[**邀测·申请试用**](https://www.volcengine.com/docs/6460/145623)】通过 vePFS Client 使用 vePFS 存储卷目前均处于邀测阶段，如需使用，请提交申请。 ## 前提条件 * 已安装 csi\-vepfs 组件，详情请参见 [csi-vepfs](https://docs.volcengine.com/docs/vke/csi-vepfs-add-on?lang=zh)。 * 已创建 vePFS 文件系统和挂载服务，并将挂载服务绑定到文件系统。详情请参见 [创建文件系统](https://www.volcengine.com/docs/6645/101615)、[创建挂载服务](https://www.volcengine.com/docs/6645/1108519)、[绑定文件系统](https://www.volcengine.com/docs/6645/1113976)。 * （可选）已在本地安装 kubectl 工具。详细操作参见 [安装和设置 kubectl](https://kubernetes.io/docs/tasks/tools/)。 ## 使用限制 ### 部署兼容性限制 * 同一个 vePFS 挂载服务不能同时用于 vePFS CSI 方案和主机预挂载方案。如果您已通过 VKE 节点预挂载 vePFS 并以 hostPath 方式供 Pod 使用，且还需使用 vePFS CSI 方案，请为 CSI 方案单独创建一个新的 vePFS 挂载服务。 * 通过 CSI 使用 vePFS 文件存储的方案与通过 vePFS\-Manager 组件使用 vePFS 的方案不能同时使用。因此，建议创建新集群使用 CSI 方案，若存量资源需要迁移最新 CSI 方案，请 [提交工单](https://console.volcengine.com/workorder/create?step=3&SubProductID=P00000210&FlowKey=SBfYPjaXlAXUeQCmmguw) 获取技术支持。 * vePFS CSI controller 会被优先调度到拥有标签`vepfs.csi.volcengine.com/controller=preferred`的节点，如果计划对 VKE 集群节点池进行频繁扩缩容，建议 CSI controller 优先调度到常驻节点（不受扩缩容影响），以保证 vePFS CSI 可以快速及时地处理 VKE 集群和 vePFS 集群的成员一致性。否则，运行 vePFS CSI controller 的节点被缩容删除时，vePFS CSI controller 可能无法维持 VKE 和 vePFS 集群间的成员一致性，导致 vePFS CSI 后续的操作缓慢。 * 已经以 VPC 网络加入到 vePFS 集群中的节点将无法使用 RDMA 网络。如果要切换成 RDMA 网络，请将 VKE 节点从 vePFS 文件系统集群中删除。 ### 组件相关限制 * 卸载 csi\-vepfs 组件不会中断正在运行的 Pod 对 vePFS 存储的访问，Pod 将持续运行至正常结束。但卸载后若尝试删除 Pod，删除操作将被阻塞，需重新安装 csi\-vepfs 后方可继续。因此，建议在所有使用 vePFS 存储的 Pod 停止运行后，再执行组件卸载操作。 * csi\-vepfs 组件会在每个节点上以独立容器运行 vePFS 文件系统客户端，默认占用 4 CPU 和 4 GiB 内存。若节点可用资源不足，客户端容器将无法启动，依赖 vePFS 存储的 Pod 也将因此阻塞在创建阶段。 * 提前删除 vePFS 挂载服务，将导致 csi\-vepfs 组件无法卸载。 * csi\-vepfs 组件删除后，部分资源无法确认能否被删除，可能构成资源残留。 * **vePFS mount service secret**：创建 vePFS PV 时，VKE 将一起创建一个 Secret，其中保存了 vePFS 挂载服务三个管理节点的地址和登录密钥，可通过以下命令查询 VKE 集群中存在的上述 Secret。 ```Bash kubectl get -n kube-system secrets | grep "^vepfs-secret-mount-[0-9a-z]*" ``` * **VKE 节点上的安全组**：为了保证 VKE 节点能够与 vePFS 文件系统集群互通，vePFS CSI 会同时将管理服务 ECS 的安全组添加到 VKE 节点的安全组列表中。但 CSI 卸载的过程中无法确定该安全组是否仍被用户使用，所以无法将它从 VKE 节点中解绑，用户可以通过 ECS 控制台，在安全组选项中查看或删除与 vePFS 挂载服务所属 ECS 节点中相同的安全组。 ### 服务挂载限制 * 单个 vePFS 实例支持绑定多个挂载服务；单个挂载服务也支持绑定到多个 vePFS 实例。 * 单个 ECS 只能加入一个 vePFS 挂载服务（相当于客户端集群），一个挂载服务可以绑定多个文件系统存储实例。 * 一个节点仅支持绑定一个挂载服务，因此，推荐一个 VKE 集群绑定一个 vePFS 挂载服务。 * 由于存储类动态制备存储卷基于 Fileset 实现，不同类型 Fileset 允许创建的 PV 数量不同。详情请参见：[Fileset 注意事项](https://www.volcengine.com/docs/6645/143696)。 * vePFS 暂不支持使用 Ubuntu 和 veLinux CentOS 兼容版等镜像，详细客户端限制参见：[客户端限制](https://www.volcengine.com/docs/6645/105557#93ee8005)。 * 当挂载目录被运行中的 Pod 使用时，请勿通过任何手段手动删除对应目录或其父目录。否则可能导致其它节点上的挂载变为`deleted`状态，进一步引发目录不可访问、Pod 启动失败或卷挂载失败。请注意： * 被 Pod 使用不仅指当前节点，也包括同一个文件系统在其它节点上的运行中 Pod。 * 如果业务需要清理目录，必须先确认所有相关 Pod 已停止使用该目录，再执行删除。 * 不支持嵌套 subpath 使用。即不能把某个目录作为一个卷的 subpath，同时再把它的子目录作为另一个卷的 subpath 供不同 Pod 使用。当父目录对应的挂载被删除或重建后，子目录挂载点可能失效，且当前没有技术方案进行自动恢复。 * 不支持同一个节点同时加入多个 vePFS 挂载服务。节点一旦通过某个挂载服务完成 vePFS 客户端初始化和挂载，在节点侧会保留该挂载服务相关的运行时状态。若您在控制台删除该 vePFS 实例或挂载服务，平台不会自动清理集群内和节点本地的 CSI 运行时状态。因此，存量已使用过原挂载服务的节点，在完成清理前，不能直接复用于其它 vePFS 挂载服务。 * 若集群中多个节点对应的 ECS 实例拥有相同的主机名（hostname），则对应节点无法加入 vePFS 挂载服务。 ### 运行性能限制 * 在一个 vePFS 文件系统内创建动态卷的过程是串行的，如果同时创建的动态卷较多，创建完成的耗时将比较久。 * 第一次在节点上启动使用 vePFS 的容器相比后续启动速度慢 15 秒左右。因为 vePFS CSI 需要在节点上为 vePFS 编译内核驱动，编译过程引入了更多的耗时，但是这个耗时仅仅发生在第一次创建使用 vePFS 卷的容器的过程中。 ## 通过控制台配置 ### 步骤一：创建存储类（StorageClass） 1. 登录 [容器服务控制台](https://console.volcengine.com/vke)。 2. 在左侧导航栏中，选择 **集群**，单击目标集群名称，进入集群管理页面。 3. 在集群管理页面左侧导航栏中，选择 **存储管理 \> 存储卷**，单击 **创建存储卷**，配置存储卷。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_79a5348f26aa5ec70a316a37a220f2aa.png) |**配置项** |**说明** | |---|---| |名称 |自定义存储类名称，并确保存储类名称在集群内唯一。 | |存储类型 |选择存储类型，本场景选择 **文件存储 ** **vePFS**。 | |可用区 |可用区是同一地域下电力、网络隔离的物理区域，可用区之间内网互通，不同可用区之间物理隔离。 | |计费类型 |按需选择资源计费类型，目前支持 **按量计费**。 | |规格 |选择创建存储卷使用的文件系统规格，不同规格提供不同的性能指标。详情请参见 [产品规格](https://www.volcengine.com/docs/6645/94130)。 | |项目 |为存储类指定所属项目，从项目维度管理集群资源的运维、授权等操作。默认选择 **default（默认项目）** 。详情请参见 [项目管理](https://www.volcengine.com/docs/6460/661241)。 | |文件系统 |选择已经创建的 vePFS 文件系统和挂载服务。

> **注意**

* > 仅支持选择 **运行中** 状态的挂载服务，且该挂载服务必须与集群在相同的 VPC 内。

* > vePFS 挂载服务将占用挂载节点实际 2 GiB 资源，请注意集群资源规划。
| |文件集 |根据实际情况为 Fileset 设置需要配额，避免单一 Fileset 占用过多的资源，包括：文件数配额、带宽 QoS、IOPS QoS。

> **说明**

> 文件数配额不能超过 iNode 上限。
| |安全组 |挂载服务客户端的安全组，暂不支持配置。该安全组将通过跨服务授权自动加入到用户节点主网卡，从而实现用户节点加入挂载服务集群的目的，使用户集群与 vePFS Server 连通。 | |回收策略 |回收策略，包括：

* **Delete**：删除 PVC 时，会立即删除 PV 以及 PV 中的数据、PV 的后端存储 fileset。

* **Retain**：删除 PVC 时，PV 以及 PV 中的数据、PV 的后端存储 fileset 均不会被删除，需要您手动删除。

> **警告**

* > 选择 **Delete** 回收策略时，删除的数据不可恢复，请根据实际情况谨慎选择。

* > 如果数据安全性要求高，推荐使用 Retain 方式以免误删数据。
| |存储卷绑定模式 |绑定模式。包括：

* **Immediate**：随存储卷声明的创建直接完成卷的绑定和分配。

* **WaitForFirstConsumer**：延迟存储卷的绑定和分配，直到使用该存储卷声明的 Pod 被创建。 | 4. 单击 **确定**，完成配置。 ### 步骤二：创建存储卷声明（PVC） 1. 在集群管理页面左侧导航栏中，选择 **存储管理 \> 存储卷声明**，单击 **创建存储卷声明**，配置存储卷声明。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b3fb9f71afdca1f29215f12cd60f8e0a.png) |**配置项** |**说明** | |---|---| |命名空间 |选择存储卷声明所属的命名空间。建议选择自定义的命名空间，或系统默认创建的 **default** 命名空间。命名空间详细介绍参见：[命名空间概述](https://www.volcengine.com/docs/6460/100958)。 | |名称 |自定义存储卷声明的名称，需确保存储卷声明名称在集群内唯一。 | |存储类型 |选择存储类型，本场景选择 **文件存储 ** **vePFS ** 。 | |访问模式 |存储卷的访问方式，目前支持 **ReadWriteMany**，表示多点读写。 | |计费类型 |按需选择资源计费类型，目前仅支持 **按量计费**。 | |创建方式 |存储卷声明的创建方式，本场景选择 **基于存储类创建**。 | |存储类 |根据实际需求选择合适的存储类。创建应用时，将自动绑定具有相同存储类且容量不小于当前 PVC 设置容量的存储卷。 | |容量 |声明的存储使用量。 | 2. 单击 **确定**，完成配置。 ### 步骤三：创建应用并挂载存储卷 vePFS 文件存储类型的动态存储卷创建完成后，可通过添加卷的方式挂载到工作负载使用，包括：无状态负载、有状态负载、任务、定时任务、守护进程。可通过创建工作负载或更新工作负载操作的容器配置步骤，为工作负载添加卷并挂载卷。详细操作参见：[工作负载](https://www.volcengine.com/docs/6460/100963)。 > **注意** > 创建工作负载过程中，会优先在节点上启动一个用于挂载 vePFS 客户端的专用容器，vePFS 客户端将占用容器 Kubernetes 节点的计算资源（默认占用 4 CPU 和 4 GiB 内存），若节点资源紧张，csi\-vepfs 客户端容器将无法启动成功，Pod 也将阻塞在创建阶段无法启动。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9e7f66aa0d231a416eb952db0f809cdb.png) ## 通过 kubectl 命令行配置已经 [连接集群](https://www.volcengine.com/docs/6460/100942) 的情况下，可通过 kubectl 命令行使用 vePFS 文件存储动态存储卷。 ### 步骤一：配置连接鉴权执行以下命令，将 vePFS 管理节点的 SSH 连接鉴权信息写在 Secret 中。 > **说明** > 以下示例中的 address、password、hostname 仅做演示，请根据实际场景替换为真实配置。 ```Bash echo -n '[ { "address":"192.168.1.210", "password":"bK8C8B5@4T6***", "hostname":"client-mount-demo-1" }, { "address":"192.168.1.209", "password":"bK8C8B5@4T6x***", "hostname":"client-mount-demo-2" }, { "address":"192.168.1.208", "password":"bK8C8B5@4T6x***", "hostname":"client-mount-demo-3" } ]' > /tmp/vepfs-hots.json kubectl create secret generic pfs-secret --namespace kube-system --from-file=vepfsHosts=/tmp/vepfs-hots.json ``` > **说明** > 如果您使用控制台创建过 vePFS 类型的 PV，VKE 将同步创建一个 Secret，保存了挂载管理节点的地址和登录密钥。您可通过`adminHostsSecretName`参数自定义 Secret 名称，也可通过命令`kubectl get -n kube-system secrets | grep "^vepfs-secret-mount-[0-9a-z]*"`查询集群中是否存在该 Secret。 ### 步骤二：创建存储类（StorageClass） 1. 创建 StorageClass 的 YAML 文件。示例文件`vke-pfs-sc.yaml`代码如下： ```YAML apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: sc-demo # 存储类名称 provisioner: vepfs.csi.volcengine.com # 存储挂载依赖的驱动 parameters: fsid: vepfs-cnbj64*** # 文件系统 ID mountServiceID: mount-c8d9*** # 挂载服务 ID fileLimit: "100000" # Fileset 文件配额数 maxIOPS: "20" # Fileset IOPS QoS 限制 maxBandwidth: "30" # Fileset 带宽 QoS 限制，单位为 MB/s mountpoint: /vepfs-cnbj645*** # 挂载服务在绑定文件系统时，指定的挂载路径 securityGroupID: sg-3nrk8xvz1*** # 挂载点客户端安全组 adminHostsSecretName: pfs-secret # 已创建 Secret 名称 adminHostsSecretNamespace: kube-system # 已创建 Secret 所在命名空间 reclaimPolicy: Delete # 存储卷回收策略。取值：Retain（保留策略），Delete（删除策略） volumeBindingMode: Immediate # 存储卷绑定模式，取值：Immediate（立即绑定和分配），WaitForFirstConsumer（延迟存储卷的绑定和分配） ``` 关键参数说明，如下表所示。 |参数 |说明 | |---|---| |provisioner |存储卷挂载依赖的驱动，本文中需要配置为`vepfs.csi.volcengine.com`，表示 csi\-vepfs 插件。 | |fsid |已创建的文件系统 ID。您可以在文件存储控制台，查看已创建的文件系统 ID。详情请参见 [查看文件系统详情](https://www.volcengine.com/docs/6645/101622)。 | |mountServiceID |已创建的挂载服务 ID。您可以在文件存储控制台，查看已创建的挂载服务 ID。 | |fileLimit |配置 Fileset 文件配额数。详情请参见 [设置 Fileset 配额与 QoS](https://www.volcengine.com/docs/6645/1158679)。 | |maxIOPS |配置 Fileset IOPS QoS 限制。详情请参见 [设置 Fileset 配额与 QoS](https://www.volcengine.com/docs/6645/1158679)。 | |maxBandwidth |配置 Fileset 带宽 QoS 限制，单位为 MB/s。详情请参见 [设置 Fileset 配额与 QoS](https://www.volcengine.com/docs/6645/1158679)。 | |mountpoint |挂载服务在绑定文件系统时，指定的挂载路径。详情请参见 [绑定文件系统](https://www.volcengine.com/docs/6645/1113976)。 | |securityGroupID |挂载点客户端安全组。 | |adminHostsSecretName |已创建的鉴权 Secret 名称，Secret 中的鉴权信息需要与挂载服务中的一致。 | |adminHostsSecretNamespace |已创建的鉴权 Secret 所属命名空间，Secret 中的鉴权信息需要与挂载服务中的一致。 | |reclaimPolicy |存储卷回收策略。取值：

* **Delete**：删除 PVC 时，会同步删除 PV 以及 PV 中的数据。

* **Retain**：删除 PVC 时，不会同步删除 PV 以及 PV 中的数据，需要您手动删除。

> **注意**

* > 如果数据安全性要求高，推荐使用 **Retain** 方式以免误删数据。

* > 选择 **Delete** 回收策略时，删除的数据不可恢复，请根据实际情况谨慎选择。
| |volumeBindingMode |存储卷的绑定模式。取值：

* **Immediate**：随存储卷声明的创建直接完成卷的绑定和分配。

* **WaitForFirstConsumer**：延迟存储卷的绑定和分配，直到使用该存储卷声明的 Pod 被创建。 | 2. 执行以下命令，创建 StorageClass。 ```Bash kubectl apply -f vke-pfs-sc.yaml ``` ### 步骤三：创建存储卷声明（PVC） 1. 创建 PVC 的 YAML 文件。示例文件`vke-pfs-pvc.yaml`代码如下： ```YAML apiVersion: v1 kind: PersistentVolumeClaim metadata: name: pvc-demo # 存储卷声明名称 namespace: default # 存储卷声明所属命名空间 spec: accessModes: - ReadWriteMany # 存储卷声明访问模式。目前仅支持 ReadWriteMany，表示多点读写 resources: requests: storage: 20Gi # 声明的存储容量 storageClassName: sc-demo # 已创建的存储类名称 ``` 关键参数说明，如下表所示。 |参数 |说明 | |---|---| |accessModes |存储卷声明的访问方式，仅支持 ReadWriteMany，表示多点读写。 | |storage |声明的存储容量，单位为 Gi。 | |storageClassName |存储类名称，必须与 StorageClass 的`metadata.name`一致。 | 2. 执行以下命令，创建 PVC。 ```Bash kubectl apply -f pvc-demo.yaml ``` ### 步骤四：创建应用并挂载存储卷 1. 创建 Deployment 的 YAML 文件。示例文件`deployment-demo.yaml`代码如下： ```YAML apiVersion: apps/v1 kind: Deployment metadata: name: deployment-demo spec: selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: doc-cn-beijing.cr.volces.com/vke/nginx-demo:v1.0 # 指定需要部署的镜像文件 ports: - containerPort: 80 name: nginx volumeMounts: - name: pfs # 存储卷名称，需与 volumes.name 字段的配置一致 mountPath: /tmp # 存储卷在容器中的挂载位置 volumes: - name: pfs # 存储卷名称，支持自定义 persistentVolumeClaim: claimName: pvc-demo # 已创建的存储卷声明名称 ``` 2. 执行以下命令，创建 Deployment。 ```Bash kubectl apply -f deployment-demo.yaml ``` ## 结果验证 ### 查看配置 1. 登录 [文件存储 vePFS 控制台](https://console.volcengine.com/vepfs)。 2. 在左侧导航栏中，选择 **文件系统** \> **文件系统列表**。 3. 在文件系统列表中，单击目标文件系统名称，进入文件系统详情页面。 4. 选择 **Fileset** 页签，即可查看系统自动创建的 Fileset ** ** 详情。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b77f71227df3960e86328676bd1691f8.png) ### 挂载验证按照上文示例创建工作负载并挂载存储卷后，您可以通过以下方式验证存储卷的挂载和持久化存储。 1. 执行以下命令，查看存储卷是否正确挂载到 Pod 的指定路径。 ```Bash kubectl exec deployment-demo-xxx -- df | grep tmp ``` 预期返回结果如下。 ```Bash fs_vepfs-cnbj645*** 6442450944 35509248 6406941696 1% /tmp ``` 2. 查看 Pod 中的挂载路径，即查看存储卷中的数据。 ```Bash kubectl exec deployment-demo-xxx -- ls /tmp ``` 预期返回结果如下。 ```Bash lost+found ``` 3. 在存储卷中写入文件。 ```Bash kubectl exec deployment-demo-xxx -- touch /tmp/test ``` 4. 删除 Pod。 ```Bash kubectl delete pod deployment-demo-xxx ``` 5. 查看新创建 Pod 下的存储卷挂载路径。 ```Bash kubectl exec deployment-demo-xxx -- ls /tmp ``` 预期返回如下，可以看到存储卷中写入的文件依然存在，未随着 Pod 的删除而被删除，实现了数据的持久化存储。 ```Bash lost+found test ```