feat(sandbox): support custom volume settings (#2957)

Author: ZUP779

apiserver/paasng/conf.yaml.tpl

@@ -909,20 +909,23 @@ DEV_SANDBOX_CLUSTER: ""
 # 存放 sandbox daemon 二进制的 key
 # AGENT_SANDBOX_DAEMON_KEY: "sandbox/daemon"
 
-# ---- Agent Sandbox 共享存储（CFS + CSI inline 方式）----
+# ---- Agent Sandbox 共享存储（CSI inline 方式）----
 
-# 是否启用 Agent Sandbox 共享卷功能，未配置关键字段（FSID/HOST）时保持关闭
+# 是否启用 Agent Sandbox 共享卷功能，未正确配置 CSI driver / volumeAttributes 时保持关闭
 # AGENT_SANDBOX_VOLUME_ENABLED: false
-# CSI driver 名称，默认腾讯云 TKE 的 CFS 驱动
-# AGENT_SANDBOX_CFS_DRIVER: "com.tencent.cloud.csi.cfs"
-# CFS 文件系统 ID
-# AGENT_SANDBOX_CFS_FSID: ""
-# CFS 挂载目标地址
-# AGENT_SANDBOX_CFS_HOST: ""
-# CFS 根路径
-# AGENT_SANDBOX_CFS_PATH: "/"
-# CFS 协议版本
-# AGENT_SANDBOX_CFS_VERS: "3"
+# CSI driver 名称，默认腾讯云 TKE 的 CFS 驱动，可替换为其他 RWX CSI driver（如 NFS、CephFS）
+# AGENT_SANDBOX_VOLUME_CSI_DRIVER: "com.tencent.cloud.csi.cfs"
+# CSI volumeAttributes，原样透传给 K8s，键值由具体 CSI driver 决定
+# CFS 示例:
+# AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES:
+#   fsid: ""
+#   host: ""
+#   path: "/"
+#   vers: "3"
+# NFS 示例:
+# AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES:
+#   server: "10.0.0.1"
+#   share: "/data"
 
 # 沙箱容器内不允许用户挂载共享卷的路径前缀黑名单，防止覆盖 daemon 或基础工具链
 # AGENT_SANDBOX_MOUNT_PATH_DENY_PREFIXES:

apiserver/paasng/paas_wl/bk_app/agent_sandbox/kres_slzs.py

@@ -145,20 +145,14 @@ def _build_resources(cpu: float, memory: float) -> Dict[str, Dict[str, str]]:
 def _build_csi_volume_source() -> Dict[str, Any]:
     """Build the ``csi`` source block for the shared inline volume.
 
-    The driver and volumeAttributes are driven by settings so that future
-    deployments can swap CFS for other RWX-capable CSI drivers (e.g. CephFS,
-    NFS) without code changes. For drivers beyond Tencent Cloud CFS, additional
-    branches can be added here once their volumeAttributes schema is known.
+    The driver and volumeAttributes are fully driven by settings so that any
+    RWX-capable CSI driver (Tencent Cloud CFS, NFS, CephFS, ...) can be used
+    without code changes: ``AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES`` is passed
+    through as-is, and its keys are defined by the target CSI driver.
     """
-    driver = settings.AGENT_SANDBOX_CFS_DRIVER
     return {
-        "driver": driver,
-        "volumeAttributes": {
-            "fsid": settings.AGENT_SANDBOX_CFS_FSID,
-            "host": settings.AGENT_SANDBOX_CFS_HOST,
-            "path": settings.AGENT_SANDBOX_CFS_PATH,
-            "vers": settings.AGENT_SANDBOX_CFS_VERS,
-        },
+        "driver": settings.AGENT_SANDBOX_VOLUME_CSI_DRIVER,
+        "volumeAttributes": dict(settings.AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES),
     }
 
 

apiserver/paasng/paasng/platform/agent_sandbox/serializers.py

@@ -177,7 +177,9 @@ class Meta:
         fields = ("uuid", "name", "display_name", "application_id", "storage_instance_id", "storage_path", "created")
 
     def get_storage_instance_id(self, obj) -> str:
-        return settings.AGENT_SANDBOX_CFS_FSID
+        # 存储实例标识，键名由具体 CSI driver 决定（CFS 为 fsid，NFS 为 server 等）
+        attrs = settings.AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES or {}
+        return attrs.get("fsid") or attrs.get("server") or ""
 
     def get_storage_path(self, obj) -> str:
         return obj.storage_path

apiserver/paasng/paasng/settings/workloads.py

@@ -118,16 +118,15 @@
 # 示例:'agent-sandbox-router.example.com', 'example.com/agent-sandbox-router'
 AGENT_SANDBOX_ROUTER_ENDPOINT = settings.get("AGENT_SANDBOX_ROUTER_ENDPOINT")
 
-# Agent Sandbox 共享存储（CFS + CSI inline 方式）
-# 未配置关键字段（FSID/HOST）时保持关闭，避免 Pod 因配置缺失而起不来
+# Agent Sandbox 共享存储（CSI inline 方式）
+# 未启用或未正确配置 CSI driver / volumeAttributes 时保持关闭，避免 Pod 因配置缺失而起不来
 AGENT_SANDBOX_VOLUME_ENABLED = settings.get("AGENT_SANDBOX_VOLUME_ENABLED", False)
-# CSI driver 名称，默认腾讯云 TKE 的 CFS 驱动
-AGENT_SANDBOX_CFS_DRIVER = settings.get("AGENT_SANDBOX_CFS_DRIVER", "com.tencent.cloud.csi.cfs")
-# CFS 文件系统 ID / 挂载目标地址 / 根路径 / 协议版本，来自 CFS 控制台
-AGENT_SANDBOX_CFS_FSID = settings.get("AGENT_SANDBOX_CFS_FSID", "")
-AGENT_SANDBOX_CFS_HOST = settings.get("AGENT_SANDBOX_CFS_HOST", "")
-AGENT_SANDBOX_CFS_PATH = settings.get("AGENT_SANDBOX_CFS_PATH", "/")
-AGENT_SANDBOX_CFS_VERS = settings.get("AGENT_SANDBOX_CFS_VERS", "3")
+# CSI driver 名称，默认腾讯云 TKE 的 CFS 驱动；可替换为其他 RWX CSI driver（如 NFS、CephFS）
+AGENT_SANDBOX_VOLUME_CSI_DRIVER = settings.get("AGENT_SANDBOX_VOLUME_CSI_DRIVER", "com.tencent.cloud.csi.cfs")
+# CSI volumeAttributes，原样透传给 K8s（键值由具体 CSI driver 决定）。
+# CFS 示例: {"fsid": "...", "host": "...", "path": "/", "vers": "3"}
+# NFS 示例: {"server": "10.0.0.1", "share": "/data"}
+AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES = settings.get("AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES", {})
 
 # ---------------
 # 资源命名配置

apiserver/paasng/tests/paas_wl/bk_app/agent_sandbox/test_kres_slzs.py

@@ -97,9 +97,8 @@ def test_single_volume_mount_is_rw(self, sbx_app):
         assert len(spec["volumes"]) == 1
         vol = spec["volumes"][0]
         assert vol["name"] == SHARED_VOLUME_NAME_IN_POD
-        assert vol["csi"]["driver"] == settings.AGENT_SANDBOX_CFS_DRIVER
-        attrs = vol["csi"]["volumeAttributes"]
-        assert set(attrs.keys()) == {"fsid", "host", "path", "vers"}
+        assert vol["csi"]["driver"] == settings.AGENT_SANDBOX_VOLUME_CSI_DRIVER
+        assert vol["csi"]["volumeAttributes"] == dict(settings.AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES)
 
         mounts = spec["containers"][0]["volumeMounts"]
         assert mounts == [
@@ -145,11 +144,12 @@ def test_two_volumes_share_single_csi_volume(self, sbx_app):
         assert sub_paths == [f"app/{vid1.replace('-', '')}", f"app/{vid2.replace('-', '')}"]
 
     def test_csi_attributes_follow_settings(self, sbx_app, settings):
-        settings.AGENT_SANDBOX_CFS_DRIVER = "com.example.csi.other"
-        settings.AGENT_SANDBOX_CFS_FSID = "fsid-x"
-        settings.AGENT_SANDBOX_CFS_HOST = "10.0.0.1"
-        settings.AGENT_SANDBOX_CFS_PATH = "/data"
-        settings.AGENT_SANDBOX_CFS_VERS = "4"
+        # 验证 driver 与 volumeAttributes 完全由 settings 透传，可适配任意 CSI 实现（如 NFS）
+        settings.AGENT_SANDBOX_VOLUME_CSI_DRIVER = "nfs.csi.k8s.io"
+        settings.AGENT_SANDBOX_VOLUME_CSI_ATTRIBUTES = {
+            "server": "10.0.0.1",
+            "share": "/data",
+        }
 
         vid = _vol_id()
         sbx = _make_sandbox(
@@ -166,12 +166,10 @@ def test_csi_attributes_follow_settings(self, sbx_app, settings):
         spec = AgentSandboxSerializer._construct_pod_spec(sbx)
         csi = spec["volumes"][0]["csi"]
 
-        assert csi["driver"] == "com.example.csi.other"
+        assert csi["driver"] == "nfs.csi.k8s.io"
         assert csi["volumeAttributes"] == {
-            "fsid": "fsid-x",
-            "host": "10.0.0.1",
-            "path": "/data",
-            "vers": "4",
+            "server": "10.0.0.1",
+            "share": "/data",
         }