文档中心

容器服务

vePFS Client 访问方式

使用 vePFS 静态存储卷

容器服务支持通过 CSI 使用 vePFS 文件存储，本文为您介绍如何创建 vePFS 文件存储类型的存储卷和存储卷声明，以及工作负载如何使用 vePFS 文件存储静态存储卷。

说明

【邀测·申请试用】使用 vePFS 文件存储静态存储卷功能和智算版规格目前均处于邀测阶段，如需使用，请提交申请。

前提条件

已安装 csi-vepfs 组件，详情请参见安装组件。

已经创建 vePFS 文件系统和挂载服务，并将挂载服务绑定到文件系统。详情请参见创建文件系统、创建挂载服务、绑定文件系统。

（可选）已在本地安装 kubectl 工具。详情请参见安装和设置 kubectl。

使用限制

使用 vePFS 文件存储时，需要注意以下部署兼容性、组件卸载、服务挂载、运行性能相关限制或影响。

部署兼容性相关限制

一个 vePFS 挂载服务不能同时用于 vePFS CSI 方案和主机预挂载 vePFS 方案。对一个 vePFS 文件系统实例，如果用户已经使用 VKE 节点预挂载 vePFS 并通过 hostpath 供给 Pod 的方式，需要额外创建一个 vePFS 挂载服务，将新的 vePFS 挂载服务配置给 vePFS CSI 使用。

通过 CSI 使用 vePFS 文件存储的方案与通过 vePFS-Manager 组件使用 vePFS 的方案不能同时使用。因此，建议创建新集群使用 CSI 方案，若存量资源需要迁移最新 CSI 方案，请提交工单获取技术支持。

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 存储至运行结束；但若 csi-vepfs 已经被卸载，删除 Pod 将会阻塞住，重新安装 csi-vepfs 后可继续删除 Pod。因此，不建议在 Pod 运行的时卸载 csi-vepfs 组件。

csi-vepfs 使文件系统客户端运行在专用容器中，vePFS 客户端将占用容器 Kubernetes 节点的计算资源（默认占用 4 CPU 和 4 GiB 内存），若节点资源紧张，csi-vepfs 客户端容器将无法启动成功，Pod 也将阻塞在创建阶段无法启动。

提前删除 vePFS 挂载服务，将导致 vePFS CSI 组件无法卸载。

vePFS CSI 组件删除后，部分资源无法确认能否被删除，可能构成资源残留。

vePFS mount service secret：创建 vePFS PV 时，VKE 将一起创建一个 Secret，其中保存了 vePFS 挂载服务三个管理节点的地址和登录秘钥，可通过以下命令查询 VKE 集群中存在的上述 Secret。

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 挂载服务。

vePFS 暂不支持使用 Ubuntu 和 veLinux CentOS 兼容版等镜像。详细客户端限制参见：客户端限制。

当挂载目录被运行中的 Pod 使用时，请勿通过任何手段手动删除对应目录或其父目录。否则可能导致其它节点上的挂载变为deleted状态，进一步引发目录不可访问、Pod 启动失败或卷挂载失败。请注意：

这里的“使用中”不仅指当前节点，也包括同一个文件系统在其它节点上的运行中 Pod。

如果业务需要清理目录，必须先确认所有相关 Pod 已停止使用该目录，再执行删除。

不支持嵌套 subpath 使用。即不能把某个目录作为一个卷的 subpath，同时再把它的子目录作为另一个卷的 subpath 供不同 Pod 使用。当父目录对应的挂载被删除或重建后，子目录挂载点可能失效，且当前没有技术方案进行自动恢复。

不支持同一个节点同时加入多个 vePFS 挂载服务。节点一旦通过某个挂载服务完成 vePFS 客户端初始化和挂载，在节点侧会保留该挂载服务相关的运行时状态。若您在控制台删除该 vePFS 实例或挂载服务，平台不会自动清理集群内和节点本地的 CSI 运行时状态。因此，存量已使用过原挂载服务的节点，在完成清理前，不能直接复用于其它 vePFS 挂载服务。

若集群中多个节点对应的 ECS 实例拥有相同的主机名（hostname），则对应节点无法加入 vePFS 挂载服务。

运行性能相关限制

第一次在节点上启动使用 vePFS 的容器相比后续启动速度慢 15 秒左右。因为 vePFS CSI 需要在节点上为 vePFS 编译内核驱动，编译过程引入了更多的耗时，但是这个耗时仅仅发生在第一次创建使用 vePFS 卷的容器的过程中。

通过控制台配置

步骤一：创建存储卷（PV）

登录容器服务控制台。

在左侧导航栏中，选择集群，单击目标集群名称，进入集群管理页面。

