文档中心

容器服务

存储卷挂载

预挂载（PreMount）

本文介绍如何在 VCI Agent Sandbox 场景下，使用存储卷挂载能力，实现 Sandbox 在预热池实例中预挂载（PreMount）存储卷，满足不同业务、不同租户对差异化存储的需求。

功能说明

预挂载模式在模板阶段固定挂载目录（mountPath），SandboxClaim 认领沙箱实例时仅动态替换存储卷（PV）与子目录（subPath），适用于挂载目录可提前确定的场景。预挂载模式当前仅支持基于 FSX + EFS 类型存储卷。

预挂载能力通过在 SandboxTemplate 与 SandboxClaim 上添加 Annotation 声明来开启和配置。核心 Annotation 说明如下所示。

分类	Annotation Key	Annotation Value 示例值	说明
SandboxTemplate	vke.volcengine.com/dynamic-mount-volume-name	data-vol	指定需要支持预挂载的 Volume 名称，对应容器volumeMounts中的name。注意 Pod Template 中必须定义对应的volumes以及volumeMounts，否则该 Annotation 配置无效。
SandboxClaim	vke.volcengine.com/dynamic-volume-mount-config	[{"volumeName":"data-vol","pvName":"pv-efs-target","subPath":"test1"}]	声明每个 Volume 要替换成的目标 PV。取值格式：JSON 数组。数组支持的字段说明如下： volumeName：目标卷名称。注意此处volumeName必须是dynamic-mount-volume-name已声明的 Volume 之一。 pvName：卷对应的 PV 名称。 subPath：（可选）挂载子目录，不同子目录可以隔离不同租户/业务。

使用限制

使用 EFS 存储卷预挂载能力时，请注意以下限制。

限制项	说明
PV 类型限制	本文提供的预挂载能力仅支持 FSX + EFS 类型的 PV，不适用于 EBS 等其他存储类型的 PV。
架构限制	需要开启预挂载特性的 Sandbox 目前仅支持调度到 VCI，即 Sandbox 已配置 Annotation：vke.volcengine.com/burst-to-vci: enforce。
预热池认领的 PVC 说明	预热池认领场景下，后端实际上会完成动态 PV 替换，但受 Kubernetes 限制，Sandbox 对应的 Pod 模板依然关联旧的 PVC 信息。该情况对 Sandbox 无影响，下次 Sandbox 休眠唤醒或重建时会自动刷新。
认领限制	认领仅一次，失败不复用。预热池中的 Sandbox 仅会被认领一次、预挂载一次。任何认领失败或预挂载异常都会直接清理 Sandbox 并转入冷启动链路，不再返回预热队列中复用，防止多租户目录串用等数据越界风险。
超时约束	动态替换耗时通常在 500ms 以内，但是随着 Sandbox 实例规模和调用 QPS 的增加，耗时会增加，通常也在 1s 以内。如果出现严重超时，可以尝试提高 SandboxClaim 的并发度或者联系您的火山引擎客户经理提升后端限流值。
安全责任与风险	使用预挂载能力相关安全责任和风险说明，请参见存储卷挂载概述。

前提条件

已创建 VCI 业务所需的集群。详细操作，请参见在 VPC-CNI 网络模型集群中使用 VCI、在 Flannel 网络模型集群中使用 VCI。

VCI 业务集群中已安装 VCI Agent Sandbox 对应的组件：agent-sandbox，用于支持 SandboxTemplate / SandboxWarmPool / SandboxClaim 等 CRD。详细操作，请参见安装指南。

已创建 EFS 文件系统和接入点，作为文件系统目录级访问入口。详细操作，请参见创建文件系统、管理接入点。

已为 EFS 接入点配置策略，控制不同身份对文件系统特定目录的访问权限。详细操作，请参见配置接入点策略。

已在本地安装 kubectl 工具，并通过 kubectl 连接目标集群。详细操作，请参见使用 kubectl 连接集群。

操作步骤

本文以初始 PV 与目标 PV 来自不同 EFS 为示例，演示完整的预挂载流程。若目标 PV 与初始 PV 来自同一个 EFS（不同子目录），只需将目标 PV 的server改为同一接入点域名、path改为不同子目录即可，其余步骤完全一致。

PV	EFS 路径	用途	标记文件
pv-sandbox-1	EFS-A 的/tenant-initial目录	初始 PV	from-initial.txt
pv-sandbox-2	EFS-B 的/tenant-target目录	动态替换目标 PV	from-target.txt

步骤一：创建保密字典（Secret）

通过 Secret 管理访问 EFS 的凭证。若目标 PV 与初始 PV 使用不同的访问凭证，请分别为两个 EFS 创建对应的 Secret。

创建 Secret 的 YAML 文件。示例 YAML 文件efs-fsx-secret.yaml内容如下所示。

说明

您可以使用echo -n "${ak}" | base64命令对 AK、SK 等进行 Base64 编码，并将下方代码中的所有******替换为您自己的实际值。更多 Base64 编码说明，请参见 FAQ。

