NetScaler® Kubernetes Gateway Controller

AI Gateway route

August 12, 2026

Contributed by:

The aigatewayroute custom resource definition (CRD) combines multiple AI service backends and attaches them to Gateway resources managed by NetScaler® Kubernetes Gateway Controller. It provides a way to define a unified AI API for a Gateway, so that downstream clients can use a single schema to interact with multiple AI backends across providers.

NetScaler Kubernetes Gateway Controller provides the following capabilities for an aigatewayroute:

Header-based and policy-based routing to AI backends through the HTTPRoute of the Gateway API. The generated HTTPRoute has the same name as the aigatewayroute.
Priority-based model spillover to backup backends, which enables automatic failover when the primary AI backends are unavailable or overloaded.
Separate front end and back end AI Gateway profiles for multi-provider deployments, which allows independent configuration of client-facing and upstream AI service policies.
Support for ratelimit and rewritepolicy CRDs for fine-grained traffic control and request or response transformation.
Support for sslprofile, tcpprofile, and httpprofile CRDs for protocol-level tuning of AI backend connections.
Built-in TCP, HTTP, and streaming analytics for observability of AI traffic patterns, token usage, and backend performance.

All of these resources are created in the same namespace as the aigatewayroute. You can customize the default behavior by attaching NetScaler policy CRDs to the generated HTTPRoute through ExtensionRef filters.

Note:

In the matching conditions, the x-ai-eg-model header is available for routing decisions based on the model name. The model name is extracted from the request content before routing.

Deploy the aigatewayroute CRD

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

kubectl create -f https://raw.githubusercontent.com/citrix/citrix-k8s-ingress-controller/master/crd/aigateway/aigatewayroute-crd.yaml
<!--NeedCopy-->

Note:

Do not modify the CRD deployment YAML file.

aigatewayroute CRD attributes

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

Attribute	Description	Supported values
`rules`	List of routing rules that this route matches the traffic to. This field is required.	Array of rules (maximum 128)
`aigatewayprofiles`	Default AI Gateway profiles to apply to the generated load balancing virtual servers and service groups.	Object
`hostnames`	Set of hostnames matched against the HTTP `Host` header to select this route. Wildcard prefixes (`*.`) are interpreted as a suffix match. IP addresses are not allowed.	Array of RFC 1123 hostnames (maximum 16)
`parentRefs`	References to the resources (usually `Gateway` objects) that this route is attached to.	Array (maximum 32)

aigatewayprofiles attributes

Each of the following profile references specifies a name (required) and an optional namespace that defaults to the aigatewayroute namespace.

Attribute	Description
`frontend`	AI Gateway profile applied to the primary load balancing virtual server.
`spillover-frontend`	AI Gateway profile applied to the spillover load balancing virtual server.
`default-backend`	AI Gateway profile applied to all backend service groups unless overridden by a per-backendRef `backend-aigatewayprofile`.

parentRefs attributes

The following table lists parentRefs attributes.

Attribute	Description	Supported values
`name`	Name of the referent. This field is required.	String
`group`	Group of the referent. When unspecified, `gateway.networking.k8s.io` is inferred.	String
`kind`	Kind of the referent.	Default: `Gateway`
`namespace`	Namespace of the referent. Defaults to the local namespace of the route.	String
`port`	Network port that this route targets.	Integer (1–65535)
`sectionName`	Name of a section (listener name for a `Gateway`) within the target resource.	String

rules attributes

Each entry in rules supports the following attributes.

Attribute	Description	Supported values
`backendRefs`	List of AI service backends that this rule routes traffic to.	Array (maximum 128)
`matches`	List of conditions that determine when this rule applies. Supports path-based, header-based, and policy expression matching.	Array (maximum 128)
`filters`	NetScaler policy CRDs to attach to this rule through `ExtensionRef`.	Array (maximum 16)
`timeouts`	Timeouts that can be configured for an HTTP request.	Object

backendRefs attributes

The following table lists backendRefs attributes.

Attribute	Description	Supported values
`name`	Name of the backend `Service` resource. This field is required.	String
`group`	API group of the referent. When empty, the core API group is inferred.	String
`kind`	Kubernetes resource kind of the referent.	Default: `Service`
`namespace`	Namespace of the backend resource. Defaults to the local namespace of the route.	String
`port`	Destination port number to use for this backend.	Integer (1–65535)
`weight`	Proportion of traffic to send to this backend relative to other backends in the same rule.	Integer (default 1)
`is_spillover`	Indicates whether this backend is a spillover backend that receives traffic only when the primary backends are unavailable or overloaded. Only one backendRef may set this to `true`.	Boolean (default `false`)
`backend-aigatewayprofile`	Backend AI Gateway profile to apply to this backend’s service group. Overrides the spec-level `default-backend` profile.	Object (`name`, `namespace`)
`filters`	Per-backend NetScaler policy CRDs to attach through `ExtensionRef`.	Array (maximum 16)