在集群管理页面左侧导航栏中，选择存储管理 > 存储卷，单击创建存储卷，配置存储卷。

配置项	说明
创建方式	选择存储卷的创建方式，目前支持静态创建。
名称	自定义存储卷的名称，需确保存储卷名称在集群内唯一。
存储类型	选择存储类型，本场景选择文件存储 vePFS。
访问类型	存储卷的访问类型，本场景选择 vePFS Client。
访问模式	存储卷的访问方式，目前支持 ReadWriteMany，表示多点读写。
规格	选择创建存储卷使用的文件系统规格，不同规格提供不同的性能指标。更多产品规格介绍，请参见产品规格。说明【邀测·申请试用】智算版规格目前处于邀测阶段，如需使用，请提交申请。
项目	为存储类指定所属项目，从项目纬度管理集群资源的运维、授权等操作。默认选择 default（默认项目）。详情请参见项目管理。
文件系统	根据实际需求，依次选择已经创建的 vePFS 文件系统、挂载服务、安全组，以及配置挂载服务的高级配置。
		挂载服务：按需选择文件系统绑定的挂载服务。注意仅支持选择 running 状态的挂载服务，仅支持与集群同 VPC 的挂载服务。 vePFS 挂载服务将占用挂载节点实际 2 GiB 资源，请注意集群资源规划。
		高级配置：配置挂载服务相关高级配置，可展示和配置以下参数。预留内存：vePFS 挂载服务的预留内存，将占用挂载节点实际 2 GiB 资源，不支持修改。访问密钥：默认生成的 secret，该秘钥已经保存 vePFS 客户端节点访问的初始密码，如已修改，请更新对应节点密码。注意若密码不正确将导致 vePFS 无法挂载，请务必确保密码准确无误。
安全组	按需选择挂载服务客户端安全组。该安全组将通过跨服务授权自动加入到用户节点主网卡，从而实现用户节点加入挂载服务集群的目的，使用户集群与 vePFS Server 连通。

单击确定，完成配置。

步骤二：创建存储卷声明（PVC）

在集群管理页面左侧导航栏中，选择存储管理 > 存储卷声明，单击创建存储卷声明，配置存储卷声明。

配置项	说明
命名空间	选择存储卷声明所属的命名空间。建议选择自定义的命名空间，或系统默认创建的 default 命名空间。命名空间详细介绍参见：命名空间概述。
名称	自定义存储卷声明的名称，需确保存储卷声明名称在集群内唯一。
存储类型	选择存储类型，本场景选择文件存储 vePFS 。
访问模式	存储卷的访问方式，目前支持 ReadWriteMany，表示多点读写。
计费类型	按需选择资源计费类型，目前仅支持按量计费。
创建方式	存储卷声明的创建方式，包括：基于存储类创建、使用已有存储卷。本场景选择使用已有存储卷。
存储卷	指定 vePFS 文件存储类型的存储卷进行关联挂载。

单击确定，完成配置。

步骤三：创建应用并挂载存储卷

vePFS 文件存储类型的静态存储卷创建完成后，可通过添加卷的方式挂载到工作负载使用，包括：无状态负载、有状态负载、任务、定时任务、守护进程。

可通过创建工作负载或更新工作负载操作的容器配置步骤，为工作负载添加卷并挂载卷。详细操作参见：工作负载。

通过 kubectl 命令行配置

已经连接集群的情况下，可通过 kubectl 命令行使用 vePFS 文件存储静态存储卷。

步骤一：配置连接鉴权

执行以下命令，将 vePFS 管理节点的 SSH 连接鉴权信息写在 Secret 中。

说明

以下示例中的 address、password、hostname 仅做演示，请根据实际场景替换为真实配置。

步骤二：创建存储卷（PV）

创建 PV 的 YAML 文件，示例文件vke-pfs-static-pv.yaml。支持挂载整个文件系统或文件系统子目录，可根据实际情况按需选择。

挂载整个文件系统
挂载文件系统子目录

挂载 vePFS 整个文件系统的 Yaml 示例如下：

