Deploy NetScaler CPX as Ingress Device

In a Kubernetes environment, you can deploy NetScaler CPX instances as ingress resource to load balance Ingress traffic for Kubernetes services. For more information see, How NetScaler Ingress Controller works.

You can deploy the NetScaler CPX container as a Kubernetes pod in a node within the cluster, or you can deploy it on a host outside the cluster if that host participates in the same overlay network as the other Kubernetes nodes.

Prerequisites

Before you begin, be sure to do the following:

localized image

Deploying NetScaler CPX as an Ingress Resource Outside the Kubernetes Cluster

NetScaler CPX can be deployed as an Ingress load balancer outside the Kubernetes cluster. A host that is outside the cluster must participate in the same overlay network as the other Kubernetes nodes.

To deploy NetScaler CPX as an Ingress Resource on a host outside the Kubernetes cluster: On the host, deploy the NetScaler CPX instance on the Docker container by using the following docker run command:

docker run -dt --privileged=true -p <port_number> -e NS_HTTP_PORT=<netscaler_HTTP_port> -e NS_HTTPS_PORT=<netscaler_HTTPS_port> -e EULA=yes -e NS_MGMT_SERVER=<MAS_IP_address> -e NS_MGMT_FINGER_PRINT="<MAS_finger_print>" -e NS_ROUTABLE=<True|False> -e NS_LB_ROLE=<lb_role> -e HOST=$HOSTNAME store/citrix/netscalercpx:12.0-53.6

Example:

docker run -dt --privileged=true -p 5080:80 -p 5443:443 -p 80:5080 -e NS_HTTP_PORT=5080 -p 443:5443 -e NS_HTTPS_PORT=5443 -e EULA=yes -e NS_MGMT_SERVER=10.217.212.226 -e NS_MGMT_FINGER_PRINT="74:EA:04:90:2C:FA:BF:7A:31:C9:52:64:D3:9C:BC:D3:O8:9F:9A:O4" -e NS_ROUTABLE=FALSE -e NS_LB_ROLE=SERVER -e HOST=$HOSTNAME store/citrix/netscalercpx:12.0-53.6

The command deploys a NetScaler CPX docker container. The following table describes the various options and environment variables used in the docker run command:

Options and NetScaler Specific Environment Variables Descriptions
-dt Specifies that the NetScaler CPX container is run in daemon form.
–privileged=true Specifies that the NetScaler CPX container runs in privileged mode.
-p Maps the ports between the NetScaler CPX and the host. By default, the Kubernetes Ingress object assumes that the cluster is accessed used ports 80 and 443.
-p 5080:80 Binds the port 80 of the container to port 5080 of the host.
-p 5443:443 Binds the port 443 of the container to port 5443 of the host.
-p 443:5443 Binds the port 5443 of the container to port 443 of the host.
-p 80:5080 Binds the port 5080 of the container to port 80 of the host.
-e NS_HTTP_PORT or -e NS_HTTPS_PORT NetScaler CPX specific environment variable that enables you to assign custom ports for management access to NetScaler CPX. NetScaler MAS uses these ports to access the NetScaler CPX.
-e NS_MGMT_SERVER NetScaler CPX specific environment variable that allows you define the NetScaler MAS server IP address. When the NetScaler CPX is deployed, it automatically registers with the NetScaler MAS server using this IP address.
-e NS_MGMT_FINGER_PRINT NetScaler CPX specific environment variable that defines the NetScaler MAS fingerprint.
-e NS_ROUTABLE=FALSE NetScaler CPX specific environment variable specifying that the NetScaler CPX container is run in non-IP-per-container mode.
-e NS_LB_ROLE=SERVER NetScaler CPX specific environment variable specifying to NetScaler CPX and NetScaler MAS that the NetScaler CPX container is used as an Ingress resource.
-e HOST=$HOSTNAME NetScaler CPX specific environment variable specifying the host name that NetScaler MAS can use to access the NetScaler CPX container. Make sure that the host name can be resolved by NetScaler MAS, or else provide an IP address.

Once you deploy the NetScaler CPX instance on the host, it automatically registers with the NetScaler Management and Analytics System (MAS). You can view the deployed NetScaler CPX instances in the NetScaler MAS UI at: Networks > Instances > NetScaler CPX.

localized image

Deploying NetScaler CPX as an Ingress Load Balancer Within the Kubernetes Cluster

To deploy NetScaler CPX as an Ingress load balancer within a Kubernetes cluster, deploy it as a Kubernetes pod on a node in the Kubernetes cluster.

To deploy NetScaler CPX as an Ingress load balancer within the Kubernetes cluster 1. (Optional) If you want to deploy the NetScaler CPX as a Kubernetes pod on a particular node in the cluster, you can use a label to designate the node. To label a Kubernetes node, use the kubectl command:

kubectl label nodes <node_IP_address> node-role=<label_name>

Example:

kubectl label nodes 10.217.222.224 node-role=ingress

    Once you have labeled a node, you can specify the label in the pod specification so that the pod is deployed in the node. 2. Define a pod specification for NetScaler CPX to deploy the NetScaler CPX container as a pod in the Kubernetes cluster. The pod specification is defined in a YAML file or a JSON script. The YAML file or the JSON script should contain the container type, CPX image file name, NetScaler MAS server IP address, and NetScaler MAS server fingerprint. The following is an example of a pod specification for NetScaler CPX:

    apiVersion: v1
    kind: Pod
    metadata:
    name: cpx-ingress
    annotations:
        NETSCALER_AS_APP: "True"
    spec:
        containers:
            - name: cpx-ingress
              image: "cpx:12.0-41.16"
        securityContext:
            privileged: true
        env:
            - name: "EULA"
              value: "yes"
            - name: "NS_MGMT_SERVER"
              value: "10.217.212.226"
            - name: "NS_MGMT_FINGER_PRINT"
              value: "74:EA:04:90:2C:FA:BF:7A:31:C9:52:64:D3:9C:BC:D3:O8:9F:9A:O4"
            - name: "NS_ROUTABLE"
              value: "FALSE"
            - name: "NS_HTTP_PORT"
              value: "5080"
            - name: "NS_HTTPS_PORT"
              value: "5443"
            - name: "NS_LB_ROLE"
              value: "SERVER"
            - name: "HOST"
              value: ""
            - name: "KUBERNETES_TASK_ID"
        valueFrom:
        fieldRef:
        fieldPath: metadata.name
            - name:"HOST"
    valueFrom:
        fieldRef:
            fieldPath: spec.nodeName
        ports:
            - containerPort: 80
              hostPort: 5080
            - containerPort: 443
              hostPort: 5443
            - containerPort: 5080
              hostPort: 80
            - containerPort: 5443
              hostPort: 443
        imagePullPolicy: Always
        nodeSelector:
            node-role: ingress

Alternatively, you can define a pod specification to deploy the NetScaler CPX as a Replication Controller, so that if NetScaler CPX goes down, Kubernetes recreates the NetScaler CPX container in the cluster. The following is a sample specification:

    apiVersion: v1
    kind: ReplicationController
    metadata:
    name: cpx-ingress
    spec:
        replicas: 1
        selector:
            app: cpx-ingress-device
        template:
        metadata:
            name: cpx-ingress
        annotations:
            NETSCALER_AS_APP: "True"
        labels:
            app: cpx-ingress-device
        spec:
            containers:
                - name: cpx-ingress
                image: "cpx:12.0-41.16"
            securityContext:
                privileged: true
            env:
                - name: "EULA"
                value: "yes"
                - name: "NS_MGMT_SERVER"
                value: "10.217.212.226"
                - name: "NS_MGMT_FINGER_PRINT"
                value: "74:EA:04:90:2C:FA:BF:7A:31:C9:52:64:D3:9C:BC:D3:O8:9F:9A:O4"
                - name: "NS_ROUTABLE"
                value: "FALSE"
                - name: "NS_HTTP_PORT"
                value: "5080"
                - name: "NS_HTTPS_PORT"
                value: "5443"
                - name: "NS_LB_ROLE"
                value: "SERVER"
                - name: "HOST"
                value: ""
                - name: "KUBERNETES_TASK_ID"
        valueFrom:
        fieldRef:
        fieldPath: metadata.name
            - name:"HOST"
    valueFrom:
        fieldRef:
            fieldPath: spec.nodeName
        ports:
            - containerPort: 80
            hostPort: 5080
            - containerPort: 443
            hostPort: 5443
            - containerPort: 5080
            hostPort: 80
            - containerPort: 5443
            hostPort: 443
        imagePullPolicy: Always
        nodeSelector:
            node-role: ingress

The following table describes the various sections, parameters, and environment variables used in the above example:

Section Parameter Description
containers name Name of the NetScaler CPX container.
  image Specifies the image for container creation.
securityContext privileged: true Specifies that the NetScaler CPX container runs in privileged mode.
env name: “EULA” A NetScaler CPX specific environment variable, which is required for verification that you have read and understand the End User License Agreement (EULA) available at: https://www.citrix.com/products/netscaler-adc/cpx-express.html.
  name: “NS_MGMT_SERVER” A NetScaler CPX environment variable that enables you define the NetScaler MAS server IP address. When the NetScaler CPX is deployed, it automatically registers with the NetScaler MAS server using this IP address.
  name: “NS_MGMT_FINGER_PRINT” A NetScaler CPX environment variable that enables you to define the NetScaler MAS fingerprint.
  name: “NS_ROUTABLE” A NetScaler CPX environment variable that enables you to specify that the NetScaler CPX container is run in non-IP-per-container mode. Be sure to set the value to “FALSE.”
  name: “NS_HTTP_PORT” or name: “NS_HTTPS_PORT” NetScaler CPX specific environment variables that enable you to assign custom ports for management access to NetScaler CPX. NetScaler MAS uses these ports to access the NetScaler CPX container.
  name: “NS_LB_ROLE” A NetScaler CPX environment variable that enables you to specify to NetScaler CPX and NetScaler MAS that the NetScaler CPX container is used as an Ingress resource.
  name: “HOST” The host name of the node on which the NetScaler CPX container is running. Using the host name, NetScaler MAS can access the NetScaler CPX container.
  name: “KUBERNETES_TASK_ID” Identifies the NetScaler CPX ID in the Kubernetes cluster.
  name: “HOST” The host name of the node on which the NetScaler CPX container is running. Using the host name, the NetScaler MAS can access the NetScaler CPX.
ports containerPort: or hostPort: Maps the ports between the NetScaler CPX container and the host. By default, the Kubernetes Ingress object assumes that the cluster is accessed at ports 80 and 443.
imagePullPolicy   Specifies how Kubernetes pulls the image.
nodeSelector node-role: The label of the node on which you want to deploy the pod.

3. Deploy the pod specification of the NetScaler CPX by using the following command:

kubectl create –f  (fileName | scriptName)

Example:

kubectl create –f sample.yaml

Once you deploy the NetScaler CPX instance on the host, it automatically registers with the NetScaler Management and Analytics System (MAS). You can view the deployed NetScaler CPX instances in the NetScaler MAS UI at: Networks > Instances > NetScaler CPX.

localized image