apiVersion: v1
data:
AccessKeyId: ****** # Base 64 编码后的账号 AK，需要替换为真实信息。
SecretAccessKey: ****** # Base 64 编码后的账号 SK，与上述 AK 匹配，需要替换为真实信息。
ExpiredTime: ****** # Base 64 编码后的临时 Token 过期时间，如果使用火山引擎账号（主账号）AK/SK，则不需要指定。
SessionToken: ****** # Base 64 编码后的临时 Token 内容，如果使用火山引擎账号（主账号）AK/SK，则不需要指定。
kind: Secret
metadata:
name: efs-fsx-key # Secret 名称。
namespace: default # Secret 所属命名空间。
type: Opaque # Secret 类型，Opaque 表示密钥类型。

执行以下命令，创建 Secret。

kubectl create -f efs-fsx-secret.yaml

步骤二：创建初始 PV 和 PVC

初始 PV 是 SandboxTemplate 中预挂载的存储卷，对应 Sandbox 被认领前默认挂载的 EFS 目录。初始 PV 可以挂载 EFS 的根目录，也可以挂载任意子目录。下文以挂载 EFS-A 的/tenant-initial目录为例。

创建初始 PV 的 YAML 文件。示例 YAML 文件pv-efs-initial.yaml内容如下所示。

apiVersion: v1
kind: PersistentVolume
metadata:
name: pv-efs-initial # PV 名称。
spec:
accessModes:
- ReadWriteMany
capacity:
storage: 20Gi
csi:
driver: fsx.csi.volcengine.com # CSI 驱动类型，本场景必须设置为 fsx.csi.volcengine.com，表示使用 csi-fsx 插件。
volumeAttributes:
path: /tenant-initial # EFS-A 的 /tenant-initial 目录。
secretName: efs-fsx-key # 访问 EFS 的凭证 Secret 名称。
secretNamespace: default # Secret 所属命名空间。
server: cnb****.cn-beijing.efs.ivolces.com # EFS 文件系统接入点域名。请替换参数值为您在“前提条件”中准备的实际接入点域名。
type: efs # 存储卷类型，本场景必须设置为 efs。
volumeHandle: pv-efs-initial
persistentVolumeReclaimPolicy: Retain
volumeMode: Filesystem

创建初始 PVC 的 YAML 文件，静态绑定到初始 PV。示例 YAML 文件pvc-efs-initial.yaml内容如下所示。

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: pvc-efs-initial # PVC 名称。
namespace: default # PVC 所属命名空间。
spec:
accessModes:
- ReadWriteMany
resources:
requests:
storage: 10Gi
volumeName: pv-efs-initial # 关联的 PV 名称。

执行以下命令，创建初始 PV 和 PVC，并确认绑定状态。

kubectl create -f pv-efs-initial.yaml
kubectl create -f pvc-efs-initial.yaml
kubectl get pvc pvc-efs-initial

预期输出中STATUS为Bound，表示 PVC 与初始 PV 静态绑定成功。

NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
pvc-efs-initial Bound pv-efs-initial 10Gi RWX 30s

（可选）在初始 EFS 目录中放置标记文件，用于后续验证切换前的状态。例如在 EFS-A 的/tenant-initial目录下创建from-initial.txt文件。详细操作，请参见挂载文件系统。

步骤三：创建 SandboxTemplate 并预挂载初始 PVC

创建 SandboxTemplate，并在 podTemplate 的 Annotations 中通过vke.volcengine.com/dynamic-mount-volume-name声明需要预挂载的 Volume 名称。示例 SandboxTemplate YAML 文件efs-demo-template.yaml内容如下所示。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
name: efs-demo-template # SandboxTemplate 名称。
namespace: default # SandboxTemplate 所属命名空间。
spec:
podTemplate:
metadata:
annotations:
vke.volcengine.com/dynamic-mount-volume-name: "data-vol" # 声明需要支持预挂载的 Volume 名称。
vke.volcengine.com/burst-to-vci: enforce # 强制调度到 VCI。
spec:
containers:
- name: app
image: doc-cn-beijing.cr.volces.com/vke/nginx-demo:v1.0 # 容器镜像的地址和版本，请配置为您自己的镜像地址。若使用公网镜像，请确保您的集群能够访问公网。
command: ["/bin/sh", "-c", "sleep 36000"]
volumeMounts:
- name: data-vol
mountPath: /data # EFS 在容器中挂载的位置。
volumes:
- name: data-vol
persistentVolumeClaim:
claimName: pvc-efs-initial # 已创建的共享 PVC 名称。

执行以下命令，创建 SandboxTemplate。

kubectl create -f efs-demo-template.yaml

步骤四：（可选）创建 SandboxWarmPool

如需使用预热池加速认领，可创建 SandboxWarmPool 引用上述 SandboxTemplate 预热沙箱实例。若不创建预热池，SandboxClaim 将直接走冷启动流程创建沙箱实例，启动耗时较长但最终挂载效果一致。

