本文介绍如何在 VCI Agent Sandbox 场景下，使用存储卷挂载能力，实现 Sandbox 在预热池实例中动态挂载（Dynamic）存储卷，满足不同业务、不同租户对差异化存储的需求。 ## 功能说明动态挂载模式无需在模板中预置 Volume，SandboxClaim 认领沙箱实例时指定容器内挂载目录（mountPath），并支持追加新的 Volume 与 volumeMount，由 VCI 以 Hidecar（影子容器）方式注入 CSI 挂载组件保障安全。适用于挂载目录在运行沙箱实例时才能确定、或已有 Annotation 含 mountPath 需低成本平移的场景。当前仅支持 TOS 类型的存储卷。动态挂载能力通过在 SandboxTemplate 与 SandboxClaim 上添加 Annotation 声明来开启和配置。核心 Annotation 说明如下所示。 |对象 |Annotation Key |Annotation Value 示例值 |说明 | |---|---|---|---| |SandboxTemplate（podTemplate） |vke.volcengine.com/csi\-sidecar\-inject |tos | 配置动态挂载能力，取值：

* **tos**：使用对象存储（TOS）动态挂载，以 Hidecar 方式注入 CSI 挂载组件，支持 S3FS 协议。

* **efs**：使用文件存储（EFS）动态挂载，以 Sidecar 方式注入 CSI 挂载组件，支持 S3FS 协议。

* **all**：同时使用 TOS 和 EFS 动态挂载。

> **说明**

> 不添加该 Annotation，则不启用动态挂载能力。
| |SandboxClaim |vke.volcengine.com/dynamic\-volume\-mount\-config |[{"volumeName":"data\-vol","pvName":"pv\-tos\-shared","mountPath":"/mnt/data","subPath":"/tenant\-a"}] |声明每个 Pod 要新增的 volumeMount 信息。

* 取值格式：JSON 数组。

* 数组支持的字段说明如下：

* `volumeName`：目标卷名称。留空时系统自动使用 pvName 作为 volumeName。

* `pvName`：卷对应的 PV 名称。

* `mountPath`：容器内挂载目录，可以是容器内任意绝对路径。包含该字段即进入动态挂载模式。

* `subPath`：PV 根目录下的子路径，用于多租户目录隔离。必须为相对 PV 根目录的合法子路径，禁止包含`..`。 | ## 使用限制使用动态挂载能力时，请注意以下限制。 |限制项 |说明 | |---|---| |模板注解强依赖 |要求 SandboxTemplate 必须带有`vke.volcengine.com/csi-sidecar-inject: "tos"` Annotation，缺失时所有带 mountPath 的请求将被拒绝。 | |单主容器限制 |动态挂载模式默认按单个业务主容器处理，会优先选中第一个`name`不带`sidecar`关键字的容器。多容器场景（不推荐）如需使用动态挂载，非主容器的`name`必须包含`sidecar`关键字，否则将默认选中第一个容器。 | |不支持原地重启 |动态挂载模式与容器原地更新（in\-place update）、可写层持久化能力不可同时使用。容器重启后挂载点可能丢失，需重新创建 Sandbox。 | |认领限制 |预热池中的 Sandbox 只会被认领一次。动态挂载失败、超时或异常时，该 Sandbox 实例将被直接清理并走冷启动链路，不会返回预热池复用，以避免数据处于中间态。 | |超时约束 |动态挂载操作超时时间为 30 秒，超时后认领失败并清理 Sandbox 实例。 | |存储类型限制 |动态挂载模式仅支持 TOS 存储类型。 | |subPath 安全校验 |subPath 禁止包含`..`路径进行遍历，必须为相对 PV 根目录的合法子目录。 | |安全责任与风险 |使用动态挂载能力相关安全责任和风险说明，请参见 [存储卷挂载概述](https://docs.volcengine.com/docs/6460/2668076)。 | ## 前提条件 * 已创建 VCI 业务所需的集群。详细操作，请参见 [在 VPC-CNI 网络模型集群中使用 VCI](https://www.volcengine.com/docs/6460/76916)、[在 Flannel 网络模型集群中使用 VCI](https://www.volcengine.com/docs/6460/1248912)。 * VCI 业务集群中已安装 VCI Agent Sandbox 对应的组件：agent\-sandbox，用于支持 SandboxTemplate / SandboxWarmPool / SandboxClaim 等 CRD。详细操作，请参见 [安装指南](https://docs.volcengine.com/docs/6460/2277052)。 * 已创建 TOS 存储桶（Bucket）。详细操作，请参见 [创建存储桶](https://www.volcengine.com/docs/6349/75024)。 * 已在本地安装 kubectl 工具，并通过 kubectl 连接目标集群。详细说明，请参见 [使用 kubectl 连接集群](https://www.volcengine.com/docs/6460/100942)。 ## 操作步骤 ### 步骤一：创建 SandboxTemplate 1. 创建 SandboxTemplate，并在 podTemplate 的 Annotations 中声明`vke.volcengine.com/csi-sidecar-inject: "tos"`，开启动态挂载模式。示例 SandboxTemplate YAML 文件`dynamic-mount-template.yaml`内容如下所示。 ```YAML apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxTemplate metadata: name: dynamic-mount-template # SandboxTemplate 名称。 namespace: default # SandboxTemplate 所属命名空间。 spec: podTemplate: metadata: annotations: vke.volcengine.com/csi-sidecar-inject: "tos" # 是否开启动态挂载。取值：tos（使用 TOS 动态挂载，Hidecar 方式注入）、efs（使用 EFS 动态挂载，Sidecar 方式注入）、all（同时使用 TOS 和 EFS 挂载）。 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"] resources: limits: cpu: "2" memory: 4Gi ``` 2. 执行以下命令，创建 SandboxTemplate。 ```Bash kubectl create -f dynamic-mount-template.yaml ``` ### 步骤二：创建 SandboxWarmPool 预热池将基于模板预热一批处于 Running 状态的 Sandbox，使认领请求直接命中预热实例。动态挂载所需的 Hidecar 与 Init 容器也在此阶段完成注入。 1. 创建 SandboxWarmPool，示例 YAML 文件`dynamic-mount-warmpool.yaml`内容如下所示。 ```YAML apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxWarmPool metadata: name: dynamic-mount-warmpool # 预热池名称。 namespace: default # 预热池所属命名空间。 spec: replicas: 10 # 预热池 Sandbox 数量。数值越大预热实例越多、认领命中率越高，但资源占用也越高，建议按业务并发峰值评估。 sandboxTemplateRef: name: dynamic-mount-template # 关联的 SandboxTemplate 名称。 updateStrategy: type: Recreate ``` 2. 执行以下命令创建 SandboxWarmPool。 ```Bash kubectl apply -f dynamic-mount-warmpool.yaml ``` ### 步骤三：创建保密字典（Secret）通过 Secret 管理访问 TOS 的凭证。 1. 创建 Secret 的 YAML 文件。示例文件`vke-tos-secret.yaml`代码如下。 > **说明** > 您可以使用`echo -n "${ak}" | base64`命令对 AK、SK 等进行 Base64 编码，并将下方代码中的所有`******`替换为您自己的实际值。更多 Base64 编码说明，请参见 [FAQ](https://docs.volcengine.com/docs/6460/1108771)。 ```YAML apiVersion: v1 kind: Secret metadata: name: tos-key # 保密字典名称。 namespace: default # 保密字典所属命名空间。 type: Opaque # 保密字典类型，本例中选择通用类型，存储任意键值对。 data: akId: ****** # Base 64 编码后的账号 AK，需要替换为真实信息。 akSecret: ****** # Base 64 编码后的账号 SK，与上述 AK 匹配，需要替换为真实信息。 ``` 2. 执行以下命令，创建 Secret。 ```Bash kubectl create -f vke-tos-secret.yaml ``` ### 步骤四：创建 TOS 存储 PV 准备动态挂载的目标 PV，目前动态挂载模式仅支持 TOS 存储类型。 1. 创建 PV 的 YAML 文件。示例 YAML 文件`pv-tos-shared.yaml`内容如下所示。 ```YAML apiVersion: v1 kind: PersistentVolume metadata: name: pv-tos-shared # PV 名称。 spec: csi: driver: tos.csi.volcengine.com # CSI 驱动类型，本场景必须设置为 tos.csi.volcengine.com，表示使用 csi-tos 插件。 nodePublishSecretRef: name: tos-key # 已创建的 TOS 访问配置相关 Secret 名称。 namespace: default # Secret 所在命名空间。 nodeStageSecretRef: # 用于引用一个 Kubernetes Secret，将其中的鉴权信息传给 csi-tos 的节点插件（Node Plugin）。 name: tos-key # 已创建的 TOS 访问配置相关 Secret 名称。 namespace: default # Secret 所在命名空间。 volumeAttributes: bucket: vke-tos # 已创建的 TOS 存储桶名称。 path: / url: https://tos-s3-cn-beijing.ivolces.com # TOS 存储桶域名。 volumeHandle: pv-tos-shared # PV 的唯一标识符，与 PV 名称保持一致。volumeHandle 应该唯一对应 :，避免相同 volumeHandle 对应不同 :，否则可能导致错误挂载盘。 ``` 2. 执行以下命令，创建 PV。 ```Bash kubectl create -f pv-tos-shared.yaml ``` ### 步骤五：创建 Sandbox 本文提供如下两种创建 Sandbox 方式。 **通过 SandboxClaim 认领** 通过创建 SandboxClaim 并指定 mountPath 的方式，发起认领 Sandbox 并声明动态挂载配置。Annotation 中包含`mountPath`字段即进入动态挂载模式，控制器通过 Hidecar 通道执行 CSI 挂载，将指定 PV 的子目录挂载到容器内的任意绝对路径。 1. 创建 SandboxClaim。示例 YAML 文件`dynamic-mount-claim.yaml`内容如下所示。 ```YAML apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxClaim metadata: name: dynamic-mount-claim # SandboxClaim 名称。 namespace: default # SandboxClaim 所属命名空间。 annotations: vke.volcengine.com/dynamic-volume-mount-config: '[{"volumeName":"data-vol","pvName":"pv-tos-shared","mountPath":"/mnt/data","subPath":"/tenant-a"}]' # 声明每个 Pod 要新增的 Volume Mount 信息。 spec: sandboxTemplateRef: name: dynamic-mount-template # 申领沙箱所使用的 SandboxTemplate 名称。 ``` 2. 执行以下命令，创建 SandboxClaim。 ```Bash kubectl create -f dynamic-mount-claim.yaml ``` **通过 E2B SDK 创建** 基于已创建的 SandboxTemplate，使用 E2B 协议创建 Sandbox，可在 Sandbox 的`metadata`中传入动态挂载 Annotation。示例代码如下，更多 E2B SDK 相关参数说明和开发指南，请参见 [E2B SDK 开发指南](https://docs.volcengine.com/docs/6460/2479109)。 > **说明** > E2B SDK 中`template`参数需配置为已创建的 SandboxTemplate 的 ID，不同方式创建的 SandboxTemplate 其 ID 取值不同： * > 通过 Kubernetes API（YAML）创建 SandboxTemplate 时：Template ID 为``，例如`default--dynamic-mount-template`。 * > 通过 VCI E2B SDK 创建 SandboxTemplate 时：Template ID 为实际返回的`template_id`参数值。 ```Python import json from e2b_code_interpreter import Sandbox sbx = Sandbox.create( template="default--dynamic-mount-template", metadata={ "vke.volcengine.com/dynamic-volume-mount-config": json.dumps([ { "volumeName": "data-vol", "pvName": "pv-tos-shared", "mountPath": "/mnt/data", "subPath": "/tenant-a" } ]) } ) print(f"sandbox id: {sbx.sandbox_id}") ``` ## 验证结果确认存储卷已按预期挂载到容器指定目录，并可正常读写。 1. 确认`/mnt/data`为独立挂载点。 ```Bash kubectl exec dynamic-mount-claim -c app -n default -- df -h /mnt/data ``` 预期返回结果如下，Mounted on 列为`/mnt/data`，Filesystem 为 TOS 挂载，说明 TOS 已挂载到目标目录。 ```Bash Filesystem Size Used Avail Use% Mounted on tosfs 10T 0 10T 0% /mnt/data ``` 2. 确认可读取子目录内容。 ```Bash kubectl exec dynamic-mount-claim -c app -n default -- ls -la /mnt/data ``` 预期返回结果如下，列出 TOS Bucket 中`tenant-a`子目录下的文件与目录。 ```Bash total 4 drwxr-xr-x 2 root root 0 Sep 15 16:20 . drwxr-xr-x 3 root root 0 Sep 15 16:20 .. -rw-r--r-- 1 root root 26 Sep 15 16:20 hello-from-tos.txt ```

容器服务