feat: implement Balanced consolidation policy

[jamesmt-aws]

Summary

Implements the Balanced consolidation policy from the RFC in #2942. Gated behind --feature-gates BalancedConsolidation=true, disabled by default.

Balanced scores each consolidation move by comparing savings and disruption as fractions of NodePool totals. A move is approved when score >= 1/consolidationThreshold. The scoring step is a filter inserted after scheduling feasibility and price comparison. It can only reject moves, never create them.

Changes

API (21 lines in nodepool.go, nodepool_status.go):

• consolidationPolicy: Balanced (new enum value)
• consolidationThreshold: 1-3 (default 2, CEL-validated to require Balanced)
• ConsolidationPolicyUnsupported status condition (set when gate is disabled)

Scoring (252 lines in new balanced.go):

• ScoreMove: the RFC formula (savings_fraction / disruption_fraction)
• ComputeNodePoolTotals: computed from all candidates before ShouldDisrupt filtering
• EvaluateBalancedMove: cross-NodePool support (each Balanced pool scored independently)
• candidateSavingsRatio: scoring-consistent sort key for candidate ranking

Integration (~30 lines each in singlenodeconsolidation.go, multinodeconsolidation.go):

• Scoring check after computeConsolidation / firstNConsolidationOption
• Events emitted on Node+NodeClaim (single-node) or NodePool (multi-node)
• Metrics recorded (histogram + counter)

Observability (71 lines in events.go, 19 lines in metrics.go):

• ConsolidationApproved / ConsolidationRejected events with score, threshold, savings%, disruption%
• karpenter_consolidation_score histogram (buckets: 0.1, 0.25, 0.33, 0.5, 1.0, 2.0, 5.0, 10.0)
• karpenter_consolidation_moves_total counter by decision and NodePool

Lines changed in existing code paths when Balanced is NOT used: 4 (new _ return values from GetCandidates). Everything else is behind ConsolidationPolicyBalanced or BalancedConsolidation feature gate checks.

Test plan

31 new tests:

• 15 unit tests covering all RFC worked examples (Oversized Node 2.81, Marginal Move 0.42, scale invariance, heterogeneous disruption, etc.)
• 9 integration tests (NodePool totals, cross-pool evaluation, candidate price edge cases)
• 3 feature gate tests (rejected when off, accepted when on, WhenEmptyOrUnderutilized unaffected)
• 5 validation tests (threshold requires Balanced, boundary values [1,3])
• 4 defaulting tests (nil -> 2 for Balanced, preserved when explicit, nil for non-Balanced)
• 4 score-based ranking tests (sort order with/without Balanced candidates)
• 1 ConsolidationPolicyUnsupported status condition test

ok  sigs.k8s.io/karpenter/pkg/controllers/disruption  63.219s
ok  sigs.k8s.io/karpenter/pkg/apis/v1                 6.694s

Related

• RFC: docs: Balanced consolidation policy RFC #2942
• Depends on: fix: use injected clock for minDrainTime check #2951 (minDrainTime clock fix, unrelated but CI fails without it)

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: jamesmt-aws
Once this PR has been reviewed and has the lgtm label, please assign njtran for approval. For more information see the 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:

• OWNERS

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

[k8s-ci-robot]

Hi @jamesmt-aws. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[jamesmt-aws]

Note: the RFC discussion (#2942) has an open question about whether this should be a new `Balanced` policy or a `consolidationThreshold` parameter on the existing `WhenEmptyOrUnderutilized`. The implementation supports either direction with minimal changes. If the decision is to go with a threshold on `WhenEmptyOrUnderutilized`, the scoring logic and tests are unchanged. The API surface changes are: remove the `Balanced` enum value, allow `consolidationThreshold` on `WhenEmptyOrUnderutilized`, and update `ShouldDisrupt` to check the threshold instead of the policy.