Product Documentation
NetScaler ingress controller
View PDF

Deploy NetScaler Ingress Controller (NSIC) with CPX in OpenShift using NetScaler Operator

November 26, 2024
Contributed by: 
C

In this setup, NetScaler Ingress Controller configures NetScaler CPX deployed in the OpenShift cluster.

Prerequisites

  • Access to Red Hat OpenShift Cluster (version 4.1 or later).
  • Deploy NetScaler Operator. For information on how to deploy NetScaler Operator, see Deploy NetScaler Operator.

  • To export to any service monitor, install the service monitor CRD by using the following command:

     kubectl create -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/refs/heads/main/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml
 <!--NeedCopy-->
  • Install Prometheus Operator if you want to view the metrics of the NetScaler CPX collected through the direct Prometheus export.

Deploy NetScaler Ingress Controller as a sidecar with NetScaler CPX

Using the NetScaler Operator, you can deploy NetScaler CPX with the NetScaler Ingress Controller as a sidecar. The NetScaler Ingress Controller configures the NetScaler CPX which is deployed as an ingress or router for an application running in the OpenShift cluster. The following diagram explains the topology.

CPX Topology

Perform the following steps:

  1. Log in to the OpenShift 4.x Cluster console.

  2. Deploy an Apache application using the console.

    1. Navigate to Workloads > Deployments > Create Deployment and use the following YAML to create the deployment.

      ---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apache
  labels:
     name: apache
spec:
  selector:
    matchLabels:
      app: apache
  replicas: 2
  template:
    metadata:
      labels:
        app: apache
    spec:
      containers:
      - name: apache
        image: httpd:latest
        ports:
        - containerPort: 80
    ---

<!--NeedCopy-->

      Application Deployment

      Note:

      The Apache application is for the demonstration purpose only. You can modify the YAML file based on your requirement.

    2. Navigate to Workloads > Pods section and ensure that the Apache application pods are up and running.

      Application pod

  3. Create a service for the Apache application. Navigate to Networking > Services > Create Service and use the following YAML to create the service.

        apiVersion: v1
    kind: Service
    metadata:
      name: apache
    spec:
      ports:
      - port: 80
        targetPort: 80
      selector:
        app: apache
<!--NeedCopy-->

    Application Service

  4. Create an Ingress for the Apache application. Navigate to Networking > Ingress > Create Ingress and use the following YAML to create the ingress.

    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cpx-ingress
spec:
  rules:
  - host: citrix-ingress-operator.com
    http:
      paths:
      - backend:
          service:
            name: apache
            port:
              number: 80
        path: /
        pathType: Prefix
