Deploying a NetScaler CPX Instance in Docker

NetScaler CPX instances are available as a Docker image file in the Docker Store. To deploy an instance, download the NetScaler CPX image from the Docker Store and then deploy the instance by using the docker run command or the Docker compose tool.

Prerequisites

Make sure that:

  • Docker host system has at least:
    • 1 CPU
    • 2 GB RAM

      Note: For better NetScaler CPX performance, you can define the number of processing engines that you want the NetScaler CPX instance to start. For every additional processing engine, you add, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, the Docker host must contain 4 vCPUs and 4 GB of memory.

  • Docker host system is running Linux Ubuntu version 14.04 or later.
  • Docker version 1.12 is installed on the host system. For information about Docker installation on Linux, see https://docs.docker.com/engine/installation/ubuntulinux/
  • Docker host has Internet connectivity.

Downloading the NetScaler CPX Image from the Docker Store

Download the NetScaler CPX Docker image file from the Docker Store and then load the NetScaler CPX Docker image. To do so, in your Docker host, run the following command:

docker pull store/citrix/netscalercpx:12.0-53.xx

After the NetScaler CPX Docker image is downloaded, you can view the details of the image by using the following command:

    docker images

For example:

    root@ubuntu:~# docker images


    REPOSITORY    TAG         IMAGE ID       CREATED    VIRTUAL SIZE


       cpx       12.0-53.xx  2e97aadf918b  43 hours ago  414 MB

In this example, note the following fields in the output:

  • REPOSITORY. Specifies the name space where the image is stored.
  • TAG. Denotes the version of the NetScaler CPX image that is installed.
  • IMAGE ID. Denotes the unique ID of the image in the Docker host.

Deploying the NetScaler CPX Instance Using the docker run Command

On the host, you can install a NetScaler CPX instance in the Docker container by using the NetScaler CPX Docker image that you loaded onto the host. Using the docker run command, install the NetScaler CPX instance with the default NetScaler CPX configuration.

Important:

If you have downloaded NetScaler CPX Express from https://www.citrix.com/products/netscaler-adc/cpx-express.html, make sure the you read and understand the End User License Aggreement (EULA) available at: https://www.citrix.com/products/netscaler-adc/cpx-express.html and accept the EULA while deploying the NetScaler CPX instance.

Install the NetScaler CPX instance on the Docker container by using the following docker run command:

docker run -dt -P --privileged=true –net=host –e NS_NETMODE=”HOST” -e CPX_CORES=<number of cores> --name <container_name> --ulimit core=-1 -e CPX_NW_DEV='<INTERFACES>' -e CPX_CONFIG=’{“YIELD”:”NO”}’ -e LS_IP=<LS_IP_ADDRESS> -e LS_PORT=<LS_PORT> e PLATFORM=CP1000 -v <host_dir>:/cpx <REPOSITORY>:<TAG>
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e CPX_NW_DEV='eth1 eth2' -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e LS_IP=10.102.38.134 -e PLATFORM=CP1000 -v /var/cpx:/cpx --name cpx_host cpx:12.0-51.xx

This example creates a container named mycpx based on the NetScaler CPX Docker image.

The -P parameter is mandatory. It tells Docker to map the ports exposed in the container by the NetScaler CPX Docker image, that is, ports 80, 22, 443, and 161/UDP, to the ports on the Docker host that are randomly selected from the user defined range. This is done to avoid conflicts if you later create multiple NetScaler CPX containers on the same Docker host. The port mappings are dynamic and are set each time the container is started or restarted. The ports are used as follows:

  • 80 is used for HTTP
  • 443 is used for HTTPs
  • 22 used for SSH
  • 161/UDP is used for SNMP.

If you want static port mappings, use the -p parameter to set them manually.

The --privileged=true option is used to run the container in privileged mode, if you are running the NetScaler CPX with multiple cores then you need to provide all the system privileges to the NetScaler CPX. if you want to run the NetScaler CPX with a single core then instead of this option you must use the --cap-add=NET_ADMIN option that enable you to run the NetScaler CPX container with full network privileges.

The--net=host is a standard docker run command option that specifies that the container is running in the host network stack and has access to all the network devices.

Note

Ignore this option, If you are running NetScaler CPX in bridge or none network.

The -e NS_NETMODE="HOST" is a NetScaler CPX specific environment variable that allows you to specify that the NetScaler CPX is started in host mode, once NetScaler CPX starts in host mode it configures 4 default iptable rules on host machine for management access to the NetScaler CPX. It uses the following ports:

  • 9995 for HTTP
  • 9996 for HTTPS
  • 9997 for SSH
  • 9998 for SNMP

If you want to specify different ports, you can use the following environment variables:

  • -e NS_HTTP_PORT=
  • -e NS_HTTPS_PORT=
  • -e NS_SSH_PORT=
  • -e NS_SNMP_PORT=

Note

Ignore this environment variable, If you are running NetScaler CPX in bridge or none network.

The -e CPX_CORES is an optional NetScaler CPX specific environment variable. You can use it to improve the performance of the NetScaler CPX instance by defining the number of processing engines that you want the NetScaler CPX container to start.

Note

For every additional processing engine you add, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, then the Docker host must contain 4 vCPUs and 4 GB of memory.

The -e EULA = yes is a mandatory NetScaler CPX specific environment variable, which is required to verify that you have read and understand the End User License Agreement (EULA) available at: https://www.citrix.com/products/netscaler-adc/cpx-express.html.

