docs: add Cluster Autoscaler scale-up simulation design

[spencercjh]

Most of this Pull Request was generated or revised with the assistance of AI tools(Codex with GPT-5.6 Sol High). I have reviewed the resulting content and take full responsibility for its accuracy, security, licensing compliance, and inclusion in this project.

What type of PR is this?

/kind design

What this PR does / why we need it:

Adds a design document for integrating HAMi device scheduling with Cluster Autoscaler's scale-up simulation.

The document introduces Cluster Autoscaler, template nodes, warm node groups, and cold-zero node groups for readers who are not familiar with the autoscaler. It also explains why HAMi cannot determine device feasibility from a Node's Allocatable resources alone and how a side-effect-free simulation filter can reuse HAMi's device-specific Fit() logic.

The document records the capability that has been validated for a single Pod in a warm node group, then describes the work that remains before the integration can be released: a separate simulation contract, complete filter results and failure details, stateful multi-Pod simulation, stable device profiles for template nodes, production deployment controls, and upstream Cluster Autoscaler support.

Which issue(s) this PR fixes:

None.

Special notes for your reviewer:

This is a documentation-only change. The implementation and validation evidence are linked from the document, including HAMi PR #2046 and the experimental Cluster Autoscaler branch. Markdown links, numeric values, URLs, and whitespace have been checked against the reviewed source document.

Does this PR introduce a user-facing change?:

No. It adds design documentation and does not change runtime behavior.

Summary by CodeRabbit

• Documentation
  • Added a design document for simulating Cluster Autoscaler scale-up decisions with HAMi-aware device filtering.
  • Documented scheduling behavior, extender configuration, request and result handling, node-group scenarios, transient device states, and side-effect boundaries.
  • Outlined validation status and remaining work for broader simulation support, security, deployment, and upstream integration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6c7ad084-a1a5-4d8e-b6c1-747b04ea0ad8

📥 Commits

Reviewing files that changed from the base of the PR and between ef18216 and c9772c9.

📒 Files selected for processing (1)

• docs/develop/dry-run-filter-design.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/develop/dry-run-filter-design.md

---

📝 Walkthrough

Walkthrough

The pull request adds a design document for HAMi-aware Cluster Autoscaler scale-up simulation. It defines scheduling flows, extender contracts, transient device state, validation results, unsupported scenarios, and remaining implementation work.

Changes

HAMi-aware Cluster Autoscaler simulation

Layer / File(s)	Summary
Simulation model and integration contract docs/develop/dry-run-filter-design.md	Defines CA template-node simulation, scheduler filtering, extender configuration, request contracts, managed-resource handling, and warm and cold-zero node groups.
HAMi simulation filtering behavior docs/develop/dry-run-filter-design.md	Describes transient device reconstruction, request-local usage state, reuse of vendor Fit() logic, side-effect boundaries, failed-node reporting, and HTTP error handling.
Validation status and remaining work docs/develop/dry-run-filter-design.md	Records test and endpoint validation, supported and unsupported scenarios, terminology, references, and remaining work for simulation state, device profiles, security, concurrency, and upstream integration.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: lengrongfu, wawa0210

Poem

A rabbit maps the nodes with care,
HAMi filters test each spare.
Warm paths glow,
Cold paths show,
While design notes guide the hare.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the addition of the Cluster Autoscaler scale-up simulation design document.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/develop/dry-run-filter-design.md`:
- Around line 190-195: Add TLS certificate verification to the HTTPS extender
configuration by supplying the appropriate CA trust settings through tlsConfig,
including serverName or client credentials when required. If this example is
intentionally non-production, clearly mark the configuration as test-only
instead of leaving certificate verification implicitly disabled.
- Around line 207-215: Update the CA implementation requirements around extender
invocation to state that an omitted or empty managedResources list causes
kube-scheduler to call that extender for every Pod. Apply resource-intersection
filtering only when managedResources is non-empty, while preserving the existing
fast path for unrelated extenders.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7ffc8bab-c28c-40b9-bacb-b137c57b0002

📥 Commits

Reviewing files that changed from the base of the PR and between 59cbf76 and 86d84fc.

📒 Files selected for processing (1)

• docs/develop/dry-run-filter-design.md

[spencercjh]

/assign @fishman

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unittests	64.46% <ø> (+0.48%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 19 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mesutoezdil]

i think it looks good

[FouoF]

/lgtm

[hami-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: FouoF, spencercjh

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [FouoF]

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