NetScaler ingress controller

Deploy the NetScaler Ingress Controller using Red Hat OpenShift Operators

An Operator is an open source toolkit designed to package, deploy, and manage Kubernetes native applications in a more effective, automated, and scalable way.

This topic covers information on how to deploy the NetScaler Ingress Controller using OpenShift Operators.

Deployment options

Based on how you want to use NetScaler, there are two ways to deploy the NetScaler Ingress Controller in an OpenShift cluster:

  • As a standalone pod in the Kubernetes cluster: In this mode, you can control the NetScaler MPX or VPX appliance deployed outside the cluster.
  • As a sidecar container alongside NetScaler CPX in the same pod: In this mode, NetScaler Ingress Controller configures the NetScaler CPX.

Deploy the NetScaler Ingress Controller as a standalone pod in the OpenShift cluster for NetScaler MPX or VPX appliances

Using the NetScaler Ingress Controller Operator you can deploy the NetScaler Ingress Controller as a standalone pod in the OpenShift cluster. The NetScaler Ingress Controller configures the NetScaler VPX or MPX which is deployed as an Ingress or router for an application running in the OpenShift cluster. The following diagram explains the topology:

Topology

Prerequisites

  • Deployed Red Hat OpenShift version 4.1 or later.
  • Determine the NS_IP IP address needed by the controller to communicate with the appliance. The IP address might be anyone of the following depending on the type of NetScaler deployment:
    • (Standalone appliances) NSIP - The management IP address of a standalone NetScaler appliance. For more information, see IP Addressing in NetScaler
    • (Appliances in High Availability mode) SNIP - The subnet IP address. For more information, see IP Addressing in NetScaler
    • (Appliances in Clustered mode) CLIP - The cluster management IP (CLIP) address for a clustered NetScaler deployment. For more information, see IP addressing for a cluster
  • The user name and password of the NetScaler VPX or MPX appliance used as the Ingress device. The NetScaler appliance must have a system user account (non-default) with certain privileges so that the NetScaler Ingress Controller can configure the NetScaler VPX or MPX appliance. For instructions to create the system user account on NetScaler, see Create System User Account for NetScaler Ingress Controller in NetScaler

    You can directly pass the user name and password as environment variables to the controller, or use Kubernetes secrets (recommended). If you want to use Kubernetes secrets, create a secret for the user name and password using the following command:

     kubectl create secret  generic nslogin --from-literal=username='cic' --from-literal=password='mypassword'
    

Specify the allowed image registries to access by operators and pods

You must specify the image registries to which operators and pods should have access for pulling the images. You can specify the allowed list of registries by updating the image.config.openshift.io/cluster custom resource definition file. Ensure to bring up the Openshift cluster before updating the image.config.openshift.io/cluster custom resource definition.

To update the image.config.openshift.io/cluster custom resource definition, perform the following steps:

  1. Run the following command:

    oc edit image.config.openshift.io/cluster
    
  2. Edit the spec field such as follows:

    spec:
      registrySources:
        allowedRegistries:
        - quay.io
        - registry.redhat.io
        - registry.connect.redhat.com
        - registry.access.redhat.com
        - image-registry.openshift-image-registry.svc:5000
    

Note:

If your application needs to pull images from registries other than the ones specified here, you can add those registries. Note:

The changes are applied to all the master and worker nodes and the node is in ‘Not Ready’ state for some time after updating the CRD. You must wait for all the nodes to be in ‘Ready’ state before proceeding to the next step. You can view the status of the nodes using the oc get nodes command:

Create a system user account for the NetScaler Ingress Controller in NetScaler

The NetScaler Ingress Controller configures the NetScaler appliance (MPX or VPX) using a system user account of the NetScaler. The system user account should have certain privileges so that the NetScaler Ingress Controller has permission to configure the following on the NetScaler:

  • Add, Delete, or View Content Switching (CS) virtual server
  • Configure CS policies and actions
  • Configure Load Balancing (LB) virtual server
  • Configure Service groups
  • Cofigure SSl certkeys
  • Configure routes
  • Configure user monitors
  • Add system file (for uploading SSL certkeys from Kubernetes)
  • Configure Virtual IP address (VIP)
  • Check the status of the NetScaler appliance

