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 and 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 the Docker Documentation.
  • Docker host has Internet connectivity.

Downloading Citrix ADC CPX Image from Quay

You can download Citrix ADC CPX image from Quay container registry using the docker pull command and deploy it on your environment. Use the following command to download Citrix ADC CPX image from Quay:

docker pull quay.io/citrix/citrix-k8s-cpx-ingress:12.0-xx.xx

For example, if you want to download the version 12.0-36.29, then use the following command:

docker pull quay.io/citrix/citrix-k8s-cpx-ingress:12.0-36.29

Use the following command to verify if Citrix ADC CPX image is installed in docker images:

root@ubuntu:~# docker images | grep 'citrix-k8s-cpx-ingress' quay.io/citrix/citrix-k8s-cpx-ingress 12.0-36.29 952a04e73101 2 months ago 469 MB

You can deploy the latest Citrix ADC CPX image from the following link: Quay

Note: It is recommended to use the latest Citrix ADC CPX image from Quay for availing the latest features of Citrix ADC CPX.

Downloading the NetScaler CPX Image from the Docker Store

Perform the following steps to download and load the Citrix ADC CPX Docker image file from the Docker Hub.

  1. Create an account in Docker Hub and login using your credentials.

  2. Search for NetScaler CPX and then click NetScaler CPX Express Rel 12.0 from the listed options.

  3. On NetScaler CPX Express Rel 12.0 page, click Proceed to Checkout.

  4. If you agree to the terms and conditions for downloading NetScaler CPX, select the check boxes for terms and services and then click Get Content. You must agree to the conditions to proceed.

  5. On your Docker host, log in with your Docker Hub user name and password

    docker login
    

    For example:

    root@ubuntu:~# docker login
    Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
    Username: example-user
    Password:
    Login Succeeded
    
  6. Once the Login is successful, run the following command to download and load the NetScaler CPX image.

    docker pull store/citrix/netscalercpx:12.0-x.x
    

    Note: In this command, 12.0–x.x refers to the available NetScaler CPX version in Docker Hub. For example, if the Docker Hub version is 12.0-56.20, use the command as docker pull store/citrix/netscalercpx:12.0-56.20.

  7. After the Citrix ADC 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-x.x  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.

Note: You can also download the image from quay.io using the docker pull quay.io/citrix/citrix-k8s-cpx-ingress:<TAG> command.

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 that you read and understand the End User License Agreement (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 enables 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

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

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 are 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:

  • LS_IP_ADDRESS is the IP address of the license server.
  • LS_PORT 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 the 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

Deploying a NetScaler CPX Instance in Docker