预热池自动扩缩容

步骤一：通过 SandboxSet 创建预热池

若已创建预热池，可直接复用现有 SandboxSet。以下为最小示例，各字段含义见注释；请将标注“必须替换”的字段改为当前集群已验证的值。

1. 将以下内容保存为 sandboxset.yaml。

   apiVersion: agents.kruise.io/v1alpha1
   kind: SandboxSet
   metadata:
     name: sandbox-pool        # SandboxSet 名称，步骤二的 PoolAutoscaler 通过此名称引用；可按需修改
     namespace: default        # 部署命名空间；PoolAutoscaler 必须与它同 namespace
   spec:
     replicas: 2               # 初始预热池大小；应用 PoolAutoscaler 后由其接管，可按成本设小一些
     scaleStrategy:
       maxUnavailable: "30%"   # 建议配置：兼作启动预算，启动失败/超时数达到该值时暂停继续扩容
     runtimes:
       - name: agent-runtime   # 注入 envd 兼容运行时，步骤三的 E2B 代码执行/文件/命令能力依赖它
     template:
       spec:
         containers:
           - name: sandbox
             image: <YOUR-SANDBOX-IMAGE>   # 必须替换：集群内可拉取的 Agent Sandbox 运行时镜像
             resources:
               requests:         # 调度申请资源，影响预热池单实例成本和可放置的节点范围
                 cpu: "1"
                 memory: 1Gi
               limits:           # 资源上限；按实际运行时需要调整，过大浪费预热成本，过小影响启动
                 cpu: "1"
                 memory: 1Gi

2. 创建预热池并查看状态。

   kubectl apply -f sandboxset.yaml
   kubectl get sandboxset sandbox-pool -n default

   runtimes: agent-runtime 是步骤三 E2B 验证的必要条件（run_code、文件读写、命令执行均依赖注入的 envd 运行时）。运行时注入机制及其对 sandbox-injection-config ConfigMap 的依赖，请参见为 Agent Sandbox 配置 Sidecar 容器自动注入。

步骤二：配置 PoolAutoscaler

以下策略按比例维护预热池：目标可用比例为 50%，使用默认容差 10%，近期平均可用比例低于 40% 时扩容，高于 60% 时缩容，两者之间不调整。百分比水位随池规模弹性伸缩，适合负载波动的业务。

1. 将以下内容保存为 pool-autoscaler.yaml。

   apiVersion: agents.kruise.io/v1alpha1
   kind: PoolAutoscaler
   metadata:
     name: sandbox-pool-autoscaler   # PoolAutoscaler 名称，仅用于标识和后续 kubectl 查询，可按需修改
     namespace: default              # 必须与目标 SandboxSet 同 namespace
   spec:
     scaleTargetRef:
       apiVersion: agents.kruise.io/v1alpha1
       kind: SandboxSet              # 仅支持 SandboxSet，不可修改
       name: sandbox-pool            # 步骤一中创建的 SandboxSet 名称
     minReplicas: 2                  # 预热池下限；百分比目标需满足缩容可达性，见下方说明
     maxReplicas: 50                 # 预热池上限；按业务峰值并发量与集群容量设置
     capacityPolicy:
       targetAvailable: "50%"        # 目标可用（未被领取的）Sandbox 占副本数的比例，随池规模弹性伸缩
       # tolerance 未设置时默认为 10%，与目标合并后形成 40%~60% 的不调整区间
       scaleUp:
         stabilizationWindowSeconds: 60    # 扩容稳定窗口，即连续两次扩容的最小间隔；设小可加快补池，但过小会导致扩容过于频繁
       scaleDown:
         stabilizationWindowSeconds: 300   # 缩容稳定窗口，即连续两次缩容的最小间隔；拉长可避免夜间流量波动频繁回收预热池
   

2. 创建 PoolAutoscaler 并查看状态。

   kubectl apply -f pool-autoscaler.yaml
   kubectl get poolautoscaler sandbox-pool-autoscaler -n default

minReplicas 和 maxReplicas 始终生效，所有策略计算出的副本数都会被限制在这个范围内。targetAvailable、tolerance 和 minReplicas 的取值共同决定空闲预热池能否收缩到 minReplicas，配置规则参见本文容量策略调优说明。

稳定窗口的取值建议保持缩容长于扩容（默认 60 秒对 300 秒，上述示例也保持了这一关系）：快速扩容可及时补齐预热池、保障领取延迟，缓慢缩容可避免瞬时流量回落时回收预热容量造成容量抖动。