To create the system user account, perform the following:

  1. Log on to the NetScaler appliance. Perform the following:
    1. Use an SSH client, such as PuTTy, to open an SSH connection to the NetScaler appliance.

    2. Log on to the appliance by using the administrator credentials.

  2. Create the system user account using the following command:

    add system user <username> <password>
    

    For example:

    add system user cic mypassword
    
  3. Create a policy to provide required permissions to the system user account. Use the following command:

    add cmdpolicy cic-policy ALLOW '^\(\?!shell)\(\?!sftp)\(\?!scp)\(\?!batch)\(\?!source)\(\?!.\*superuser)\(\?!.\*nsroot)\(\?!install)\(\?!show\s+system\s+\(user|cmdPolicy|file))\(\?!\(set|add|rm|create|export|kill)\s+system)\(\?!\(unbind|bind)\s+system\s+\(user|group))\(\?!diff\s+ns\s+config)\(\?!\(set|unset|add|rm|bind|unbind|switch)\s+ns\s+partition).\*|\(^install\s\*\(wi|wf))|\(^\S+\s+system\s+file)^\(\?!shell)\(\?!sftp)\(\?!scp)\(\?!batch)\(\?!source)\(\?!.\*superuser)\(\?!.\*nsroot)\(\?!install)\(\?!show\s+system\s+\(user|cmdPolicy|file))\(\?!\(set|add|rm|create|export|kill)\s+system)\(\?!\(unbind|bind)\s+system\s+\(user|group))\(\?!diff\s+ns\s+config)\(\?!\(set|unset|add|rm|bind|unbind|switch)\s+ns\s+partition).\*|\(^install\s\*\(wi|wf))|\(^\S+\s+system\s+file)'
    

    Note: The system user account would have privileges based on the command policy that you define.

    The command policy mentioned in step 3 is similar to the built-in sysAdmin command policy with another permission to upload files.

    In the command policy specification provided, special characters which need to be escaped are already omitted to easily copy-paste into the NetScaler command line.

    For configuring the command policy from the NetScaler configuration wizard (GUI), use the following command policy specification.

    ^\(?!shell)\(?!sftp)\(?!scp)\(?!batch)\(?!source)\(?!.\*superuser)\(?!.\*nsroot)\(?!install)\(?!show\s+system\s+\(user|cmdPolicy|file))\(?!\(set|add|rm|create|export|kill)\s+system)\(?!\(unbind|bind)\s+system\s+\(user|group))\(?!diff\s+ns\s+config)\(?!\(set|unset|add|rm|bind|unbind|switch)\s+ns\s+partition).\*|\(^install\s\*\(wi|wf))|\(^\S+\s+system\s+file)^\(?!shell)\(?!sftp)\(?!scp)\(?!batch)\(?!source)\(?!.\*superuser)\(?!.\*nsroot)\(?!install)\(?!show\s+system\s+\(user|cmdPolicy|file))\(?!\(set|add|rm|create|export|kill)\s+system)\(?!\(unbind|bind)\s+system\s+\(user|group))\(?!diff\s+ns\s+config)\(?!\(set|unset|add|rm|bind|unbind|switch)\s+ns\s+partition).\*|\(^install\s\*\(wi|wf))|\(^\S+\s+system\s+file)
    
  4. Bind the policy to the system user account using the following command:

    bind system user cic cic-policy 0
    

Deploy the NetScaler Ingress Controller as a standalone pod using Operators

