NetScaler ingress controller

Listener

December 31, 2023

Contributed by:

The Listener CRD represents the endpoint information of the content switching load balancing virtual server. This topic contains a sample Listener CRD object and also explains the various attributes of the Listener CRD. For the complete CRD definition, see Listener.yaml.

Note:

An Ingress resource and content routing CRDs (Listener CRD and HTTPRoute CRD) cannot co-exist for the same endpoint (IP address and port). The usage of content routing CRDs with Ingress is not supported.

Listener CRD object example

The following is an example of a Listener CRD object.

apiVersion: citrix.com/v1
kind: Listener
metadata:
  name: my-listener
  namespace: default
spec:
  certificates:
  - secret:
      name: my-secret
    # Secret named 'my-secret' in current namespace bound as default certificate
    default: true
  - secret:
      # Secret 'other-secret' in demo namespace bound as SNI certificate
      name: other-secret
      namespace: demo
  - preconfigured: second-secret
    # preconfigured certkey name in ADC
  vip: '192.168.0.1' # Virtual IP address to be used, not required when CPX is used as ingress device
  port: 443
  protocol: https
  redirectPort: 80
  secondaryVips:
  - "10.0.0.1"
  - "1.1.1.1"
  policies:
    httpprofile:
      config:
        websocket: "ENABLED"
    tcpprofile:
      config:
        sack: "ENABLED"
    sslprofile:
      config:
        ssl3: "ENABLED"
    sslciphers:
    - SECURE
    - MEDIUM
    analyticsprofile:
      config:
      - type: webinsight
        parameters:
           allhttpheaders: "ENABLED"
    csvserverConfig:
      rhistate: 'ACTIVE'
  routes:
    # Attach the policies from the below Routes
  - name: domain1-route
    namespace: default
  - name: domain2-route
    namespace: default
  - labelSelector:
      # Attach all HTTPRoutes with label route=my-route
      route: my-route
  # Default action when traffic matches none of the policies in the HTTPRoute
  defaultAction:
    backend:
      kube:
        namespace: default
        port: 80
        service: default-service
        backendConfig:
          lbConfig:
            # Use round robin LB method for default service
            lbmethod: ROUNDROBIN
          servicegroupConfig:
            # Client timeout of 20 seconds
            clttimeout: "20"

<!--NeedCopy-->

For more examples, see Listener examples.

Listener.spec

The Listener.spec attribute defines the Listener custom resource specification. The following table explains the various fields in the Listener.spec attribute.

Field	Description	Type	Required
`protocol`	Specifies the protocol of the load balancing content switching virtual server. Allowed values are: `http` and `https`.	string	yes
`port`	Specifies the port number of the load balancing content switching virtual server. The default port number for the HTTP protocol is 80 and the HTTPS protocol is 443.	integer	No
`routes`	Specifies the list of HTTPRoute resources that is to be attached to the Listener resource. The order of evaluation is as per the order of the list. That is, if multiple entries are present first route specified in the list has highest priority and so on.	[ ] routes	No
`certificates`	Specifies the list of certificates for the SSL virtual server if the protocol is HTTPS. This field is required if the protocol is HTTPS.	[ ] certificates	No
`vip`	Specifies the endpoint IP Address for the load balancing content switching virtual server. This address is required for NetScaler VPX and MPX devices, but not required for NetScaler CPXs present in the Kubernetes cluster. For NetScaler CPX, `vip` is same as the primary IP address of the NetScaler CPX allocated by the CNI.	string	No
`defaultAction`	Specifies the default action to take if none of the HTTPRoute resources specified in `routes` match the traffic.	action	No
`policies`	Specifies the option that enables you to customize HTTP, TCP, and SSL policies associated with the front-end virtual server.	[ ] Listener.policies	No
`redirectPort`	Specifies that the HTTP traffic on this port is redirected to the HTTPS port.	Integer	No
`secondaryVips`	Specifies a set of IP addresses which are used as VIPs with the primary VIP. An IPset is created and these VIPs are added to the IPset.	[ ] string	No

Listener.certificates

The Listener.certificates attribute defines the TLS certificate related information for the SSL virtual server.

Following is an example for the Listener.certificates attribute.

    certificates:
    - secret:
        name: my-secret
        namespace: demo
      default: true
    - preconfigured: configured-secret
<!--NeedCopy-->

The following table explains the various fields in the Listener.certificates attribute.

