NetScaler® Kubernetes Gateway Controller

Rate limit

August 12, 2026

Contributed by:

The ratelimit custom resource definition (CRD) lets you configure rate limiting and throttling policies on NetScaler® using Kubernetes-native configuration. You can use the ratelimit CRD to protect your services and AI backends from overload by limiting the rate of requests, connections, or tokens.

You can use the ratelimit CRD to:

Throttle traffic based on request rate, connection count, or token rate.
Apply limits per client IP address, per API path, per HTTP method, or per API client identified by an HTTP header.
Choose the action to take when a limit is exceeded, such as dropping, resetting, redirecting, or responding to requests.
Collect traffic analytics with stream identifiers for observability of requests, connections, response times, bandwidth, and token usage.

The ratelimit CRD is referenced from an aigatewayroute through an ExtensionRef filter, or applied directly to services through servicenames or targetRef.

Note:

You must specify at least one of ratelimits or streams.

Deploy the ratelimit CRD

Download the ratelimit CRD and deploy it using the following command:

kubectl create -f https://raw.githubusercontent.com/netscaler/netscaler-k8s-ingress-controller/refs/heads/master/crd/ratelimit/ratelimit-crd.yaml
<!--NeedCopy-->

Note:

Do not modify the CRD deployment YAML file.

ratelimit CRD attributes

The following table lists the top-level attributes available under spec for the ratelimit CRD.

Attribute	Description	Supported values
`ingressclass`	Ingress class. If not specified, all NetScaler Ingress Controllers in the cluster process the resource. Otherwise, only the controller with that ingress class processes it.	String
`servicenames`	Name of the services to which the rate limit policies are applied.	Array of strings (maximum length 127)
`gatewayClassName`	Name of the `GatewayClass` that this profile is applied to.	String
`targetRef`	List of target resources where this profile is applied.	Array
`selector_keys`	Traffic match criteria to which the rate limit or throttling applies.	Object
`ratelimits`	List of rate limit configurations.	Array
`streams`	List of stream identifier configurations for traffic analytics and tracking.	Array

targetRef attributes

Attribute	Description
`name`	Name of the target resource.
`namespace`	Namespace of the target resource.
`group`	Group of the target resource.
`kind`	Kind of the target resource.
`sectionName`	Specific section within the target resource.

selector_keys attributes

The selector_keys.basic object defines the traffic stream selection criteria. All keys are applied as an AND condition. If no keys are specified, the rate limit applies at the service level.

Attribute	Description	Supported values
`path`	API resource path prefix match, for example `/api/v1/products`.	Array of strings
`method`	HTTP methods to match.	`GET`, `PUT`, `POST`, `DELETE`, `HEAD`, `OPTIONS`, `TRACE`, `CONNECT`, `PATCH`, `UNKNOWN_METHOD`
`header_name`	HTTP header that identifies the unique API client, for example `X-apikey`.	String
`per_client_ip`	When set, applies the throttling limit to each unique client IP address accessing the API resource.	Boolean

ratelimits attributes

Each entry in ratelimits supports the following attributes. The req_threshold attribute is required.

Attribute	Description	Supported values
`req_threshold`	Maximum requests per timeslice to be allowed. This field is required.	Integer
`timeslice`	Timeslice in milliseconds, in multiples of 10. Defaults to 1000 milliseconds.	Integer
`limittype`	Limit type. Defaults to `SMOOTH` if not specified.	`BURSTY`, `SMOOTH`
`mode`	Metric to which the limit is applied.	`REQUEST_RATE`, `CONNECTION`, `TOKEN_RATE`
`alertsintimeslice`	Number of alerts to raise within a timeslice.	Integer
`throttle_action`	Action to take when the limit is exceeded. `DROP` drops requests exceeding the limit, `RESET` resets the client connection, `REDIRECT` redirects to the specified URL, `RESPOND` responds with `429 Exceeded allowed rate of requests`.	`DROP`, `RESET`, `REDIRECT`, `RESPOND`, `NOOP`
`redirect_url`	Redirect URL used when `throttle_action` is `REDIRECT`.	String
`logpackets`	Adds an audit message action that specifies whether to log the message, and to which log.	Object (`logexpression`, `loglevel`)

The logpackets object supports the following attributes. Both are required when logpackets is used.

Attribute	Description	Supported values
`logexpression`	Default-syntax expression that defines the format and content of the log message.	String (maximum length 7991)
`loglevel`	Audit log level that specifies the severity of the generated log message.	`EMERGENCY`, `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFORMATIONAL`, `DEBUG`

streams attributes

Each entry in streams supports the following attributes. The sort attribute is required.

