RateLimitPolicy

microgateway.airlock.com/v1alpha1

RateLimitPolicy is a Direct Attached Policy for the Kubernetes Gateway API.
It defines a rule-based policy for enforcing rate limits.

---
config:
  theme: base
  themeVariables:
    secondaryColor: '#ffffff'
---
block
  columns 7

  classDef al_ref_box fill:#F2F2F2,stroke:#555;
  classDef al_mgw_box fill:#70991F,stroke:#555;
  classDef al_gwapi_box fill:#326CE5,stroke:#555;
  classDef al_std_box fill:#808B8F,stroke:#555;
  classDef al_self_box fill:#70991F,stroke:#777,stroke-width:5px; 

  
  space:2
  block:Targets:3
    columns 3
    HTTPRoute["<a href='../../../gateway-api/http-route/v1'>&nbsp;&nbsp;HTTPRoute&nbsp;&nbsp;</a>"]
    space:2
    class HTTPRoute al_gwapi_box
  end
  class Targets al_ref_box
  space:2
  
  space:7
  
  space:3
  
  RateLimitPolicy["<a href='../../../microgateway/rate-limit-policy/v1alpha1'>&nbsp;&nbsp;<b>RateLimitPolicy</b>&nbsp;&nbsp;</a>"]
  class RateLimitPolicy al_self_box
  
  space:3
  

  RateLimitPolicy -- "<i>attaches to</i>" --> Targets

apiVersion: microgateway.airlock.com/v1alpha1
kind: RateLimitPolicy
metadata:
  name: rate-limit-policy-example
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: backend
  policies:
    - requestConditions:
        path:
          matcher:
            prefix: /customer1/
        remoteIP:
          cidrRanges:
            - 192.168.1.0/24
            - 192.168.2.0/24
      threatHandlingMode: LogOnly
      rateLimitHeaders: DraftVersion3
      local:
        limit:
          requests: 1000
          per: 1s

RateLimitPolicy

Field	Description	Type	Required
metadata	defines the resource’s metadata	ObjectMeta	yes
spec	defines the desired rate limit configuration.	object	yes
status	describes the current status of the RateLimitPolicy.	object	no

RateLimitPolicy.spec

Field	Description	Type	Required	Default	Allowed Values
policies	configures rate limit policies. The first matching policy (from top to bottom) applies. Rate limits are enforced independently per policy item. Requests matched by one policy do not count towards the rate limit of other policies.	object[]	yes
targetRefs	are the resources this policy is being attached to. Referenced resources must be in the same namespace as the policy. Support: HTTPRoute.	object[]	yes

RateLimitPolicy.spec.policies[]

Field	Description	Type	Required	Default	Allowed Values
blockResponse	configures the “429 Too Many Requests” response sent when the rate limit is exceeded.	object	no
countBy	applies the rate limit separately per request property, e.g., per client IP. If not set, all requests share a single counter.	object	no		`ip{}`
local	configures rate limiting enforced per Airlock Microgateway Engine pod. If not set, no rate limiting is applied.	object	no
rateLimitHeaders	configures whether rate limit headers are sent with responses. Meaning of the possible values: Disabled: No rate limit headers are sent. DraftVersion3: The X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers are sent.	enum	no	`Disabled`	`Disabled`, `DraftVersion3`
requestConditions	defines additional request properties which must all be matched in order for this policy to apply. A policy without request conditions will always match.	object	no
threatHandlingMode	specifies how a threat is handled when the rate limit is exceeded.	enum	no	`Block`	`Block`, `LogOnly`

RateLimitPolicy.spec.policies[].blockResponse

Field	Description	Type	Required	Default	Allowed Values
retryAfter	configures the Retry-After header sent in the response. If not specified, no Retry-After header is sent.	object	no

RateLimitPolicy.spec.policies[].blockResponse.retryAfter

Field	Description	Type	Required	Default	Allowed Values
value	defines the duration sent in the Retry-After header. If not set, the value will be determined dynamically based on the time remaining until the current rate limit window resets. Must have second precision and be strictly positive (i.e., 0s or 1.5s are not allowed).	string	no		See link

RateLimitPolicy.spec.policies[].countBy

Field	Description	Type	Required	Default	Allowed Values
ip	applies the rate limit per client IP.	object	no

RateLimitPolicy.spec.policies[].countBy.ip