Field	Description	Type	Required
`secret`	Specifies TLS certificates specified through the Kubernetes secret resource. The secret must contain keys `tls.crt` and `tls.key`. These keys contain the certificate and private key. Either the secret or the preconfigured field is required. All certificates are bound to the SSL virtual server as SNI certificates.	certificates.secret	No
`preconfigured`	Specifies the name of the preconfigured TLS `certkey` in NetScaler, and this field is applicable only for Tier-1 VPX and MPX devices. The `certkey` must be present before the actual deployment of the Listener resource and otherwise deployment of the resource fails with an error. The NetScaler Ingress Controller does not manage the life cycle of `certkey`. So, you have to manage any addition or deletion of `certkey` manually. Either the secret or the preconfigured field is required.	string	No
`default`	Specifies the default certificate. Only one of the certificates can be marked as default. The default certificate is presented if virtual server receives the traffic without an SNI field. This certificate can be used to access the HTTPS application using the IP Address. Applicable values are `true` and `false`	boolean	No

Listener.certificates.Secret

This attribute represents the Kubernetes secret resource for the TLS certificates that has to be bound to the SSL virtual server.

The following table explains the various fields in the Listener.certificate.Secret attribute.

Field	Description	Type	Required
`name`	Specifies the name of the Kubernetes secret resource. The secret must contain keys named `tls.crt` and `tls.key`. These keys contain the certificate and private key. If more than one `tls.crt` field is present in the secret object, then the first certificate is considered as a server certificate and remaining certificates are considered as intermediate CA certificates. Also, certificates are linked recursively to each other starting from the server certificate.	string	yes
`namespace`	Specifies the namespace of the Kubernetes secret resource. If this value is not specified, the namespace is considered as same as the Listener resource.	string	No

Listener.routes

This attribute represents the list of HTTPRoute objects that are attached to the Listener resource. The following table explains the various fields in the Listener.routes attribute.

Field	Description	Type	Required
`name`	Specifies the name of the HTTPRoute resource evaluated for the routing decision to the back end server. Either the `name` or the `labelSelector` is required.	string	No
`namespace`	Specifies the namespace of the HTTPRoute resource. The default value is the name space of the Listener resource.	string	No
`labelSelector`	Specifies the label selector of the HTTPRoute resource. This field provides another way to attach HTTPRoute resources. HTTPRoute objects with label keys and values matching this selector are automatically attached to the listener resource. If routes get attached through the labelSelector, routes are attached without any specific order. Exception for this rule is a route with a default path (’/’) which is always attached at the end. As shown in the example, any HTTPRoute objects with labels and are attached to the listener object. For more information on labels and selectors, see the Kubernetes Documentation.	object	No

Listener.action

This attribute represents the default action if a request to the load balancing virtual server does not match any of the route objects presented in the Listener.routes field.

The following table explains the various fields in the Listener.action attribute.

Field	Description	Type	Required
`backend`	The default action for this field is to send the traffic to a back-end service. Either the back end or the redirect is required.	action.backend	No
`redirect`	The default action is to redirect the traffic. Either the back end or redirect is required.	action.redirect	No

Listener.action.backend

This attribute specifies the back end service for the default action. The following table explains the various fields in the Listener.action.backend attribute.

Field	Description	Type	Required
`kube`	Specifies the Kubernetes service information for the back end service.	action.backend.kube

Listener.action.backend.kube

This attribute represents the Kubernetes back end service for the default back end. If the service is of type NodePort or Loadbalancer, the node IP address and NodePort are used to send the traffic to the back end.

Following is an example for the Listener.action.backend.kube attribute.

        kube:
          service: default-service
          namespace: default
          port: 80
          backendConfig:
            lbConfig:
              lbmethod: ROUNDROBIN
            servicegroupConfig:
              clttimeout: '20'
<!--NeedCopy-->

The following table explains the various fields in the Listener.action.backend.kube attribute.

Field	Description	Type	Required
`service`	Specifies the name of the Kubernetes service for the default back end.	string	yes
`namespace`	Specifies the namespace of the Kubernetes service for the default back end.	string	yes
`port`	Specifies the port number of the Kubernetes service for the default back end.	integer	yes
`backendConfig`	Specifies the back-end configurations for the default back end.	BackendConfig	no

BackendConfig

This attribute represents the back end configurations of NetScaler. Following is an example for the BackendConfig attribute.

    backendConfig:
     sercureBackend: true
     lbConfig:
       lbmethod: ROUNDROBIN
     servicegroupConfig:
       clttimeout: '20'
<!--NeedCopy-->

The following table explains the various fields in the BackendConfig attribute.

