Merge pull request opensandbox-group#579 from Spground/feature/public-handle-eviction

feat(k8s): add eviction handler in pool

Author: Spground

kubernetes/README-ZH.md

@@ -30,6 +30,21 @@ Pool 自定义资源维护一个预热的计算资源池，以实现快速沙箱
 - 基于需求的自动资源分配和释放
 - 实时状态监控，显示总数、已分配和可用资源
 
+### Pod 驱逐
+Pool 支持优雅的 Pod 驱逐，适用于节点维护或资源回收等场景：
+
+**工作原理：**
+- 用户通过给 Pod 打上 `pool.opensandbox.io/evict` 标签请求驱逐
+- 控制器会跳过已分配给 BatchSandbox 的 Pod（保护使用中的工作负载）
+- 空闲 Pod 将被删除，触发池补充容量
+- 标记驱逐的 Pod 不会被分配给新的 BatchSandbox
+
+**自定义驱逐行为：**
+您可以通过以下方式实现自定义驱逐策略：
+1. 在 Pool 上设置 `pool.opensandbox.io/eviction-handler` 标签选择您的处理器
+2. 实现 `EvictionHandler` 接口，包含 `NeedsEviction()` 和 `Evict()` 方法
+3. 在工厂函数中注册您的处理器
+
 ### 任务编排
 集成的任务管理系统，在沙箱内执行自定义工作负载：
 - **可选执行**：任务调度完全可选 - 可以在不带任务的情况下创建沙箱

kubernetes/README.md

@@ -30,6 +30,21 @@ The Pool custom resource maintains a pool of pre-warmed compute resources to ena
 - Automatic resource allocation and deallocation based on demand
 - Real-time status monitoring showing total, allocated, and available resources
 
+### Pod Eviction
+Pool supports graceful pod eviction for scenarios like node maintenance or resource reclamation:
+
+**How it works:**
+- Users label a pod with `pool.opensandbox.io/evict` to request eviction
+- The controller skips pods already allocated to BatchSandbox (protecting in-use workloads)
+- Idle pods are deleted, triggering the pool to replenish capacity
+- Pods marked for eviction are excluded from new allocations
+
+**Custom eviction behavior:**
+You can implement custom eviction strategies by:
+1. Setting `pool.opensandbox.io/eviction-handler` label on the Pool to select your handler
+2. Implementing the `EvictionHandler` interface with `NeedsEviction()` and `Evict()` methods
+3. Registering your handler in the factory function
+
 ### Task Orchestration
 Integrated task management system that executes custom workloads within sandboxes:
 - **Optional Execution**: Task scheduling is completely optional - sandboxes can be created without tasks

kubernetes/internal/controller/allocator.go

