docs(warm-pool): add warm pool guide, ADR and examples

[Brend-Smits]

Warm pool stack (review in order; each PR is based on the previous one):

1. feat(compute-providers): add EC2 standby primitives for warm pools #5491 feat(compute-providers): add EC2 standby primitives for warm pools
2. feat(pool): keep a warm pool of stopped instances #5492 feat(pool): keep a warm pool of stopped instances
3. feat(scale-up): start warm instances before launching cold runners #5493 feat(scale-up): start warm instances before launching cold runners
4. feat(scale-down): sweep stopped warm instances #5494 feat(scale-down): sweep stopped warm instances
5. feat(runners): boot modes for warm pool instances #5495 feat(runners): boot modes for warm pool instances
6. feat(runners): add warm_pool option to the root module #5496 feat(runners): add warm_pool option to the root module
7. feat(multi-runner): support warm_pool in runner configs #5497 feat(multi-runner): support warm_pool in runner configs
8. docs(warm-pool): add warm pool guide, ADR and examples #5498 docs(warm-pool): add warm pool guide, ADR and examples (this PR)
9. fix(compute-providers): add warm pool boot modes to the EC2 template #5499 fix(compute-providers): add warm pool boot modes to the EC2 template
10. feat(runners): warm pool support for Windows runners #5500 feat(runners): warm pool support for Windows runners
11. fix(scale-down): do not sweep warm instances that are being activated #5501 fix(scale-down): do not sweep warm instances that are being activated
12. feat(pool): index warm instances and stay within the Spot API budget #5505 feat(pool): index warm instances and stay within the Spot API budget
13. fix(scale-up): start warm instances before registering them #5506 fix(scale-up): start warm instances before registering them
14. feat(pool): mark primed warm instances warm on their stop event #5507 feat(pool): mark primed warm instances warm on their stop event

Background

This PR adds a new type of runner pool called "warm runners". These runners are essentially 'stopped' after they booted up and will be booted up again next time there's demand for it. This greatly reduces job start up times as we don't have to rely on cold starts anymore.
I have only ran this in my dev environment so far, and it's working there. Have yet to deploy this to staging for extended testing.

Description

• ADR-0004 records the design: stopped standby instances owned by the pool lambda, on-demand and persistent spot, lease-based activation in scale-up, and cleanup in the pool and scale-down lambdas.
• docs/warm-pool.md covers configuration, lifecycle, spot behaviour, metrics, the custom user data requirement, burst tuning and troubleshooting.
• The multi-runner example gets on-demand and spot warm pool runner configs, and the default example shows the option commented out.

Test Plan

The full stack was deployed to a sandbox AWS account with the multi-runner example (on-demand and spot warm pools, legacy and v2 stacks). Covered: pool fill and refill, warm activation for single jobs and bursts of 5, 10 and 20 jobs with pools of 5, cold fallback for the remainder, drift and max-age eviction, spot interruption, disabling warm mode, and scale-down cleanup, with no leaked persistent spot requests. Warm jobs started in about 65-78 s from dispatch versus 133-198 s for cold runners in the same bursts.

Related Issues

Supersedes #5204.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Copilot review overview

🟡 Changes recommended

The migration command can affect unrelated deployments, and several lifecycle and disabling statements are inaccurate.

Review effort: Balanced
Findings: 4

Open (4)

• Clarify warm runners can execute multiple jobs · New
• Rename log metric to reflect pre-registration timing · New
• Prevent disabled pool configuration from requiring an owner · New
• Scope runner spot request cancellation to the deployment · New

What changed in this PR

Adds warm-pool architecture, configuration, operations, and migration documentation alongside runnable examples.

Changes:

• Adds a warm-pool guide and ADR.
• Adds on-demand and spot multi-runner examples.
• Updates navigation and v1-to-v2 configuration mapping.

File	Description
mkdocs.yaml	Adds guide and ADR navigation.
examples/​default/​main.tf	Shows optional warm-pool configuration.
examples/​multi-runner/​templates/​runner-configs/​linux-x64-warm.yaml	Adds an on-demand example.
examples/​multi-runner/​templates/​runner-configs/​linux-x64-warm-spot.yaml	Adds a spot example.
docs/​warm-pool.md	Documents configuration and operations.
docs/​multi-runner-v1-to-v2-configuration.md	Maps the warm-pool setting.
docs/​adr/​0004-warm-pool-standby.md	Records the architectural decision.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.