NetScaler® Kubernetes Gateway Controller

Rewrite and responder policies

August 12, 2026

Contributed by:

The rewritepolicy custom resource definition (CRD) lets you configure rewrite and responder policies on NetScaler® using Kubernetes-native configuration. These policies let you rewrite information in requests and responses, and respond to requests based on the characteristics of the request.

You can use the rewritepolicy CRD for scenarios such as:

Rewriting the URL, host name, or headers of a request or response.
Inserting, deleting, or replacing HTTP headers.
Redirecting requests to a different URL, responding with a custom payload, or dropping and resetting connections.
Referencing datasets, patsets, and string maps in policy expressions.
Making HTTP callouts to an external agent to retrieve information used in policy decisions.

The rewritepolicy 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 rewrite-policies or responder-policies.

Deploy the rewritepolicy CRD

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

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

Note:

Do not modify the CRD deployment YAML file.

rewritepolicy CRD attributes

The following table lists the top-level attributes available under spec for the rewritepolicy 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
`gatewayClassName`	Name of the `GatewayClass` that this profile is applied to.	String
`targetRef`	List of target resources where this profile is applied (`name`, `namespace`, `group`, `kind`, `sectionName`).	Array
`rewrite-policies`	List of rewrite policies.	Array
`responder-policies`	List of responder policies.	Array
`dataset`	List of datasets referenced by policy expressions.	Array
`patset`	List of pattern sets referenced by policy expressions.	Array
`stringmap`	List of string maps referenced by policy expressions.	Array
`httpcallout_policy`	List of HTTP callout configurations.	Array

Rewrite policy

Each entry in rewrite-policies supports the following attributes. The rewrite-policy object is required.

Attribute	Description	Supported values
`servicenames`	Name of the services to bind to the rewrite policy.	Array of strings (maximum length 127)
`goto-priority-expression`	Expression or value specifying the next policy to evaluate if the current policy evaluates to `TRUE`. `NEXT` evaluates the policy with the next higher priority number, `END` ends policy evaluation. Defaults to `END`.	String (maximum length 1499)
`logpackets`	Adds an audit message action (`logexpression`, `loglevel`).	Object
`rewrite-policy`	The rewrite policy definition. This object is required.	Object

The rewrite-policy object supports the following attributes. The rewrite-criteria, operation, target, and direction attributes are required.

Attribute	Description	Supported values
`rewrite-criteria`	Expression against which traffic is evaluated. Required.	String (maximum length 1299)
`operation`	Type of user-defined rewrite action. Required.	`noop`, `delete`, `insert_http_header`, `delete_http_header`, `corrupt_http_header`, `insert_before`, `insert_after`, `replace`, `replace_http_res`, `delete_all`, `replace_all`, `insert_before_all`, `insert_after_all`, and other supported operations
`target`	Default-syntax expression that specifies which part of the request or response to rewrite. Required.	String (maximum length 1229)
`direction`	Bind point to which to bind the policy. Required.	`REQUEST`, `RESPONSE`
`default-action`	Action to perform if the result of policy evaluation is undefined (UNDEF).	`NOREWRITE`, `RESET`, `DROP`
`modify-expression`	Default-syntax expression that specifies the content to insert, or that replaces the specified string.	String (maximum length 7991)
`multiple-occurence-modify`	Search facility used to match multiple strings in the request or response.	String (maximum length 171)
`additional-multiple-occurence-modify`	Additional criteria to refine the search results. Starts with the `extend(m,n)` operation.	String (maximum length 1299)
`comment`	Any comments to preserve information about this rewrite policy.	String (maximum length 255)

Responder policy

Each entry in responder-policies supports the following attributes. The responder-policy object is required.

Attribute	Description	Supported values
`servicenames`	Name of the services to bind to the responder policy.	Array of strings (maximum length 127)
`goto-priority-expression`	Expression or value specifying the next policy to evaluate if the current policy evaluates to `TRUE`. Defaults to `END`.	String (maximum length 1499)
`logpackets`	Adds an audit message action (`logexpression`, `loglevel`).	Object
`responder-policy`	The responder policy definition. This object is required.	Object

The responder-policy object supports the following attributes. The respond-criteria attribute is required, and exactly one of redirect, respondwith, noop, reset, or drop must be specified.

Attribute	Description	Supported values
`respond-criteria`	Default-syntax expression that the policy uses to determine whether to respond to the request. Required.	String (maximum length 1299)
`redirect`	Redirect the request when it matches the policy (`url` required, `redirect-status-code`, `redirect-reason`).	Object
`respondwith`	Respond to the request when it matches the policy (`http-payload-string` required).	Object
`noop`	Send the request to the protected server instead of responding to it.	Object
`reset`	Reset the client connection by closing it when the request matches the policy.	Object
`drop`	Drop the request without sending a response when it matches the policy.	Object
`default-action`	Action to perform if the result of policy evaluation is undefined (UNDEF).	`NOOP`, `RESET`, `DROP`
`comment`	Any comments to preserve information about this responder policy.	String (maximum length 255)

Dataset

Each entry in dataset supports the following attributes. The name, type, and values attributes are required.

Attribute	Description	Supported values
`name`	Name of the dataset.	String (maximum length 32)
`type`	Type of value to bind to the dataset.	`ipv4`, `number`, `ipv6`, `ulong`, `double`, `mac`
`values`	Values of the specified type associated with this dataset.	Array of strings
`comment`	Any comments to preserve information about this dataset.	String (maximum length 255)

Patset

Each entry in patset supports the following attributes. The name and values attributes are required.

