Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The following topics cover the configurations generic for all four deployment patterns described in the previous section:

Table of Contents
maxLevel3
minLevel3

Prerequisites

1. In this example, we use the following products.

  • WSO2 Elastic Load Balancer 2.0.1 or higher
  • MySQL server
  • SVNKit

2. When configuring a deployment pattern with all 4 API Manager components, extract the API Manager full distribution into four folders and name them as Publisher, Store, Key Manager and Gateway.

3. Different physical servers are used for the installation of the server instances. If deploying on a single machine for testing purposes, change the offset of all servers in <APIM _HOME>/repository/conf/carbon.xml file. This is done to avoid port conflicts that occur when running multiple WSO2 product instances in the same server.

4. This document is based on server installations on a single machine. Following are the port numbers used for the component servers:

 

...

 

...

We use shared databases to share information among distributed sever nodes of the API Manager. The following table shows a summarized view of the shared database configuration:

 User Manager DB
(prod_umdb)
API Manager DB
(prod_apimgtdb)
Registry
(prod_regdb)
Configuration Fileuser-mgt.xmlapi-manager.xmlregistry.xml
Datasourcejdbc/WSO2UM_DBjdbc/WSO2AM_DBjdbc/Reg_DB
Can be shared by which API Manager ComponentsPublisher, Store, Key ManagerPublisher, StorePublisher, Store, Key Manager

Details of the configuration are given below.

User Manager Database Configuration

Let's take a look at configuring the User Manager database that is shared with the API Publisher, Store, and Key Manager servers.

Info
titleNote

In this example, the Publisher and Store use the same user store. If required, separate user stores can be configured for these server nodes.  

1. Copy the MySQL JDBC driver jar file into the <APIM_HOME>/repository/component/lib folder for all API Manager components.

2. Create a new MySQL database by the name prod_umdb , and create user manager tables using the script available in <APIM_HOME>/dbscripts/mysql.sql. In this example we use MySQL database but you can also use other types of databases as well.

Code Block
mysql -u root -p
When prompted, specify the password to the access the mySQL database with the specified username.

mysql> create database prod_umdb;
mysql> use prod_umdb;
mysql> source mysql.sql;

3. Create a new user and grant access to the database as follows.

Code Block
mysql> grant all on reg_db.* TO user@localhost identified by "password";
  • user : The username for the user who needs access to the database
  • password : The password for the user who needs access the database

4. Update <APIM _HOME>/repository/conf/datasources/master-datasources.xml file in the Publisher, Store, and Key Manager server instances to connect to the above database.

Code Block
languagehtml/xml
<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://192.168.139.1:3306/prod_umdb?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>
  • url : The URL of the registry mySQL database
  •  username : The username to access the mySQL database
  •  password : The password to access the mySQL database
  •  jdbc/WSO2UM_DB : The same name used for the datasource in INSTALL_HOME/repository/conf/user-mgr.xml file for all the components  

5. Configure <APIM _HOME>/repository/conf/user-mgt.xml for all the API Manager components as shown below.

This configuration is used to define the user manager database of the API Manager components, and is required in the Publisher, Store, and Key Manager server instances where the user manager database needs to be shared.

Code Block
languagehtml/xml
<UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
   <Property name="dataSource">jdbc/WSO2UM_DB</Property>
   <Property name="ReadOnly">false</Property>
   <Property name="IsEmailUserName">false</Property>
   ...
</UserStoreManager>
  • url : The URL of the mySQL user manager database
  • username : The username to access the mySQL database
  • password : The password to access the mySQL database
  • jdbc/WSO2UM_DB : The datasource name for the datasource used as the user manager database

In the current installation, the primary user store (defined first in user-mgt.xml  file) contains administration users and passwords. These user credentials are used for the initial login to the management console UI of the API Manager. To enable user names that contain email addresses, add the following parameter in INSTALL_HOME/repository/conf/carbon.xml file:

Code Block
languagehtml/xml
<EnableEmailUserName>true</EnableEmailUserName> 

Registry Database Configuration

This section describes the creation and configuration of the registry database that will be used by the Publisher and Store server instances. The Governance space (/_system/governance) of the Publisher and Store instances are mounted to a common location within a remote governance registry instance. We will use MySQL as the registry database in this particular governance registry instance.  

1. Copy the mysql jar file into <APIM _HOME>/repository/component/lib folder for all API Manager components. 

2. Create a new mySQL database by the name prod_regdb , and create tables using the script available in <APIM_HOME>/dbscripts/mysql.sql file.  folder of the API Manager distribution. In this example we use MySQL database but you can also use other types of databases as well. 

Code Block
mysql> create database prod_regdb;
mysql> use prod_regdb;
mysql> source mysql.sql;

3. Create a new user and grant access to the database as follows.

Code Block
mysql> grant all on reg_db.* TO user@localhost identified by "password";
  • user : The username for the user who needs access to the database
  • password : The password for the user who needs access the database

4. To define a datasource for the registry, update <APIM _HOME>/repository/conf/datasources/master-datasources.xml file in the API Publisher and Store server instances to connect to the database created above.

Code Block
languagehtml/xml
<datasource>
   <name>WSO2_REG_DB</name>
   <description>The datasource used for the registry</description>
   <jndiConfig>
      <name>jdbc/WSO2_RegDB</name>
   </jndiConfig>
   <definition type="RDBMS">
      <configuration>
         <url>jdbc:mysql://192.168.139.1:3306/prod_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>
  • url : The URL of the registry mySQL database
  • username : The username to access the mySQL database
  • password : The password to access the mySQL database 
  • jdbc/WSO2_RegDB : The same name used for the datasource in the INSTALL_HOME/repository/conf/api-manager.xml file for all the components

