This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Clustering API Manager
Before you set up a cluster for WSO2 API Manager, you can create a distributed deployment of its four main components: Publisher, Store, Key Manager, and Gateway. This page describes how to set up the distributed deployment in the following sections:
Note: These instructions are based on API Manager 1.3 and earlier versions. If you are using multi-tenancy in version 1.4 and later, all nodes should use the same user store, as all servers are servicing the same set of tenants, and the Governance Registry and Key Manager should be on the same gateway node.
Understanding the API Manager architecture
API Manager uses the following four main components:
Publisher | Creates and publishes APIs |
Store | Provides a user interface to search, select, and subscribe to APIs |
Key Manager | Used for authentication, security, and key-related operations |
Gateway | Responsible for securing, protecting, managing, and scaling API calls |
Additionally, API Manager uses three databases. The API Manager components use the databases as follows:
(API Manager Database) apimgtdb | (User Manager Database) userdb | (Registry Database) regdb | |
Publisher | Used | Used | Used |
Store | Used | Used | Used |
Key Manager | Used | Used | Not Used |
Gateway | Used | Not Used | Not Used |
When we consider distributed deployment of WSO2 API Manager, we have the option of separating its four components and clustering each component as needed. Let's look more closely at how the API Manager components are deployed separately.
Creating the distributed deployment
In the following diagram, the four components are set up in a distributed deployment, and the three databases are connected to the relevant components respectively. To set up each API Manager component in separate servers, simply remove the unwanted Jaggery apps from the deployment directory. For example, to set up only API Gateway in a severer, remove the store and publisher Jaggery apps. The entire setup is fronted by an instance of WSO2 Elastic Load Balancer (ELB). Notice the port offset and the HTTPS port of each WSO2 server component.
To achieve this deployment, we will complete the following tasks:
- Install and configure API Manager and ELB
- Install and configure the databases
- Configure the connections among the components
Installing and configuring API Manager and ELB
The following steps describe how to download, install, and configure API Manager and ELB. We will create four instances of API Manager and one ELB instance.
- Download the latest versions of WSO2 API Manager and WSO2 ELB. In this example, we are using API Manager version 1.3.1 and ELB version 2.0.3.
- Unzip the API Manager zipped archive, and make four copies of the unzipped directory, renaming each of those directories respectively as KeyManager, Gateway, Publisher, and Store.
These four directories will be used for each component of the API Manager. Each of these unzipped directories will be referred to as <APIM_HOME> or <PRODUCT_HOME> in this document. - Unzip the ELB zipped archive.
This directory is used for the Elastic Load Balancer. - Because we are going to run five WSO2 servers (ELB, KeyManager, Gateway, Publisher, and Store) on the same machine, we need to set the PortOffset attribute to avoid any port usage conflict, as follows:
In each of the directories you just created, open the
<PRODUCT_HOME>/repository/conf/carbon.xml
file.Edit the <PortOffset> attribute in each file as shown in the PortOffset column in the following table. The port value will automatically be increased as shown in the Port Value column, allowing all five WSO2 server instances to run on the same machine.
WSO2 Server instance
PortOffset
Port Value
ELB
0
9443
KeyManager
1
9444
Gateway
2
9445
Publisher
3
9446
Store
4
9447
Installing and configuring the databases
The following steps describe how to download and install MySQL Server, create the databases, configure the data sources, and configure the API Manager components to connect to them.
Download and install MySQL Server.
Download the MySQL JDBC driver.
Unzip the downloaded MySQL driver zipped archive, and copy the MySQL JDBC driver JAR (
mysql-connector-java-x.x.xx-bin.jar
) into the<APIM_HOME>/repository/components/lib
directory of each of the four API Manager directories.- Enter the following command in a terminal/command window, where
username
is the username you want to use to access the databases:
mysql -u username -p
- When prompted, specify the password that will be used to access the databases with the username you specified.
Create the three databases using the following commands, where
<APIM_HOME>
is the path to any of the API Manager instances you installed, andusername
andpassword
are the same as those you specified in the previous steps:mysql> create database apimgtdb; mysql> use apimgtdb; mysql> source <APIM_HOME>/dbscripts/apimgt/mysql.sql; mysql> grant all on apimgtdb.* TO username@localhost identified by "password"; mysql> create database userdb; mysql> use userdb; mysql> source <APIM_HOME>/dbscripts/mysql.sql; mysql> grant all on userdb.* TO username@localhost identified by "password"; mysql> create database regdb; mysql> use regdb; mysql> source <APIM_HOME>/dbscripts/mysql.sql; mysql> grant all on regdb.* TO username@localhost identified by "password";
Configure the data sources for the three database as follows:
Open the
<APIM_HOME>/repository/conf/datasources/master-datasources.xml
file in all four API Manager components.Enable the components to access the API Manager database by modifying the WSO2AM_DB data source in all four
master-datasources.xml
files as follows:<datasource> <name>WSO2AM_DB</name> <description>The datasource used for the API Manager database</description> <jndiConfig> <name>jdbc/WSO2AM_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://apimgtdb.mysql-wso2.com:3306/apimgtdb?autoReconnect=true& relaxAutoCommit=true</url> <username>user</username> <password>password</password> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
Enable the KeyManager, Publisher, and Store components to access the users database by configuring the WSO2UM_DB data source in their
master-datasources.xml
files as follows:<datasource> <name>WSO2UM_DB</name> <description>The datasource used by user manager</description> <jndiConfig> <name>jdbc/WSO2UM_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://userdb.mysql-wso2.com:3306/userdb?autoReconnect=true& relaxAutoCommit=true</url> <username>user</username> <password>password</password> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
Enable the Publisher and Store components to access the registry database by configuring the WSO2REG_DB data source in their
master-datasources.xml
files as follows:<datasource> <name>WSO2REG_DB</name> <description>The datasource used by user manager</description> <jndiConfig> <name>jdbc/WSO2REG_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://regdb.mysql-wso2.com:3306/regdb?autoReconnect=true& relaxAutoCommit=true</url> <username>user</username> <password>password</password> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
Modify the /etc/hosts entries to map the IP addresses to the data source URLs:
127.0.0.1 apimgtdb.mysql-wso2.com
127.0.0.1 userdb.mysql-wso2.com
127.0.0.1 regdb.mysql-wso2.com
- To give each of the components access to the API Manager database, open the
<APIM_HOME>/repository/conf/api-manager.xml
file in each of the components and add the following line as the first child node of the root element (if it is not already there):
<DataSourceName>
jdbc/WSO2AM_DB </DataSourceName>
To give the Key Manager, Publisher, and Store components access to the users database, open the
<APIM _HOME>/repository/conf/user-mgt.xml
file in each of these three components and add or modify thedataSource
property of the<UserStoreManager>
element as follows:<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager"> <Property name="dataSource">jdbc/WSO2UM_DB</Property> <Property name="ReadOnly">false</Property> <Property name="IsEmailUserName">false</Property> ... </UserStoreManager>
- To give the Publisher and Store components access to the registry database, open the
<APIM_HOME>/repository/conf/registry.xml
file in each of these two components and configure them as follows:In the Publisher component's
registry.xml
file, add or modify thedataSource
attribute of the<dbConfig name="govregistry">
element as follows:<dbConfig name="govregistry"> <dataSource>jdbc/WSO2REG_DB</dataSource> </dbConfig> <remoteInstance url="https://publisher.apim-wso2.com"> <id>gov</id> <dbConfig>govregistry</dbConfig> <readOnly>false</readOnly> <enableCache>true</enableCache> <registryRoot>/</registryRoot> </remoteInstance> <mount path="/_system/governance" overwrite="true"> <instanceId>gov</instanceId> <targetPath>/_system/governance</targetPath> </mount>
In the Store component's
registry.xml
file, add or modify thedataSource
attribute of the<dbConfig name="govregistry">
element as follows (note that this configuration is nearly identical to the previous step with the exception of theremoteInstance
URL):<dbConfig name="govregistry"> <dataSource>jdbc/WSO2REG_DB</dataSource> </dbConfig> <remoteInstance url="https://store.apim-wso2.com"> <id>gov</id> <dbConfig>govregistry</dbConfig> <readOnly>false</readOnly> <enableCache>true</enableCache> <registryRoot>/</registryRoot> </remoteInstance> <mount path="/_system/governance" overwrite="true"> <instanceId>gov</instanceId> <targetPath>/_system/governance</targetPath> </mount>
Modify the /etc/hosts entries to map the relevant IP addresses to the remoteInstance URLs:
xx.xxx.x.206 publisher.apim-wso2.com
xx.xxx.x.206 store.apim-wso2.com
Configuring the connections among the components
You will now configure the inter-component relationships illustrated in the following diagram by modifying their <APIM_HOME>/repository/conf/api-manager.xml
files. Because the Key Manager component does not depend on any other components, you do not modify this file for the Key Manager.
- Open the
<APIM_HOME>/repository/conf/api-manager.xml
files in the Gateway, Publisher, and Store components. - Modify each of the files as follows:
Gateway: configure the connection to the Key Manager component as follows:
<APIKeyManager> <ServerURL>https://keymanager.apim-wso2.com:9444/services/</ServerURL> <Username>admin</Username> <Password>admin</Password> ... </APIKeyManager>
Publisher and Store: configure connections to the Key Manager and Gateway as follows:
<APIKeyManager> <ServerURL>https://keymanager.apim-wso2.com:9444/services/</ServerURL> <Username>admin</Username> <Password>admin</Password> ... </APIKeyManager> <AuthManager> <ServerURL>https://keymanager.apim-wso2.com:9444/services/</ServerURL> <Username>admin</Username> <Password>admin</Password> </AuthManager> <APIGateway> <ServerURL>https://gwmanager.apim-wso2.com:9445/services/</ServerURL> <Username>admin</Username> <Password>admin</Password> <APIEndpointURL> http://gwmanager.apim-wso2.com:8282,https://gwmanager.apim-wso2.com:8245 </APIEndpointURL> </APIGateway>
Creating a connection to the Key Manager from the Publisher is required in API Manager 1.3.0 but is no longer required in API Manager 1.4.0.
Modify the /etc/hosts entries to map the relevant IP addresses to the ServerURLs you just configured:
xx.xxx.x.206 keymanager.apim-wso2.com
xx.xxx.x.206 gwmanager.apim-wso2.com
You have now successfully distributed and deployed the WSO2 API Manager components. To cluster API Manager, create a cluster of Gateway components. Because the Gateway component is built on WSO2 ESB, you can use the steps in Creating a Cluster to cluster it.