apiVersion: v1
kind: PersistentVolume
metadata:
name: pfs-static-pv # 存储卷名称，集群内唯一
namespace: default
annotations:
pv.kubernetes.io/provisioned-by: vepfs.csi.volcengine.com
spec:
accessModes:
- ReadWriteMany # 存储卷访问方式，仅支持 ReadWriteMany，表示多点读写
capacity:
storage: 20Gi # 声明的存储容量，Kubernetes 必填字段，仅用于校验，容量无实际意义
csi:
driver: vepfs.csi.volcengine.com # 存储挂载依赖的驱动
readOnly: false
nodeStageSecretRef: # 已创建的鉴权 Secret，Secret 中的鉴权信息需要与挂载服务中的一致
name: pfs-secret # Secret 名称
namespace: kube-system # Secret 所在命名空间
controllerPublishSecretRef:
name: pfs-secret
namespace: kube-system
volumeAttributes:
fsid: vepfs-cnsh67*** # 文件系统的 ID
hpcClusterID: vepfs-cluster-id-*** # HPC 集群 ID，仅使用智算版时需要绑定 HPC 集群
mountServiceID: mount-6de0*** # 挂载服务 ID
securityGroupID: sg-3679xag6w*** # 挂载点客户端安全组
mountpoint: /vepfs-cnsh67*** # 挂载服务在绑定文件系统时，指定的挂载路径
volumeHandle: vepfs-cnsh67*** # 存储卷的唯一标识符，要求与 fsid 保持一致
persistentVolumeReclaimPolicy: Retain # 存储卷回收策略。取值：Retain（保留策略），Delete（删除策略）
volumeMode: Filesystem # 存储卷类型。取值：Filesystem（将卷作为文件系统使用，会被 Pod 挂载到某个目录）；Block（将卷作为块设备使用）
挂载 vePFS 文件系统子目录的 Yaml 示例如下：
注意
目前，仅通过 Yaml 静态创建 vePFS 类型 PV 时，支持挂载 vePFS 文件系统子目录（subpath）。
创建 PV 时必须使用已经创建的 vePFS 文件系统子目录，否则，创建 Pod 过程将无法挂载 volume。

apiVersion: v1
kind: PersistentVolume
metadata:
name: pfs-static-pv # 存储卷名称，集群内唯一
namespace: default
annotations:
pv.kubernetes.io/provisioned-by: vepfs.csi.volcengine.com
spec:
volumeMode: Filesystem
accessModes: # 存储卷访问方式，仅支持 ReadWriteMany，表示多点读写
- ReadWriteMany
capacity:
storage: 20Gi # 声明的存储容量，Kubernetes 必填字段，仅用于校验，容量无实际意义
persistentVolumeReclaimPolicy: Retain # 存储卷回收策略。取值：Retain（保留策略），Delete（删除策略）
csi:
driver: vepfs.csi.volcengine.com # 存储挂载依赖的驱动，本示例为 vepfs.csi.volcengine.com ，表示 csi-vepfs 插件
readOnly: false
nodeStageSecretRef: # Secret 对应的不同 vePFS 挂载服务
name: pfs-secret
namespace: kube-system
controllerPublishSecretRef:
name: pfs-secret
namespace: kube-system
volumeAttributes:
fsid: vepfs-cnbjexxxxac6e7b3 # 文件系统 ID
hpcClusterID: vepfs-cluster-id-xxx # HPC 集群 ID，仅 fsid 使用智算版时需要绑定 HPC 集群
mountServiceID: mount-ff0b**** # 挂载服务
securityGroupID: msadgh-14332 # vePFS 挂载点客户端安全组
mountpoint: /vepfs-cnbjexxxxac6e7b3 # 挂载点，对应文件系统 ID
subpath: /l1.dir1/l2.dir1 # 挂载文件系统的子目录，务必使用已经创建的 vePFS 文件系统子目录
volumeHandle: vepfs-cnbjexxxxac6e7b3 # 文件系统 ID

关键参数说明，如下表所示。

参数	说明
accessModes	存储卷访问方式，仅支持 ReadWriteMany，表示多点读写，即存储卷仅能被多个 Pod 以读写方式挂载。
storage	存储卷声明容量，单位为 Gi。该字段为 Kubernetes 必填字段，取值无实际意义，仅用于校验。
driver	存储卷挂载依赖的驱动，本文中需要配置为 vepfs.csi.volcengine.com，表示 csi-vepfs 插件。
nodeStageSecretRef	已创建的鉴权 Secret 名称和命名空间，Secret 中的鉴权信息需要与挂载服务中的一致。
controllerPublishSecretRef	已创建的鉴权 Secret 名称和命名空间，Secret 中的鉴权信息需要与挂载服务中的一致。
fsid	已创建的文件系统 ID。说明您可以在文件存储控制台，查看已创建的文件系统 ID。详情请参见查看文件系统详情。
hpcClusterID	HPC 集群 ID。仅使用智算版时，需要绑定 HPC 集群。
mountServiceID	已创建的挂载服务 ID。
securityGroupID	挂载点客户端安全组。
mountpoint	挂载服务在绑定文件系统时，指定的挂载路径。详情请参见绑定文件系统。
volumeHandle	存储卷唯一标识符，与存储卷（PV）的名称保持一致即可。
persistentVolumeReclaimPolicy	存储卷回收策略。包括： Retain：保留策略，即当绑定该 PV 的 PVC 被删除时，保留该 PV。 Delete：删除策略，即当绑定该 PV 的 PVC 被删除时，同步删除该 PV。
volumeMode	存储卷类型。包括： Filesystem：（默认值）将存储卷作为文件系统使用。存储卷会被格式化并挂载一个文件系统（如 ext4、xfs），再将该文件系统挂载到容器指定路径。您可以在容器中使用ls命令（例如ls /data）能查看挂载的目录或文件，并可以直接读写文件。 Block：将存储卷作为块设备使用。直接暴露给容器，不格式化、不挂载文件系统。您可以通过/dev/block/xxx 类似的路径操作块设备，应用需支持裸块设备读写。