Field	Description	Type	Required	Default	Allowed Values
numberOfCounters	specifies the maximum number of distinct client IP addresses tracked. This has implications on the memory usage. Consult the documentation for more information.	int64	no	`10000`	`[1, 9223372036854775807]`

RateLimitPolicy.spec.policies[].local

Field	Description	Type	Required	Default	Allowed Values
limit	configures the applied rate limit.	object	yes

RateLimitPolicy.spec.policies[].local.limit

Field	Description	Type	Required	Default	Allowed Values
per	is the time window of the requests/time rate.	string (duration)	no	`1s`	See link
requests	specifies the number of requests allowed per the given time window.	int32	yes		`[1, 2147483647]`

RateLimitPolicy.spec.policies[].requestConditions

Field	Description	Type	Required	Default	Allowed Values
header	defines the matching headers of a request.	object	no
invert	indicates whether the request condition should be inverted.	bool	no	`false`	`true`, `false`
mediaType	defines the matching media type from the content-type header of a request.	object	no
method	defines the matching methods of a request.	enum[]	no		`CONNECT`, `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, `PUT`, `TRACE`
path	defines the matching path of a request.	object	no
remoteIP	defines the matching remote IPs of a request. Note: Depending on your setup you may need to adapt the `remoteIP` configuration in the GatewayParameters resource to ensure correct client IP detection.	object	no

RateLimitPolicy.spec.policies[].requestConditions.header

Field	Description	Type	Required	Default	Allowed Values
name	defines the name of a header.	object	no
value	defines the value of a header.	object	no

RateLimitPolicy.spec.policies[].requestConditions.header.name

Field	Description	Type	Required	Default	Allowed Values
matcher	defines the way to match a string. In comparison to a normal StringMatcher, a value is always matched ignoring the case and can’t be inverted.	object	yes		`contains{}`, `exact{}`, `prefix{}`, `regex{}`, `suffix{}`

RateLimitPolicy.spec.policies[].requestConditions.header.name.matcher

Field	Description	Type	Required
contains	defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
exact	defines an explicit match on the string specified here. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
prefix	defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
regex	defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used. The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
suffix	defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no

RateLimitPolicy.spec.policies[].requestConditions.header.value

Field	Description	Type	Required	Default	Allowed Values
matcher		object	yes		`contains{}`, `exact{}`, `prefix{}`, `regex{}`, `suffix{}`

RateLimitPolicy.spec.policies[].requestConditions.header.value.matcher

Field	Description	Type	Required	Default	Allowed Values
contains	defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
exact	defines an explicit match on the string specified here. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
ignoreCase	indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group `(?i:...)`.	bool	no	`false`	`true`, `false`
prefix	defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
regex	defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used. The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
suffix	defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no

RateLimitPolicy.spec.policies[].requestConditions.mediaType

Field	Description	Type	Required	Default	Allowed Values
matcher		object	yes		`contains{}`, `exact{}`, `prefix{}`, `regex{}`, `suffix{}`

RateLimitPolicy.spec.policies[].requestConditions.mediaType.matcher

Field	Description	Type	Required
contains	defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
exact	defines an explicit match on the string specified here. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
prefix	defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
regex	defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used. The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
suffix	defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no

RateLimitPolicy.spec.policies[].requestConditions.path

Field	Description	Type	Required	Default	Allowed Values
matcher		object	yes		`contains{}`, `exact{}`, `prefix{}`, `regex{}`, `suffix{}`

RateLimitPolicy.spec.policies[].requestConditions.path.matcher

Field	Description	Type	Required	Default	Allowed Values
contains	defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
exact	defines an explicit match on the string specified here. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
ignoreCase	indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group `(?i:...)`.	bool	no	`false`	`true`, `false`
prefix	defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
regex	defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used. The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex. Only one of exact, prefix, suffix, regex or contains can be set.	string	no
suffix	defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead. Only one of exact, prefix, suffix, regex or contains can be set.	string	no

RateLimitPolicy.spec.policies[].requestConditions.remoteIP

Field	Description	Type	Required	Default	Allowed Values
cidrRanges	defines the IPv4 or IPv6 CIDR ranges, e.g. `196.148.3.128/26` or `2001:db8::/28`.	string[]	yes
invert	indicates whether the match should be inverted.	bool	no	`false`	`true`, `false`

RateLimitPolicy.spec.targetRefs[]

Field	Description	Type	Required	Allowed Values
group	is the group of the target resource.	string	yes	`gateway.networking.k8s.io`
kind	is kind of the target resource.	string	yes	`HTTPRoute`
name	is the name of the target resource.	string	yes

RateLimitPolicy.status

Field	Description	Type
ancestors	is a list of ancestor resources (usually Gateways) that are associated with the policy, and the status of the policy with respect to each ancestor. When this policy attaches to a parent, the controller that manages the parent and the ancestors MUST add an entry to this list when the controller first sees the policy and SHOULD update the entry as appropriate when the relevant ancestor is modified. Note that choosing the relevant ancestor is left to the Policy designers; an important part of Policy design is designing the right object level at which to namespace this status. Note also that implementations MUST ONLY populate ancestor status for the Ancestor resources they are responsible for. Implementations MUST use the ControllerName field to uniquely identify the entries in this list that they are responsible for. Note that to achieve this, the list of PolicyAncestorStatus structs MUST be treated as a map with a composite key, made up of the AncestorRef and ControllerName fields combined. A maximum of 16 ancestors will be represented in this list. An empty list means the Policy is not relevant for any ancestors. If this slice is full, implementations MUST NOT add further entries. Instead they MUST consider the policy unimplementable and signal that on any related resources such as the ancestor that would be referenced here. For example, if this list was full on BackendTLSPolicy, no additional Gateways would be able to reference the Service targeted by the BackendTLSPolicy.	object[]

RateLimitPolicy.status.ancestors[]

Field Description Type

ancestorRef corresponds with a ParentRef in the spec that this PolicyAncestorStatus struct describes the status of. object

conditions

Field	Description	Type
ancestorRef	corresponds with a ParentRef in the spec that this PolicyAncestorStatus struct describes the status of.	object
conditions	Conditions describes the status of the Policy with respect to the given Ancestor. Possible conditions: `Accepted`: indicates whether the policy has been accepted or rejected by a targeted resource, and why. Possible reasons for this condition to be True are: “Accepted” Possible reasons for this condition to be False are: “Conflicted” “Invalid” “TargetNotFound”	Condition[]
controllerName	is a domain/path string that indicates the name of the controller that wrote this status. This corresponds with the controllerName field on GatewayClass. Example: “example.net/gateway-controller”. The format of this field is DOMAIN “/” PATH, where DOMAIN and PATH are valid Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). Controllers MUST populate this field when writing status. Controllers should ensure that entries to status populated with their ControllerName are cleaned up when they are no longer necessary.	string

Conditions describes the status of the Policy with respect to the given Ancestor.

Possible conditions:

Accepted: indicates whether the policy has been accepted or rejected by a targeted resource, and why.

Possible reasons for this condition to be True are:
- “Accepted”
Possible reasons for this condition to be False are:
- “Conflicted”
- “Invalid”
- “TargetNotFound”

Condition[]

controllerName is a domain/path string that indicates the name of the controller that wrote this status. This corresponds with the controllerName field on GatewayClass.

Example: “example.net/gateway-controller”.

The format of this field is DOMAIN “/” PATH, where DOMAIN and PATH are valid Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).

Controllers MUST populate this field when writing status. Controllers should ensure that entries to status populated with their ControllerName are cleaned up when they are no longer necessary. string

RateLimitPolicy.status.ancestors[].ancestorRef

Field	Description	Type
group	is the group of the referent. When unspecified, “gateway.networking.k8s.io” is inferred. To set the core API group (such as for a “Service” kind referent), Group must be explicitly set to "" (empty string).	string
kind	is kind of the referent. There are two kinds of parent resources with “Core” support: Gateway (Gateway conformance profile) Service (Mesh conformance profile, ClusterIP Services only) Support for other resources is Implementation-Specific.	string
name	is the name of the referent.	string
namespace	is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. Note: This section only applies to the Gateway API experimental channel ParentRefs from a Route to a Service in the same namespace are “producer” routes, which apply default routing rules to inbound connections from any namespace to the Service. ParentRefs from a Route to a Service in a different namespace are “consumer” routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route.	string
port	is the network port this Route targets. It can be interpreted differently based on the type of parent resource. When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It’s not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. Note: This section only applies to the Gateway API experimental channel When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway.	int32
sectionName	is the name of a section within the target resource. In the following resources, SectionName is interpreted as the following: Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. Implementations MAY choose to support attaching Routes to other resources. If that is the case, they MUST clearly document how SectionName is interpreted. When unspecified (empty string), this will reference the entire resource. For the purpose of status, an attachment is considered successful if at least one section in the parent resource accepts it. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway.	string