Enhancement Description

• One-line enhancement description (can be used as a release note):
  Expose or otherwise provide a machine-readable view of the most recent HorizontalPodAutoscaler scaling decision to help users understand why a specific desired replica count was selected.
• Kubernetes Enhancement Proposal:
  　KEP-6107: Improve HPA explainability for operational tooling #6111
• Discussion Link: https://kubernetes.slack.com/archives/C09R1LV8S/p1778593168018659
• PRs by stage and milestone:
  • Alpha -  v1.37, tentative
    • KEP (k/enhancements) update PR(s):
    • Code (k/k) update PR(s):
    • Docs (k/website) update PR(s):

Please keep this description up to date. This will help the Enhancement Team to track the evolution of the enhancement efficiently.

/sig autoscaling

Summary

HorizontalPodAutoscaler currently exposes status fields such as currentReplicas, desiredReplicas, currentMetrics, and conditions.

These fields are useful, but when multiple metrics are configured, it can still be difficult to understand why a particular desiredReplicas value was selected.

This enhancement proposes improving HPA explainability by providing a machine-readable view of the most recent scaling decision. The goal is to improve troubleshooting and observability without changing the HPA scaling algorithm.

One possible API surface is HPA status, but this issue does not assume that status is the only or final design. Other options, such as conditions, events, or another mechanism, should be discussed with SIG Autoscaling.

The initial Alpha scope would be limited to the most recent reconciliation decision only.

Possible information exposed by the decision trace may include:

• selected or driving metric
• per-metric proposed replicas
• invalid metric reasons
• final decision reason
• whether the final decision was affected by limits, stabilization, tolerance, or invalid metrics

Open questions:

• What is the appropriate API surface for this information?
• Should this be guarded by a feature gate?
• What is the minimal useful Alpha scope?
• How can we avoid exposing controller implementation details that would make the API hard to evolve?
• How should this relate to existing HPA status fields, conditions, events, and controller logs?

One possible API surface is HPA status, but this issue does not assume that status is the only or final design.