Attribute	Description	Supported values
`interval`	Number of minutes of data to use when calculating session statistics (number of requests, bandwidth, and response times).	Integer (1–10080)
`sampleCount`	Size of the sample from which to select a request for evaluation. To evaluate all requests, set the sample count to 1.	Integer (1–65535)
`sort`	Sort stored records by the specified statistics column, in descending order. This field is required.	`REQUESTS` (default), `CONNECTIONS`, `RESPTIME`, `BANDWIDTH`, `RESPTIME_BREACHES`, `TOKENS`, `NONE`
`snmpTrap`	Enable or disable SNMP trap for the stream identifier.	`ENABLED`, `DISABLED`
`appflowLog`	Enable or disable AppFlow logging for the stream identifier.	`ENABLED`, `DISABLED`
`trackAckOnlyPackets`	Track ACK-only packets. Applicable only when packet rate limiting is used.	`ENABLED`, `DISABLED`
`trackTransactions`	Track transactions exceeding the configured threshold. When set to `TOKENS`, the transaction threshold attributes do not apply.	`RESPTIME`, `TOKENS`, `NONE`
`maxTransactionThreshold`	Maximum per-transaction value of the tracked metric.	Integer (minimum 0)
`minTransactionThreshold`	Minimum per-transaction value of the tracked metric.	Integer (minimum 0)
`acceptanceThreshold`	Non-breaching transactions to total transactions threshold, expressed as a percentage. A maximum of 6 decimal places is supported.	String (maximum length 10)
`breachThreshold`	Breaching transactions threshold calculated over the interval.	Integer (minimum 0)
`log`	Location where objects collected on the identifier are logged.	`SYSLOG`, `NONE`
`logInterval`	Time interval in minutes for logging the collected objects. Must be greater than or equal to the interval of the stream identifier.	Integer (1–10080)
`logLimit`	Maximum number of objects to be logged in the log interval.	Integer (1–1000)

How to write the rate limit configuration

In the ratelimit YAML definition, set the kind as ratelimit. In the spec section, select the traffic to throttle with selector_keys, and define the limits under ratelimits, the analytics under streams, or both.

Keep the following guidelines in mind:

Specify at least one of ratelimits or streams.
Use mode: TOKEN_RATE to enforce token-based rate limiting for AI backends.
Use selector_keys.basic.per_client_ip or header_name to apply per-client limits.
Attach the ratelimit CRD to an aigatewayroute through an ExtensionRef filter, or bind it to services through servicenames or targetRef.

Sample rate limit configurations

Token-based rate limiting

The following configuration limits traffic per client IP address to 100,000 tokens per minute and responds with a 429 status when the limit is exceeded.

apiVersion: citrix.com/v1beta1
kind: ratelimit
metadata:
  name: token-ratelimit
  namespace: default
spec:
  selector_keys:
    basic:
      path:
      - /v1/chat/completions
      method:
      - POST
      per_client_ip: true
  ratelimits:
  - req_threshold: 100000
    timeslice: 60000
    mode: TOKEN_RATE
    limittype: SMOOTH
    throttle_action: RESPOND
<!--NeedCopy-->

Per-API-client request rate limiting with logging

The following configuration limits each API client (identified by the X-apikey header) to 500 requests per second and logs when the limit is breached.

apiVersion: citrix.com/v1beta1
kind: ratelimit
metadata:
  name: apikey-ratelimit
  namespace: default
spec:
  servicenames:
  - ai-backend-service
  selector_keys:
    basic:
      header_name: X-apikey
  ratelimits:
  - req_threshold: 500
    timeslice: 1000
    mode: REQUEST_RATE
    limittype: BURSTY
    throttle_action: DROP
    logpackets:
      logexpression: "\"Rate limit exceeded for client: \" + HTTP.REQ.HEADER(\"X-apikey\")"
      loglevel: WARNING
<!--NeedCopy-->

Stream identifier for traffic analytics

The following configuration collects analytics on token usage without enforcing a limit.

apiVersion: citrix.com/v1beta1
kind: ratelimit
metadata:
  name: token-analytics
  namespace: default
spec:
  selector_keys:
    basic:
      path:
      - /v1/chat/completions
  streams:
  - interval: 5
    sampleCount: 1
    sort: TOKENS
    appflowLog: ENABLED
    trackTransactions: TOKENS
    log: SYSLOG
    logInterval: 5
    logLimit: 100
<!--NeedCopy-->

The official version of this product documentation is in English. Any non-English version is solely provided for your convenience and may include machine-translated content. For more information, please refer to the Machine Translation Disclaimer on Cloud Software Group home.

Was this helpful

NetScaler Secure Deployment Guide

Rate limit

August 12, 2026

Contributed by:

August 12, 2026

Contributed by:

Rate limit

Deploy the ratelimit CRD

ratelimit CRD attributes

targetRef attributes

selector_keys attributes

ratelimits attributes

streams attributes

How to write the rate limit configuration

Sample rate limit configurations

Token-based rate limiting

Per-API-client request rate limiting with logging

Stream identifier for traffic analytics

Related articles

In this article