Prerequisite knowledge
Working knowledge of API Manager and application servers, in general.
User level: All
Required products
Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)


In this article, we will talk about setting up a cluster in API manager. We will also talk about how to load balance multiple web-services end-point servers with API Manager, and setting up components in API in a distributed manner.

Why use a Cluster

You can use a cluster to serve one or more of the following purposes:
  • High Throughput - To handle high volumes of client requests.
  • Low ART/latency - To keep the overall Average Response Time (ART) for servicing a web-service or the latency introduced by the API Manager, when handling high volumes of request.
  • High availability - To ensure fault-tolerance when a member node fails.
But before we set up a cluster, let us see how we can configure API Manager in a distributed mode. You can have a distributed set-up, to overcome limited physical resources (CPU, main memory, and so on) in one machine.

API Manager in a distributed configuration

In this section, we shall discuss how to set up the different components of APIM: the core API Manager server, Analytics server, and the Data Store in remote machines.
The Add-On components: Data Store and Analytics Server
Install the Analytics Server and the Data Store using the API Manager Add-On installer.
Ensure that both the services are running, before proceeding to install the core API Manager service. In Windows, the services should start automatically post-installation, but in other platforms, you may need to start the services manually by running the elasticsearch and the “redis-server” scripts in the bin directory of the respective installations.
By default, redis binds to the loopback address. To enable remote access to the redis server, edit the redis config file in <APIM_root>\database\datastore directory, and change the bind address in the “General section” to the IP address or the host-name of the host-machine.
In Windows, edit the file
In a non-Windows environment, edit the file
To ensure that the server loads the configuration settings, start it with the config file as the parameter, as follows:
Ensure that the ports used by the services (Redis: 6379; ElasticSearch: 9200, 9300) are not blocked by a firewall.
API Manager
When you run the API Manager installer, click No when the choice to install the Data Store and Analytics server comes up.
The installer prompts for the location of the remote Data Store and the port number on which the Data Store service is listening to  (default is port 6379). You can find the port number in the “port” attribute, under “general” settings in the following redis config file:
The installer will prompt you for the password to connect to the redis server. You can find that in the “requirepass” setting in the “security” section of the following file:
Enter the IP Address or the hostname of the remote ElasticSearch host when prompted.
The installer requires you to enter the cluster-name in the next (default value “groot-elasticsearch”) screen. You can find the setting in the “” setting in the “Cluster” section of the elasticsearch.yml file at
The API Manager is now installed in a distributed mode with a remote Data Store and Analytics server.
If you expect to handle large volumes of traffic that can be overwhelming for a single node of API Manager, you can scale up vertically, by installing multiple API Manager instances on the same machine. But even a powerful machine may have limited resources. A better solution might be to scale out horizontally, by installing API Manager instances on different remote machines.

Clustering in API Manager

By default, API Manager automatically detects and adds itself to a cluster of pre-existing nodes sharing the same Data Store and Analytics Server.
The peer nodes in the cluster are listed in the Cluster section in the API Manager administrator console. The details of the nodes in the cluster are stored in the cluster.xml file in <APIM_root>/conf directory.
To add a new API Manager node to a pre-existing API Manager instance, so that they form a cluster, you can specify the address of the Data Store and the Analytics server that the pre-existing instance uses when installing the new API Manager instance.
Enabling Cluster Post-Installation
If you have a pre-installed API Manager instance, that you want to be a part of a cluster, you can connect your API Manager node to the Data Store and the Analytics Server used by that cluster.
Enter the Data Store and Analytics Server details in the API Manager Administrator Console.
The figure below shows the page where you can enter the Data Store configurations.
The figure below shows the page where you can enter the Analytics Server configurations.
After entering the details above, you need to restart your API Manager node. After restarting, the node joins the cluster and loads all the configuration from the specified Data Store.
Inter-node Communication in a cluster
A configuration change in an API Manager node in a cluster (such as a new SLA plan, a newly published API or eviction of a subscriber), reflects on all other nodes. This is made possible by a Publish/Subscribe messaging service among all the nodes in the cluster. This also makes the API Manager cluster fault tolerant. If any node goes down, there is no impact on availability as the configuration changes are available on other operational nodes.
Load balancing an API Manager cluster
A web server can act as the font-end for an API Manager cluster. The supported web servers are Apache HTTPD and IIS.
The API Manager packages the WSConfig tool that creates a connector between a web server and an API Manager cluster. You can alternatively use a load balancer of your choice.
The wsconfig tool is located in the <apim_home>/wsconfig directory. To create a connector, copy this directory along with the cluster.xml file in <apim_home>/wsconfig/config to the machine where your web server is hosted. Place the cluster.xml file in the same directory as the wsconfig tool.
Before copying the cluster.xml file ensure that it is up-to-date with all the APIM nodes in your cluster. Note that this file is dynamically updated to list all the running APIM instances. So, if a member APIM server is brought down, the entries related to that node will be dropped from the xml file.
You can run the wsconfig tool in the GUI or command-console mode. To install the web server connector in the command-console mode, run it with the following parameters:
        ./wsconfig -ws <IIS|Apache> -site <site> | -dir <path> -vhost <vhost>
        [-norestart] [-v]
        [-bin <path>] [-service <servicename>] (Apache/Windows only)
        [-bin <path>] [-script <path>] (Apache/UNIX only)