<!--NeedCopy-->

    Application CPX Ingress

  5. Navigate to Operators > Installed Operators and select NetScaler Operator.

    NetScaler Ingress Controller Operator

  6. Click NetScaler CPX with Ingress Controller tab.

    deploy CPX with Ingress Controller

  7. Click Create NetScalerCpxWithIngressController.

    The NetScaler CPX with NetScaler Ingress Controller YAML definition is displayed.

    cpx with nsic YAML

    Note:

    • Ensure that the acceptLicense parameter is set to Yes.
    • To associate NSIC with the ingress resource specified in this procedure, provide the ingress class name using the ingressClass parameter as ingressClass: [‘nsic-cpx].

    Refer to the following table to configure other available parameters depending on your use case.

    Parameters Mandatory or Optional Default value Description
    acceptLicense Mandatory no Set Yes to accept the NetScaler Ingress Controller EULA.
    affinity Optional N/A Affinity labels for pod assignment.
    nodeSelector Optional N/A The node label key:value pair to be used for nodeSelector option in NetScaler Ingress Controller deployment.
    podAnnotations Optional N/A Map of annotations to add to the pods.
    replicaCount Optional 1 The number of CPX-NSIC pods to be deployed. With cpxBgpRouter : true, replicaCount is 1 because CPX is deployed as a DaemonSet.
    tolerations Optional N/A Specify the tolerations for the CPX-NSIC deployment.
    Parameter Mandatory/Optional Default value Description
    admSettings  
    ADMIP Optional N/A The NetScaler Console (formerly NetScaler ADM) IP address.
    bandWidth Optional 1000 The desired bandwidth capacity for NetScaler CPX in Mbps.
    bandWidthLicense Optional false Set this parameter to true if you want to use bandwidth-based licensing for NetScaler CPX.
    cpxCores Optional 1 The desired number of vCPUs for NetScaler CPX.
    licenseEdition Optional PLATINUM The possible values are Standard, Platinum, and Enterprise.
    licenseServerIP Optional N/A NetScaler Console (formerly NetScaler ADM) IP address to license NetScaler CPX. For more information, see Licensing.
    licenseServerPort Optional 27000 NetScaler Console (formerly NetScaler ADM) port if non-default port is used.
    loginSecret Optional N/A The secret key to log in to NetScaler Console.
    platform Optional false Set to true to enable CP1000 platform license.
    vCPULicense Optional N/A Set the value to true if you want to use a vCPU-based license for NetScaler CPX.
    Parameter Mandatory/Optional Default value Description
    analyticsConfig  
    distributedTracing.enable Optional false Set the value to true to enable OpenTracing in NetScaler.
    distributedTracing.samplingrate Optional 100 The OpenTracing sampling rate in percentage.
    endpoint.metrics.service Optional N/A Set this value as the IP address or DNS address of the analytics server. Format:servicename.namespace.svc.cluster.local, namespace/servicename.
    endpoint.transactions.service Optional N/A Set this parameter as the IP address or service name with namespace of the analytics service deployed in the Kubernetes environment. Format: namespace/servicename.
    required Mandatory false Set this parameter to true if you want to configure NetScaler to send metrics and transaction records to the analytics service.
    timeseries.port Optional 5563 The port used to expose analytics service for the time-series endpoint.
    timeseries.metrics.enable Optional false Set this value to true to enable sending metrics from NetScaler.
    timeseries.metrics.mode Optional Avro The mode of metric endpoint.
    timeseries.metrics.exportFrequency Optional 30 The time interval for exporting the time-series data. The possible values range from 30 to 300 seconds.
    timeseries.metrics.schemaFile Optional schema.json The name of a schema file with the required NetScaler counters to be added and configured for the metrics collector. A reference schema file reference_schema.json with all the supported counters is also available in path /var/metrics_conf/. This schema file can be used as a reference to build a custom list of counters.
    timeseries.metrics.enableNativeScrape Optional false Set this parameter to true for native export of metrics.
    timeseries.auditlogs.enable Optional false Set this parameter to true to export audit log data from NetScaler.
    timeseries.events.enable Optional false Set this paramter to true to export events from NetScaler.
    transactions.enable Optional false Set this parameter to true to export transactions from NetScaler.
    transactions.port Optional 5557 The port used to expose analytics service for transaction endpoint.
    Parameter Mandatory/Optional Default value Description
    exporter  
    required Optional false Set this parameter to true to run the Exporter for NetScaler Stats along with NetScaler Ingress Controller to pull metrics for NetScaler CPX.
    image Optional quay.io/netscaler/netscaler-adc-metrics-exporter@sha256:3d54b9151c742c00117be74e1ffd54430358e4cf628fe1f02d503088583f678 The metrics exporter image hosted on Quay.io.
    pullPolicy Optional IfNotPresent The exporter image pull policy.
    resources Optional {} CPU/memory resources for the metrics exporter container.
    ports.containerPort Optional 8888 The exporter container port.
    extraVolumes Optional N/A Additional volumes for the additional volumeMounts.
    imagePullSecrets Optional N/A A list of Kubernetes secrets to be used for pulling the images from a private Docker registry or repository. For more information on how to create this secret, see Pull an Image from a Private Registry.
    Parameter Mandatory/Optional Default value Description
    ingressController  
    defaultSSLCertSecret Optional N/A The Kubernetes secret name that needs to be used as a default non-SNI certificate in NetScaler.
    defaultSSLSNICertSecret Optional N/A The Kubernetes secret name that needs to be used as a default SNI certificate in NetScaler.
    disableAPIServerCertVerify Optional false Set this parameter to true for disabling API server certificate verification.
    disableOpenshiftRoutes false By default OpenShift routes are processed in the OpenShift environment. Set this parameter to true to disable processing of the OpenShift routes by NetScaler Ingress Controller.  
    enableLivenessProbe Optional true Set this parameter to false to disable liveness probe settings for NetScaler Ingress Controller.
    enableReadinessProbe Optional true Readiness probe settings for NetScaler Ingress Controller.
    entityPrefix Optional N/A The prefix for the resources on NetScaler CPX.
    extraVolumeMounts Optional N/A  
    image Mandatory quay.io/netscaler/netscaler-k8s-ingress-controller@sha256:2ff38654476234bfe2c3908932702b90c8ec6ed3cfb7c7f467dc6181df0f1adf The NetScaler Ingress Controller image hosted on Quay.io.
    ingressClass Optional N/A Parameter to associate a particular ingress resource with NetScaler Ingress Controller. For more information on ingress class, see Ingress class support. For Kubernetes version >= 1.19, this parameter creates an IngressClass object with the name specified here.
    ipam Optional false Set this parameter to true to enable IP address management using the IPAM controller.
    jsonLog Optional false Set this parameter to true if log messages are required in the JSON format.
    kubernetesURL Optional N/A The kube-apiserver url that NetScaler Ingress Controller uses to register the events. If the value is not specified, NetScaler Ingress Controller uses the internal kube-apiserver IP address.
    livenessProbe.initialDelaySeconds Optional 30 The time period in seconds for which Kubernetes waits before performing the first liveness check.
    livenessProbe.periodSeconds Optional 60 After the initial delay, Kubernetes performs a liveness check every 60 seconds.
    logLevel Optional INFO The log level to control the logs generated by NSIC. The supported log levels are: CRITICAL, ERROR, WARNING, INFO, DEBUG, TRACE, and NONE.
    logProxy Optional N/A Elasticsearch or Kafka or Zipkin endpoint for NetScaler observability exporter.
    namespaceLabels Optional N/A The namespace labels selectors to be used by NetScaler Ingress Controller for routeSharding in OpenShift cluster.
    openshift Optional true Set this parameter to false if the OpenShift environment is not being used.
    optimizeEndpointBinding Optional false Set to true to enable binding of back-end endpoints to a service group in a single API-call. We recommended to set this parameter to true when the number of endpoints (pods) per application are large in number. Applicable only for NetScaler Version >=13.0-45.7
    profileHttpFrontend Optional N/A The front-end HTTP profile. For details, see Configuration using FRONTEND_HTTP_PROFILE
    profileSslFrontend Optional N/A The front-end SSL profile. For details, see Configuration using FRONTEND_SSL_PROFILE
    profileTcpFrontend Optional N/A The front-end TCP profile. For details, see Configuration using FRONTEND_TCP_PROFILE
    pullPolicy Mandatory IfNotPresent The NetScaler Ingress Controller image pull policy.
    rbacRole Optional false To deploy NSIC with RBAC role, set rbacRole=true. By default, NSIC gets installed with ClusterRole (rbacRole=false).
    readinessProbe Optional N/A Readiness probe settings.
    resources Optional {} CPU/memory resources for the NetScaler Ingress Controller container.
    routeLabels Optional ’’ You can use this parameter to provide the route labels selectors to be used by NetScaler Ingress Controller for routeSharding in the OpenShift cluster.
    setAsDefaultIngressClass Optional False Sets the IngressClass object as the default ingress class. New ingresses without an “ingressClassName” field specified will be assigned this ingress class. This parameter is applicable only for Kubernetes versions >= 1.19.
    updateIngressStatus Optional True Set this parameter if Status.LoadBalancer.Ingress field of the ingress resources managed by NetScaler Ingress Controller needs to be updated with allocated IP addresses. For more information see this.
    Parameter Mandatory/Optional Default value Description
    netscalerCpx  
    bgpSettings.bgpConfig Optional N/A This parameter represents BGP configurations in the YAML format. For the description about individual fields, refer the documentation
    cpxBgpRouter Optional false If this parameter is set to true, CPX is deployed as a daemonset in the BGP controller mode, where the BGP advertisements are done for attracting external traffic to the Kubernetes clusters.
    cpxCommands Optional N/A User-provided NetScaler bootup config that is applied when CPX is instantiated. This config is not a dynamic config, and any subsequent changes to the configmap don’t reflect in the CPX config unless the pod is restarted. For more info, refer this.
    cpxLicenseAggregator Optional N/A IP address/FQDN of the CPX License Aggregator if it is being used to license the CPX.
    cpxShellCommands Optional N/A A user-provided bootup config that is applied when CPX is instantiated. Note that this is not a dynamic config, and any subsequent changes to the configmap don’t reflect in the CPX config unless the pod is restarted. For more info, refer the documentation.
    daemonSet Optional false Set this parameter to true if NetScaler CPX must be deployed as a DaemonSet.
    enableLivenessProbe Optional true Set to false to disable liveness probe settings for NetScaler CPX.
    enableStartupProbe Optional true Set to false to disable the startupProbe settings for NetScaler CPX.
    extraVolumeMounts Optional N/A  
    hostName Optional N/A This entity is used to set Hostname of the CPX.
    image Mandatory quay.io/netscaler/netscaler-cpx@sha256:04defadf6311259d6ada5380498ed7afe8035b11ee3c1d7b456faa94472b5550 NetScaler CPX image hosted on Quay.io.
    ingressIP Optional N/A External IP address to be used by ingress resources if the value is not overridden by ingress.com/frontend-ip annotation in ingress resources. This IP address is also advertised to external routers when cpxBgpRouter is set to true.
    livenessProbe Optional N/A livenessProbe settings for NetScaler CPX.
    mgmtHttpPort Optional 9080 The HTTP port to be used for a NodePort CPX service.
    mgmtHttpsPort Optional 9443 The HTTPS port to be used for a NodePort CPX service.
    nitroReadTimeout Optional 20 The nitro read timeout in seconds.
    nsConfigDnsRec Optional false To enable/disable DNS address record addition in NetScaler through ingress.
    nsCookieVersion Optional 0 The persistence cookie version. Possible values are 0 and 1.
    nsDnsNameserver Optional N/A DNS nameservers in NetScaler.
    nsEnableLabels Optional true Enable labels for NetScaler CPX.
    nsGateway Optional 192.168.1.1 Gateway used by CPX for internal communication when it’s run in the host mode, i.e when cpxBgpRouter is set to true. If this parameter is not specified, the first IP address in the nsIP network is used as a gateway. It must be in the same network as nsIP.
    nsHTTP2ServerSide Optional OFF Set this parameter to ON to enable HTTP2 for NetScaler service group configurations.
    nsIP Optional 192.168.1.2 NetScaler IP address used by NetScaler CPX for internal communication when it’s run in the host mode, i.e when cpxBgpRouter is set to true. A /24 internal network is created in this IP range which is used for internal communications within the network namespace.
    nsLbHashAlgo.required Optional false Set this parameter to true to set the LoadBalancing consistent hashing algorithm.
    nsLbHashAlgo.hashFingers Optional 256 The number of fingers to be used for the hashing algorithm. Possible values are from 1 to 1024.
    nsLbHashAlgo.hashAlgorithm Optional ‘default’ Supported algorithms are default, jarh, and prac.
    nsProtocol Optional http The protocol used for communication between NetScaler CPX and NetScaler Ingress Controller.
    nsSvcLbDnsRec Optional false Set this parameter to true to enable DNS address record addition in NetScaler through the type LoadBalancer service.
    prometheusCredentialSecret Optional N/A The secret key required to create a read-only user for native export of metrics using Prometheus.
    pullPolicy Mandatory IfNotPresent The NetScaler CPX image pull policy.
    service.annotations Optional N/A Dictionary of annotations to be used in the CPX service. For example, see this.
    service.spec Optional N/A Specification settings of NetScaler CPX.
    startupProbe Optional N/A Startup probe settings for NetScaler CPX.

  8. After updating the values for the required parameters, click Create. Ensure that the NetScaler CPX with Ingress Controller is successfully deployed and initialized.

    deploy CPX with Ingress Controller deployed

  9. Attach privileged security context constraints to the service account of NetScaler CPX (as it runs as a privileged pod) by using the following command:

    • Get the service account name used by NetScaler CPX using the following command in the namespace where NetScaler CPX has been deployed: oc get sa

    • Attach privileged SCC to the service account of NetScaler CPX:

    oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<CPX-ServiceAccount-Name retrieved in the previous step>
<!--NeedCopy-->

  10. Navigate to Workloads > Pods section and verify that the netscaler-cpx-with-ingress-controller pod is up and running.

    deploy CPX with Ingress Controller pods

  11. Verify the deployment by sending traffic.

    1. Obtain the NodePort details using the following command:

      oc get svc
<!--NeedCopy-->

    2. Use cpx-service NodePort and send the traffic as shown in the following command:

      curl http://citrix-ingress-Operator.com:<NodePort> --resolve citrix-ingress-Operator.com:<NodePort>:<Master-Node-IP>
<!--NeedCopy-->

    The preceding curl command should return the following output:

    <html><body><h1>It works!</h1></body></html>
<!--NeedCopy-->

Note:

When you delete an NSIC instance, the ClusterRole and ClusterRole binding associated with the service account of the NSIC instance are not deleted automatically. You must manually delete the ClusterRole and ClusterRole binding associated with the service account of the deleted NSIC instance.

References

Deploy NetScaler Ingress Controller (NSIC) with CPX in OpenShift using NetScaler Operator
November 26, 2024
Contributed by: 
C
November 26, 2024
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.