Field	Description	Type	Required
`secureBackend`	Specifies whether the communication is secure or not. If the value of the `secureBackend` field is `true` secure communication is used to communicate with the back end. The default value is `false`, that means HTTP is used for the back end communication.
`lbConfig`	Specifies the NetScaler load balancing virtual server configurations for the given back end. One can specify key-value pairs as shown in the example which sets the LBVserver configurations for the back end. For all the valid configurations, see LB virtual server configurations.	object	No
`servicegroupConfig`	Specifies the NetScaler service group configurations for the given back end. One can specify the key-value pairs as shown in the example which sets the service group configurations for the back end. For all the valid configurations, see service group configurations.	object	No

Listener.action.redirect

    defaultAction:
      redirect:
       httpsRedirect: true
       responseCode: 302
<!--NeedCopy-->

The following table explains the various fields in the Listener.action.redirect attribute.

Field	Description	Type	Required
`httpsRedirect`	Redirects the HTTP traffic to HTTPS if this field is set to `yes`. Only the scheme is changed to HTTPS without modifying the other URL part. Either `httpsRedirect`, `hostRedirect` or `targetExpression` is required.	boolean	No
`hostRedirect`	Rewrites the host name part of the URL to the value set here and redirect the traffic. Other part of the URL is not modified during redirection.	string	No
`targetExpression`	Specifies the NetScaler expression for redirection. For example, to redirect traffic to HTTPS from HTTP, the following expression can be used: "”https://”+HTTP.REQ.HOSTNAME + HTTP.REQ.URL.HTTP_URL_SAFE”.	string	No
`responseCode`	Specifies the response code. The default response code is 302, which can be customized using this attribute.	Integer	No

Listener.policies

This attribute represents the default policies which are used for the Listener when policies are not specified. By using Listener.policies, you can customize the TCP, HTTP, and SSL behavior.

Following is an example for the Listener.policies attribute.

    policies:
     httpprofile:
      config:
       websocket: "ENABLED"
     tcpprofile:
      config:
       sack: "ENABLED"
     sslprofile:
      config:
       ssl3: "ENABLED"
     sslciphers:
      - HIGH
      - MEDIUM
      analyticsprofile:
       config:
       - type: webinsight
         parameters:
          allhttpheaders: "ENABLED"
      csvserverConfig:
       rhistate: 'ACTIVE'
       stateupdate: ‘ENABLED’
<!--NeedCopy-->

The following table explains the various fields in the Listener.policies attribute.

Field	Description	Type	Required
`httpprofile`	Specifies the HTTP configuration for the front end virtual server.	Listener.policies.httpprofile	No
`tcpprofile`	Specifies the TCP configuration for the front-end virtual server.	Listener.policies.tcpprofile	No
`sslprofile`	Specifies the SSL configuration for the front-end virtual server	Listener.policies.sslprofile	No
`sslciphers`	Specifies the list of ciphers which are to be bound to the SSL profile. The order is as specified in the list with the higher priority is provided to the first in the list and so on. You can use any SSL ciphers available in NetScaler or user created cipher groups in this field. For information about the list of ciphers available in the NetScaler, see Ciphers in NetScaler.	[ ] string	No
`analyticsprofile`	Specifies the analytics profile configuration for the front-end virtual server	Listener.policies.analyticsprofile	No
`csvserverConfig`	Specifies the front-end CS virtual server configuration for the Listener. You can specify the key value pair as shown in the example which sets the CS virtual server configuration for the front-end.	Object	No

Listener.policies.tcpprofile

This attribute represents the TCP profile settings for the front-end CS virtual server.

Following is an example for the Listener.policies.tcpprofile attribute.

    policies:
     tcpprofile:
      config:
       sack: "ENABLED"
       nagle: “ENABLED”
---
    policies:
     tcpprofile:
      preconfigured: test-tcp-profile
<!--NeedCopy-->

The following table explains the various fields in the Listener.policies.tcpprofile attribute.

Field	Description	Type	Required
`preconfigured`	Specifies the name of the preconfigured TCP profile that is to be used for the front-end CS virtual server. This profile must be present in the NetScaler before applying the policy. Otherwise, the Listener resource fails to apply. Either `preconfigured` or `config` is required.	string	No
`config`	Specifies the TCP profile settings for the front-end virtual server. You can specify the key-value pair as shown in the example to tune the TCP characteristics of the virtual server.	Object	No

Listener.policies.httpprofile

This attribute represents the HTTP configuration for the front-end CS virtual server.

Following is an example for the Listener.policies.httpprofile attribute.

    policies:
     httpprofile:
      config:
       websocket: "ENABLED"