matches attributes

The following table lists matches attributes.

Attribute	Description	Supported values
`path`	HTTP request path matcher. Defaults to a `PathPrefix` match on `/`.	`type`: `Exact`, `PathPrefix`, `RegularExpression`; `value`: string
`headers`	HTTP request header matchers. Use AND for multiple values.	`name`, `value`, `type`: `Exact`, `RegularExpression`
`policyExpression`	NetScaler policy expression for advanced matching, evaluated in addition to header matches.	String

filters attributes

The following table lists filters attributes.

Attribute	Description	Supported values
`type`	Type of filter. Currently only `ExtensionRef` is supported.	`ExtensionRef`
`extensionRef`	Reference to a NetScaler policy CRD (`group`, `kind`, `name` — all required). Supported kinds include `ratelimit`, `rewritepolicy`, `aigatewayprofile`, `sslprofile`, `tcpprofile`, and `httpprofile`.	Object

timeouts attributes

The following table lists timeouts attributes.

Attribute	Description	Supported values
`request`	Maximum duration for the gateway to respond to an HTTP request.	Duration, for example `30s`
`backendRequest`	Timeout for an individual request from the gateway to a backend. Cannot be longer than `request`.	Duration, for example `20s`

Note:

For streaming responses (such as chat completions with stream=true), set longer timeouts because the response can take time to complete.

How to write the route configuration

In the aigatewayroute YAML definition, set the kind as aigatewayroute. In the spec section, add the parentRefs that attach the route to a Gateway, the aigatewayprofiles that select the front end and back end profiles, and one or more rules that match and route traffic.

Keep the following guidelines in mind:

The rules field is mandatory.
Backends with lower priority values are preferred. Set is_spillover: true in maximum one backend in a rule to designate the failover backend.
Use the x-ai-eg-model header or policyExpression in matches to route by model name.
Attach policy CRDs (ratelimit, rewritepolicy, and so on) at the rule level or per-backend through ExtensionRef filters.

Sample route configurations

Model routing to multiple backends

The following configuration routes requests to different backends based on the model name carried in the x-ai-eg-model header.

apiVersion: citrix.com/v1
kind: aigatewayroute
metadata:
  name: ai-model-route
  namespace: default
spec:
  parentRefs:
  - name: ai-gateway
    sectionName: https
  aigatewayprofiles:
    frontend:
      name: frontend-profile
    default-backend:
      name: backend-profile
  rules:
  - matches:
    - headers:
      - name: x-ai-eg-model
        value: gpt-5
    backendRefs:
    - name: gpt-5-backend
      port: 80
  - matches:
    - headers:
      - name: x-ai-eg-model
        value: gpt-5-codex
    backendRefs:
    - name: gpt-5-codex-backend
      port: 80
<!--NeedCopy-->

Priority-based model spillover

The following configuration sends traffic to a primary backend and spills over to a backup backend when the primary is unavailable or overloaded.

apiVersion: citrix.com/v1
kind: aigatewayroute
metadata:
  name: ai-spillover-route
  namespace: default
spec:
  parentRefs:
  - name: ai-gateway
    sectionName: https
  aigatewayprofiles:
    frontend:
      name: frontend-profile
    spillover-frontend:
      name: spillover-frontend-profile
    default-backend:
      name: backend-profile
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1/chat/completions
    backendRefs:
    - name: primary-backend
      port: 80
      weight: 1
    - name: backup-backend
      port: 80
      is_spillover: true
      backend-aigatewayprofile:
        name: backup-backend-profile
    timeouts:
      request: 120s
      backendRequest: 110s
<!--NeedCopy-->

Attach a rate limit policy to a rule

The following configuration attaches a ratelimit CRD to a routing rule through an ExtensionRef filter.

apiVersion: citrix.com/v1
kind: aigatewayroute
metadata:
  name: ai-ratelimited-route
  namespace: default
spec:
  parentRefs:
  - name: ai-gateway
    sectionName: https
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1/chat/completions
    filters:
    - type: ExtensionRef
      extensionRef:
        group: citrix.com
        kind: ratelimit
        name: token-ratelimit
    backendRefs:
    - name: llama-backend
      port: 80
<!--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

AI Gateway route

August 12, 2026

Contributed by:

August 12, 2026

Contributed by:

AI Gateway route

Deploy the aigatewayroute CRD

aigatewayroute CRD attributes

aigatewayprofiles attributes

parentRefs attributes

rules attributes

backendRefs attributes

matches attributes

filters attributes

timeouts attributes

How to write the route configuration

Sample route configurations

Model routing to multiple backends

Priority-based model spillover

Attach a rate limit policy to a rule

Related articles

In this article