Attribute	Description	Supported values
`name`	Name of the patset.	String (maximum length 32)
`values`	Strings of characters that constitute the patterns associated with this patset.	Array of strings
`comment`	Any comments to preserve information about this patset.	String (maximum length 255)

String map

Each entry in stringmap supports the following attributes. The name and values attributes are required.

Attribute	Description	Supported values
`name`	Name of the string map.	String (maximum length 32)
`values`	List of key-value pairs to bind to this string map. Each pair has a `key` and a `value` (each with a maximum length of 2047 characters).	Array of objects
`comment`	Any comments to preserve information about this string map.	String (maximum length 255)

HTTP callout

Each entry in httpcallout_policy supports the following attributes. The name, server_ip, and server_port attributes are required.

Attribute	Description	Supported values
`name`	HTTP callout name.	String (maximum length 32)
`server_ip`	IP address of the callout agent server to which the callout is sent.	String
`server_port`	Port of the callout agent server.	Integer (1–65535)
`http_method`	Method used in the HTTP request. Defaults to `GET`.	`GET`, `POST`
`host_expr`	String expression to configure the `Host` header. Mutually exclusive with the full HTTP request expression.	String (maximum length 255)
`url_stem_expr`	String expression for generating the URL stem.	String (maximum length 8191)
`headers`	One or more headers to insert into the HTTP request (`name`, `expr`). Maximum of eight headers.	Array of objects
`parameters`	One or more query parameters to insert into the request (`name`, `expr`).	Array of objects
`body_expr`	Advanced string expression for generating the body of the request.	String
`full_req_expr`	Exact HTTP request, as an expression, that NetScaler sends to the callout agent.	String
`scheme`	Scheme for the callout server. Defaults to `HTTP`.	`HTTP`, `HTTPS`
`cache_for_secs`	Duration, in seconds, for which the callout response is cached.	Integer (1–31536000)
`return_type`	Type of data that the callout agent returns. `TEXT` treats the value as text, `NUM` as a number, `BOOL` as a Boolean.	`TEXT`, `NUM`, `BOOL`
`result_expr`	Expression that extracts the callout results from the response. Must be a response-based expression (begins with `HTTP.RES`).	String (maximum length 8191)
`comment`	Any comments to preserve information about this HTTP callout.	String (maximum length 255)

How to write the policy configuration

In the rewritepolicy YAML definition, set the kind as rewritepolicy. In the spec section, add one or more of the following sections: rewrite-policies, responder-policies, dataset, patset, stringmap, and httpcallout_policy.

Keep the following guidelines in mind:

Specify at least one of rewrite-policies or responder-policies.
For a rewrite policy, the rewrite-criteria, operation, target, and direction attributes are mandatory.
For a responder policy, the respond-criteria attribute is mandatory, and you must specify exactly one action out of redirect, respondwith, noop, reset, or drop.
Attach the rewritepolicy CRD to an aigatewayroute through an ExtensionRef filter, or bind it to services through servicenames or targetRef.

Sample policy configurations

Rewrite policy to add a response header

The following configuration inserts a custom header into the HTTP response.

apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
  name: add-response-header
  namespace: default
spec:
  rewrite-policies:
  - servicenames:
    - ai-backend-service
    rewrite-policy:
      operation: insert_http_header
      target: "x-ai-gateway"
      modify-expression: "\"netscaler\""
      rewrite-criteria: "HTTP.RES.IS_VALID"
      direction: RESPONSE
      comment: "Add AI gateway response header"
<!--NeedCopy-->

Responder policy to redirect a request

The following configuration redirects matching requests to another URL.

apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
  name: redirect-policy
  namespace: default
spec:
  responder-policies:
  - servicenames:
    - ai-backend-service
    responder-policy:
      redirect:
        url: "\"https://backup.example.com\" + HTTP.REQ.URL"
        redirect-status-code: 302
      respond-criteria: "HTTP.REQ.URL.CONTAINS(\"/deprecated\")"
      comment: "Redirect deprecated endpoint"
<!--NeedCopy-->

Responder policy with a custom response

The following configuration responds directly to matching requests with a custom payload.

apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
  name: block-policy
  namespace: default
spec:
  responder-policies:
  - servicenames:
    - ai-backend-service
    responder-policy:
      respondwith:
        http-payload-string: "\"HTTP/1.1 429 Too Many Requests\\r\\n\\r\\nRate limit exceeded\""
      respond-criteria: "HTTP.REQ.HEADER(\"x-ai-eg-model\").EQ(\"restricted-model\")"
      comment: "Block restricted model requests"
<!--NeedCopy-->

Rewrite policy with a dataset

The following configuration defines a dataset and uses it in a rewrite policy.

apiVersion: citrix.com/v1
kind: rewritepolicy
metadata:
  name: dataset-policy
  namespace: default
spec:
  dataset:
  - name: blocked_ips
    type: ipv4
    values:
    - "192.0.2.1"
    - "192.0.2.2"
  responder-policies:
  - servicenames:
    - ai-backend-service
    responder-policy:
      drop: {}
      respond-criteria: "CLIENT.IP.SRC.EQUALS_ANY(\"blocked_ips\")"
      comment: "Drop requests from blocked IPs"
<!--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

Rewrite and responder policies

August 12, 2026

Contributed by:

August 12, 2026

Contributed by:

Rewrite and responder policies

Deploy the rewritepolicy CRD

rewritepolicy CRD attributes

Rewrite policy

Responder policy

Dataset

Patset

String map

HTTP callout

How to write the policy configuration

Sample policy configurations

Rewrite policy to add a response header

Responder policy to redirect a request

Responder policy with a custom response

Rewrite policy with a dataset

Related articles

In this article