Perform the following:

  1. Log on to OpenShift 4.1 Cluster console.

  2. Deploy an Apache application using the console. Perform the following:

    1. Navigate to Workloads > Deployments > Create Deployment and use the apache.yaml to create the deployment.

      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 apache-service.yaml to create the service.

    Application Service

  4. Create an ingress for the Apache application. Navigate to Networking > Ingress > Create Ingress and use the apache-ingress-vpx.yaml to create the ingress. Ensure that you update VIP of the NetScaler VPX in the ingress YAML before applying it in the cluster.

    Application Ingress

  5. Navigate to Catalog > OperatorHUB, select the NetScaler Ingress Controller Operator, and click Install.

    NetScaler Ingress Controller operator

    Install

    You have the following options to subscribe to the NetScaler Ingress Controller Operator:

    • All namespaces on the cluster (default) - Allows the NetScaler Ingress Controller operator to subscribe to every namespace present on the OpenShift cluster and hence allows you to initiate the NetScaler Ingress Controller from any namespace on the cluster.
    • A specific namespace on the cluster - Allows the NetScaler Ingress Controller operator to subscribe to the selected namespace on the OpenShift cluster. You can initiate the NetScaler Ingress Controller instance on the selected namespace only.

    For the demonstration purpose, you can subscribe the NetScaler Ingress Controller operator to the default namespace.

    Application Subscription

    Wait until the NetScaler Ingress Controller operator is subscribed successfully.

    Application Subscription confirmation

  6. Navigate to Workloads > Pods section and verify that the cic-operator pod is up and running.

    Application Pod UP and Running

  7. Navigate to Catalog > Installed Operators and select the NetScaler Ingress Controller operator.

    Application POD and CIC

  8. Click NetScaler Ingress Controller and in the Overview tab, select Create New on the option to create the CRD for the NetScaler Ingress Controller operator.

    Create New

    The NetScaler Ingress Controller YAML definition is displayed.

    Parameter lists

    The following table lists the mandatory and optional parameters and their default values that you can configure also during installation. Ensure that you set the license.accept parameter to yes and provide the IP address of the NetScaler VPX instance in the nsIP parameter.

    Parameters Mandatory or Optional Default value Description
    license.accept Mandatory no Set yes to accept the NetScaler Ingress Controller end user license agreement.
    cic.image Mandatory quay.io/citrix/citrix-k8s-ingress-controller:1.26.7 The NetScaler Ingress Controller image.
    cic.pullPolicy Mandatory Always The NetScaler Ingress Controller image pull policy.
    loginFileName Mandatory nslogin The secret key to log on to the NetScaler VPX or MPX. For information on how to create the secret keys, see Prerequisites.
    nsIP Mandatory N/A The IP address of the NetScaler device. For details, see Prerequisites.
    nsVIP Optional N/A The virtual IP address on the NetScaler device.
    nsPort Optional 443 The port used by the NetScaler Ingress Controller to communicate with NetScaler. You can port 80 for HTTP.
    nsProtocol Optional HTTPS The protocol used by the NetScaler Ingress Controller to communicate with NetScaler. You can also use HTTP on port 80.
    logLevel Optional DEBUG The log level to control the logs generated by the NetScaler Ingress Controller. The supported log levels are: CRITICAL, ERROR, WARNING, INFO, and DEBUG. For more information, see Log Levels.
    kubernetesURL Optional N/A The kube-apiserver url that the NetScaler Ingress Controller uses to register the events. If the value is not specified, the NetScaler Ingress Controller uses the internal kube-apiserver IP address.
    ingressClass Optional N/A If multiple ingress load balancers are used to load balance different ingress resources. You can use this parameter to specify the NetScaler Ingress Controller to configure NetScaler associated with specific ingress class. For more information on Ingress class, see Ingress class support.
    nodeWatch Optional false Use the argument if you want to automatically configure the network route from the Ingress NetScaler VPX or MPX to the pods in the Kubernetes cluster. For more information, see Automatically configure a route on the NetScaler instance.
    defaultSSLCert Optional N/A Default SSL certificate that must be used as a non-SNI certificate in NetScaler.
    exporter.required Optional false Use the argument, if you want to run the Exporter for NetScaler Stats along with the NetScaler Ingress Controller to pull metrics for the NetScaler VPX or MPX
    exporter.image Optional quay.io/citrix/citrix-adc-metrics-exporter:1.4.6 The image of Exporter for NetScaler Stats.
    exporter.pullPolicy Optional Always The pull policy for the Exporter for NetScaler Stats image.
    exporter.ports.containerPort Optional 8888 The container port of the Exporter for NetScaler Stats.
    openshift Optional true Set this argument if OpenShift environment is being used.

    After you have updated the values of the required parameters, click Create.

  9. Navigate to Workloads > Pods section and ensure that the citrix-ingress-controller pod is up and running.

    NetScaler Ingress Controller Deployment Success

  10. Verify the deployment by sending traffic as shown:

    curl http://citrix-ingress-operator.com --resolve citrix-ingress-operator.com:80:<VIP>
            
        It works!
    

Deploy the NetScaler Ingress Controller as a sidecar with NetScaler CPX

Using the NetScaler Ingress Controller Operator you can deploy a 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

Prerequisites

Deploy the NetScaler Ingress Controller as a sidecar with NetScaler CPX using Operators

