feat(sandbox): support release sandboxinstance cr for ai agent app

Author: ZUP779

apiserver/paasng/paas_wl/bk_app/sandbox_instance/__init__.py

@@ -0,0 +1,15 @@
+# TencentBlueKing is pleased to support the open source community by making
+# 蓝鲸智云 - PaaS 平台 (BlueKing - PaaS System) available.
+# Copyright (C) Tencent. All rights reserved.
+# Licensed under the MIT License (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#     http://opensource.org/licenses/MIT
+#
+# Unless required by applicable law or agreed to in writing, software distributed under
+# the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied. See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# We undertake not to change the open source license (MIT license) applicable
+# to the current version of the project delivered to anyone in the future.

apiserver/paasng/paas_wl/bk_app/sandbox_instance/constants.py

@@ -0,0 +1,59 @@
+# TencentBlueKing is pleased to support the open source community by making
+# 蓝鲸智云 - PaaS 平台 (BlueKing - PaaS System) available.
+# Copyright (C) Tencent. All rights reserved.
+# Licensed under the MIT License (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#     http://opensource.org/licenses/MIT
+#
+# Unless required by applicable law or agreed to in writing, software distributed under
+# the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied. See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# We undertake not to change the open source license (MIT license) applicable
+# to the current version of the project delivered to anyone in the future.
+
+from blue_krill.data_types.enum import StrStructuredEnum
+
+# SandboxInstance CR 的 API Group / Version, 由集群侧 sandbox-controller 负责协调
+SANDBOX_INSTANCE_API_VERSION = "advanced.bkbcs.tencent.com/v1beta1"
+SANDBOX_INSTANCE_KIND = "SandboxInstance"
+
+# 运行时类, 沙箱 Pod 由 cube runtime 承载(一个 SandboxInstance 一个 MicroVM)
+DEFAULT_RUNTIME_CLASS_NAME = "cube"
+
+# 本期网络模式固定为 direct-cni
+DEFAULT_NETWORK_MODE = "direct-cni"
+
+# 触发重调度重启的注解 key(值为 RFC3339 时间戳, 值变化即触发一次)
+RESTARTED_AT_ANNOTATION = "advanced.bkbcs.tencent.com/restartedAt"
+
+# rootfs 系统盘相关默认值
+ROOTFS_DISK_NAME = "rootfs"
+ROOTFS_DISK_ROLE = "rootfsDisk"
+ROOTFS_DISK_IMAGE = "rootdisk.img"
+ROOTFS_DISK_SOURCE_PATH = "rootfs"
+ROOTFS_DISK_FS_TYPE = "ext4"
+
+# rootfs 持久化时, operator 自动创建的 PVC 后缀 / 存储卷名
+STATE_VOLUME_NAME = "cube-state"
+
+
+class DesiredState(StrStructuredEnum):
+    """SandboxInstance 期望运行态, 通过 spec.desiredState 声明"""
+
+    RUNNING = "Running"
+    STOPPED = "Stopped"
+
+
+class SandboxInstancePhase(StrStructuredEnum):
+    """SandboxInstance 生命周期阶段, 见 status.phase"""
+
+    PENDING = "Pending"
+    CREATING = "Creating"
+    RUNNING = "Running"
+    STOPPING = "Stopping"
+    STOPPED = "Stopped"
+    FAILED = "Failed"
+    TERMINATING = "Terminating"

apiserver/paasng/paas_wl/bk_app/sandbox_instance/crd.py

@@ -0,0 +1,27 @@
+# TencentBlueKing is pleased to support the open source community by making
+# 蓝鲸智云 - PaaS 平台 (BlueKing - PaaS System) available.
+# Copyright (C) Tencent. All rights reserved.
+# Licensed under the MIT License (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#     http://opensource.org/licenses/MIT
+#
+# Unless required by applicable law or agreed to in writing, software distributed under
+# the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied. See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# We undertake not to change the open source license (MIT license) applicable
+# to the current version of the project delivered to anyone in the future.
+
+from paas_wl.infras.resources.base.kres import BaseKresource
+
+
+class SandboxInstance(BaseKresource):
+    """CRD: SandboxInstance(sbi), 最小沙箱运行实例, 由集群侧 sandbox-controller 协调渲染 cube Pod。
+
+    与 BkApp CR 一样, 本类仅复用底层通用的 dynamic client 下发能力
+    (create_or_update / patch / get / delete), 不与 BkApp 的数据模型耦合。
+    """
+
+    kind = "SandboxInstance"

