Deploying a Citrix ADC CPX Instance in Docker

Citrix ADC CPX instances are available as a Docker image file in the Docker Store. To deploy an instance, download the Citrix ADC 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 Citrix ADC CPX performance, you can define the number of processing engines that you want the Citrix ADC 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 Citrix ADC CPX Image from the Docker Store

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

docker pull store/citrix/netscalercpx:12.1-48.xx

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.1-48.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 Citrix ADC CPX image that is installed.

  • IMAGE ID. Denotes the unique ID of the image in the Docker host.

Deploying the Citrix ADC CPX Instance Using the docker run Command

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

Important:

If you have downloaded Citrix ADC 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 Citrix ADC CPX instance.

Install the Citrix ADC 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.1-48.xx

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

The -P parameter is mandatory. It tells Docker to map the ports exposed in the container by the Citrix ADC 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 Citrix ADC 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 Citrix ADC CPX with multiple cores then you need to provide all the system privileges to the Citrix ADC CPX. if you want to run the Citrix ADC 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 Citrix ADC 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 Citrix ADC CPX in bridge or none network.

The -e NS_NETMODE="HOST" is a Citrix ADC CPX specific environment variable that allows you to specify that the Citrix ADC CPX is started in host mode, once Citrix ADC CPX starts in host mode it configures 4 default iptable rules on host machine for management access to the Citrix ADC 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 Citrix ADC CPX in bridge or none network.

The -e CPX_CORES is an optional Citrix ADC CPX specific environment variable. You can use it to improve the performance of the Citrix ADC CPX instance by defining the number of processing engines that you want the Citrix ADC 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 Citrix ADC 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 Citrix ADC CPX license type.

If you are running Docker in host network, you can assign dedicated network interfaces to the Citrix ADC 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 Citrix ADC CPX container until you uninstall the Citrix ADC CPX container. When the Citrix ADC CPX container is provisioned all the assigned network interfaces are added to the NetScaler networking namespace.

Note

If you are running Citrix ADC 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 Citrix ADC 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 Citrix ADC CPX specific environment variable that enables you to control the throughput performance of the Citrix ADC CPX container. When the Citrix ADC 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 Citrix ADC 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 Citrix ADC CPX container to yield CPU in idle scenarios, define {"YIELD” : “Yes”}
  • If you want the Citrix ADC 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 Citrix ADC 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 Citrix ADC 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 Citrix ADC CPX Instances by Using Docker Compose

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

Important

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

To provision multiple Citrix ADC 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 Citrix ADC CPX image.
  • privileged: true provides all root privileges to the Citrix ADC CPX instance.
  • cap_add provides network privileges to the Citrix ADC CPX instance.
  • <host_directory_path> denotes the directory on the docker host that you want to mount for the Citrix ADC CPX instance.
  • <number_processing_engine> is the number of processing engines that you want the Citrix ADC 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 Citrix ADC CPX instance, you must add the following line to the compose file: container_name:<name_of_container> Run the following command to provision multiple Citrix ADC 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 Citrix ADC CPX instance, run the following command: docker-compose -f <compose_file_name> up –d