创建 SandboxWarmPool，示例 YAML 文件efs-demo-warmpool.yaml内容如下所示。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
name: efs-demo-warmpool # 预热池名称。
namespace: default # 预热池所属命名空间。
spec:
replicas: 10 # 预热池 Sandbox 数量。数值越大预热实例越多、认领命中率越高，但资源占用也越高，建议按业务并发峰值评估。
sandboxTemplateRef:
name: efs-demo-template # 关联的 SandboxTemplate 名称。
updateStrategy:
type: Recreate

执行以下命令创建 SandboxWarmPool。

kubectl apply -f efs-demo-warmpool.yaml

步骤五：创建目标 PV

目标 PV 是 SandboxClaim 认领时要动态替换成的存储卷。目标 PV 可以与初始 PV 来自同一个 EFS（不同子目录），也可以来自完全不同的 EFS 文件系统，两者的区别仅在于 PV 的server和path是否相同。下文以挂载 EFS-B 的/tenant-target目录（与初始 PV 来自不同 EFS）为例。

创建目标 PV 的 YAML 文件。示例 YAML 文件pv-efs-target.yaml代码内容如下所示。

apiVersion: v1
kind: PersistentVolume
metadata:
name: pv-efs-target # PV 名称。
spec:
accessModes:
- ReadWriteMany
capacity:
storage: 20Gi
csi:
driver: fsx.csi.volcengine.com # CSI 驱动类型，本场景必须设置为 fsx.csi.volcengine.com，表示使用 csi-fsx 插件。
volumeAttributes:
path: /tenant-target # EFS-B 的 /tenant-target 目录。
secretName: efs-fsx-key # 访问 EFS 的凭证 Secret 名称。
secretNamespace: default # Secret 所属命名空间。
server: cnb****.cn-beijing.efs.ivolces.com # EFS 文件系统接入点域名。请替换参数值为您在“前提条件”中准备的实际接入点域名。
type: efs # 存储卷类型，本场景必须设置为 efs。
volumeHandle: pv-efs-target
persistentVolumeReclaimPolicy: Retain
volumeMode: Filesystem

执行以下命令，创建 PV。

kubectl create -f pv-efs-target.yaml

（可选）在目标 EFS 目录中放置标记文件，用于后续验证切换后的状态。例如在 EFS-B 的/tenant-target目录下创建from-target.txt。详细操作，请参见挂载文件系统。

步骤六：创建 SandboxClaim 并指定目标 PV

在 SandboxClaim 中通过 Annotations：vke.volcengine.com/dynamic-volume-mount-config指定要替换的目标 PV。

注意

SandboxClaim 命中预热池时走热启动认领流程，未命中时自动降级为冷启动，两者最终替换效果一致。

认领失败时系统会清理 Sandbox、不再复用，防止中间态数据污染或泄露。

创建 SandboxClaim，示例 YAML 文件efs-demo-claim.yaml内容如下所示。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
name: efs-demo-claim # SandboxClaim 名称。
namespace: default # SandboxClaim 所属命名空间。
annotations:
vke.volcengine.com/dynamic-volume-mount-config: '[{"volumeName":"data-vol","pvName":"pv-efs-target"}]' # 指定要替换的目标 PV。
spec:
sandboxTemplateRef:
name: efs-demo-template # 申领沙箱所使用的 SandboxTemplate 名称。

执行以下命令创建 SandboxClaim。

kubectl apply -f efs-demo-claim.yaml

验证结果

通过标记文件与接入点信息验证初始 PV 是否被目标 PV 成功替换。下文示例中，目标 PV（pv-efs-target）对应 EFS-B 的/tenant-target目录，其中预置了标记文件from-target.txt。初始 PV（pv-efs-initial）对应 EFS-A 的/tenant-initial目录，其中预置了标记文件from-initial.txt。

执行以下命令，确认已挂载目标 EFS 目录的标记文件。

kubectl exec efs-demo-claim -c app -- sh -c "cat /data/from-target.txt"

预期输出结果如下：

CONTENT-FROM-TARGET-EFS

执行以下命令，确认初始 EFS 目录的标记文件已不可见，即证明挂载点已从初始 PV 切换到目标 PV，初始 EFS 目录不再可见。

kubectl exec efs-demo-claim -c app -- sh -c "cat /data/from-initial.txt"

预期输出结果如下：

cat: /data/from-initial.txt: No such file or directory

执行以下命令，确认接入点已切换到目标 EFS。

kubectl exec efs-demo-claim -c app -- df -h /data | tail -1

预期输出结果如下，挂载源为目标 EFS 子目录对应的接入点域名，即表明卷对应的 PV 已切换。

cnbj****.efs.ivolces.com:/tenant-target 8.0E 0 8.0E 0% /data

此外，可在 Controller 日志中观测到完整的认领与挂载链路，关键节点依次为：

Attempting sandbox adoption

Performing dynamic volume mount

Executing volume mount command via k8s exec

Volume mount command executed successfully

Successfully adopted sandbox from warm pool

最近更新时间：2026.09.18 16:01:27

这个页面对您有帮助吗？

有用

无用