Skip to content

feat: add optional name field to RateLimitRule for improved observability #9466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Aias00 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat: add optional name field to RateLimitRule for improved observability #9466

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
53b621d
feat: add optional name field to RateLimitRule for improved observabi…
Aias00 Jul 9, 2026
c7ba8d1
release-notes: correct scope of named RateLimitRule to local and global
Aias00 Jul 10, 2026
7f71d3d
fix: resolve CI lint and gen-check failures for RateLimitRule name
Aias00 Jul 10, 2026
5d5c7d3
test: sync helm CRD snapshots for RateLimitRule name field
Aias00 Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions api/v1alpha1/ratelimit_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ type GlobalRateLimit struct {
// to rate limit the request.
//
// +kubebuilder:validation:MaxItems=256
// +kubebuilder:validation:XValidation:rule="self.all(r, !has(r.name) || self.filter(r2, has(r2.name) && r2.name == r.name).size() == 1)", message="rate limit rule names must be unique within the global rules slice"
Rules []RateLimitRule `json:"rules"`
}

Expand All @@ -69,6 +70,7 @@ type LocalRateLimit struct {
// +kubebuilder:validation:MaxItems=16
// +kubebuilder:validation:XValidation:rule="self.all(r, !has(r.cost) || !has(r.cost.response))", message="response cost is not supported for Local Rate Limits"
// +kubebuilder:validation:XValidation:rule="self.all(r, !has(r.limit.fromMetadata))", message="limit fromMetadata is not supported for Local Rate Limits"
// +kubebuilder:validation:XValidation:rule="self.all(r, !has(r.name) || self.filter(r2, has(r2.name) && r2.name == r.name).size() == 1)", message="rate limit rule names must be unique within the local rules slice"
Rules []RateLimitRule `json:"rules"`
}