执行以下命令，创建 PV。

kubectl create -f vke-vepfs-static-pv.yaml

步骤三：创建存储卷声明（PVC）

创建 PVC 的 YAML 文件。示例文件vke-pfs-static-pvc.yaml代码如下：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: pfs-static-pvc # 存储卷声明名称
namespace: default # 存储卷声明所属命名空间
spec:
accessModes:
- ReadWriteMany # 存储卷声明访问模式。目前仅支持 ReadWriteMany，表示多点读写
resources:
requests:
storage: 20Gi # 声明的存储容量，Kubernetes 必填字段，仅用于校验，容量无实际意义
volumeMode: Filesystem # 存储卷类型，取值：Filesystem（将存储卷作为文件系统使用）、Block（将存储卷作为块设备使用），必须与 PV 中配置的类型一致
volumeName: pfs-static-pv # 已创建的存储卷名称

关键参数说明，如下表所示。

参数	说明
accessModes	存储卷声明的访问方式，仅支持 ReadWriteMany，表示多点读写。
storage	声明的存储容量，单位为 Gi。需要与已创建的存储卷容量一致。
volumeMode	存储卷类型，必须与 PV 中配置的类型一致。包括： Filesystem：（默认值）将存储卷作为文件系统使用。存储卷会被格式化并挂载一个文件系统（如 ext4、xfs），再将该文件系统挂载到容器指定路径。您可以在容器中使用ls命令（例如ls /data）能查看挂载的目录或文件，并可以直接读写文件。 Block：将卷作为块设备使用。直接暴露给容器，不格式化、不挂载文件系统。您可以通过/dev/block/xxx类似的路径操作块设备，应用需支持裸块设备读写。
volumeName	存储卷名称，必须与 PV 中配置的名称一致。

执行以下命令，创建 PVC。

kubectl create -f vke-pfs-static-pvc.yaml

执行以下命令，查看 PVC 与 PV 的静态绑定结果。

kubectl get pvc

预期输出结果如下，表示 PVC 与 PV 静态绑定成功。

NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
vke-pfs-static-pvc Bound vke-pfs-static-pv 10Pi RWX 2m36s

步骤四：创建应用并挂载存储卷

创建 Deployment 的 YAML 文件。示例文件deployment-nginx-static.yaml代码如下：

apiVersion: apps/v1
kind: Deployment
metadata:
name: deployment-nginx-static
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
mountPath: /tmp # 存储卷在容器中的挂载位置
volumes:
- name: pfs
persistentVolumeClaim:
claimName: pfs-static-pvc # 已创建的 PVC 名称

执行以下命令，创建 Deployment。

kubectl apply -f deployment-nginx-static.yaml

注意

创建工作负载过程中，会优先在节点上启动一个用于挂载 vePFS 客户端的专用容器，vePFS 客户端将占用容器 Kubernetes 节点的计算资源（默认占用 4 CPU 和 4 GiB 内存），若节点资源紧张，csi-vepfs 客户端容器将无法启动成功，Pod 也将阻塞在创建阶段无法启动。

结果验证

按照上文示例创建工作负载并挂载存储卷后，您可以通过以下方式验证存储卷的挂载和持久化存储。

执行以下命令，查看存储卷是否正确挂载到 Pod 的指定路径。

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

预期返回结果如下。

fs_vepfs-cnsh67*** 6442450944 27478016 6414972928 1% /tmp

查看 Pod 中的挂载路径，即查看存储卷中的数据。

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

预期返回结果如下。

lost+found

在存储卷中写入文件。

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

删除 Pod。

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

查看新创建 Pod 下的存储卷挂载路径。

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

预期返回如下，可以看到存储卷中写入的文件依然存在，未随着 Pod 的删除而被删除，实现了数据的持久化存储。

lost+found
test