全部产品
Search
文档中心

容器计算服务 ACS:为Agent Sandbox挂载共享存储

更新时间:Apr 20, 2026

本文介绍如何在创建Agent Sandbox时为沙箱挂载OSS或NAS静态存储卷。

前提条件

  1. 已完成Agent Sandbox的基础环境搭建,具体操作,请参见创建Agent Sandbox

  2. 在集群组件管理中,确认ack-agent-sandbox-controller组件版本为v0.5.10及以上。

    在集群的sandbox-system命名空间内存在一份名为sandbox-injection-config的ConfigMap对象,该对象在组件安装后默认带有初始配置项。如需特殊定制或配置修改,请在修改前联系阿里云技术支持评估配置的完备性。
  3. 在集群组件管理中,确认ack-sandbox-manager组件版本为v0.5.0及以上。

该功能通过白名单开放中,如需使用,请提交工单

使用限制

  • 支持基于E2B接口的create功能、休眠/唤醒功能以及原地升级镜像后的运行时存储挂载,但目前不支持基于Checkpoint机制创建快照后恢复存储挂载。

  • 若挂载NAS共享存储并配合休眠/唤醒功能,将导致沙箱的休眠能力失效。

  • 目前OSS静态存储挂载仅支持AccessKey鉴权方式。

  • 在配置网络策略或流量策略时,请务必确保已放行访问 OSS/NAS 管控端点的出方向流量。

挂载共享存储

ACS支持在调用Sandbox.createSandbox.beta_create接口时,为沙箱在运行时挂载一个存储卷(PV),如阿里云NAS等。此功能依赖agent-runtime组件。

步骤一:配置存储挂载能力

ACS提供动态注入Sidecar的配置方案。您只需在SandboxSet或Sandbox对象上设置spec.runtimes参数,框架会在Sandbox被创建时自动注入所需的CSI配置,包括agent-runtime和存储相关的CSI Sidecar配置。

以下为SandboxSet配置示例:

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxSet
metadata:
  name: code-interpreter-inject-test
  namespace: default
spec:
  runtimes:
  - name: csi           # 使能CSI挂载能力,新建的Sandbox会被注入对应的Sidecar
  - name: agent-runtime # 注入envd等环境管理工具
  replicas: 4
  template:
    metadata:
      labels:
        alibabacloud.com/acs: "true"
    spec:
      automountServiceAccountToken: false
      containers:
      - image: registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/code-interpreter:v1.6
        imagePullPolicy: IfNotPresent
        name: sandbox
        resources:
          limits:
            cpu: "1"
            memory: 1Gi
          requests:
            cpu: "1"
            memory: 1Gi
      terminationGracePeriodSeconds: 30

以下为Sandbox对象的配置示例:

apiVersion: agents.kruise.io/v1alpha1
kind: Sandbox
metadata:
  name: code-interpreter-inject-test-xxx
  namespace: default
spec:
  runtimes:
  - name: csi           # 提供CSI挂载能力
  - name: agent-runtime # 注入envd等环境管理工具
  ...

查看注入后的Pod效果示例

以下为SandboxSet扩容后,Sandbox对应的Pod对象中被自动注入的配置内容(包括agent-runtimecsi-sidecarcsi-agent-sidecar的init容器,以及相关的volumes和volumeMounts)。

apiVersion: v1
kind: Pod
metadata:
  labels:
    agents.kruise.io/sandbox-pool: code-interpreter-inject-test
    alibabacloud.com/acs: "true"
  name: code-interpreter-inject-test-xxx
  namespace: default
