docs: Add User Documentation for GPU Limiter and Scale-to-Zero Features

[ev-shindin]

Summary

Adds comprehensive user-facing documentation for the GPU Limiter and Scale-to-Zero features, along with cross-references throughout existing documentation to ensure discoverability.

Changes

New Documentation Files

File	Description
docs/user-guide/gpu-limiter.md	Complete user guide for GPU Limiter (Experimental) - 307 lines
docs/user-guide/scale-to-zero.md	Complete user guide for Scale-to-Zero - 405 lines
docs/user-guide/scale-from-zero.md	Placeholder for Scale-from-Zero documentation - 30 lines
config/samples/saturation-scaling-config.yaml	Sample ConfigMap with enableLimiter: true

Updated Documentation

File	Changes
README.md	Added GPU Limiter and Scale-to-Zero to Key Features section and User Guide links
docs/README.md	Added links to new user guides in documentation index
charts/workload-variant-autoscaler/README.md	Added configuration sections for GPU Limiter and Scale-to-Zero with Helm examples
charts/workload-variant-autoscaler/values.yaml	Improved comments for limitedMode and scaleToZero with doc references

Documentation Content

GPU Limiter (Experimental)

The GPU Limiter documentation covers:

• Problem statement: unfulfillable scale-up requests, unfair resource distribution
• Solution: resource-aware scaling that constrains decisions based on GPU availability
• Scaling pipeline diagram showing where limiter fits
• Greedy-by-saturation allocation algorithm explanation
• GPU type awareness (H100, A100, MI300X tracked separately)
• Configuration via saturation-scaling-config ConfigMap with enableLimiter: true
• Prerequisites: GPU operator, deployment GPU requirements
• Example scenarios: single model, multiple models competing, heterogeneous GPU types
• Troubleshooting and best practices

Scale-to-Zero

The Scale-to-Zero documentation covers:

• Problem statement: wasted GPU resources, higher costs for idle models
• Solution: automatic scaling to zero after configurable retention period
• Decision logic and retention period explanation
• Configuration via model-scale-to-zero-config ConfigMap
• Namespace-scoped overrides for multi-environment deployments
• Prerequisites: HPA feature gate, Prometheus metrics
• Example scenarios: development, production with mixed criticality, cost optimization
• Troubleshooting and best practices
• Reference to Scale-from-Zero for scaling back up

Scale-from-Zero (Placeholder)

Basic placeholder documentation noting:

• Feature monitors EPP queue for pending requests
• Automatically triggers scale-up when traffic arrives
• Works in conjunction with Scale-to-Zero
• Full documentation coming soon

Helm Chart Updates

Added configuration sections to chart README:

# GPU Limiter
wva:
  capacityScaling:
    default:
      enableLimiter: true

# Scale to Zero
wva:
  scaleToZero: true

Improved values.yaml comments:

# GPU Limiter mode - constrains scaling based on actual GPU availability (Experimental)
# When enabled, scale-up decisions are limited by available GPUs per accelerator type
# Uses greedy-by-saturation algorithm to prioritize most saturated models
# See docs/user-guide/gpu-limiter.md for details
limitedMode: false

# Scale to Zero - automatically scale idle models to zero replicas
# When enabled, models with no traffic for the retention period will scale to 0
# Requires: Kubernetes 1.27+ (HPAScaleToZero feature gate) and HPA minReplicas: 0
# Configure retention periods via model-scale-to-zero-config ConfigMap
# See docs/user-guide/scale-to-zero.md for details
scaleToZero: false

Related Issues

• Addresses documentation gap for GPU Limiter feature
• Addresses documentation gap for Scale-to-Zero feature
• Improves feature discoverability in main README

Checklist

• User guide for GPU Limiter created
• User guide for Scale-to-Zero created
• Placeholder for Scale-from-Zero created
• Main README updated with feature highlights
• docs/README.md index updated
• Helm chart README updated with configuration examples
• Helm values.yaml comments improved
• Sample ConfigMap added to config/samples/

[lionelvillard]

LGTM. Added few comments.

[lionelvillard]

We now have a troubleshooting guide. Can you move this section over there?

[ev-shindin]

I moved this to another to saturation-scaling-config.md. Or it should be in another file?

[lionelvillard]

I would make this pipeline more generic. Basically there is a pipeline block before GPU limiter and after it. The block before computes a desired number of replicas and the saturation analyzer is just an example.