feat: usage limit policy plugin

[evacchi]

What type of PR is this?

/kind feature

What this PR does / why we need it:

This PR introduces pluggable UsageLimitPolicy interface. The goal is to complement "Improved Flow Control Request Management". The PR is a follow up to the initial discussion in #2268

The interfaces may be used to implement the proposal in the doc, as well as dynamically-adaptable behavior (as demonstrated here).

a UsageLimitPolicy returns a list of "ceilings" for a given list of priorities:

	// ComputeLimit calculates usage ceilings for all currently active priority levels based on current
	// saturation. The plugin observes the active priority domain (which changes dynamically as workloads
	// come and go) and computes relative ceilings from scratch on each call.
	//
	// Parameters:
	//   - ctx: Request context for logging, tracing, etc.
	//   - saturation: Current pool-wide resource saturation as a fraction [0.0, 1.0]
	//   - priorities: Ordered list of currently active priority levels (highest first)
	//
	// Returns:
	//   - ceilings: Computed ceiling for each given priority (n-th ceiling is assigned to the given n-th priority)
	//     - 0.0 = fully gated (cannot dispatch regardless of current saturation)
	//     - 1.0 = no gating (can dispatch until fully saturated)
	//     - Values between 0.0 and 1.0 reserve capacity headroom
	//
	ComputeLimit(ctx context.Context, saturation float64, priorities []int) (ceilings []float64)

We provide a few example/utility implementations:

• a usagelimits.DefaultPolicy() that always returns 1.0 for all given priorities
• a usagelimits.NewConstPolicy(usageLimitName string, threshold float64) constructor for fixed thresholds for all given priorities
• a usagelimits.NewPolicyFunc(...) constructor to define a policy by a func
• an example of registering and accessing a custom policy via config
• an example of a linear spacing policy as described in feat: pool-wide saturation, usage limit policy and evictor #2268 (comment)

Note

This PR implicitly requires pool-wide saturation addressed in #2343; thus, this PR should ideally be merged after #2343, and it's likely to require a rebase then.

Which issue(s) this PR fixes:

Related #1861, #2268, #2343, Improved Flow Control Request Management

Does this PR introduce a user-facing change?:

NONE

[netlify]

✅ Deploy Preview for gateway-api-inference-extension ready!

Name	Link
🔨 Latest commit	abf251f
🔍 Latest deploy log	https://app.netlify.com/projects/gateway-api-inference-extension/deploys/69cea1c108b5f90008900eef
😎 Deploy Preview	https://deploy-preview-2530--gateway-api-inference-extension.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[k8s-ci-robot]

Hi @evacchi. 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.

[LukeAVanDrie]

The new interface and its integration LGTM. Thanks for picking this up! I just have some feedback on the config loading path so we are consistent with other plugins.

[LukeAVanDrie]

nit: We may be getting to a point where we want to group dependencies into a config struct. Not blocking this PR on this refactoring effort though.

E.g.,

type Dependencies struct {
    Registry           contracts.FlowRegistry
    SaturationDetector contracts.SaturationDetector
    PodLocator         contracts.PodLocator
    UsageLimitPolicy   flowcontrol.UsageLimitPolicy
    Clock              clock.WithTicker
}
...
func NewFlowController(ctx context.Context, poolName string, config *Config, deps Dependencies) { ... }

[evacchi]

very good point, been thinking the same. Let's schedule this and the other refactoring. I can take this one if you'd like

[ahg-g]

do we have an issue tracking all followups?

[evacchi]

created issue for this #2764 will self-assign (the other one, i.e. unwrap the config value, I am doing in this PR)

[evacchi]

thanks for suggestions, will address this tomorrow!

[evacchi]

rebasing

[evacchi]

double-checked integration into llm-d-inference-scheduler with a plugin impl there, and it should be fine

[LukeAVanDrie]

/lgtm
/approve

@ahg-g; mind taking a look at this when you get a moment?

[ahg-g]

/ok-to-test

[evacchi]

@ahg-g good to go now

[ahg-g]

do we have an issue tracking all followups?

[ahg-g]

/approve
/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ahg-g, evacchi, LukeAVanDrie

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 [ahg-g]

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