Perform the following:

  1. Log on to OpenShift 4.1 Cluster console.

  2. Deploy an Apache application using the console. Perform the following:

    1. Navigate to Workloads > Deployments > Create Deployment and use the apache.yaml to create the deployment.

      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 apache-service.yaml to create the service.

    Application Service

  4. Create an Ingress for the Apache application. Navigate to Networking > Ingress > Create Ingress and use the apache-ingress-cpx.yaml to create the ingress.

    Application CPX Ingress

  5. Navigate to Catalog > OperatorHUB, select the NetScaler CPX with Ingress Controller Operator and click Install.

    Operator Hub

    Operator Hub Install

    You have the following options to subscribe to the NetScaler Ingress Controller Operator:

    • All namespaces on the cluster (default) - Allows the NetScaler Ingress Controller operator to subscribe to every namespace present on the OpenShift cluster and hence allows you to initiate the NetScaler CPX from any namespace on the cluster.
    • A specific namespace on the cluster - Allows the NetScaler Ingress Controller operator to subscribe to the selected namespace on the OpenShift cluster. You can initiate the NetScaler CPX instance on the selected namespace only.

    For the demonstration purpose, you can subscribe the NetScaler Ingress Controller operator to the default namespace.

    Subscription

    Wait until the operator is subscribed successfully.

    Subscription

  6. Navigate to Workloads > Pods section and verify that the cic-operator pod is up and running.

  7. Navigate to Catalog > Installed Operators and select the NetScaler Ingress Controller operator.

    Application POD and CIC

  8. Click NetScaler CPX with Ingress Controller and in the Overview tab, select Create New on the option to create the CRD for the NetScaler CPX with the Ingress Controller operator.

    Create New

    The NetScaler CPX with ingress controller YAML definition is displayed.

    Parameter lists

    The following table lists the mandatory and optional parameters and their default values that you can configure during installation. Ensure that you set the license.accept parameter to yes.

    Parameters Mandatory or Optional Default value Description
    license.accept Mandatory no Set yes to accept the NetScaler Ingress Controller end user license agreement.
    cpx.image Mandatory quay.io/citrix/citrix-k8s-cpx-ingress:13.0-83.27 The NetScaler CPX image.
    cpx.pullPolicy Mandatory Always The NetScaler CPX image pull policy.
    lsIP Optional N/A Provide the NetScaler Application Delivery Management (ADM) IP address to license NetScaler CPX. For more information, see Licensing
    lsPort Optional 27000 NetScaler ADM port if a non-default port is used.
    platform Optional N/A Platform license. The platform is CP1000.
    cic.image Mandatory quay.io/citrix/citrix-k8s-ingress-controller:1.21.9 The NetScaler Ingress Controller image.
    cic.pullPolicy Mandatory Always The NetScaler Ingress Controller image pull policy.
    cic.required Optional true Specifies this parameter to run the NetScaler Ingress Controller as a sidecar with NetScaler CPX
    defaultSSLCert Optional N/A Default SSL certificate that must be used as a non-SNI certificate in NetScaler.
    exporter.required Optional false Use the argument if you want to run the Exporter for NetScaler Stats along with the NetScaler Ingress Controller to pull metrics for the NetScaler CPX
    exporter.image Optional quay.io/citrix/citrix-adc-metrics-exporter:1.4.6 The image for the Exporter for NetScaler Stats.
    exporter.pullPolicy Optional Always The image pull policy for the Exporter for NetScaler Stats
    exporter.ports.containerPort Optional 8888 The container port of Exporter for the NetScaler Stats.
    ingressClass Optional N/A If multiple ingress load balancers are used to load balance different ingress resources. You can use this parameter to specify the NetScaler Ingress Controller to configure NetScaler associated with specific ingress class.
    openshift Optional true Set this argument if OpenShift environment is being used.

    After you have updated the values of the required parameters, click Create.

  9. Navigate to Workloads > Pods section and ensure that the cpx-ingress pod is up and running.

    NetScaler Ingress Controller Deployment Success

  10. Verify the deployment by sending traffic. Perform the following:

    1. Obtain the NodePort details using the following command:

      oc get svc

    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>
      <html><body><h1>It works!</h1></body></html>
      
Deploy the NetScaler Ingress Controller using Red Hat OpenShift Operators