NetScaler® Profiles support
The NetScaler Kubernetes Gateway Controller introduces Profile CRDs (including SSL profile, HTTP profile, and TCP profile) to achieve robust, centralized configuration. These profiles allow cluster operators to define standardized, reusable infrastructure settings, such as TLS ciphers, TCP optimizations, or HTTP timeouts, that application developers can effortlessly apply to their routing definitions.
Deploy the NetScaler Rewrite and Responder CRD
The NetScaler Rewrite and Responder CRD deployment YAML file: rewrite-responder-policies-deployment.yaml.
Note:
Ensure that you do not modify the deployment YAML file.
Deploy the CRD, using the following command:
kubectl apply -f profiles_crd.yaml
<!--NeedCopy-->
For example,
root@1:~# kubectl apply -f profiles_crd.yaml
customresourcedefinition.apiextensions.k8s.io/httpprofiles.citrix.com created
customresourcedefinition.apiextensions.k8s.io/tcpprofiles.citrix.com created
customresourcedefinition.apiextensions.k8s.io/sslprofiles.citrix.com created
<!--NeedCopy-->
Profile specification
All Profile CRDs use one of the following two fields to define the desired NetScaler configuration. These fields are mutually exclusive:
spec.preconfiguredspec.config
| Field | Purpose | Action on NetScaler |
|---|---|---|
| spec.preconfigured | Use an existing profile on the NetScaler appliance. | The controller does not create a profile. It uses the provided string value as the profile name for binding. |
| spec.config | Define a profile. | The controller creates a uniquely named profile (based on the CRD’s metadata) on the NetScaler, using the key-value pairs you provide in the config block. |
Add NetScaler profiles in NetScaler Kubernetes Gateway Controller
You can add NetScaler profiles (HTTP, TCP, and SSL) in the Kubernetes Gateway resources as Frontend profile and Backend profile.
Frontend profiles
Frontend profiles are used to apply settings directly to the Gateway’s listeners. For example, the frontend content switching virtual server on the NetScaler. These profiles must include targetRef section for binding.
A single frontend profile CRD can be efficiently applied to multiple Gateways.
Example 1 Frontend SSL Profile set on all Gateway listeners
The following example defines a new frontend SSL profile with custom configuration parameters, and applies it to all listeners or content switching virtual servers of the “my-gateway” resource.
apiVersion: citrix.com/v1
kind: sslprofile
metadata:
name: frontend-ssl-custom
namespace: production
spec:
targetRef:
- name: my-gateway
namespace: production
kind: Gateway
group: gateway.networking.k8s.io
config:
sslprofiletype: "frontend"
sessreuse: "ENABLED"
zerorttearlydata: "DISABLED"
hsts: "ENABLED"
preload: "YES"
<!--NeedCopy-->
Backend Profiles
Backend Profiles are used to configure settings that affect the connection between the Gateway(NetScaler) and the backend Kubernetes application. For example, service groups or servers.
Backend Profiles must not contain a targetRef. Instead, they are attached directly to a specific HTTPRoute rule using the standard ExtensionRef filter type in the HTTPRoute, allowing granular control per route.
Example 1: Backend preconfigured SSL Profile for HTTPRoute
The following example defines a profile that uses an existing NetScaler profile named “manual_secure_backend” and is intended for use by HTTPRoutes (no targetRef is present).
apiVersion: citrix.com/v1
kind: sslprofile
metadata:
name: simple-ssl-profile-backend
spec:
# Define the existing profile name
preconfigured: "manual_secure_backend"
<!--NeedCopy-->
Example 2: Apply a Backend Profile to HTTPRoute
The following HTTPRoute references the backend sslprofile created in the previous example through an ExtensionRef filter.
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-httproute
spec:
parentRefs:
- name: my-gateway-http
namespace: default
hostnames:
- "example123.com"
rules:
- filters:
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "sslprofile"
name: "simple-ssl-profile-backend" # References the Profile CRD name
matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: app1-svc
namespace: default
port: 80
<!--NeedCopy-->
Types of NetScaler profiles
The following NetScaler profile types are supported:
- HTTP profile
- TCP profile
- SSL profile
SSL Profile
An SSL profile is a collection of settings for SSL entities. It offers ease of configuration and flexibility. Instead of configuring the settings on each application, you can configure them in a profile and bind the profile to all the application that the settings apply to.
The SSL profile CRD schema reference is as follows:
| Field | Type | Description | Required for Frontend Profiles | Required for Backend Profiles |
|---|---|---|---|---|
| preconfigured | string | Mutually exclusive with config. The name of a preconfigured or built-in SSL profile existing on the NetScaler appliance to be used. | No | No |
| config | object | Mutually exclusive with preconfigured. Contains all the parameters related to the NetScaler NITRO API for a fully custom profile. Customers can specify any valid NITRO SSL profile parameters here. For information about key-value pairs supported in the SSL profile, see SSL profile. | No | No |
| targetRef | array of objects | A list of target resources (typically a Gateway) where this profile is applied. This field is required for Frontend Profiles and must be omitted for Backend Profiles. | Yes | No |
| gatewayClassName | string | Name of the GatewayClass that this SSL profile must be applied to. Used for scoping the profile to a specific controller instance in multitenant environments. |
No | No |
| sslciphers | array of strings | List of ciphers to be bound to the SSL profile. The priority is determined by the order in the list and can include a cipher suite, a predefined cipher group, or a user-created cipher group. | No | No |
Importanat
If you use a pre-configured SSL profile, you must bind ciphers manually through NetScaler, and
spec.policies.sslciphersare ignored.Built-in cipher groups are supported in Tier-1 and Tier-2 NetScaler, but user-defined cipher groups are supported only in a Tier-1 NetScaler.
Example 1: Preconfigured Frontend SSL Profile
apiVersion: citrix.com/v1
kind: sslprofile
metadata:
name: frontend-ssl-preconfigured
spec:
targetRef:
- name: my-gateway-https2
sectionName: https
preconfigured: "ns_default_ssl_profile_frontend"
<!--NeedCopy-->
Example 2: Custom Frontend SSL Profile
apiVersion: citrix.com/v1
kind: sslprofile
metadata:
name: frontend-ssl-custom
spec:
targetRef:
- name: my-gateway-https # Applying to all csvservers in the Gateway
sslciphers:
- "HIGH"
config:
sslprofiletype: "frontend"
sessreuse: "ENABLED"
sesstimeout: 300
clientauth: "DISABLED"
ssl3: "DISABLED"
tls1: "DISABLED"
tls11: "DISABLED"
includesubdomains: "YES"
maxage: 31536000
preload: "YES"
<!--NeedCopy-->
Example 3: Preconfigured Backend SSL Profile and the HTTPRoute referring the profile
apiVersion: citrix.com/v1
kind: sslprofile
metadata:
name: backend-ssl-preconfigured
spec:
preconfigured: "ns_default_ssl_profile_backend"
<!--NeedCopy-->
apiVersion: gateway.networking.k8s.io/v1
kind: HTTP Route
metadata:
name: my-httproute
spec:
parentRefs:
- name: my-gateway-https
hostnames:
- "example123.com"
rules:
- filters:
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "sslprofile"
name: "backend-ssl-preconfigured"
matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: app1-svc
namespace: default
port: 443
<!--NeedCopy-->
Example 4: Custom Backend SSL Profile and HTTPRoute referring the profile
apiVersion: citrix.com/v1
kind: sslprofile
metadata:
name: backend-ssl-custom
spec:
sslciphers:
- "HIGH"
config:
sslprofiletype: "backend"
sessreuse: 'ENABLED'
sesstimeout: 300
serverauth: 'ENABLED'
insertionencoding: 'Unicode'
ssl3: 'ENABLED'
tls1: 'DISABLED'
tls12: 'ENABLED'
<!--NeedCopy-->
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-httproute2
spec:
parentRefs:
- name: my-gateway-https2
hostnames:
- "example123.com"
rules:
- filters:
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "sslprofile"
name: "backend-ssl-custom"
matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: app1-svc
port: 443
<!--NeedCopy-->
TCP profile
A TCP profile is a collection of TCP settings used to optimize transport layer behavior. This profile allows you to apply advanced settings, such as TCP Fast Open or HyStart to improve connection performance and efficiency.
TCP Profile CRD schema reference
| Field | Type | Description | Required for Frontend Profiles | Required for Backend Profiles |
|---|---|---|---|---|
| preconfigured | string | Mutually exclusive with config. The name of a preconfigured or built-in TCP profile existing on the NetScaler appliance to use. | No | No |
| config | object | Mutually exclusive with preconfigured. Contains all the parameters related to the NetScaler NITRO API for a fully custom profile. Customers can specify any valid NITRO TCP profile parameters. For information about all the possible key-value pairs for a TCP profile, see TCP profile. | No | No |
| targetRef | array of objects | A list of target resources (typically a Gateway) where this profile is applied. This field is required for Frontend profiles and must be omitted for Backend profiles. | Yes | No |
| gatewayClassName | string | Name of the GatewayClass that this TCP profile must be applied to. Used for scoping the profile to a specific controller instance in multitenant environments. |
No | No |
Example 1: Preconfigured Frontend TCP Profile
apiVersion: citrix.com/v1
kind: tcpprofile
metadata:
name: frontend-tcp-preconfigured
spec:
targetRef:
- name: my-gateway-https2
sectionName: https # Applying to specific csvserver/Listener in the Gateway
preconfigured: "nstcp_default_profile"
<!--NeedCopy-->
Example 2: Custom Frontend TCP Profile
apiVersion: citrix.com/v1
kind: tcpprofile
metadata:
name: frontend-tcp-custom
spec:
targetRef:
- name: my-gateway-https # Applying to all csvservers in the Gateway
config:
mss: 1000
sack: ENABLED
buffersize: 10000
ka: ENABLED
name: "dummy" # Will be ignored, tcpprofile will be generated based on metadata.name and metadata.namespace
<!--NeedCopy-->
Example 3: Preconfigured Backend TCP profile and HTTPRoute referring the profile
apiVersion: citrix.com/v1
kind: tcpprofile
metadata:
name: backend-tcp-preconfigured
spec:
preconfigured: "nstcp_default_profile"
<!--NeedCopy-->
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-httproute
spec:
parentRefs:
- name: my-gateway-https
hostnames:
- "example123.com"
rules:
- filters:
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "tcpprofile"
name: "backend-tcp-preconfigured"
matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: app1-svc
port: 443
<!--NeedCopy-->
Example 4: Custom Backend TCP profile and HTTPRoute referring the profile
apiVersion: citrix.com/v1
kind: tcpprofile
metadata:
name: backend-tcp-custom
spec:
config:
mss: 1000
sack: ENABLED
buffersize: 10000
ka: ENABLED
<!--NeedCopy-->
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-httproute2
spec:
parentRefs:
- name: my-gateway-https2
hostnames:
- "example123.com"
rules:
- filters:
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "sslprofile"
name: "backend-ssl-custom"
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "tcpprofile"
name: "backend-tcp-custom"
# Applying SSL and TCPProfile to the same rule
matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: app1-svc
namespace: default
port: 443
<!--NeedCopy-->
HTTP Profile
An HTTP profile is a collection of HTTP settings used to configure various application layer behaviors, such as enabling WebSocket, customizing HTTP timeouts, or setting strict validation rules.
HTTP profile CRD schema reference
| Field | Type | Description | Required for Frontend Profiles | Required for Backend Profiles |
|---|---|---|---|---|
| preconfigured | string | Mutually exclusive with config. The name of a preconfigured or built-in HTTP profile existing on the NetScaler appliance to use. | No | No |
| config | object | Mutually exclusive with preconfigured. Contains all the parameters related to the NetScaler NITRO API for a fully custom profile. Customers can specify any valid NITRO TCP profile parameters. For information about all the possible key-value pairs for the HTTP profile see, HTTP profile. | No | No |
| targetRef | array of objects | A list of target resources (typically a Gateway) where this profile is applied. This field is required for Frontend profiles and must be omitted for Backend profiles. | Yes | No |
| gatewayClassName | string | Name of the GatewayClass that this HTTP profile must be applied to. Used for scoping the profile to a specific controller instance in multitenant environments. | No | No |
Example 1: Preconfigured Frontend HTTP profile
apiVersion: citrix.com/v1
kind: httpprofile
metadata:
name: frontend-http-preconfigured
spec:
targetRef:
- name: my-gateway-https
kind: Gateway
preconfigured: "frontend1"
<!--NeedCopy-->
Example 2: Custom Frontend HTTP profile
apiVersion: citrix.com/v1
kind: httpprofile
metadata:
name: frontend-http-custom
spec:
targetRef:
- name: my-gateway-https
kind: Gateway
group: gateway.networking.k8s.io # Applying to all CSvserver in the Gateway
config:
websocket: "ENABLED"
http2: ENABLED
reqtimeout: 10
dropinvalreqs: ENABLED
<!--NeedCopy-->
Example 3: Preconfigured Backend HTTP profile and HTTPRoute referring the profile
apiVersion: citrix.com/v1
kind: httpprofile
metadata:
name: backend-http-preconfigured
spec:
preconfigured: "nshttp_default_profile"
<!--NeedCopy-->
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-httproute
namespace: default
spec:
parentRefs:
- name: my-gateway-https
hostnames:
- "example123.com"
rules:
- filters:
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "tcpprofile"
name: "backend-tcp-preconfigured"
matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: app1-svc
namespace: default
port: 443
<!--NeedCopy-->
Example 4: Custom Backend HTTP profile and HTTPRoute referring the profile
apiVersion: citrix.com/v1
kind: httpprofile
metadata:
name: backend-http-custom
spec:
config:
websocket: "ENABLED"
http2: ENABLED
reqtimeout: 10
dropinvalreqs: ENABLED
<!--NeedCopy-->
# HTTProute referring custom backend sslprofile
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-httproute2
namespace: default
spec:
parentRefs:
- name: my-gateway-https2
namespace: default
hostnames:
- "example123.com"
rules:
- filters:
# Here we are referring to all types of profiles for this rule.
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "sslprofile"
name: "backend-ssl-custom"
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "httpprofile"
name: "backend-http-custom"
- type: ExtensionRef
extensionRef:
group: "citrix.com"
kind: "tcpprofile"
name: "backend-tcp-custom"
matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: app1-svc
namespace: default
port: 443
<!--NeedCopy-->
Controller scoping through spec.gatewayClassName
The spec.gatewayClassName field controls which NetScaler Gateway Controller instances process the profile CRD. This control is crucial in multitenant or multi-controller environments.
| Scenario | spec.gatewayClassName |
Controller Behavior |
|---|---|---|
| Scoped | PRESENT (for example, netscaler-prod) |
Only the Controller instance managing that specific GatewayClass processes the Profile, ensuring isolation and targeted configuration. |
| Global | ABSENT | All NetScaler Gateway Controller instances in the cluster are free to accept and configure the profile on their respective NetScaler appliances. |
If a Profile specifies a gatewayClassName that is not currently deployed in the cluster, the profile CRD is skipped until the corresponding GatewayClass becomes available.