步骤三：使用 E2B 业务流量验证

以下单文件脚本模拟真实业务流量：每个并发循环从预热池领取一个 Sandbox，执行代码、读写文件、执行命令，短暂持有后释放。预热池的扩缩容状态可通过步骤四的命令另行观察。

准备工作：

1. 本地已安装 Python 3.9 及以上版本，并已配置目标集群的 kubeconfig（用于 kubectl 观察状态）。

2. 安装 E2B SDK（版本须与 ack-sandbox-manager 组件兼容）：pip install e2b-code-interpreter。

3. 准备可访问的 E2B 服务域名、API Key；集群使用自签证书时，还需准备 CA 证书。

将脚本保存为 poolautoscaler-verify.py。

#!/usr/bin/env python3
"""Generate E2B business traffic against a PoolAutoscaler-managed pool.

Usage:
  E2B_API_KEY='<YOUR-E2B-API-KEY>' \
  E2B_DOMAIN='<YOUR-E2B-DOMAIN>' \
  SSL_CERT_FILE='<YOUR-CA-FILE>' \
  python poolautoscaler-verify.py --template sandbox-pool
"""
import argparse, os, sys, threading, time
from concurrent.futures import ThreadPoolExecutor

stop = threading.Event()

def business_loop(loop_id, template, hold, deadline):
    """One worker: claim a sandbox, run business calls, hold, then release."""
    from e2b_code_interpreter import Sandbox
    seq = 0
    while time.monotonic() < deadline and not stop.is_set():
        seq += 1
        sandbox = None
        try:
            # no timeout: the SDK timeout is the sandbox lifetime, not a create wait
            sandbox = Sandbox.create(template=template)
            sandbox.run_code(f"print('loop={loop_id} seq={seq}')")
            path = f"verify-{loop_id}-{seq}.txt"
            content = f"loop={loop_id} seq={seq}\n"
            sandbox.files.write(path, content)
            assert sandbox.files.read(path) == content, "file content mismatch"
            assert sandbox.commands.run(f"cat {path}").stdout == content
            stop.wait(hold)          # simulate the business holding the sandbox
            sandbox.kill()
        except Exception as exc:
            if sandbox is not None:
                try:
                    sandbox.kill()   # release the claimed sandbox before backing off
                except Exception:
                    pass
            print(f"loop {loop_id} seq {seq} failed: "
                  f"{type(exc).__name__}: {exc}", file=sys.stderr, flush=True)
            stop.wait(5)             # back off before the next attempt
 
 
def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--template", default="sandbox-pool",
                        help="SandboxSet name, i.e. the E2B template")
    parser.add_argument("--concurrency", type=int, default=10,
                        help="simultaneous business sandboxes; each consumes one pool slot")
    parser.add_argument("--duration-seconds", type=int, default=300)
    parser.add_argument("--hold-seconds", type=int, default=30,
                        help="how long each loop holds its sandbox before releasing")
    args = parser.parse_args()
    if not os.getenv("E2B_API_KEY"):
        parser.error("E2B_API_KEY must be set")

    deadline = time.monotonic() + args.duration_seconds
    print(f"load: {args.concurrency} loops x {args.duration_seconds}s, "
          f"hold={args.hold_seconds}s (Ctrl+C stops early)", flush=True)
    try:
        with ThreadPoolExecutor(max_workers=args.concurrency) as pool:
            futures = [pool.submit(business_loop, i, args.template,
                                   args.hold_seconds, deadline)
                       for i in range(args.concurrency)]
            for future in futures:
                future.result()
    except KeyboardInterrupt:
        print("interrupted; waiting for in-flight sandboxes to settle...", flush=True)
    finally:
        stop.set()
    return 0


if __name__ == "__main__":
    main()

运行脚本（另开一个终端执行步骤四的观察命令，可实时看到扩容）：

E2B_API_KEY='<YOUR-E2B-API-KEY>' \
E2B_DOMAIN='<YOUR-E2B-DOMAIN>' \
SSL_CERT_FILE='<YOUR-CA-FILE>' \
python poolautoscaler-verify.py \
  --template sandbox-pool \
  --concurrency 10 \
  --duration-seconds 300 \
  --hold-seconds 30

参数说明：

• --concurrency：并发领取数。建议不超过池内稳态可用数（由 minReplicas 与 targetAvailable 共同决定）：超过会击穿预热池，首次数据面调用可能返回 503（属预期现象，稍后重试即可），正常补池约需 20~30 秒。

• --hold-seconds：每个 Sandbox 的业务持有时长；越长则单位时间领取次数越少。

• --duration-seconds：压测总时长，建议不小于扩容稳定窗口（默认 60 秒）的 3 倍，以观察至少两轮扩容。

预期现象：压测期间使用步骤四的命令观察，currentCapacity.available 下降、desiredReplicas 逐步抬升，说明容量策略检测到领取消耗并补充预热池。池被击穿时 create 虽返回 running，但数据面可能尚未就绪，首次调用返回 503 属预期现象，稍后重试即可。

验证缩容（可选）：流量结束后，手动调低 targetAvailable 并观察预热池收敛。

kubectl patch poolautoscaler sandbox-pool-autoscaler -n default \
  --type merge -p '{"spec":{"capacityPolicy":{"targetAvailable":"10%"}}}'
kubectl get sandboxset sandbox-pool -n default -w

预热池应逐步缩至 minReplicas（示例为 2）。验证完成后，将 targetAvailable 改回原值即可。

步骤四：观测扩缩容节奏与启动保护

kubectl get poolautoscaler sandbox-pool-autoscaler -n default -o yaml
kubectl get sandboxset sandbox-pool -n default -o yaml
kubectl describe poolautoscaler sandbox-pool-autoscaler -n default

重点查看 status.currentReplicas、status.desiredReplicas、status.currentCapacity.available 和 status.conditions。这些是最近一次调谐（Reconcile，控制器周期性将实际状态对齐期望状态的过程）的观测值，可能与 SandboxSet 的实时状态存在短暂偏差；可用 Sandbox 数为 0 时，status.currentCapacity.available 字段不显示。扩缩容动作与异常原因会以事件形式记录在 PoolAutoscaler 对象上，常见事件参见本文常见事件。

容量策略基于近期一段观察时间内的平均可用数量做决策，以平滑瞬时波动；首次扩缩容可以立即执行，后续按稳定窗口节奏执行：扩容稳定窗口默认 60 秒，缩容稳定窗口默认 300 秒，可通过 stabilizationWindowSeconds 调整（参见本文参数配置约束说明）。扩容稳定窗口的默认值已包含 Pending 超时的安全余量；配置更大的值时以配置值为准。

当 SandboxSet 当前 generation 的 ScalingLimited=True 时，PoolAutoscaler 暂停继续扩容，避免在启动失败或 Pending 超时已耗尽预算时继续提高目标；缩容不受此限制。正在创建的 Sandbox 的创建并发由 SandboxSet 控制，PoolAutoscaler 不直接管理 Pod。限流的触发条件、恢复方式与排查步骤参见本文故障排查：扩容限流的触发与恢复。

调参建议：从小范围配置起步——较小的 minReplicas、maxReplicas 和较长的缩容稳定窗口——结合启动成功率、领取延迟及预热成本逐步调整。若需临时观察或人工接管，可暂停自动扩缩容（恢复时设为 false 或删除该字段）：

kubectl patch poolautoscaler sandbox-pool-autoscaler -n default \
  --type merge -p '{"spec":{"suspend":true}}'

步骤五（可选）：删除 PoolAutoscaler

不再需要自动扩缩容时（例如业务下线或改为固定规模），可删除 PoolAutoscaler。删除后，SandboxSet 和现有 Sandbox 均会保留，SandboxSet 副本数维持在删除前的值，不会自动缩容；如需回收预热池，需再手动调整 spec.replicas 或删除 SandboxSet。

kubectl delete poolautoscaler sandbox-pool-autoscaler -n default

触发条件

SandboxSet 的 spec.scaleStrategy.maxUnavailable 同时作为启动预算；未设置时默认为当前副本数（相当于 100%，即需全部实例启动异常才触发限流）。注意它与 updateStrategy.maxUnavailable（滚动更新用，默认 20%）是不同字段。处于创建阶段的 Sandbox 按以下两类计数占用预算：

• Failed：Ready condition 为 False 且 reason 为 StartContainerFailed、PodCreateFailed 或 Unschedulable，即明确的启动失败（容器启动失败、镜像或配置错误、创建 API 失败、调度失败如节点资源不足或底层调度错误等）。