Expand All @@ -92,6 +94,22 @@ const (
// RateLimitRule defines the semantics for matching attributes
// from the incoming requests, and setting limits for them.
type RateLimitRule struct {
// Name is a user-facing name for this rule that can be used for debugging
// and observability. When set, the rate limit key will include this name,
// making it easier to identify in metrics and dashboards.
// The name must be unique within a policy and should be a stable identifier
// that won't change when the rule order changes.
//
// When name is set, the rate limit key format becomes:
// <policy-namespace>/<policy-name>/rule/<rule-name>
// When name is not set, the format remains:
// <policy-namespace>/<policy-name>/rule/<rule-index>
//
// +optional
// +kubebuilder:validation:MaxLength=64
// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9._-]+$`
// +kubebuilder:validation:XValidation:rule="!self.matches('^[0-9]+$')", message="rate limit rule name must not be purely numeric to avoid collision with auto-generated index-based rule names"
Name *string `json:"name,omitempty"`
// ClientSelectors holds the list of select conditions to select
// specific clients using attributes from the traffic flow.
// All individual select conditions must hold True for this rule
Expand Down
5 changes: 5 additions & 0 deletions api/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

49 changes: 49 additions & 0 deletions ...s/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1847,6 +1847,26 @@ spec:
- requests
- unit
type: object
name:
description: |-
Name is a user-facing name for this rule that can be used for debugging
and observability. When set, the rate limit key will include this name,
making it easier to identify in metrics and dashboards.
The name must be unique within a policy and should be a stable identifier
that won't change when the rule order changes.

When name is set, the rate limit key format becomes:
<policy-namespace>/<policy-name>/rule/<rule-name>
When name is not set, the format remains:
<policy-namespace>/<policy-name>/rule/<rule-index>
maxLength: 64
pattern: ^[a-zA-Z0-9._-]+$
type: string
x-kubernetes-validations:
- message: rate limit rule name must not be purely numeric
to avoid collision with auto-generated index-based
rule names
rule: '!self.matches(''^[0-9]+$'')'
shadowMode:
description: |-
ShadowMode indicates whether this rate-limit rule runs in shadow mode.
Expand Down Expand Up @@ -1876,6 +1896,11 @@ spec:
type: object
maxItems: 256
type: array
x-kubernetes-validations:
- message: rate limit rule names must be unique within the
global rules slice
rule: self.all(r, !has(r.name) || self.filter(r2, has(r2.name)
&& r2.name == r.name).size() == 1)
required:
- rules
type: object
Expand Down Expand Up @@ -2258,6 +2283,26 @@ spec:
- requests
- unit
type: object
name:
description: |-
Name is a user-facing name for this rule that can be used for debugging
and observability. When set, the rate limit key will include this name,
making it easier to identify in metrics and dashboards.
The name must be unique within a policy and should be a stable identifier
that won't change when the rule order changes.

When name is set, the rate limit key format becomes:
<policy-namespace>/<policy-name>/rule/<rule-name>
When name is not set, the format remains:
<policy-namespace>/<policy-name>/rule/<rule-index>
maxLength: 64
pattern: ^[a-zA-Z0-9._-]+$
type: string
x-kubernetes-validations:
- message: rate limit rule name must not be purely numeric
to avoid collision with auto-generated index-based
rule names
rule: '!self.matches(''^[0-9]+$'')'
shadowMode:
description: |-
ShadowMode indicates whether this rate-limit rule runs in shadow mode.
Expand Down Expand Up @@ -2293,6 +2338,10 @@ spec:
- message: limit fromMetadata is not supported for Local Rate
Limits
rule: self.all(r, !has(r.limit.fromMetadata))
- message: rate limit rule names must be unique within the
local rules slice
rule: self.all(r, !has(r.name) || self.filter(r2, has(r2.name)
&& r2.name == r.name).size() == 1)
type: object
type:
description: |-
Expand Down
49 changes: 49 additions & 0 deletions ...gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1846,6 +1846,26 @@ spec:
- requests
- unit
type: object
name:
description: |-
Name is a user-facing name for this rule that can be used for debugging
and observability. When set, the rate limit key will include this name,
making it easier to identify in metrics and dashboards.
The name must be unique within a policy and should be a stable identifier
that won't change when the rule order changes.

When name is set, the rate limit key format becomes:
<policy-namespace>/<policy-name>/rule/<rule-name>
When name is not set, the format remains:
<policy-namespace>/<policy-name>/rule/<rule-index>
maxLength: 64
pattern: ^[a-zA-Z0-9._-]+$
type: string
x-kubernetes-validations:
- message: rate limit rule name must not be purely numeric
to avoid collision with auto-generated index-based
rule names
rule: '!self.matches(''^[0-9]+$'')'
shadowMode:
description: |-
ShadowMode indicates whether this rate-limit rule runs in shadow mode.
Expand Down Expand Up @@ -1875,6 +1895,11 @@ spec:
type: object
maxItems: 256
type: array
x-kubernetes-validations:
- message: rate limit rule names must be unique within the
global rules slice
rule: self.all(r, !has(r.name) || self.filter(r2, has(r2.name)
&& r2.name == r.name).size() == 1)
required:
- rules
type: object
Expand Down Expand Up @@ -2257,6 +2282,26 @@ spec:
- requests
- unit
type: object
name:
description: |-
Name is a user-facing name for this rule that can be used for debugging
and observability. When set, the rate limit key will include this name,
making it easier to identify in metrics and dashboards.
The name must be unique within a policy and should be a stable identifier
that won't change when the rule order changes.

When name is set, the rate limit key format becomes:
<policy-namespace>/<policy-name>/rule/<rule-name>
When name is not set, the format remains:
<policy-namespace>/<policy-name>/rule/<rule-index>
maxLength: 64
pattern: ^[a-zA-Z0-9._-]+$
type: string
x-kubernetes-validations:
- message: rate limit rule name must not be purely numeric
to avoid collision with auto-generated index-based
rule names
rule: '!self.matches(''^[0-9]+$'')'
shadowMode:
description: |-
ShadowMode indicates whether this rate-limit rule runs in shadow mode.
Expand Down Expand Up @@ -2292,6 +2337,10 @@ spec:
- message: limit fromMetadata is not supported for Local Rate
Limits
rule: self.all(r, !has(r.limit.fromMetadata))
- message: rate limit rule names must be unique within the
local rules slice
rule: self.all(r, !has(r.name) || self.filter(r2, has(r2.name)
&& r2.name == r.name).size() == 1)
type: object
type:
description: |-
Expand Down
8 changes: 4 additions & 4 deletions internal/gatewayapi/backendtrafficpolicy.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1422,8 +1422,8 @@ func (t *Translator) buildLocalRateLimit(policy *egv1a1.BackendTrafficPolicy) (*
if err != nil {
return nil, err
}
// Set the Name field as <policy-ns>/<policy-name>/rule/<rule-index>
irRule.Name = irRuleName(policy.Namespace, policy.Name, i)
// Set the Name field as <policy-ns>/<policy-name>/rule/<rule-name-or-index>
irRule.Name = irRuleName(policy.Namespace, policy.Name, i, rule.Name)

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Either honor local rule names or reject them

This accepts spec.rateLimit.local.rules[].name and stores it in the IR, but I checked internal/xds/translator/local_ratelimit.go and local descriptor/action construction never reads rule.Name; it uses the loop index rIdx for all rule-<n>-* keys. Users can now configure a valid local rule name that has no observable effect and still gets index-based descriptor churn after reordering. Please either use the name in local descriptor generation or disallow/document the field for local rate limits.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Wire local rule names into local descriptors

When a local rule has spec.rateLimit.local.rules[].name, this line copies the name into IR, but the local xDS path never consumes ir.RateLimitRule.Name: buildRouteLocalRateLimits still passes the loop index rIdx into every build*LocalRateLimit* helper, which emits rule-<index>-... descriptor keys (internal/xds/translator/local_ratelimit.go:209-233,269-287). As a result accepted local names do not change local rate-limit keys/metrics, despite the API and release note promising both local and global rule keys use the provided name; either wire the name into those descriptors or reject/document local names as unsupported.

Useful? React with 👍 / 👎.

irRules = append(irRules, irRule)
}

Expand Down Expand Up @@ -1460,8 +1460,8 @@ func (t *Translator) buildGlobalRateLimit(policy *egv1a1.BackendTrafficPolicy) (
if err != nil {
return nil, err
}
// Set the Name field as <policy-ns>/<policy-name>/rule/<rule-index>
irRules[i].Name = irRuleName(policy.Namespace, policy.Name, i)
// Set the Name field as <policy-ns>/<policy-name>/rule/<rule-name-or-index>
irRules[i].Name = irRuleName(policy.Namespace, policy.Name, i, rule.Name)

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include rule names in non-shared global descriptors

For the default global case (shared unset/false), this IR name is never used by the xDS/RLS config: I checked internal/xds/translator/ratelimit.go, where buildRouteRateLimits and addRateLimitDescriptor still choose getRouteDescriptor(route.Name) plus getRouteRuleDescriptor(domainRuleIdx, ...). A policy like the added example with name: basic-limit but no shared: true therefore still emits rule-0-* descriptors and will churn counters/metrics when rules are reordered. Please thread the named key into the non-shared descriptor path, or restrict the API/docs to the shared-only case.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Wire non-shared names into global descriptors

For a global rule without shared: true, setting this IR name still has no effect on the generated RLS keys: buildRouteRateLimits and addRateLimitDescriptor choose getRouteDescriptor(route.Name) for non-shared rules and then derive match keys from getRouteRuleDescriptor(domainRuleIdx, ...) (internal/xds/translator/ratelimit.go:260-298,759-764,856-866). Thus a normal named rule such as by-org still produces route/rule-1-match-* descriptors and loses the stable user name in Envoy/RLS metrics; please use rule.Name in the non-shared descriptor/action path or narrow the API/docs to shared rules.

Useful? React with 👍 / 👎.

}

return rateLimit, nil
Expand Down
5 changes: 4 additions & 1 deletion internal/gatewayapi/helpers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -517,7 +517,10 @@ func irDestinationSettingName(destName string, backendIdx int) string {
return fmt.Sprintf("%s/backend/%d", destName, backendIdx)
}

func irRuleName(policyNamespace, policyName string, ruleIndex int) string {
func irRuleName(policyNamespace, policyName string, ruleIndex int, ruleName *string) string {
if ruleName != nil && *ruleName != "" {
return fmt.Sprintf("%s/%s/rule/%s", policyNamespace, policyName, *ruleName)
}
return fmt.Sprintf("%s/%s/rule/%d", policyNamespace, policyName, ruleIndex)
}

Expand Down
77 changes: 77 additions & 0 deletions internal/gatewayapi/testdata/backendtrafficpolicy-with-ratelimit-named-rule.in.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
gateways:
- apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
namespace: envoy-gateway
name: gateway-1
spec:
gatewayClassName: envoy-gateway-class
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All
httpRoutes:
- apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: default
name: httproute-1
spec:
hostnames:
- gateway.envoyproxy.io
parentRefs:
- namespace: envoy-gateway
name: gateway-1
sectionName: http
rules:
- matches:
- path:
value: "/"
backendRefs:
- name: service-1
port: 8080
backendTrafficPolicies:
- apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
namespace: default
name: policy-for-route
spec:
targetRef:
group: gateway.networking.k8s.io
kind: HTTPRoute
name: httproute-1
rateLimit:
type: Global
global:
rules:
# Named shared rule -> key uses the name: default/policy-for-route/rule/by-ip
- name: by-ip
clientSelectors:
- sourceCIDR:
type: "Distinct"
value: "0.0.0.0/0"
limit:
requests: 20
unit: Hour
shared: true
# Named non-shared rule -> key uses the name: default/policy-for-route/rule/by-org
- name: by-org
clientSelectors:
- headers:
- name: x-org-id
type: Distinct
limit:
requests: 30
unit: Hour
# Unnamed rule -> key falls back to the index: default/policy-for-route/rule/2
- clientSelectors:
- headers:
- name: x-team
value: blue
limit:
requests: 40
unit: Hour
Loading
Loading