feat(Flow Control)/Expand Flow Control capacity limits schema(resource.Quantity) (kubernetes-sigs#2492)

* feat(conf): add config `Limits` in EndponintPickerConfig
- add struct CapacityLimits
- add Limits Config in PriorityBandConfig and FlowControlConfig

* feat(config): Modify the MaxBytes configuration logic within the `NewConfigFromAPI` function:
- Add New Logic: Implement logic to write the new configuration field `Limit.MaxBytes` to a `uint64` variable, including the necessary type conversion.
- Remove Old Logic: Delete the existing logic responsible for writing the legacy `MaxBytes` configuration.

* chore(conf): supplyment the comment for new conf

* feat(conf): delete the old config `MaxBytes`
- use the new conf for the logs print

* refactor(config): extract `resolveMaxBytes` helper and improve Limits comments

* feat(test): change the `MaxBytes` in test to `Limit.MaxBytes`

* feat(test): add `ShouldSucceed_WithKubernetesQuantityFormat` to test the k8s case

* chore(deepcopy): remake `deepcopy.go`

* revert(config): flat the `Limits`

* chore(make): after `make`

* feat(docs): supplyment flow control docs for the description of `quantity format`

Author: BizerNotNull

apix/config/v1alpha1/endpointpickerconfig_types.go

@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"strings"
 
+	"k8s.io/apimachinery/pkg/api/resource"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
@@ -271,13 +272,11 @@ type ParserConfig struct {
 // FlowControlConfig configures the Flow Control layer.
 type FlowControlConfig struct {
 	// +optional
-	// MaxBytes defines the global capacity limit for the Flow Control system.
-	// It represents the maximum aggregate byte size of all active requests across all priority
-	// levels. If this limit is exceeded, new requests will be rejected even if their specific
-	// priority band has capacity.
-	// If 0 or omitted, no global limit is enforced (unlimited).
-	// Default: 0 (unlimited).
-	MaxBytes *int64 `json:"maxBytes,omitempty"`
+	// MaxBytes is the global maximum number of bytes allowed across all priority levels.
+	// If exceeded, new requests will be rejected even if their specific priority band has capacity.
+	// Accepts standard Kubernetes resource quantities (e.g., "1Gi", "500M").
+	// If not specified, no global limits are enforced.
+	MaxBytes *resource.Quantity `json:"maxBytes,omitempty"`
 
 	// +optional
 	// DefaultRequestTTL serves as a fallback timeout for requests that do not specify their own
@@ -315,9 +314,10 @@ type PriorityBandConfig struct {
 
 	// +optional
 	// MaxBytes is the maximum number of bytes allowed for this priority band.
-	// If 0 or omitted, the system default is used.
-	// Default: 1 GB.
-	MaxBytes *int64 `json:"maxBytes,omitempty"`
+	// If exceeded, new requests at this priority will be shed.
+	// Accepts standard Kubernetes resource quantities (e.g., "1Gi", "500M").
+	// If not specified, the system default is used (e.g., 1 GB).
+	MaxBytes *resource.Quantity `json:"maxBytes,omitempty"`
 
 	// +optional
 	// FairnessPolicyRef specifies the name of the policy that governs flow selection.

apix/config/v1alpha1/zz_generated.deepcopy.go

@@ -156,7 +156,7 @@ schedulingProfiles:
 featureGates:
 - flowControl
 flowControl:
-  maxBytes: 1024
+  maxBytes: "1024"
   defaultRequestTTL: 1m
 `
 
@@ -172,7 +172,7 @@ schedulingProfiles:
   - pluginRef: maxScore
 featureGates: [] # Explicitly empty
 flowControl:
-  maxBytes: 1024
+  maxBytes: "1024"
 `
 
 // successComplexFlowControlConfigText tests that Flow Control configuration with custom plugins is correctly loaded.

pkg/epp/config/loader/testdata_test.go

@@ -22,6 +22,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"k8s.io/apimachinery/pkg/api/resource"
 	"k8s.io/utils/ptr"
 
 	configapi "sigs.k8s.io/gateway-api-inference-extension/apix/config/v1alpha1"
@@ -71,11 +72,11 @@ func TestNewConfigFromAPI(t *testing.T) {
 		{
 			name: "Success - Explicit Values",
 			apiConfig: &configapi.FlowControlConfig{
-				MaxBytes: ptr.To(int64(2048)),
+				MaxBytes: ptr.To(resource.MustParse("2048")),
 			},
 			assertion: func(t *testing.T, cfg *Config) {
 				assert.Equal(t, uint64(2048), cfg.Registry.MaxBytes,
-					"MaxBytes should be correctly translated from int64 in API to uint64 in internal config")
+					"MaxBytes should be correctly translated from resource.Quantity in API to uint64 in internal config")
 			},
 		},
 	}

pkg/epp/flowcontrol/config_test.go

@@ -22,6 +22,7 @@ import (
 	"slices"
 	"time"
 
+	"k8s.io/apimachinery/pkg/api/resource"
 	"k8s.io/apimachinery/pkg/util/sets"
 
 	configapi "sigs.k8s.io/gateway-api-inference-extension/apix/config/v1alpha1"
@@ -347,6 +348,19 @@ func WithBandMaxBytes(maxBytes uint64) PriorityBandConfigOption {
 
 // --- Constructors ---
 
+// resolveMaxBytes extracts and validates MaxBytes from a resource.Quantity pointer.
+// Returns 0 (use default) if maxBytes is nil.
+func resolveMaxBytes(maxBytes *resource.Quantity) (uint64, error) {
+	if maxBytes == nil {
+		return 0, nil
+	}
+	v := maxBytes.Value()
+	if v < 0 {
+		return 0, fmt.Errorf("MaxBytes must be non-negative, got %d", v)
+	}
+	return uint64(v), nil
+}
+
 // NewConfigFromAPI creates a new Config by translating the API configuration.
 func NewConfigFromAPI(apiConfig *configapi.FlowControlConfig, handle plugin.Handle) (*Config, error) {
 	if apiConfig == nil {
@@ -355,11 +369,12 @@ func NewConfigFromAPI(apiConfig *configapi.FlowControlConfig, handle plugin.Hand
 
 	opts := make([]ConfigOption, 0, len(apiConfig.PriorityBands)+3)
 
-	if apiConfig.MaxBytes != nil {
-		if *apiConfig.MaxBytes < 0 {
-			return nil, fmt.Errorf("MaxBytes must be non-negative, got %d", *apiConfig.MaxBytes)
-		}
-		opts = append(opts, WithMaxBytes(uint64(*apiConfig.MaxBytes)))
+	maxBytes, err := resolveMaxBytes(apiConfig.MaxBytes)
+	if err != nil {
+		return nil, fmt.Errorf("global %w", err)
+	}
+	if maxBytes > 0 {
+		opts = append(opts, WithMaxBytes(maxBytes))
 	}
 
 	if apiConfig.DefaultPriorityBand != nil {
@@ -386,11 +401,12 @@ func buildDefaultPriorityBandTemplate(
 	apiBand *configapi.PriorityBandConfig,
 ) (*PriorityBandConfig, error) {
 	bandOpts := make([]PriorityBandConfigOption, 0, 3)
-	if apiBand.MaxBytes != nil {
-		if *apiBand.MaxBytes < 0 {
-			return nil, fmt.Errorf("DefaultPriorityBand MaxBytes must be non-negative, got %d", *apiBand.MaxBytes)
-		}
-		bandOpts = append(bandOpts, WithBandMaxBytes(uint64(*apiBand.MaxBytes)))
+	maxBytes, err := resolveMaxBytes(apiBand.MaxBytes)
+	if err != nil {
+		return nil, fmt.Errorf("DefaultPriorityBand %w", err)
+	}
+	if maxBytes > 0 {
+		bandOpts = append(bandOpts, WithBandMaxBytes(maxBytes))
 	}
 	if apiBand.OrderingPolicyRef != "" {
 		bandOpts = append(bandOpts, WithOrderingPolicy(apiBand.OrderingPolicyRef, handle))
@@ -409,11 +425,12 @@ func buildDefaultPriorityBandTemplate(
 
 func buildPriorityBand(handle plugin.Handle, band configapi.PriorityBandConfig) (*PriorityBandConfig, error) {
 	bandOpts := make([]PriorityBandConfigOption, 0, 3)
-	if band.MaxBytes != nil {
-		if *band.MaxBytes < 0 {
-			return nil, fmt.Errorf("priority band %d MaxBytes must be non-negative, got %d", band.Priority, *band.MaxBytes)
-		}
-		bandOpts = append(bandOpts, WithBandMaxBytes(uint64(*band.MaxBytes)))
+	maxBytes, err := resolveMaxBytes(band.MaxBytes)
+	if err != nil {
+		return nil, fmt.Errorf("priority band %d %w", band.Priority, err)
+	}
+	if maxBytes > 0 {
+		bandOpts = append(bandOpts, WithBandMaxBytes(maxBytes))
 	}
 	if band.OrderingPolicyRef != "" {
 		bandOpts = append(bandOpts, WithOrderingPolicy(band.OrderingPolicyRef, handle))

pkg/epp/flowcontrol/registry/config.go

@@ -22,6 +22,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"k8s.io/apimachinery/pkg/api/resource"
 	"k8s.io/utils/ptr"
 
 	configapi "sigs.k8s.io/gateway-api-inference-extension/apix/config/v1alpha1"
@@ -529,15 +530,15 @@ func TestNewConfigFromAPI(t *testing.T) {
 		{
 			name: "ShouldSucceed_WithFullConfiguration",
 			apiConfig: &configapi.FlowControlConfig{
-				MaxBytes: ptr.To(int64(100)),
+				MaxBytes: ptr.To(resource.MustParse("100")),
 				PriorityBands: []configapi.PriorityBandConfig{
 					{
 						Priority: 1,
-						MaxBytes: ptr.To(int64(50)),
+						MaxBytes: ptr.To(resource.MustParse("50")),
 					},
 				},
 				DefaultPriorityBand: &configapi.PriorityBandConfig{
-					MaxBytes: ptr.To(int64(10)),
+					MaxBytes: ptr.To(resource.MustParse("10")),
 				},
 			},
 			assertion: func(t *testing.T, cfg *Config) {
@@ -555,6 +556,25 @@ func TestNewConfigFromAPI(t *testing.T) {
 					"DefaultPriorityBand template MaxBytes should be translated")
 			},
 		},
+		{
+			name: "ShouldSucceed_WithKubernetesQuantityFormat",
+			apiConfig: &configapi.FlowControlConfig{
+				MaxBytes: ptr.To(resource.MustParse("1Gi")),
+				PriorityBands: []configapi.PriorityBandConfig{
+					{
+						Priority: 1,
+						MaxBytes: ptr.To(resource.MustParse("500Mi")),
+					},
+				},
+			},
+			assertion: func(t *testing.T, cfg *Config) {
+				assert.Equal(t, uint64(1073741824), cfg.MaxBytes,
+					"1Gi should be correctly parsed as 1073741824 bytes")
+				require.Contains(t, cfg.PriorityBands, 1)
+				assert.Equal(t, uint64(524288000), cfg.PriorityBands[1].MaxBytes,
+					"500Mi should be correctly parsed as 524288000 bytes")
+			},
+		},
 		{
 			name: "ShouldSucceed_WithPolicyReferences",
 			apiConfig: &configapi.FlowControlConfig{
@@ -626,7 +646,7 @@ func TestNewConfigFromAPI(t *testing.T) {
 				PriorityBands: []configapi.PriorityBandConfig{
 					{
 						Priority: 1,
-						MaxBytes: ptr.To(int64(0)), // Explicitly zero
+						MaxBytes: ptr.To(resource.MustParse("0")), // Explicitly zero
 					},
 				},
 			},
@@ -640,7 +660,7 @@ func TestNewConfigFromAPI(t *testing.T) {
 			name: "ShouldApplyDefault_WhenDefaultPriorityBandMaxBytesIsZero",
 			apiConfig: &configapi.FlowControlConfig{
 				DefaultPriorityBand: &configapi.PriorityBandConfig{
-					MaxBytes: ptr.To(int64(0)), // Explicitly zero
+					MaxBytes: ptr.To(resource.MustParse("0")), // Explicitly zero
 				},
 			},
 			assertion: func(t *testing.T, cfg *Config) {
@@ -654,17 +674,17 @@ func TestNewConfigFromAPI(t *testing.T) {
 		{
 			name: "ShouldError_WithNegativeGlobalMaxBytes",
 			apiConfig: &configapi.FlowControlConfig{
-				MaxBytes: ptr.To(int64(-1)),
+				MaxBytes: ptr.To(resource.MustParse("-1")),
 			},
-			expectedErr: "MaxBytes must be non-negative",
+			expectedErr: "global MaxBytes must be non-negative",
 		},
 		{
 			name: "ShouldError_WithNegativePriorityBandMaxBytes",
 			apiConfig: &configapi.FlowControlConfig{
 				PriorityBands: []configapi.PriorityBandConfig{
 					{
 						Priority: 1,
-						MaxBytes: ptr.To(int64(-100)),
+						MaxBytes: ptr.To(resource.MustParse("-100")),
 					},
 				},
 			},
@@ -674,7 +694,7 @@ func TestNewConfigFromAPI(t *testing.T) {
 			name: "ShouldError_WithNegativeDefaultPriorityBandMaxBytes",
 			apiConfig: &configapi.FlowControlConfig{
 				DefaultPriorityBand: &configapi.PriorityBandConfig{
-					MaxBytes: ptr.To(int64(-5)),
+					MaxBytes: ptr.To(resource.MustParse("-5")),
 				},
 			},
 			expectedErr: "DefaultPriorityBand MaxBytes must be non-negative",

pkg/epp/flowcontrol/registry/config_test.go

@@ -400,20 +400,21 @@ form:
 
 ```yaml
 flowControl:
-  maxBytes: 10737418240 # 10 GB
+  maxBytes: 10Gi # 10737418240 bytes
   defaultRequestTTL: 60s
   defaultPriorityBand:
-    maxBytes: 1073741824
+    maxBytes: 10Gi
   priorityBands:
   - priority: 100
-    maxBytes: 5368709120
+    maxBytes: 5Gi
     orderingPolicyRef: fcfs-ordering-policy
     fairnessPolicyRef: global-strict-fairness-policy
 ```
 
 The fields in the `flowControl` section are:
 
-- `maxBytes`: Defines the global capacity limit (in bytes) for all active requests across all priority levels.
+- `maxBytes`: Defines the global capacity limit for all active requests across all priority levels.
+    - Supports Kubernetes quantity format (e.g., `10Gi`, `512Mi`, `1048576Ki`) as well as plain integers (in bytes).
     - If `0` or omitted, no global limit is enforced (unlimited), though individual priority band limits still apply.
 - `defaultRequestTTL`: A fallback timeout for requests that do not specify their own deadline.
     - If `0` or omitted, it defaults to the client context deadline, meaning requests may wait indefinitely unless cancelled by the client.
@@ -427,6 +428,7 @@ Both the `defaultPriorityBand` template and the entries in `priorityBands` use t
 
 - `priority`: (Required for `priorityBands` entries) The integer priority level. Higher values indicate higher priority.
 - `maxBytes`: The maximum aggregate byte size allowed for this specific priority band.
+    - Supports Kubernetes quantity format (e.g., `5Gi`, `512Mi`) as well as plain integers (in bytes).
     - If `0` or omitted, the system default (1 GB) is used.
 - `orderingPolicyRef`: The name of the Ordering Policy plugin to use (e.g., `fcfs-ordering-policy`).
     - Defaults to `fcfs-ordering-policy` if omitted.