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.

  1. 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.
  2. 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.
  3. Unzip the ELB zipped archive.
    This directory is used for the Elastic Load Balancer.
  4. 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:
    1. In each of the directories you just created, open the <PRODUCT_HOME>/repository/conf/carbon.xml file.

    2. 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.

  1. Download and install MySQL Server.

  2. Download the MySQL JDBC driver.

  3. 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.

  4. 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
  5. When prompted, specify the password that will be used to access the databases with the username you specified.
  6. Create the three databases using the following commands, where <APIM_HOME> is the path to any of the API Manager instances you installed, and username and password 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"; 
  7. Configure the data sources for the three database as follows:

    1. Open the <APIM_HOME>/repository/conf/datasources/master-datasources.xml file in all four API Manager components.

    2. 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&amp;       
              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>
    3. 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&amp;       
              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> 
    4. Enable the Publisher and Store components to access the registry database by configuring the WSO2REG_DB data source in their master-datasources.xmlfiles 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&amp;       
              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> 
    5. 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

  8. 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>
  9. 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 the dataSource 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>
  10. To give the Publisher and Store components access to the registry database, open the <APIM_HOME>/repository/conf/registry.xmlfile in each of these two components and configure them as follows:
    1. In the Publisher component's registry.xml file, add or modify the dataSource 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>
    2. In the Store component's registry.xml file, add or modify the dataSource attribute of the <dbConfig name="govregistry"> element as follows (note that this configuration is nearly identical to the previous step with the exception of the remoteInstance 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>
    3. 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. 

  1. Open the <APIM_HOME>/repository/conf/api-manager.xml files in the Gateway, Publisher, and Store components.
  2. 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.

  3. 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.