• TimedOut：长期停留在 Creating/ResourcePending 状态，且创建时间超过 Pending 超时阈值（默认 50 秒）仍未 Ready。该计数在 SandboxSet 的 status message 与事件中显示为 Timeout。

当 Failed + TimedOut >= 启动预算 时，SandboxSet 写入如下状态，同时发出 Warning 级 ScalingLimited 事件。

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxSet
metadata:
  name: sandbox-pool
  namespace: default
status:
  conditions:
    - type: ScalingLimited
      status: "True"
      reason: StartupBudgetExhausted
      message: '2 of 2 startup slots are blocked: Timeout=1, Failed=1'

PoolAutoscaler 检测到该 condition 后：

• 暂停扩容：status.desiredReplicas 不再抬升，即使可用数量已低于下水位；等待期间周期性发出 Normal 级 ScaleBlocked 事件。

• 缩容不受影响：上水位触发的缩容照常执行。

• 容错处理：仅当 SandboxSet 报告的是当前 generation 的显式 True 才阻塞；condition 缺失、陈旧或为 Unknown 时按无信号处理，扩容照常，避免升级或首次调谐期间误阻塞。

恢复方式

恢复不需要人工干预，满足任一条件后预算自动释放：

• 失败的 Sandbox 被删除（手动删除或业务侧清理），或其 Pod 恢复 Running 且 Ready 变为 True；

• Pending 超时的 Sandbox 完成启动进入 Running，或被删除。

当 Failed + TimedOut 降回预算以下，SandboxSet 下一次调谐会将 ScalingLimited 改回 False，PoolAutoscaler 随即恢复扩容并继续补池。

常见事件

PoolAutoscaler 在每次调谐时将扩缩容动作与异常原因记录为自身对象的事件，常用查看方式：

# 查看 PoolAutoscaler 的事件列表
kubectl describe poolautoscaler sandbox-pool-autoscaler -n default

# 按对象筛选事件
kubectl get events -n default --field-selector involvedObject.name=sandbox-pool-autoscaler

SandboxSet 自身在启动预算耗尽时会在其对象上发出 Warning 级 ScalingLimited 事件，与 PoolAutoscaler 侧的 ScaleBlocked 事件成对出现，详见本文故障排查：扩容限流的触发与恢复。

确保空闲预热池能收缩到 minReplicas

容量策略应保证空闲预热池能够收缩到 minReplicas，否则预热池会停留在 minReplicas 之上，空闲资源无法回收到预期下限。判定方法是检查最后一步缩容：当预热池副本数为 minReplicas + 1 时，上水位必须不大于 minReplicas，这一步缩容才能触发。

• 绝对值目标 T 与解析后的容差 D（含默认容差）：需满足 T + D <= minReplicas。满足时，空闲预热池的稳定规模就是 minReplicas。

• 百分比目标 p% 与百分比容差 q%（含默认容差）：需满足 p + q <= 100 × minReplicas / (minReplicas + 1)。百分比水位随预热池缩小而降低，空闲时会逐步收敛到 minReplicas。

• 百分比目标配绝对容差 D：在 minReplicas + 1 个副本处评估，需满足 ceil((minReplicas + 1) × p%) + D <= minReplicas。

• 绝对目标 T 配百分比容差 q%：容差按 ceil(T × q%) 解析，需满足 T + ceil(T × q%) <= minReplicas。

常见配置的效果如下：

场景一演示了百分比目标的配置方式：水位随池规模弹性伸缩，适合负载波动的业务。需要固定规模的预热池时，可改用绝对值目标并设置 tolerance: 0，同时让 minReplicas 不小于目标值。无论哪种方式，都请按上述规则核对 minReplicas。

如果预热池长期停留在高于 minReplicas 的规模且 status.conditions 无异常，通常是上述规则未满足：此时可调低 targetAvailable 或 tolerance，或调高 minReplicas，然后观察 status.desiredReplicas 与 status.currentCapacity.available 是否逐步收敛。

通用约束

容量策略约束

缩容可达性虽然不是当前版本的硬性校验，但配置不当会导致预热池无法缩至 minReplicas，建议按本文确保空闲预热池能收缩到 minReplicas 的规则核对。

cronPolicies 的校验规则（最多 20 条、name 唯一、五段合法 Cron 表达式、合法时区、targetReplicas >= 0）已在本文CRD 字段说明中标注，此处不再重复。