全部文档
当前文档
最近更新时间：2026-10-13 23:31:02
文件存储KPFS（Kingsoft cloud Performance File Storage）支持在Kubernetes集群中使用，可为容器提供解耦的文件存储，方便在容器间共享数据。
金山云容器服务KCE（Kingsoft Cloud Container Engine）基于原生的Kubernetes进行开发和适配，整合了金山云虚拟化、网络、存储等能力，为客户提供高可靠、高性能、高度可扩展的容器管理服务。支持资源调度、服务发现、灰度升级，弹性伸缩和服务编排等功能特性，方便用户在金山云容器平台轻松部署、运维容器化的应用。
本文通过KCE服务介绍在Kubernetes集群中挂载KPFS存储卷的使用方案。
创建Helm应用
前往容器服务，在Helm 应用页面，选择集群，单击新建按钮
配置应用信息
选择Chart来源，Ksyun Helm Chart，选择kpfs-csi-driver，选择最新版本，点击部署
更新Helm values.yaml文件
在K8S集群中任意一个非Master节点上执行以下命令：
ps -ef | grep kubelet | grep root-dir如果结果不为空，则代表该集群的 kubelet 的根目录（--root-dir）做了定制，需要在 values.yaml中将 kubeletDir 根据实际情况进行设置
kubeletDir: <kubelet-dir>如下图所示，待所有容器都处于Running时，驱动部署完成
kubectl -n kube-system get pods -l app.kubernetes.io/name=kpfs-csi-driver根据集群所在地域下载对应地域的Helm Chart文件
使用Helm部署CSI
将步骤1下载的文件拷贝到worker节点的/root目录下并解压缩
#解压helm安装包
unzip ./kpfs-csi-driver-1.2.2.zip更新安装包下的 values.yaml文件
在K8S集群中任意一个非Master节点上执行以下命令：
ps -ef | grep kubelet | grep root-dir如果结果不为空，则代表该集群的 kubelet 的根目录（--root-dir）做了定制，需要在 values.yaml中将 kubeletDir 根据实际情况进行设置：
kubeletDir: <kubelet-dir>安装CSI Driver
helm upgrade --install kpfs-csi-driver kpfs-csi-driver -n kpfs-c2-csi --create-namespace检查部署状态，使用下方命令确认CSI驱动组件正常运行
kubectl -n kpfs-c2-csi get pods -l app.kubernetes.io/name=kpfs-csi-driver在CSI驱动中，挂载KPFS文件系统所需的认证信息，均存在 Kubernetes Secret 中，因此您必须先创建文件系统认证信息。通过 kubectl apply -f secret.yaml指令创建认证信息：
apiVersion: v1
metadata:
name: kpfs-secret
namespace: default
kind: Secret
type: Opaque
stringData:
name: ${KPFS_NAME} #KPFS文件系统名称
token: ${KPFS_TOKEN} # 访问KPFS文件系统所需的Token（参考KPFS控制台-文件系统详情页挂载方法中的Token值）
access-key: ${ACCESS_KEY}
secret-key: ${SECRET_KEY}字段说明：
name：KPFS文件系统名称。
token：访问KPFS文件系统所需的Token（参见KPFS控制台-文件系统详情页挂载方法中的Token值）。
access-key / secret-key：账户的AK/SK信息（参见快速上手）。
通过kubectl apply -f pv.yaml 指令创建PV，可用kubectl get pv查看：
apiVersion: v1
kind: PersistentVolume
metadata:
name: kpfs-pv
labels:
type: kpfs-pv
name: test_csi
spec:
capacity:
storage: 10Pi
volumeMode: Filesystem
accessModes:
- ReadWriteMany
persistentVolumeReclaimPolicy: Retain
csi:
driver: csi.kpfs.com #CSI驱动的名称，用于匹配KPFS的CSI驱动程序
volumeHandle: kpfs-pv
fsType: kpfs
nodePublishSecretRef:
name: kpfs-secret
namespace: default字段说明：
storage：不支持给静态 PV 设置存储容量，填写任意有效值即可。
accessModes：PV访问模式，支持ReadWriteMany （允许多个node读写访问）和 ReadOnlyMany （允许多个node只读访问）两种访问方式。您可根据使用CSI驱动的方式不同， 在PV定义中，填写需要的accessModes。
persistentVolumeReclaimPolicy：静态PV仅支持Retain，PV删除时对应KPFS文件系统不会被删除。
nodePublisSecretRef：先前的步骤中创建好的文件系统认证信息（Secret）。
通过kubectl apply -f pvc.yaml 指令创建PVC：
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: kpfs-pvc-static #pvc的名称
namespace: default
spec:
accessModes:
- ReadWriteMany
volumeMode: Filesystem
storageClassName: ""
resources:
requests:
storage: 10Pi
selector:
matchLabels: #需要匹配的pv的label，才能把pvc和pv成功绑定
type: kpfs-pv
name: test_csi通过kubectl apply -f app.yaml 指令创建Pod：
apiVersion: v1
kind: Pod
metadata:
name: kpfs-app-static
namespace: default
spec:
containers:
- args:
- -c
- while true; do echo $(date -u) >> /data/out-static.txt; sleep 5; done #向挂载路径每5s写一个时间戳
command:
- /bin/sh
image: library/centos
name: app
volumeMounts:
- mountPath: /data
name: data
resources:
requests:
cpu: 10m
volumes:
- name: data
persistentVolumeClaim: #引用PVC
claimName: kpfs-pvc-staticPod创建完成后，可以进入容器确认数据正常写入：
kubectl exec -ti kpfs-app-static -- tail -f /data/out-static.txt挂载子目录
在静态配置下，如果没有显式指定挂载子目录，文件系统的根目录将会被挂载进容器，因此如果对应用有数据隔离的要求，希望让多个应用共享同一个子目录，可使用subdir参数挂载子目录。如果子目录尚不存在，会在挂载前自动创建。示例如下：
apiVersion: v1
kind: PersistentVolume
metadata:
name: kpfs-pv
labels:
type: kpfs-pv
name: test_csi
spec:
capacity:
storage: 10Pi
volumeMode: Filesystem
accessModes:
- ReadWriteMany
persistentVolumeReclaimPolicy: Retain
mountOptions:
- subdir=${/SUB_DIR} #SUB_DIR为子目录名称
csi:
driver: csi.kpfs.com #CSI驱动的名称，用于匹配KPFS的CSI驱动程序
volumeHandle: kpfs-pv
fsType: kpfs
nodePublishSecretRef:
name: kpfs-secret
namespace: default动态配置方式，创建PV的基础配置参数在StorageClass中定义。您只需创建PVC，指定StorageClass，并且在Pod中引用该PVC，就会自动为您创建一个PV，每一个PV会最终对应KPFS文件系统中的一个子目录。适用于大量应用且不同应用、不同团队间需要实现数据隔离的场景。
StorageClass（存储类）里指定了创建PV所需的各类配置，您可以将其理解为动态配置下的Profile：不同的StorageClass就是不同的Profile，可以在其中指定不同的认证信息、挂载配置，让动态配置下可以同时使用不同的文件系统，或者指定不同的挂载。
通过kubectl apply -f sc.yaml 指令创建StorageClass：
#sc yaml示例
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: kpfs-csi-provisioner-retain
provisioner: csi.kpfs.com
parameters:
csi.storage.k8s.io/provisioner-secret-name: kpfs-secret
csi.storage.k8s.io/provisioner-secret-namespace: default
csi.storage.k8s.io/node-publish-secret-name: kpfs-secret
csi.storage.k8s.io/node-publish-secret-namespace: default
reclaimPolicy:
Retain字段说明：
reclaimPolicy：动态PV支持Delete|Retain两种回收策略。Delete策略会导致在删除PV时，PVC子目录随着一起释放。如果数据安全性要求高，推荐使用Retain，以免误删数据。
parameters：先前的步骤中创建好的文件系统认证信息（Secret）。
通过kubectl apply -f pvc.yaml 指令创建PVC：
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: kpfs-test-pvc-sc
spec:
accessModes:
- ReadWriteMany
storageClassName: kpfs-csi-provisioner-sc
resources:
requests:
storage: 10Gi字段说明：
accessModes:PV访问模式，支持ReadWriteMany （允许多个node读写访问）和 ReadOnlyMany （允许多个node只读访问）两种访问方式。
storage:目前不支持给动态 PV 设置存储容量，填写任意有效值即可。
storageClassName：指定使用的StorageClass。
通过kubectl apply -f app.yaml 指令创建Pod：
apiVersion: v1
kind: Pod
metadata:
name: kpfs-app-sc
namespace: default
spec:
containers:
- args:
- -c
- while true; do echo $(date -u) >> /data/out-1.txt; sleep 5; done
command:
- /bin/sh
image: library/centos
name: app
volumeMounts:
- mountPath: /data
name: data
resources:
requests:
cpu: 10m
volumes:
- name: data
persistentVolumeClaim:
claimName: kpfs-test-pvc-scPod创建完成后，可以进入容器确认数据正常写入：
kubectl exec -ti kpfs-app-sc -- tail -f /data/out-1.txt纯净模式