The -e PLATFORM=CP1000 parameter specifies the NetScaler CPX license type.

If you are running Docker in host network, you can assign dedicated network interfaces to the NetScaler CPX container using the -e CPX_NW_DEV environment variable. You need to define the network interfaces separated by a whitespace. The network interfaces that you define is held by the NetScaler CPX container until you uninstall the NetScaler CPX container. When the NetScaler CPX container is provisioned all the assigned network interfaces are added to the NetScaler networking namespace.

Note

If you are running NetScaler CPX in bridge or none network and if you change the Docker or container network, such as, configure another network connection to the container or remove an existing network, then make sure that you restart the NetScaler CPX container to use the updated network.

docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_NW_DEV='eth1 eth2' -e CPX_CORES=5 -e PLATFORM=CP1000 --name cpx_host cpx:12.0-53.x

The -e CPX_CONFIG is a NetScaler CPX specific environment variable that enables you to control the throughput performance of the NetScaler CPX container. When the NetScaler CPX does not receive any incoming traffic to process, it yields the CPU during this idle time, hence resulting in low throughput performance. You can use the CPX_CONFIG environment variable to control the throughput performance of the NetScaler CPX container in such scenarios. You need to the provide following values to the CPX_CONFIG environment variable in JSON format:

  • If you want the NetScaler CPX container to yield CPU in idle scenarios, define {"YIELD” : “Yes”}
  • If you want the NetScaler CPX container to avoid yielding the CPU in idle scenarios so that you can get high throughput performance, define {“YIELD” : “No”}
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e PLATFORM=CP1000 --name cpx_host cpx:12.0-51.x
docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e EULA=yes -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"Yes"}' -e PLATFORM=CP1000 --name cpx_host cpx:12.0-51.xx

The –v parameter is an optional parameter that specifies the mount point of the NetScaler CPX mount directory, /cpx. A mount point is a directory on the host, in which you mount the /cpx directory. The /cpx directory stores the logs, configuration files, SSL certificates, and core dump files. In the example, the mount point is /var/cpx and the NetScaler CPX mount directory is /cpx.

If you purchased a license or have an evaluation license, you can upload the license to a license server and specify the license server location with the docker run command, by using the -e LS_IP=<LS_IP_ADDRESS> -e LS_PORT=<LS_PORT> parameter. In this case, you do not need to accept the EULA.

docker run -dt --privileged=true --net=host -e NS_NETMODE="HOST" -e CPX_CORES=5 –e CPX_CONFIG='{"YIELD":"No"}' -e LS_IP=10.102.38.134 -e PLATFORM=CP1000 --name cpx_host cpx:12.0-51.xx

Where:

  • is the IP address of the license server.
  • is the port of the license server.

You can view the images running on your system and the ports mapped to the standard ports by using the command: docker ps

Deploying NetScaler CPX Instances by Using Docker Compose

You can use the Compose tool of Docker to provision a single NetScaler CPX instance or multiple NetScaler CPX instances. To provision NetScaler CPX instances by using Compose, you must first write a compose file specifying the NetScaler CPX image, the ports that you want to open for the NetScaler CPX instance, and the privileges for your NetScaler CPX instance.

Important

Make sure that you have installed Docker Compose tool on the host.

To provision multiple NetScaler CPX instances:

  1. Write a compose file, where:
  • <service-name> is the name of the service you want to provision.
  • image:<repository>:<tag> denotes the repository and the versions of the NetScaler CPX image.
  • privileged: true provides all root privileges to the NetScaler CPX instance.
  • cap_add provides network privileges to the NetScaler CPX instance.
  • <host_directory_path> denotes the directory on the docker host that you want to mount for the NetScaler CPX instance.
  • <number_processing_engine> is the number of processing engines that you want the NetScaler CPX instance to start. For every additional processing engine, make sure that the Docker host contains the equivalent number of vCPUs and amount of memory in GB. For example, if you want to add 4 processing engines, then the Docker host must contain 4 vCPUs and 4 GB of memory.

The compose file generally follows a format similar to:

    <service-name>:
    container_name:
    image: <repository>:<tag>
    ports:
        - 22
        - 80
        - 443
        - 161/udp
        - 35021-35030
    tty: true
    cap_add:
        - NET_ADMIN
    ulimits:
    core: -1
    volumes:
        - <host_directory_path>:/cpx
    environment:
        - EULA=yes
        - CPX_CORES=<number_processing_engine>
        - CPX_CONFIG='{"YIELD":"Yes"}'
    CPX_0:
    container_name: CPX_0
    image: cpx:12.0-53.xx
    ports:
        -  443
        -  22
        -  80
        -  161/udp
        -  35021-35030
    tty: true
    cap_add:
        - NET_ADMIN
    ulimits:
        core: -1
    volumes:
        - /root/test:/cpx
    environment:
        -  CPX_CORES=2
        -  EULA=yes

Note: If you want to provision a single NetScaler CPX instance, you must add the following line to the compose file: container_name:<name_of_container> Run the following command to provision multiple NetScaler CPX instances: docker-compose -f <compose_file_name> scale <service-name>=<number of instances> up –d docker-compose -f docker-compose.yml scale cpxlb=3 up –d

If you want to provision a single NetScaler CPX instance, run the following command: docker-compose -f <compose_file_name> up –d