---
    policies:
     httpprofile:
     preconfigured: test-http-profile
<!--NeedCopy-->

The following table explains the various fields in the Listener.policies.httpprofile attribute.

Field	Description	Type	Required
`preconfigured`	Specifies the name of the preconfigured HTTP profile that is to be used for the front end CS virtual server. This profile must be present in the NetScaler before applying the policy. Otherwise, Listener resource fails to apply. Either `preconfigured` or `config` is required.	string	No
`config`	Specifies the HTTP profile settings for the front-end virtual server. You can specify the key-value pair as shown in the example to tune the HTTP protocol characteristics of the virtual server.	Object	No

Listener.policies.sslprofile

This attribute represents the SSL profile for the front-end CS virtual server.

Following is an example for the Listener.policies.sslprofile attribute.

    policies:
     sslprofile:
      config:
       ssl3: "ENABLED"
---
    policies:
     sslprofile:
      preconfigured: test-ssl-profile
<!--NeedCopy-->

The following table explains the various fields in the Listener.policies.sslprofile attribute.

Field	Description	Type	Required
`preconfigured`	Specifies the name of the preconfigured SSL profile that is to be used for the front-end SSL virtual server. This profile must be present in the NetScaler before applying the policy. Otherwise, the Listener resource fails to apply. Either `preconfigured` or `config` is required.	string	No
`config`	Specifies the SSL profile configuration for the front-end virtual server. You can specify the key-value pair as shown in the example to tune the SSL characteristics of the virtual server.	Object	No
	Note: You must enable the default profiles using the `set ssl parameter -defaultProfile ENABLED` command in NetScaler for using the advanced SSL features.

Listener.policies.analyticsprofile

This attribute represents the analytics profile that is used to export counters and metrics to NetScaler Observability Exporter. By configuring this attribute, you can choose what is to be exported by creating and binding the analytics profile.

Following is an example for the Listener.policies.analyticsprofile attribute.

    policies:
     analyticsprofile:
      config:
      - type: webinsight
        parameters:
         allhttpheaders: "ENABLED"
---
    policies:
     analyticsprofile:
      preconfigured:
      - test-analytics-profile
      - test2-analytics-profile
<!--NeedCopy-->

The following table explains the various fields in the Listener.policies.analyticsprofile attribute.

Field	Description	Type	Required
`preconfigured`	Specifies the list of preconfigured analytics profiles that needs to be bound to the front-end virtual server. These profiles must be present in the NetScaler before applying the policy. Otherwise, the Listener resource fails to apply. Either `preconfigured` or `config` is required.	[ ] string	No
`config`	Specifies the list of analytics profiles which is to be bound to the front-end virtual server. This determines the fields to be exported to NetScaler Observability Exporter.	[ ] Listener.policies.analyticsprofile.config	No

Listener.policies.analyticsprofile.config

This attribute represents the analytics profile configuration for the different types of insights and HTTP header parameters which need to be exported.

The following table explains the various fields in the Listener.policies.analyticsprofile.config attribute.

Field	Description	Type	Required
`type`	Specifies the type that determines the type of analytics profile to be enabled. You can enable one or more of the following types: `webinsight`, `tcpinsight`, `securityinsight`, `videoinsight`, `hdxinsight`, `gatewayinsight`, `timeseries`, `lsninsight`, and `botinsight`	string	Yes
`parameters`	Specifies the additional parameters to be enabled as part of the analytics profile. You can specify the key-value pair as shown in the example. For example, using this field, you can select the HTTP parameters to be exported as part of `webinsight`	Object	No

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Listener

December 31, 2023

Contributed by:

December 31, 2023

Contributed by:

Listener CRD object example
Listener.spec
Listener.certificates
Listener.certificates.Secret
Listener.routes
Listener.action
Listener.action.backend
Listener.action.backend.kube
BackendConfig
Listener.action.redirect
Listener.policies
Listener.policies.tcpprofile
Listener.policies.httpprofile
Listener.policies.sslprofile
Listener.policies.analyticsprofile
Listener.policies.analyticsprofile.config

Was this helpful

Listener

Listener CRD object example

Listener.spec

Listener.certificates

Listener.certificates.Secret

Listener.routes

Listener.action

Listener.action.backend

Listener.action.backend.kube

BackendConfig

Listener.action.redirect

Listener.policies

Listener.policies.tcpprofile

Listener.policies.httpprofile

Listener.policies.sslprofile

Listener.policies.analyticsprofile

Listener.policies.analyticsprofile.config

In this article