Merge pull request #604 from fengcone/feature/public-scaleLimiter

feat(pool): add scaleStrategy to control scaling behavior

Author: Spground

kubernetes/README-ZH.md

@@ -412,6 +412,14 @@ spec:
 kubectl apply -f pool-example.yaml
 ```
 
+**可选：配置扩容速率控制** - 添加 `scaleStrategy` 限制扩容节奏：
+```yaml
+  scaleStrategy:
+    maxUnavailable: "20%"  # 或绝对数量如 5
+```
+
+该配置控制扩容过程中允许不可用的 Pod 数量。例如，当 `poolMax=50` 且 `maxUnavailable=20%` 时，每次最多扩容 10 个 Pod。
+
 使用资源池创建一批沙箱：
 
 ```yaml

kubernetes/README.md

@@ -411,6 +411,14 @@ Apply the pool configuration:
 kubectl apply -f pool-example.yaml
 ```
 
+**Optional: Configure scale rate control** - Add `scaleStrategy` to limit the pace of scaling:
+```yaml
+  scaleStrategy:
+    maxUnavailable: "20%"  # or absolute number like 5
+```
+
+This controls how many pods can be unavailable during scaling. For example, with `poolMax=50` and `maxUnavailable=20%`, at most 10 pods will be scaled at once.
+
 Create a batch of sandboxes using the pool:
 
 ```yaml