@@ -173,9 +173,8 @@ func (syncer *annoAllocationSyncer) GetRelease(ctx context.Context, sandbox *san
 type AllocSpec struct {
 	// sandboxes need to allocate
 	Sandboxes []*sandboxv1alpha1.BatchSandbox
-	// pool
-	Pool *sandboxv1alpha1.Pool
-	// all pods of pool
+	Pool      *sandboxv1alpha1.Pool
+	// all candidate pods
 	Pods []*corev1.Pod
 }
 
@@ -194,6 +193,7 @@ type SandboxSyncInfo struct {
 
 type Allocator interface {
 	Schedule(ctx context.Context, spec *AllocSpec) (*AllocStatus, []SandboxSyncInfo, bool, error)
+	GetPoolAllocation(ctx context.Context, pool *sandboxv1alpha1.Pool) (map[string]string, error)
 	PersistPoolAllocation(ctx context.Context, pool *sandboxv1alpha1.Pool, status *AllocStatus) error
 	SyncSandboxAllocation(ctx context.Context, sandbox *sandboxv1alpha1.BatchSandbox, pods []string) error
 }
@@ -269,7 +269,7 @@ func (allocator *defaultAllocator) initAllocation(ctx context.Context, spec *All
 	status := &AllocStatus{
 		PodAllocation: make(map[string]string),
 	}
-	status.PodAllocation, err = allocator.getPodAllocation(ctx, spec.Pool)
+	status.PodAllocation, err = allocator.GetPoolAllocation(ctx, spec.Pool)
 	if err != nil {
 		return nil, err
 	}
@@ -421,7 +421,7 @@ func (allocator *defaultAllocator) doDeallocate(ctx context.Context, status *All
 	return deallocate, nil
 }
 
-func (allocator *defaultAllocator) getPodAllocation(ctx context.Context, pool *sandboxv1alpha1.Pool) (map[string]string, error) {
+func (allocator *defaultAllocator) GetPoolAllocation(ctx context.Context, pool *sandboxv1alpha1.Pool) (map[string]string, error) {
 	alloc, err := allocator.store.GetAllocation(ctx, pool)
 	if err != nil {
 		return nil, err

kubernetes/internal/controller/allocator_mock.go

@@ -0,0 +1,26 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// 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.
+
+package eviction
+
+import (
+	"context"
+
+	corev1 "k8s.io/api/core/v1"
+)
+
+type EvictionHandler interface {
+	NeedsEviction(pod *corev1.Pod) bool
+	Evict(ctx context.Context, pod *corev1.Pod) error
+}

kubernetes/internal/controller/eviction/eviction.go

@@ -0,0 +1,47 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// 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.
+
+package eviction
+
+import (
+	"context"
+
+	corev1 "k8s.io/api/core/v1"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+const LabelEvict = "pool.opensandbox.io/evict"
+
+type defaultEvictionHandler struct {
+	client client.Client
+}
+
+func newDefaultEvictionHandler(c client.Client) EvictionHandler {
+	return &defaultEvictionHandler{client: c}
+}
+
+func (h *defaultEvictionHandler) NeedsEviction(pod *corev1.Pod) bool {
+	if pod.DeletionTimestamp != nil {
+		return false
+	}
+	_, ok := pod.Labels[LabelEvict]
+	return ok
+}
+
+func (h *defaultEvictionHandler) Evict(ctx context.Context, pod *corev1.Pod) error {
+	if pod.DeletionTimestamp != nil {
+		return nil
+	}
+	return h.client.Delete(ctx, pod)
+}

kubernetes/internal/controller/eviction/eviction_default.go

@@ -0,0 +1,32 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// 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.
+
+package eviction
+
+import (
+	"context"
+
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	sandboxv1alpha1 "github.com/alibaba/OpenSandbox/sandbox-k8s/apis/sandbox/v1alpha1"
+)
+
+const LabelEvictionHandler = "pool.opensandbox.io/eviction-handler"
+
+func NewEvictionHandler(_ context.Context, c client.Client, pool *sandboxv1alpha1.Pool) EvictionHandler {
+	switch pool.Labels[LabelEvictionHandler] {
+	default:
+		return newDefaultEvictionHandler(c)
+	}
+}

kubernetes/internal/controller/eviction/eviction_factory.go

@@ -0,0 +1,167 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// 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.
+
+package eviction
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/controller-runtime/pkg/client/fake"
+
+	sandboxv1alpha1 "github.com/alibaba/OpenSandbox/sandbox-k8s/apis/sandbox/v1alpha1"
+)
+
+func newTestPod(name string, labels map[string]string, deleting bool) *corev1.Pod {
+	pod := &corev1.Pod{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      name,
+			Namespace: "default",
+			Labels:    labels,
+		},
+	}
+	if deleting {
+		now := metav1.NewTime(time.Now())
+		pod.DeletionTimestamp = &now
+		pod.Finalizers = []string{"test-finalizer"}
+	}
+	return pod
+}
+
+func TestDefaultEvictionHandler_NeedsEviction(t *testing.T) {
+	handler := newDefaultEvictionHandler(nil)
+
+	tests := []struct {
+		name   string
+		pod    *corev1.Pod
+		expect bool
+	}{
+		{
+			name:   "pod with eviction label",
+			pod:    newTestPod("pod-1", map[string]string{LabelEvict: ""}, false),
+			expect: true,
+		},
+		{
+			name:   "pod without eviction label",
+			pod:    newTestPod("pod-2", map[string]string{"other": "label"}, false),
+			expect: false,
+		},
+		{
+			name:   "pod with no labels",
+			pod:    newTestPod("pod-3", nil, false),
+			expect: false,
+		},
+		{
+			name:   "pod with eviction label but already deleting",
+			pod:    newTestPod("pod-4", map[string]string{LabelEvict: ""}, true),
+			expect: false,
+		},
+		{
+			name:   "pod deleting without eviction label",
+			pod:    newTestPod("pod-5", nil, true),
+			expect: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := handler.NeedsEviction(tt.pod)
+			if got != tt.expect {
+				t.Errorf("NeedsEviction() = %v, want %v", got, tt.expect)
+			}
+		})
+	}
+}
+
+func TestDefaultEvictionHandler_Evict(t *testing.T) {
+	scheme := runtime.NewScheme()
+	_ = corev1.AddToScheme(scheme)
+
+	t.Run("deletes a pod", func(t *testing.T) {
+		pod := newTestPod("pod-1", map[string]string{LabelEvict: ""}, false)
+		c := fake.NewClientBuilder().WithScheme(scheme).WithObjects(pod).Build()
+		handler := newDefaultEvictionHandler(c)
+
+		err := handler.Evict(context.Background(), pod)
+		if err != nil {
+			t.Fatalf("Evict() returned error: %v", err)
+		}
+
+		got := &corev1.Pod{}
+		err = c.Get(context.Background(), keyFor(pod), got)
+		if err == nil {
+			t.Error("expected pod to be deleted, but it still exists")
+		}
+	})
+
+	t.Run("skips pod already deleting", func(t *testing.T) {
+		pod := newTestPod("pod-2", map[string]string{LabelEvict: ""}, true)
+		c := fake.NewClientBuilder().WithScheme(scheme).WithObjects(pod).Build()
+		handler := newDefaultEvictionHandler(c)
+
+		err := handler.Evict(context.Background(), pod)
+		if err != nil {
+			t.Fatalf("Evict() returned error: %v", err)
+		}
+
+		got := &corev1.Pod{}
+		err = c.Get(context.Background(), keyFor(pod), got)
+		if err != nil {
+			t.Error("expected pod to still exist since it was already deleting")
+		}
+	})
+}
+
+func TestNewEvictionHandler(t *testing.T) {
+	scheme := runtime.NewScheme()
+	_ = corev1.AddToScheme(scheme)
+	_ = sandboxv1alpha1.AddToScheme(scheme)
+	c := fake.NewClientBuilder().WithScheme(scheme).Build()
+	ctx := context.Background()
+
+	t.Run("returns default handler when no label", func(t *testing.T) {
+		pool := &sandboxv1alpha1.Pool{
+			ObjectMeta: metav1.ObjectMeta{Name: "pool-1"},
+		}
+		h := NewEvictionHandler(ctx, c, pool)
+		if h == nil {
+			t.Fatal("expected non-nil handler")
+		}
+		if _, ok := h.(*defaultEvictionHandler); !ok {
+			t.Errorf("expected *defaultEvictionHandler, got %T", h)
+		}
+	})
+
+	t.Run("returns default handler for unknown label value", func(t *testing.T) {
+		pool := &sandboxv1alpha1.Pool{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:   "pool-2",
+				Labels: map[string]string{LabelEvictionHandler: "unknown-handler"},
+			},
+		}
+		h := NewEvictionHandler(ctx, c, pool)
+		if _, ok := h.(*defaultEvictionHandler); !ok {
+			t.Errorf("expected *defaultEvictionHandler, got %T", h)
+		}
+	})
+}
+
+func keyFor(obj metav1.Object) types.NamespacedName {
+	return types.NamespacedName{Name: obj.GetName(), Namespace: obj.GetNamespace()}
+}