spec:
  containers:
  - env:
    # 被注入的环境变量
    - name: ENVD_DIR
      value: /mnt/envd
    - name: GODEBUG
      value: multipathtcp=0
    - name: POD_UID
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: metadata.uid
    image: example:tag
    imagePullPolicy: IfNotPresent
    # 被注入的lifecycle
    lifecycle:
      postStart:
        exec:
          command:
          - bash
          - -c
          - /mnt/envd/envd-run.sh
    name: sandbox
    resources:
      limits:
        cpu: "2"
        memory: 2Gi
      requests:
        cpu: "2"
        memory: 2Gi
    volumeMounts:
    # 被注入的volumeMounts
    - mountPath: /mnt/envd
      name: envd-volume
    - mountPath: /run/csi/mount-root
      mountPropagation: HostToContainer
      name: mount-root
    - mountPath: /var/run/csi/sockets/nasplugin.csi.alibabacloud.com
      name: nas-plugin-dir
    - mountPath: /var/run/csi/sockets/ossplugin.csi.alibabacloud.com
      name: oss-plugin-dir
  initContainers:
  # 被注入的agent-runtime init容器
  - command:
    - sh
    - /workspace/entrypoint_inner.sh
    env:
    - name: ENVD_DIR
      value: /mnt/envd
    - name: __IGNORE_RESOURCE__
      value: "true"
    image: registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/agent-runtime:v0.0.5
    name: init
    restartPolicy: Always
  # 被注入的csi-sidecar容器
  - args:
    - --endpoint=unix://var/run/csi/sockets/driverplugin.csi.alibabacloud.com-replace/csi.sock
    - --driver=nas,oss
    - --v=1
    - --run-controller-service=false
    - --run-node-service=true
    - --feature-gates=AlinasMountProxy=true
    env:
    - name: __IGNORE_RESOURCE__
      value: "true"
    - name: KUBELET_ROOT_DIR
      value: /
    - name: ALIBABA_CLOUD_NETWORK_TYPE
      value: vpc
    - name: REGION_ID
      value: cn-zhangjiakou   # 请替换为实际地域ID
    - name: OSS_SKIP_GLOBAL_MOUNT
      value: "true"
    image: registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/csi-plugin:v1.35.1-2592a4872
    name: csi-sidecar
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 100m
        memory: 128Mi
    restartPolicy: Always
    securityContext:
      privileged: true
  # 被注入的csi-agent-sidecar容器
  - args:
    - --socket=/run/cnfs/alinas-mounter.sock
    - --v=4
    env:
    - name: __IGNORE_RESOURCE__
      value: "true"
    image: registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/csi-agent:v1.35.4-3c34d4a-aliyun
    name: csi-agent-sidecar
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 1Gi
    restartPolicy: Always
    securityContext:
      privileged: true
  # 被注入的volumes
  volumes:
  - emptyDir: {}
    name: envd-volume
  - hostPath:
      path: /dev/fuse
      type: CharDevice
    name: fuse-device
  - hostPath:
      path: /var/run/csi
      type: DirectoryOrCreate
    name: mount-root
  - emptyDir: {}
    name: nas-plugin-dir
  - emptyDir: {}
    name: oss-plugin-dir
  - emptyDir: {}
    name: run-cnfs
  - emptyDir: {}
    name: efc-metrics-dir
  - emptyDir: {}
    name: ossfs-metrics-dir
  - emptyDir: {}
    name: csi-agent-config

步骤二:创建存储卷

根据您的存储需求,在集群中创建对应的PV对象。以下分别介绍OSS和NAS静态存储卷的创建方法。

创建OSS存储卷

创建一份描述OSS的PersistentVolume对象和对应的访问密钥Secret对象。更多信息,请参见使用OSS静态存储卷

apiVersion: v1
kind: Secret
metadata:
  name: oss-secret
  # 密钥对象仅允许在sandbox-system命名空间
  namespace: sandbox-system
stringData:
  akId: <YOUR_ACCESS_KEY_ID>       # 访问OSS的AccessKey ID
  akSecret: <YOUR_ACCESS_KEY_SECRET> # 访问OSS的AccessKey Secret