Example (Apache HTTPD/RHEL7):
./wsconfig -ws Apache -dir /opt/apache/conf -vhost All -bin /opt/apache/bin/httpd -script /opt/apache/bin/apachectl –v
Let us pick the example of Apache HTTPD webserver (on Linux) to see what happens when a connector is created. The configuration files created and the changes done by the tool, post connector configuration, are as follows:
<wsconfig_home>/connectors directory is created that contains the following files:
  • : contains the web-server connector configuration.
  • : contains the URL mapping for the requests that are routed by the web-server to the API Manager. By default, all the requests to the web-server (except the requests to the API Manager admin portal) are forwarded to API Manager.
  • : the connector library module.
  • mod_jk_vhost.conf : contains the mapping for the connector library, the file and the connector log file. Apache’s httpd.conf file references this file for the location of the aforementioned files. You can set the log level for the connector here. For example, if you need to debug any connector related issue, set the log level to “debug”.
  • mod_jk.log : logs the exchange between the web-sever and APIM, flowing through the connector.
  • wsconfig.log : contains a record of the changes when connector is installed or uninstalled.
The Apache HTTPD configuration file (<httpd_home>/conf/httpd.conf) is modified to include connector configuration in the following files :
  • <httpd_home>/conf/mod_jk.conf : contains the location of the file. It also contains the location of the shared memory file, that contains the configuration and runtime information shared by all the worker threads.
  • <httpd_home>/conf/ This file contains the details (IP address, AJP port, timeout etc) of the API Manager's nodes in the cluster. You can set the load balancing factor for each node. All the communication between the web-server and API Manager happens over AJP protocol. The AJP ports should match the ports specified in the API Manager’s config.xml file. 
Clustering the End-Points
If your back-end web service is hosted on multiple application servers, you can use the built-in API Manager load-balancing mechanism to distribute the load equitably on all the back-end servers. Alternatively, you can use a load-balancer of your choice,
To configure the load-balancing settings, when registering a web-service, navigate to the “Endpoints” section and follow the instructions below.
Select Load Balancer as the Endpoint type.
Select Round Robin or Weighted Round Robin (in case you want the traffic routed proportionately according to the assigned weights, to the web-services nodes) as the load-balancing algorithm. A simple round robin assigns a load factor of 1, to all the participant nodes.
Specify the URL of the individual web-service nodes by clicking Add another endpoint, as required.
Clustering Analytics server
A cluster of APIM manager under sufficient load may generate large volumes of metrics data. To handle that efficiently, you may need to use more than one Analytics server.
You can use the API Manager Add-ons installer to install secondary instances of Analytics server on remote machines. An ElasticSearch cluster is identified by a cluster-name that is unique to the network. For an ElasticSearch node to be a part of this cluster, it must use the same cluster name. Therefore, ensure that you specify the cluster name used in the primary ElasticSearch instance, when installing secondary instances. You can find the setting in the Server> API Analytics Server section  of the APIM administrator console or the elasticsearch.yml file in the <apim_root>/database/analytics/config directory.
To enable clustering in each of the Analytics server instances, enable the zen discovery setting in the “discovery” section of the elasticsearch.yml file. true
To load the changes in the configuration file, restart the ElasticSearch instances. These instances would now behave as a single entity that can distribute and share shards in an index. The cluster automatically elects a master node, which decides on allocating shards to different nodes.
You can validate if the setting is effected by examining the ElasticSearch.log file.
For example, the first ElasticSearch instance that is started should elect itself as the master. This should be reflected in its log as shown below:
[2016-03-01 16:50:04,877][INFO ][cluster.service ] [Vance Astrovik] new_master [Vance Astrovik][IgQb4fafRTiUM_OnzvXF3w][][inet[/]], reason: zen-disco-join (elected_as_master) [2016-03-01 16:50:04,948][INFO ][http] [Vance Astrovik] bound_address {inet[/0:0:0:0:0:0:0:0:9200]}, publish_address {inet[/]} [2016-03-01 16:50:04,949][INFO ][node] [Vance Astrovik] started
When the second ElasticSearch instance is started, it should detect the master and add join the cluster.
[2016-03-01 16:55:15,570][INFO ][cluster.service ] [Kurt Wagner] detected_master [Vance Astrovik][IgQb4fafRTiUM_OnzvXF3w][][inet[/]], added {[Vance Astrovik][IgQb4fafRTiUM_OnzvXF3w][][inet[/]],}, reason: zen-disco-receive(from master [[Vance Astrovik][IgQb4fafRTiUM_OnzvXF3w][][inet[/]]]) [2016-03-01 16:55:15,671][INFO ][http] [Kurt Wagner] bound_address {inet[/0:0:0:0:0:0:0:0:9200]}, publish_address {inet[/]} [2016-03-01 16:55:15,672][INFO ][node] [Kurt Wagner] started
The addition of a new member is recorded by the master instances, as follows:
[2016-03-01 16:52:29,762][INFO ][cluster.service ] [Vance Astrovik] added {[Kurt Wagner][igG3kwEtQW2bM03f5k51iA][][inet[/]],}, reason: zen-disco-receive(join from node[[Kurt Wagner][igG3kwEtQW2bM03f5k51iA][][inet[/]]])
To register additional Analytics server instances with your API Manager, log-on to the administrator console, navigate to the Server > API Analytics Server section, click on “Add Address” and specify the hostname or the IP address of the machine hosting the new Analytics server.
The Data Store
The API Manager, presently, does not support a cluster of Redis servers. All API Manager nodes share the same configuration settings in the form of a common Data Store, so that any configuration change (such as a new SLA plan, or a new user) in one node reflects instantly on all the nodes in the cluster.
Similarly, an API registered on one node can be accessed from any other node. For every client request that the API Manager processes, a call is made to the Redis server to fetch and update the rate-limiting and throttling information for that API.
Therefore, ensure that Redis performs at its best by using a high bandwidth NIC card and a high clock-speed CPU on the host machine.