@@ -428,6 +436,53 @@ Apply the batch sandbox configuration:
 kubectl apply -f pooled-batch-sandbox.yaml
 ```
 
+##### Pooled Sandbox with Scale Rate Control
+
+The Pool supports configurable scale rate control through `scaleStrategy`, which limits the pace of scaling operations to prevent resource contention:
+
+```yaml
+apiVersion: sandbox.opensandbox.io/v1alpha1
+kind: Pool
+metadata:
+  name: scale-controlled-pool
+spec:
+  template:
+    spec:
+      containers:
+      - name: sandbox-container
+        image: nginx:latest
+        ports:
+        - containerPort: 80
+  capacitySpec:
+    bufferMax: 20
+    bufferMin: 5
+    poolMax: 50
+    poolMin: 10
+  scaleStrategy:
+    # MaxUnavailable controls the maximum number of pods that can be unavailable during scaling.
+    # Can be an absolute number (ex: 5) or a percentage of desired pods (ex: "10%").
+    # Defaults to 25% if not specified.
+    maxUnavailable: "20%"
+```
+
+**ScaleStrategy parameters:**
+
+- **maxUnavailable**: Specifies the maximum number of pods that can be unavailable during scaling operations. This can be:
+  - An absolute number (e.g., `5` means at most 5 pods can be unavailable at once)
+  - A percentage string (e.g., `"10%"` means at most 10% of desired pods can be unavailable)
+  - Defaults to `25%` if not specified
+
+**Use cases:**
+
+- **Prevent resource contention**: Limit scaling pace to avoid overwhelming the cluster with simultaneous pod creation/deletion
+- **Gradual scaling**: Ensure smooth scaling transitions by capping the rate of change
+- **Production stability**: Protect production workloads from aggressive scaling that might impact service quality
+
+Apply the pool configuration:
+```sh
+kubectl apply -f pool-with-scale-strategy.yaml
+```
+
 ##### Pooled Sandbox With Heterogeneous Tasks
 Create a batch of sandboxes with process-based heterogeneous tasks. For task execution to work properly, the task-executor must be deployed as a sidecar container in the pool template and share the process namespace with the sandbox container:
 

kubernetes/apis/sandbox/v1alpha1/pool_types.go

@@ -17,6 +17,7 @@ package v1alpha1
 import (
 	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/util/intstr"
 )
 
 // EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
@@ -32,6 +33,9 @@ type PoolSpec struct {
 	// CapacitySpec controls the size of the resource pool.
 	// +kubebuilder:validation:Required
 	CapacitySpec CapacitySpec `json:"capacitySpec"`
+	// ScaleStrategy controls the scaling behavior.
+	// +optional
+	ScaleStrategy *ScaleStrategy `json:"scaleStrategy,omitempty"`
 }
 
 type CapacitySpec struct {
@@ -53,6 +57,15 @@ type CapacitySpec struct {
 	PoolMin int32 `json:"poolMin"`
 }
 
+// ScaleStrategy controls the pace of scaling operations.
+type ScaleStrategy struct {
+	// MaxUnavailable is the maximum number of pods that can be unavailable during scaling.
+	// Can be an absolute number (ex: 5) or a percentage of desired pods (ex: "20%").
+	// Defaults to 25%.
+	// +optional
+	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`
+}
+
 // PoolStatus defines the observed state of Pool.
 type PoolStatus struct {
 	// ObservedGeneration is the most recent generation observed for this BatchSandbox. It corresponds to the

kubernetes/apis/sandbox/v1alpha1/zz_generated.deepcopy.go

@@ -84,6 +84,19 @@ spec:
                 - poolMax
                 - poolMin
                 type: object
+              scaleStrategy:
+                description: ScaleStrategy controls the scaling behavior.
+                properties:
+                  maxUnavailable:
+                    anyOf:
+                    - type: integer
+                    - type: string
+                    description: |-
+                      MaxUnavailable is the maximum number of pods that can be unavailable during scaling.
+                      Can be an absolute number (ex: 5) or a percentage of desired pods (ex: "20%").
+                      Defaults to 25%.
+                    x-kubernetes-int-or-string: true
+                type: object
               template:
                 description: Pod Template used to create pre-warmed nodes in the pool.
                 x-kubernetes-preserve-unknown-fields: true

kubernetes/config/crd/bases/sandbox.opensandbox.io_pools.yaml

@@ -20,6 +20,7 @@ import (
 	"encoding/hex"
 	gerrors "errors"
 	"fmt"
+	"math"
 	"sort"
 	"time"
 
@@ -30,6 +31,7 @@ import (
 	"k8s.io/apimachinery/pkg/fields"
 	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/types"
+	"k8s.io/apimachinery/pkg/util/intstr"
 	"k8s.io/apimachinery/pkg/util/json"
 	"k8s.io/client-go/tools/record"
 	"k8s.io/client-go/util/retry"
@@ -447,11 +449,19 @@ func (r *PoolReconciler) scalePool(ctx context.Context, args *scaleArgs) error {
 		if createCnt > maxNewPods {
 			createCnt = maxNewPods
 		}
-		log.Info("Scaling up pool", "pool", pool.Name, "createCnt", createCnt)
-		for range createCnt {
-			if err := r.createPoolPod(ctx, pool, args.latestRevision); err != nil {
-				log.Error(err, "Failed to create pool pod")
-				errs = append(errs, err)
+		maxUnavailable := r.getMaxUnavailable(pool, desiredSchedulableCnt)
+		notReadyCnt := r.countNotReadyPods(pods)
+		limitedCreatCnt := maxUnavailable - notReadyCnt
+		createCnt = int32(math.Max(0, math.Min(float64(createCnt), float64(limitedCreatCnt))))
+		if createCnt > 0 {
+			log.Info("Scaling up pool with constraint", "pool", pool.Name,
+				"createCnt", createCnt, "maxUnavailable", maxUnavailable,
+				"notReadyCnt", notReadyCnt, "desiredSchedulableCnt", desiredSchedulableCnt, "limitedCreatCnt", limitedCreatCnt)
+			for range createCnt {
+				if err := r.createPoolPod(ctx, pool, args.latestRevision); err != nil {
+					log.Error(err, "Failed to create pool pod")
+					errs = append(errs, err)
+				}
 			}
 		}
 	}
@@ -541,6 +551,37 @@ func (r *PoolReconciler) pickPodsToDelete(pods []*corev1.Pod, idlePodNames []str
 	return podsToDelete
 }
 
+// getMaxUnavailable returns the resolved maxUnavailable value.
+// If not specified, defaults to 25% of desiredTotal.
+// Minimum return value is 1 to ensure scaling progress.
+func (r *PoolReconciler) getMaxUnavailable(pool *sandboxv1alpha1.Pool, desiredTotal int32) int32 {
+	defaultPercentage := intstr.FromString("25%")
+
+	maxUnavailable := &defaultPercentage
+	if pool.Spec.ScaleStrategy != nil && pool.Spec.ScaleStrategy.MaxUnavailable != nil {
+		maxUnavailable = pool.Spec.ScaleStrategy.MaxUnavailable
+	}
+
+	result, err := intstr.GetScaledValueFromIntOrPercent(maxUnavailable, int(desiredTotal), true)
+	if err != nil || result < 1 {
+		result = 1
+	}
+	return int32(result)
+}
+
+// countNotReadyPods returns the count of pods that are not ready.
+// A pod is considered not ready if it doesn't have a Ready condition
+// with status True.
+func (r *PoolReconciler) countNotReadyPods(pods []*corev1.Pod) int32 {
+	var count int32
+	for _, pod := range pods {
+		if !isPodReady(pod) {
+			count++
+		}
+	}
+	return count
+}
+
 func (r *PoolReconciler) createPoolPod(ctx context.Context, pool *sandboxv1alpha1.Pool, latestRevision string) error {
 	log := logf.FromContext(ctx)
 	pod, err := utils.GetPodFromTemplate(pool.Spec.Template, pool, metav1.NewControllerRef(pool, sandboxv1alpha1.SchemeBuilder.GroupVersion.WithKind("Pool")))