5. Define the registry database in <APIM _HOME>/repository/conf/registry.xml file of the Publisher and Store server instances. The following configuration mounts the governance space to the remote registry instance. 

Code Block
languagehtml/xml
<dbConfig name="govregistry">
   <dataSource>jdbc/WSO2_RegDB</dataSource>
</dbConfig>
<remoteInstance url="https://192.168.139.1"> 
   <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>
  • remoteInstance url : the URL of the Publisher/Store server node
  • datasource             : The name of the datasource provided for the registry database in the master-datasources.xml file
  • username               : The username to access the mySQL database    

6. Start the server with the following command:

  • On Linux, use wso2server.sh -Dsetup
  • On Windows, use wso2server.sh -Dsetup

API Manager Database Configuration

This section describes the creation and configuration of the API manager database used by the Publisher, Store, and Key Manager server instances.

1. Create a new database by the name prodapimgt_db , and run <APIM_HOME>/dbscripts/apimgt/mysql.sql script.  

Code Block
mysql> create database prod_apimgt_db;
mysql> use prodapimgt_db;
mysql> source mysql.sql

2. Define the datasource for the API Manager database in <APIM _HOME>/repository/conf/datasources/master-datasources.xml file to connect to the above databases.

Code Block
languagehtml/xml
<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://192.168.139.1:3306/prod_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>
  • url : The URL of the API Manager database
  •  username : The username to access the mySQL database
  •  password : The password to access the mySQL database
  •  jdbc/WSO2AM_DB : The same name used for the datasource in the INSTALL_HOME/repository/conf/api-manager.xml file for all the components
Info
titleNote
Specifying ?autoReconnect=true&amp;relaxAutoCommit=true in the DB connection string allows the server to recover from stale or dead DB connections.

Next, let's take a look at deploying individual components of the API Manager.

...

Caching Configuration

Refer to section Caching Configuration for information.

API Key Manager Server Configuration

The Key Manager server is primarily used to validate API keys. The same Auth Manager server can be used as the authentication manager as well. Key Manager is also used for caching configuration as discussed above.

API Gateway Configuration

API Gateway is used to route API calls made by API consumers. The Gateway component validates and authenticates users against given API keys that are stored in the Key Manager Server.
 

1. Ensure that the datasource in <APIM_HOME>/repository/conf/api-manager.xml file is set to the API Manager database defined above. Configuration should be as follows:

Code Block
languagehtml/xml
<DataSourceName>jdbc/WSO2AM_DB</DataSourceName>

2. Configure the <APIKeyManager> element in <APIM_HOME>/repository/conf/api-manager.xml as shown below. This is required to specify the Key Manager server, which the gateway uses for authentication of all incoming API calls. In this sample, key management validation caching will be stored in the gateway, so this parameter will be set to true.

Code Block
languagehtml/xml
<APIKeyManager> <ServerURL>https://192.168.139.1:9444/services/</ServerURL>

     <Username>admin</Username>
     <Password>admin</Password>
  •   ServerURL : URL of the Key Manager Server node
  • Username : Username to connect to the Key Manager Server
  • Password  : Password to connect to the Key Manager Server

3. Configure caching as required.

Info
titleInfor
The <AuthManager> and <Database> elements in <APIM_HOME>/repository/conf/api-manager.xml are not required for the API Gateway instance, so you can comment them out.

API Publisher and API Store

API Publisher publishes APIs to the API Store, where users can access them. When users subscribes to an API, they generates access tokens to make API calls to that API.  

1. Connect to the API manager database created above by configuring <APIM_HOME>/repository/conf/api-manager.xml as follows:         

Code Block
languagehtml/xml
<DataSourceName>jdbc/WSO2AM_DB</DataSourceName>

2. Connect the API provider instance to the API Key manager in <APIM_HOME>/repository/conf/api-manager.xml file.

Code Block
languagehtml/xml
<APIKeyManager>
   <ServerURL>https://192.168.139.1:9444/services/</ServerURL>
   <Username>admin</Username>
   <Password>admin</Password>
...

 3. Configure the <AuthManager> element to the Key Manager server node. For example,  

Code Block
languagehtml/xml
<AuthManager>
    <ServerURL>https://192.168.139.1:9444/services/</ServerURL>
    <Username>admin</Username>
    <Password>admin</Password>
</AuthManager>
  • ServerURL   : The URL of the Key Manager server
  • Username   : Username to connect to the Key Manager Server
  • Password    : Password to connect to the Key Manager Server

4. Configure the <APIGateway> element to the API Gateway server node. For example,  

Code Block
languagehtml/xml
<APIGateway>
    <ServerURL>https://192.168.139.1:9445/services/</ServerURL>
    <Username>admin</Username>
    <Password>admin</Password>          
    <APIEndpointURL>http://192.168.139.1:8282,https://192.168.139.1:8245</APIEndpointURL>   
</APIGateway>
  • ServerURL           : The URL of the API Gateway Server
  • Username           : Username to connect to the API Gateway Server
  • Password            : Password to connect to the API Gateway Server
  • APIEndpointURL   : Endpoint URL for APIs hosted on the Gateway
Info
titleInfor
If the Publisher and Store component servers need to be separated, create another instance with a copy of the configurations in this section. The two server distributions can then be named so that one is the Publisher and the other is the Store.

Next, refer to Clustering the Gateway Server NodesYou can install multiple instances of WSO2 products in a cluster to ensure that if one instance becomes unavailable or is experiencing high traffic, another instance will seamlessly handle the requests. For complete information on clustering, see Clustering WSO2 Products.