Skip to content

docs(kruiseagents): add PoolAutoscaler user manual - #401

Merged
furykerry merged 5 commits into
openkruise:masterfrom
ywExcellent:docs/poolautoscaler-user-manual
Sep 10, 2026
Merged

docs(kruiseagents): add PoolAutoscaler user manual#401
furykerry merged 5 commits into
openkruise:masterfrom
ywExcellent:docs/poolautoscaler-user-manual

Conversation

@ywExcellent

@ywExcellent ywExcellent commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

Ⅰ. Describe what this PR does

Adds a bilingual (EN/ZH) user manual for PoolAutoscaler, the warm-pool autoscaling capability of Kruise Agents, covering:

  • Background and use cases: when to use PoolAutoscaler vs. metric-based autoscaling
  • Step-by-step guide:
    1. Create the warm-pool SandboxSet (with runtime injection required for E2B verification)
    2. Configure the PoolAutoscaler capacity policy (percentage-based demo)
    3. Run business traffic to verify scaling, using an embedded single-file Python script based on the E2B SDK (no local test project needed)
    4. Observe scaling behavior and startup protection (ScalingLimited)
    5. Optionally remove the policy when no longer needed
  • Capacity policy watermarks and scale-down reachability: how targets and tolerance form the dead zone, the minReplicas+1 upper-watermark rule, and why targetAvailable: "100%" makes an idle pool never shrink
  • Parameter configuration constraints: webhook validation rules for general fields, capacity policy, and cron policies
  • Exception scenarios: scale-up rate limiting — budget source (scaleStrategy.maxUnavailable), Failed/TimedOut counters, ScalingLimited condition, automatic recovery, and troubleshooting commands
  • CRD field reference

The page is registered in sidebars-kruiseagents.js under User Manuals, right after Warm Pool Management, which it builds upon.

Ⅱ. Does this pull request fix one issue?

NONE

Ⅲ. Describe how to verify it

  1. Both language versions are added in the same change and stay structurally aligned (headings, code blocks, embedded script are byte-identical).
  2. Embedded verification script: extracted with sed, passes python3 -m py_compile; --help and the missing-E2B_API_KEY error path verified.
  3. Sidebar entry registered; node -e "require('./sidebars-kruiseagents.js')" passes.
  4. Constraint tables cross-checked against pkg/webhook/poolautoscaler/validating in openkruise/agents.

Ⅳ. Special notes for reviews

  • Follows the bilingual doc contract from the repo AGENTS.md: EN source + ZH mirror added together, same structure.
  • The verification script intentionally keeps only the core business loop (create → run_code → file write/read → command → hold → kill); pool observation is left to the kubectl commands in step 4.
  • Requires PoolAutoscaler GA in the agents repo (feature gate default-on landed as feat(poolautoscaler): enable feature gate by default agents#938).

@kruise-bot

kruise-bot commented Sep 7, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign ls-2018 for approval by writing /assign @ls-2018 in a comment. For more information see:The Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kruise-bot

kruise-bot commented Sep 7, 2026

Copy link
Copy Markdown

Welcome @ywExcellent! It looks like this is your first PR to openkruise/openkruise.io 🎉

少师
docs(kruiseagents): add PoolAutoscaler user manual
c1024fb 
Add a bilingual (EN/ZH) user manual for PoolAutoscaler covering:

- Background, use cases, and prerequisites
- Step-by-step guide: create the warm pool SandboxSet, configure the
  PoolAutoscaler capacity policy, run business traffic to verify scaling
  (with an embedded single-file verification script), observe scaling and
  startup protection, and optionally remove the policy
- Capacity policy watermarks and scale-down reachability constraints
  (including the 100% target pitfall)
- Parameter configuration constraints from webhook validation
- Exception scenarios: scale-up rate limiting (ScalingLimited) trigger and
  recovery
- CRD field reference

Both language versions are added in the same change and the page is
registered in sidebars-kruiseagents.js after Warm Pool Management.

Signed-off-by: 少师 <zengyuwei.zyw@alibaba-inc.com>
@ywExcellent
ywExcellent force-pushed the docs/poolautoscaler-user-manual branch from 30ca89e to c1024fb Compare September 7, 2026 14:34
furykerry
furykerry reviewed Sep 10, 2026
View reviewed changes
Comment thread kruiseagents/user-manuals/poolautoscaler.md Outdated
The SandboxSet's `spec.scaleStrategy.maxUnavailable` doubles as the startup budget; when unset it defaults to the current replica count (equivalent to 100%, i.e. no cap on concurrent scale-up). Note this is a different field from `updateStrategy.maxUnavailable` (for rolling updates, default 20%). Sandboxes in the creating phase occupy the budget through two counters:

- **Failed**: Ready condition is `False` with reason `StartContainerFailed` or `PodCreateFailed` — a definitive startup failure (container startup failure, image/config errors, create API failures, etc.).
- **TimedOut**: stuck in Creating/ResourcePending longer than 50 seconds (the built-in pending timeout) without becoming Ready.

@furykerry furykerry Sep 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add schedule failed reason?

Comment thread kruiseagents/user-manuals/poolautoscaler.md
Comment thread kruiseagents/user-manuals/poolautoscaler.md Outdated

- **Mostly TimedOut**: the underlying creation speed cannot keep up with the scaling rhythm. Lower the SandboxSet's `scaleStrategy.maxUnavailable` to reduce the per-batch creation volume, or contact the cluster administrator to evaluate underlying supply capacity.

## Capacity Policy Parameters and Scale-Down Reachability

@furykerry furykerry Sep 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider rephrase the title as Capacity Policy Parameters Tuning Guide

Comment thread kruiseagents/user-manuals/poolautoscaler.md Outdated
少师 and others added 4 commits September 10, 2026 14:41
少师
docs(kruiseagents): address review feedback on PoolAutoscaler manual
f125b9b 
- Add Unschedulable to the Failed startup-blocker reasons (schedule failures)
- Add apiVersion/kind to the ScalingLimited condition YAML example
- Rename 'Capacity Policy Parameters and Scale-Down Reachability' to
  'Capacity Policy Parameters Tuning Guide' and update anchor references
- Document the startup-budget role of scaleStrategy.maxUnavailable in
  warmpool-management.md with a link to the PoolAutoscaler manual
- Apply the same changes to the Simplified Chinese mirror

Signed-off-by: 少师 <zengyuwei.zyw@alibaba-inc.com>
少师
docs(kruiseagents): align scaleStrategy.maxUnavailable doc with start…
331695f 
…up-budget semantics

agents #910 changed scaleStrategy.maxUnavailable from a general
unavailable-replica budget to a startup-failure budget: healthy
Creating sandboxes no longer consume the budget, and batches no
longer wait for the previous batch to become available.

- Describe the field as a per-batch creation cap and the startup
  budget, instead of a cap on concurrently creating sandboxes
- Fix the batching tip: the next batch is issued once the controller
  observes the previous batch, not after it becomes available
- Clarify that only definitively failing sandboxes (failed reasons or
  pending timeout) occupy the budget; healthy creating ones do not
- Fix the REPLICAS column description: claimed sandboxes are not
  counted (creating + available only)
- Add the UPDATEDREPLICAS/UPDATEDAVAILABLEREPLICAS columns to the
  kubectl get sbs example to match the CRD printer columns
- Apply the same changes to the Simplified Chinese mirror

Signed-off-by: 少师 <zengyuwei.zyw@alibaba-inc.com>
@furykerry
docs(kruiseagents): refine PoolAutoscaler guidance
7173e07 
Keep the warm-pool example platform-neutral and clarify its English guidance.

Signed-off-by: 守辰 <shouchen.zz@alibaba-inc.com>
@furykerry
Merge remote PoolAutoscaler documentation updates
9070167 
Integrate reviewed upstream documentation changes with the platform-neutral PoolAutoscaler example.

Signed-off-by: 守辰 <shouchen.zz@alibaba-inc.com>
@furykerry
furykerry merged commit ffa8ba1 into openkruise:master Sep 10, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@furykerry furykerry furykerry left review comments
@zmberg zmberg Awaiting requested review from zmberg

Assignees

No one assigned

Labels

size/XL

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@ywExcellent @kruise-bot @furykerry