---
apiVersion: v1
kind: PersistentVolume
metadata:
  labels:
    alicloud-pvname: oss-pv-sandbox-system
  name: oss-pv-sandbox-system
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 50Gi
  csi:
    driver: ossplugin.csi.alibabacloud.com
    nodePublishSecretRef:
      name: oss-secret
      namespace: sandbox-system
    volumeAttributes:
      bucket: <OSS_BUCKET>               # 替换为OSS上的实际的Bucket名称
      otherOpts: -o umask=022 -o allow_other
      url: <OSS_ENDPOINT>               # OSS访问端点,请替换为实际OSS Endpoint地址
    volumeHandle: oss-pv-sandbox-system
  persistentVolumeReclaimPolicy: Retain
  storageClassName: test
  volumeMode: Filesystem

创建NAS存储卷

创建NAS的PersistentVolume资源。NAS存储不支持公网挂载,您需要提前在NAS控制台配置挂载点。更多信息,请参见使用NAS静态存储卷

apiVersion: v1
kind: PersistentVolume
metadata:
  labels:
    alicloud-pvname: nas-pv-sandbox-system
  name: nas-pv-sandbox-system
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  csi:
    driver: nasplugin.csi.alibabacloud.com
    volumeAttributes:
      # 替换成实际的NAS挂载点地址,挂载点所属VPC必须与集群所属VPC一致。
      server: xxx.xxx.extreme.nas.aliyuncs.com
      # 挂载NAS的目录地址
      path: /share
    volumeHandle: nas-pv-sandbox-system
  mountOptions:
  - nolock,tcp,noresvport
  - vers=3
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem

步骤三:通过E2B SDK挂载存储卷

挂载单个存储卷

您可以参考以下Python代码,从预热池中获取Sandbox后,将存储卷挂载到沙箱内的指定目录。

挂载OSS存储卷示例

from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(template="code-interpreter-inject-test", timeout=300, metadata={
    "e2b.agents.kruise.io/csi-volume-name": "oss-pv-sandbox-system", # OSS的PersistentVolume名称
    "e2b.agents.kruise.io/csi-mount-point": "/data-oss",
    "e2b.agents.kruise.io/csi-subpath": "data-subPath"  # 相对路径,表示在OSS Bucket内的相对子目录
})

挂载NAS存储卷示例

from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(template="code-interpreter-inject-test", timeout=300, metadata={
    "e2b.agents.kruise.io/csi-volume-name": "nas-pv-sandbox-system",
    "e2b.agents.kruise.io/csi-mount-point": "/data-nas",
    "e2b.agents.kruise.io/csi-subpath": "data-subPath"
})
如遇504响应问题,请前往配置管理 > 配置项修改sandbox-injection-config,将registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/csi-agent:v1.35.3-cgroupv1-dport-forbidden替换为registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/csi-agent:v1.35.4-3c34d4a-aliyun,再重新创建Sandbox即可。

metadata参数说明如下:

参数

说明

e2b.agents.kruise.io/csi-volume-name

指定PersistentVolume对象的名称。

e2b.agents.kruise.io/csi-mount-point

指定存储卷在容器内的挂载目录。

e2b.agents.kruise.io/csi-subpath

指定存储卷在远端存储内的子目录名(相对路径)。

挂载多个存储卷

如果需要一次挂载多个存储卷,可以使用e2b.agents.kruise.io/csi-volume-config参数,通过JSON数组格式指定多个挂载配置。

若同时配置了e2b.agents.kruise.io/csi-volume-config(新协议)和单卷挂载参数(旧协议),新协议的优先级高于旧协议。

以下为同时挂载多个存储卷的Python代码示例:

from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(template="code-interpreter-inject-test", timeout=600, metadata={
    "e2b.agents.kruise.io/csi-volume-config": '[{"pvName":"pv-nas-fast","mountPath":"/data-nas","subPath":"data-subPath","readOnly":true},{...}]'
})
print(f"sandbox id: {sbx.sandbox_id}")

csi-volume-config相关配置说明如下:

字段

类型

说明

pvName

String

PersistentVolume对象名称。

mountPath

String

期望挂载到容器内的目录路径。

subPath

String

远端存储的子目录名(相对路径),可选。

readOnly

Boolean

是否以只读方式挂载,可选,默认为false。