apiserver/paasng/paas_wl/bk_app/sandbox_instance/entities.py

@@ -0,0 +1,164 @@
+# TencentBlueKing is pleased to support the open source community by making
+# 蓝鲸智云 - PaaS 平台 (BlueKing - PaaS System) available.
+# Copyright (C) Tencent. All rights reserved.
+# Licensed under the MIT License (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#     http://opensource.org/licenses/MIT
+#
+# Unless required by applicable law or agreed to in writing, software distributed under
+# the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied. See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# We undertake not to change the open source license (MIT license) applicable
+# to the current version of the project delivered to anyone in the future.
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from paas_wl.bk_app.sandbox_instance.constants import (
+    DEFAULT_NETWORK_MODE,
+    DEFAULT_RUNTIME_CLASS_NAME,
+    ROOTFS_DISK_FS_TYPE,
+    ROOTFS_DISK_IMAGE,
+    ROOTFS_DISK_NAME,
+    ROOTFS_DISK_ROLE,
+    ROOTFS_DISK_SOURCE_PATH,
+    SANDBOX_INSTANCE_API_VERSION,
+    SANDBOX_INSTANCE_KIND,
+    STATE_VOLUME_NAME,
+    DesiredState,
+)
+
+
+@dataclass(frozen=True)
+class RootfsConfig:
+    """rootfs 系统盘 + 持久化 PVC 配置。
+
+    当提供时, operator 会用 volumeClaimTemplates 自动创建一块空白持久 PVC,
+    cube 首启在其中 seed 出 rootdisk.img, 重建 Pod 时复用该盘以保留 rootfs 变更。
+    不提供时, 沙箱重启数据会丢失。
+
+    :param disk_size: disk-image 文件大小, 形如 "50Gi"。
+    :param pvc_size: 承载 disk-image 的 PVC 容量, 需 >= disk_size, 形如 "60Gi"。
+    """
+
+    disk_size: str
+    pvc_size: str
+
+
+@dataclass
+class SandboxInstanceSpec:
+    """SandboxInstance 的业务参数, 由后端按此拼装出完整 CR manifest。
+
+    :param name: 沙箱实例名(同时作为 CR name 与 Pod name)。
+    :param namespace: 下发的目标命名空间。
+    :param image: 主容器镜像。
+    :param cpu_cores: vCPU 核数。
+    :param memory: 内存, 形如 "4Gi"。
+    :param command: 主容器 command, 可选。
+    :param args: 主容器 args, 可选。
+    :param rootfs: rootfs 持久化配置, 不提供则不持久化。
+    :param desired_state: 期望运行态, 默认 Running。
+    :param runtime_class_name: 运行时类, 默认 cube。
+    :param annotations: 透传到渲染出的 Pod 的注解(如 TKE 网络相关)。
+    :param labels: 透传到 CR metadata 的标签, sandbox-controller 会继承到渲染出的 cube Pod。
+    :param guest_mac: guest 内可见 MAC, 可选。
+    """
+
+    name: str
+    namespace: str
+    image: str
+    cpu_cores: int
+    memory: str
+    command: List[str] = field(default_factory=list)
+    args: List[str] = field(default_factory=list)
+    rootfs: Optional[RootfsConfig] = None
+    desired_state: DesiredState = DesiredState.RUNNING
+    runtime_class_name: str = DEFAULT_RUNTIME_CLASS_NAME
+    annotations: Dict[str, str] = field(default_factory=dict)
+    labels: Dict[str, str] = field(default_factory=dict)
+    guest_mac: str = ""
+
+    def build_manifest(self) -> Dict[str, Any]:
+        """按业务参数拼装出完整的 SandboxInstance CR manifest(dict)。"""
+        pvc_claim_name = f"{self.name}-pvc"
+
+        domain: Dict[str, Any] = {
+            "cpu": {"cores": self.cpu_cores},
+            "memory": self.memory,
+        }
+
+        # v1beta1: 容器 / 卷统一下沉到 spec.podTemplate(扁平 PodSpec)
+        pod_template: Dict[str, Any] = {"containers": [self._build_main_container()]}
+
+        spec: Dict[str, Any] = {
+            "desiredState": self.desired_state.value,
+            "runtimeClassName": self.runtime_class_name,
+            "network": self._build_network(),
+            "domain": domain,
+            "podTemplate": pod_template,
+        }
+
+        # rootfs 持久化: 挂载系统盘 + 声明持久 PVC
+        if self.rootfs:
+            domain["devices"] = {
+                "disks": [
+                    {
+                        "name": ROOTFS_DISK_NAME,
+                        "volumeName": STATE_VOLUME_NAME,
+                        "role": ROOTFS_DISK_ROLE,
+                        "image": ROOTFS_DISK_IMAGE,
+                        "sourcePath": ROOTFS_DISK_SOURCE_PATH,
+                        "size": self.rootfs.disk_size,
+                        "fsType": ROOTFS_DISK_FS_TYPE,
+                    }
+                ]
+            }
+            pod_template["volumes"] = [
+                {
+                    "name": STATE_VOLUME_NAME,
+                    "persistentVolumeClaim": {"claimName": pvc_claim_name},
+                }
+            ]
+            spec["volumeClaimTemplates"] = [
+                {
+                    "metadata": {"name": pvc_claim_name},
+                    "spec": {
+                        "accessModes": ["ReadWriteOnce"],
+                        "resources": {"requests": {"storage": self.rootfs.pvc_size}},
+                    },
+                }
+            ]
+
+        metadata: Dict[str, Any] = {"name": self.name, "namespace": self.namespace}
+        if self.annotations:
+            metadata["annotations"] = dict(self.annotations)
+        if self.labels:
+            metadata["labels"] = dict(self.labels)
+
+        return {
+            "apiVersion": SANDBOX_INSTANCE_API_VERSION,
+            "kind": SANDBOX_INSTANCE_KIND,
+            "metadata": metadata,
+            "spec": spec,
+        }
+
+    def _build_network(self) -> Dict[str, Any]:
+        network: Dict[str, Any] = {"mode": DEFAULT_NETWORK_MODE}
+        if self.guest_mac:
+            network["guestMAC"] = self.guest_mac
+        return network
+
+    def _build_main_container(self) -> Dict[str, Any]:
+        container: Dict[str, Any] = {
+            "name": "main",
+            "image": self.image,
+            "imagePullPolicy": "IfNotPresent",
+        }
+        if self.command:
+            container["command"] = self.command
+        if self.args:
+            container["args"] = self.args
+        return container

apiserver/paasng/paas_wl/bk_app/sandbox_instance/exceptions.py

@@ -0,0 +1,27 @@
+# TencentBlueKing is pleased to support the open source community by making
+# 蓝鲸智云 - PaaS 平台 (BlueKing - PaaS System) available.
+# Copyright (C) Tencent. All rights reserved.
+# Licensed under the MIT License (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#     http://opensource.org/licenses/MIT
+#
+# Unless required by applicable law or agreed to in writing, software distributed under
+# the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied. See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# We undertake not to change the open source license (MIT license) applicable
+# to the current version of the project delivered to anyone in the future.
+
+
+class SandboxInstanceError(Exception):
+    """SandboxInstance 相关操作的基础异常"""
+
+
+class SandboxInstanceDeployError(SandboxInstanceError):
+    """下发 / 更新 / 删除 SandboxInstance CR 失败"""
+
+
+class SandboxInstanceNotFound(SandboxInstanceError):
+    """SandboxInstance CR 不存在"""