fix(k8s): delete auto-created PVCs on sandbox deletion when opted in

Follow-up to #661, addressing the post-merge review by @yinsyim
(#661 (comment)).

The original PR assumed StorageClass.reclaimPolicy would clean up
auto-created PVCs, but reclaimPolicy only governs what happens to the PV
*after* the PVC is deleted — it does not delete the PVC when the
sandbox/workload terminates. Auto-created PVCs were leaking on every
sandbox deletion.

This PR fixes that by:

- Gating cleanup on the existing deleteOnSandboxTermination PVC field
  (default false, opt-in), uniform with Docker semantics. Opt-in PVCs are
  labeled with `opensandbox.io/volume-managed-by=server` and
  `opensandbox.io/id=<sandbox_id>`. Pre-existing PVCs and opt-out PVCs are
  never deleted by the server.

- Attaching ownerReferences from each opt-in PVC to the just-created
  workload CR after create_workload succeeds. Kubernetes garbage
  collection then deletes the PVC whenever the CR goes away — by the
  delete_sandbox API, by TTL expiry handled in the controller, or by any
  cascade. The label-based sweep in delete_sandbox remains as a fallback.

- Sweeping auto-created PVCs when sandbox creation fails before
  returning. Previously create_workload / _wait_for_sandbox_ready
  failures left labeled PVCs orphaned because the caller has no sandbox
  id to call delete_sandbox with.

- Rejecting 400 when the same claim_name appears in multiple Volume
  entries with inconsistent createIfNotExists / deleteOnSandboxTermination
  flags (first-wins previously caused either silent leaks or silent
  deletions).

Server changes:
- services/k8s/client.py: add list_pvcs, delete_pvc, patch_pvc.
- services/k8s/kubernetes_service.py:
  - _ensure_pvc_volumes: label only on opt-in; reject conflicting flags;
    return the list of newly auto-created managed PVCs.
  - new _attach_pvc_owner_references: best-effort patch after
    create_workload, gated on workload_info exposing apiVersion/kind/uid.
  - new _cleanup_managed_pvcs: list-by-selector + delete; best-effort.
  - delete_sandbox: call cleanup after workload deletion succeeds or 404s,
    never on transient errors.
  - create_sandbox: finally-sweep on any failure before return.
- services/k8s/batchsandbox_provider.py and agent_sandbox_provider.py:
  return apiVersion and kind alongside name and uid so the
  ownerReference can be constructed.

Spec, docs, SDKs, RBAC:
- specs/sandbox-lifecycle.yml + server/api/schema.py: replace the stale
  "Docker only / no effect on K8s / StorageClass reclaim policy handles
  it" description with correct cross-backend semantics. The reclaim-policy
  reference remains but is reframed (the PVC delete triggers it).
- docs/public/api/spec-inline.js: regenerated via `pnpm docs:spec` so
  the published API docs reflect the new description.
- SDKs: regenerated Python lifecycle and JS lifecycle from the spec;
  hand-edited Python sandbox model, C# model, and Kotlin model
  docstrings.
- kubernetes/charts/opensandbox-server: grant `delete` and `list` on
  persistentvolumeclaims so the cleanup path runs under the stock chart.

Tests:
- Label stamping for opt-in and opt-out paths.
- Cleanup on success, on 404 sweep, no-cleanup on transient error,
  best-effort tolerance of list_pvcs failure, no-touch for pre-existing
  PVCs.
- Conflict validation rejects mismatched flags and allows matching ones.
- create_sandbox finally-sweep covers create_workload and
  wait_for_ready failures.
- _attach_pvc_owner_references patches each managed PVC with the right
  body, is best-effort on failure, and skips when owner info is
  incomplete.

End-to-end verified on a real cluster:
- opt-in PVC carries labels and ownerReferences; delete_sandbox API
  cleans it via the label sweep; direct CR delete (simulating TTL) is
  cleaned via K8s GC.
- opt-out PVC has no labels or ownerReferences and survives any CR
  delete.
- Pre-existing PVCs are untouched.

Author: xfgong

docs/public/api/spec-inline.js

@@ -28,7 +28,7 @@ rules:
     verbs: ["create", "delete", "get"]
   - apiGroups: [""]
     resources: ["persistentvolumeclaims"]
-    verbs: ["create", "get"]
+    verbs: ["create", "delete", "get", "list", "patch"]
   - apiGroups: ["node.k8s.io"]
     resources: ["runtimeclasses"]
     verbs: ["get", "list"]

kubernetes/charts/opensandbox-server/templates/server.yaml

@@ -163,7 +163,8 @@ public class PVC
     public bool? CreateIfNotExists { get; set; }
 
     /// <summary>
-    /// Gets or sets whether auto-created Docker volumes should be removed on sandbox deletion.
+    /// Gets or sets whether the auto-created volume (Docker named volume or Kubernetes PVC)
+    /// should be removed on sandbox deletion. Pre-existing volumes are never removed.
     /// </summary>
     [JsonPropertyName("deleteOnSandboxTermination")]
     public bool? DeleteOnSandboxTermination { get; set; }

sdks/sandbox/csharp/src/OpenSandbox/Models/Sandboxes.cs

@@ -1302,9 +1302,9 @@ export interface components {
             /**
              * @description When true, the volume is automatically removed when the sandbox
              *     is deleted. Only applies to volumes that were auto-created by the
-             *     server (Docker only). Pre-existing volumes are never removed.
-             *     Has no effect on Kubernetes PVCs, whose lifecycle is managed by
-             *     the StorageClass reclaim policy.
+             *     server on this request; pre-existing volumes are never removed.
+             *     For Kubernetes, the resulting PVC delete triggers the bound PV's
+             *     StorageClass reclaim policy (`Retain`/`Delete`).
              * @default false
              */
             deleteOnSandboxTermination: boolean;

sdks/sandbox/javascript/src/api/lifecycle.ts

@@ -406,7 +406,7 @@ class Host private constructor(
  * @property claimName Name of the platform volume. In Kubernetes this is the PVC name;
  * in Docker this is the named volume name.
  * @property createIfNotExists When true (default), auto-create volume if absent.
- * @property deleteOnSandboxTermination When true, delete auto-created Docker volume on sandbox deletion.
+ * @property deleteOnSandboxTermination When true, delete the auto-created volume (Docker named volume or Kubernetes PVC) on sandbox deletion. Pre-existing volumes are never removed.
  * @property storageClass Kubernetes StorageClass for auto-created PVCs. Null means default class.
  * @property storage PVC storage request for auto-created PVCs (e.g. "1Gi").
  * @property accessModes Access modes for auto-created PVCs (e.g. ["ReadWriteOnce"]).

sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/SandboxModels.kt

@@ -46,9 +46,9 @@ class PVC:
                  Default: True.
             delete_on_sandbox_termination (bool | Unset): When true, the volume is automatically removed when the sandbox
                 is deleted. Only applies to volumes that were auto-created by the
-                server (Docker only). Pre-existing volumes are never removed.
-                Has no effect on Kubernetes PVCs, whose lifecycle is managed by
-                the StorageClass reclaim policy.
+                server on this request; pre-existing volumes are never removed.
+                For Kubernetes, the resulting PVC delete triggers the bound PV's
+                StorageClass reclaim policy (`Retain`/`Delete`).
                  Default: False.
             storage_class (None | str | Unset): Kubernetes StorageClass name for auto-created PVCs. Null means
                 use the cluster default. Ignored for Docker volumes.

sdks/sandbox/python/src/opensandbox/api/lifecycle/models/pvc.py

@@ -200,8 +200,9 @@ class PVC(BaseModel):
         default=False,
         alias="deleteOnSandboxTermination",
         description=(
-            "When true, auto-created Docker volume is removed on sandbox deletion. "
-            "Ignored for Kubernetes PVCs."
+            "When true, the auto-created volume (Docker named volume or "
+            "Kubernetes PVC) is removed on sandbox deletion. Pre-existing "
+            "volumes are never removed."
         ),
     )
     storage_class: str | None = Field(

sdks/sandbox/python/src/opensandbox/models/sandboxes.py

@@ -180,9 +180,9 @@ class PVC(BaseModel):
         description=(
             "When true, the volume is automatically removed when the sandbox is "
             "deleted. Only applies to volumes that were auto-created by the server "
-            "(Docker only). Pre-existing volumes are never removed. Has no effect "
-            "on Kubernetes PVCs, whose lifecycle is managed by the StorageClass "
-            "reclaim policy."
+            "on this request; pre-existing volumes are never removed. For "
+            "Kubernetes, the resulting PVC delete then triggers the bound PV's "
+            "StorageClass reclaim policy (Retain/Delete)."
         ),
     )
 

server/opensandbox_server/api/schema.py

@@ -210,6 +210,8 @@ def create_workload(
         return {
             "name": created["metadata"]["name"],
             "uid": created["metadata"]["uid"],
+            "apiVersion": f"{self.group}/{self.version}",
+            "kind": "Sandbox",
         }
 
     def _apply_platform_node_selector(

server/opensandbox_server/services/k8s/agent_sandbox_provider.py

@@ -297,6 +297,8 @@ def create_workload(
         return {
             "name": created["metadata"]["name"],
             "uid": created["metadata"]["uid"],
+            "apiVersion": f"{self.group}/{self.version}",
+            "kind": "BatchSandbox",
         }
 
     def _apply_platform_node_selector(
@@ -364,6 +366,8 @@ def _create_workload_from_pool(
         return {
             "name": created["metadata"]["name"],
             "uid": created["metadata"]["uid"],
+            "apiVersion": f"{self.group}/{self.version}",
+            "kind": "BatchSandbox",
         }
 
     def _extract_template_pod_extras(self) -> tuple[list[Dict[str, Any]], list[Dict[str, Any]]]: