Page Comparison

Follow the instructions below to deploy WSO2 API Manager (WSO2 API-M) in a distributed environment, as depicted in the following deployment diagram:

...

Expand

title	Click here for instructions to configure and start the Key Manager.

This section involves setting up the Key Manager node and enabling it to work with the other components in a distributed deployment.

Warning
Skip this step if you are using WSO2 Identity Server as the Key Manager and follow the instructions mentioned in Configuring WSO2 Identity Server as a Key Manager to configure and start the Key Manager.

Open the <API-M_HOME>/repository/conf/api-manager.xml file in the Key Manager node and change the <ServerURL> element that appears under the <APIGateway> section, so that it points to the API Manager Gateway.
You need to add these configurations so that when a user is deleted or when the role of a user is updated in the Key Manager, it will update the Gateway cache by clearing the cache entries of a particular user.
- If you are working with a single Gateway in distributed set up, you need to replace [GATEWAY_SERVER_HOST] with the host of the Gateway node.
- If you are working with Gateways in a High Availability (HA) setup that uses a shared file system (e.g., NFS), you need to replace [GATEWAY_SERVER_HOST] with the host of the Gateway load balancer node.
- If you are working with Gateways in a High Availability (HA) setup that uses rsync, you need to replace [GATEWAY_SERVER_HOST] with the host of the Gateway Manager node.
- You need to replace [port] with the management transport port. For more information, see Default Product Ports.
  Code Block
  <ServerURL>https://$[GATEWAY_SERVER_HOST]:[port]/services/</ServerURL>

Configure the API key validator in the Key Manager.
The Thrift protocol is normally enabled by default. However, if you have disabled the Thrift protocol, enable it as follows in the <API-M_HOME>/repository/conf/api-manager.xml file.

Localtabgroup

Localtab

active	true
id	single-Key-Manager-KM
title	Single Key Manager

When you are using a single Key Manager, you need to add WSClient for the <KeyValidatorClientType> element to use the Web Service Client, and change <EnableThriftServer> to false to optimize performance.

Code Block

language	none

<APIKeyValidator>    
	
    <KeyValidatorClientType>WSClient</KeyValidatorClientType>   
    <EnableThriftServer>false</EnableThriftServer>
    <ThriftServerHost>localhost</ThriftServerHost>
    <!--ThriftServerPort>10397</ThriftServerPort-->
    ...
</APIKeyValidator>

Localtab

id	HA-Key-Manager-KM
title	Key Manager with HA

When you are using multiple Key Managers fronted by a load balancer, you need to add WSClient for the <KeyValidatorClientType> element to use the Web Service Client, and change <EnableThriftServer> to false to optimize performance.

Code Block

language	none

<APIKeyValidator>
	...
	<KeyValidatorClientType>WSClient</KeyValidatorClientType>    
 
    <EnableThriftServer>false</EnableThriftServer>
    <ThriftServerHost>localhost</ThriftServerHost>
    <!--ThriftServerPort>10397</ThriftServerPort-->
    ...
</APIKeyValidator>

Tip
If you wish to encrypt the Auth Keys (access tokens, client secrets, and authorization codes), see Encrypting OAuth Keys.

Disable the Policy Deployer under the Throttling configurations.

Code Block
<ThrottlingConfigurations> ... <PolicyDeployer> <Enabled>false</Enabled> ... </PolicyDeployer> ... </ThrottlingConfigurations>

Optionally, configure High Availability (HA) for the Key Manager.
Warning
These steps are ONLY applicable if you need to configure HA for the Key Manager.
1. Make a copy of the active instance configured above and use this copy as the second Key Manager active instance.
2. Configure a load balancer to front the two Key Manager nodes.
  For information on configuring the load balancer, see Configuring the Proxy Server and the Load Balancer.

Configure the Key Manager to communicate with the Traffic Manager.

Warning
This is available only as a WUM update and is effective from 30th September 2020 (2020-09-30). For more information on updating WSO2 API Manager, see Updating WSO2 API Manager.

Localtabgroup

Localtab

active	true
id	single-TM-KM
title	Single Traffic Manager

Configure the Key Manager with a single Traffic Manager as follows:

Info
9611 and 9711 are the Traffic Manager receiver ports for the binary type.

Update the Throttling configurations as follows:

Code Block

language	xml

<ThrottlingConfigurations>
		<TrafficManager>
			<Type>Binary</Type>
			<ReceiverUrlGroup>tcp://${carbon.local.ip}:${receiver.url.port}</ReceiverUrlGroup>
            <AuthUrlGroup>ssl://${carbon.local.ip}:${auth.url.port}</AuthUrlGroup>
            <Username>${admin.username}</Username>
            <Password>${admin.password}</Password>
		</TrafficManager>        
</ThrottlingConfigurations>

Configure JMSConnectionParameters to connect to the broker running within the Traffic Manager.

Code Block

title	Example

<JMSConnectionParameters>
   <transport.jms.ConnectionFactoryJNDIName>TopicConnectionFactory</transport.jms.ConnectionFactoryJNDIName>
   <transport.jms.DestinationType>topic</transport.jms.DestinationType>
   <java.naming.factory.initial>org.wso2.andes.jndi.PropertiesFileInitialContextFactory</java.naming.factory.initial>
	<connectionfactory.TopicConnectionFactory>amqp://${admin.username}:${admin.password}@clientid/carbon?brokerlist='tcp://[traffic-manager-hostname]:${jms.port}?retries='5'%26connectdelay='50''</connectionfactory.TopicConnectionFactory>   
</JMSConnectionParameters>

Localtab

id	TM-HA-KM
title	HA of Traffic Manager

Configure the Key Manager with multiple Traffic Managers, which are fronted by a load balancer as follows:

Follow the instructions below to configure the Key Manager to communicate with the Traffic Managers and to push token revocation events to both Traffic Manager instances.

Configure the receiver URL group <ReceiverUrlGroup> and Authentication URL Group <AuthUrlGroup> values, which are under the <TrafficManager> element in the <API-M_HOME>/repository/conf/api-manager.xml file, in order to contain all the Traffic Manager receiver URLs.
This is required when you have more than one Traffic Manager instance, and you are publishing to both as per the deployment pattern selected. As an example, if you are using two Traffic Manager instances and data should be published to both of them, the ReceiverUrlGroup and AuthUrlGroup should be configured as follows:

Code Block

title	Example

<ThrottlingConfigurations>
   <EnableAdvanceThrottling>true</EnableAdvanceThrottling>
	<TrafficManager>
		<Type>Binary</Type>
      	<ReceiverUrlGroup>{tcp://[Traffic-Manager-1-host]:9611}, {tcp://[Traffic-Manager-2-host]:9611}</ReceiverUrlGroup>
      	<!--ReceiverUrlGroup>tcp://${carbon.local.ip}:9612</ReceiverUrlGroup-->
      	<AuthUrlGroup>{ssl://[Traffic-Manager-1-host]:9711}, {ssl://[Traffic-Manager-2-host]:9711}</AuthUrlGroup>
      	<!--AuthUrlGroup>ssl://${carbon.local.ip}:9712</AuthUrlGroup-->
		<Username>${admin.username}</Username>
		<Password>${admin.password}</Password>
	</TrafficManager>
...
</ThrottlingConfigurations>

[Traffic-Manager-1-host] and [Traffic-Manager-2-host] are the IPs/hostnames of two Traffic Manager nodes.

Based on the above configuration, the Key Manager publishes events to both the Traffic Managers.

Configure JMSConnectionParameters to connect to multiple brokers running within each Traffic Manager using fail over mechanism.

Code Block

title	Example

<JMSConnectionParameters>
   <transport.jms.ConnectionFactoryJNDIName>TopicConnectionFactory</transport.jms.ConnectionFactoryJNDIName>
   <transport.jms.DestinationType>topic</transport.jms.DestinationType>
   <java.naming.factory.initial>org.wso2.andes.jndi.PropertiesFileInitialContextFactory</java.naming.factory.initial>
   <connectionfactory.TopicConnectionFactory>amqp://${admin.username}:${admin.password}@clientid/carbon?failover='roundrobin'%26cyclecount='2'%26brokerlist='tcp://[Traffic-Manager-1-host]:${jms.port}?retries='5'%26connectdelay='50';tcp://[Traffic-Manager-2-host]:${jms.port}?retries='5'%26connectdelay='50''</connectionfactory.TopicConnectionFactory>
</JMSConnectionParameters>

Add the following in the <API-M_HOME>/repository/conf/api-manager.xml file for each of the Key Manager nodes in the deployment.
Code Block
<TokenRevocationNotifier> <Enabled>true</Enabled> </TokenRevocationNotifier>
Start the WSO2 API-M Key Manager node(s).
Make sure to run the product optimizer either before starting the server or while starting the server, so that the resource utilization can be optimized on each of the nodes. For more information on product profile optimization, see Product Profiles.

Note

It is not recommended to share the Solr directory between the Store and Publisher servers. You need to have separate Solr directories for each of the latter mentioned servers so that they will perform Solr indexing separately.

Warning

If you get an error similar to the following in both or one of the nodes, check whether you have shared the Solr directory.

Code Block
org.apache.solr.common.SolrException: SolrCore 'registry-indexing' is not available due to init failure: Index locked for write for core registry-indexing

...

Expand

title	Click here for instructions to configure and start the Gateway.

This section involves setting up the Gateway node and enabling it to work with the other components in the distributed deployment.

Note

Steps 1 to 5 in the following section are common irrespective of your API-M deployment, such as deploying a single Gateway node or deploying multiple Gateway nodes for High Availability (HA). However, if you are using two Gateway nodes for high availability (HA), first follow the instructions that is available in the Distributed Deployment of the Gateway document, and then carry out the following steps to configure the connections from Gateway(s) to other components.

Open the <API-M_HOME>/repository/conf/api-manager.xml file in the Gateway node.

Modify the api-manager.xml file as follows. This configures the connection to the Key Manager component.

Localtabgroup

Localtab

active	true
id	single-Key-Manager-GW
title	Single Key Manager

Configure the Gateway with a single Key Manager as follows:

Configure the API Key Validator.

Code Block

language	none

<APIKeyValidator> 
  <ServerURL>https://[Key-Manager-host]:9443/services/</ServerURL>
  <Username>${admin.username}</Username>
  <Password>${admin.password}</Password>
  ...
</APIKeyValidator>

[Key-Manager-host] - If you have a single Key Manager node, this should be the host of the Key Manager (i.e., the host of the WSO2 Identity Server).

Note
To change the admin password, see Changing the super admin password. If your password has special characters, follow the guidelines mentioned as a note under step 2 in the latter mentioned section.

Use WSClient as the KeyValidatorClientType in the <API-M_HOME>/repository/conf/api-manager.xml file.
Code Block
language none
<KeyValidatorClientType>WSClient</KeyValidatorClientType>
Disable the Thrift Server to optimize performance.
You need to configure this in the Gateway <API-M_HOME>/repository/conf/api-manager.xml file
Code Block
<APIKeyValidator> ... <EnableThriftServer>false</EnableThriftServer> </APIKeyValidator>

Localtab

id	HA-Key-Manager-GW
title	Key Managers with HA

Configure the Gateway with multiple Key Managers, which are fronted by a load balancer as follows:

Configure the APIKeyValidator as follows:

Code Block

language	none

<APIKeyValidator> 
  <ServerURL>https://[Key-Manager-LB-host]:9443/services/</ServerURL>
  <Username>${admin.username}</Username>
  <Password>${admin.password}</Password>
  ...
</APIKeyValidator>

[Key-Manager-LB-host] - If there are multiple Key Managers (i.e., Multiple WSO2 Identity Servers as the Key Manager) fronted by a load balancer, this should be the host of the Key Manager's load balancer. For example, in the configuration we have defined key-manager as the load balancer host in the Key Manager section.

Note
To change the admin password, see Changing the super admin password. If your password has special characters, follow the guidelines mentioned as a note under step 2 in the latter mentioned section.

Use WSClient as KeyValidatorClientType in the <API-M_HOME>/repository/conf/api-manager.xml file.
Note that you can only use the Web Service Client when the Key Manager cluster is fronted by a load balancer.
Code Block
language none
<KeyValidatorClientType>WSClient</KeyValidatorClientType>
Ensure that Thrift is disabled in the Gateway.
This is enabled by default in all instances of the product, so you need to disable the Thrift server by setting EnableThriftServer to false in the <API-M_HOME>/repository/conf/api-manager.xml file of each node.
Code Block
language none
<EnableThriftServer>false</EnableThriftServer>

If you need to enable JSON Web Token (JWT), you have to enable it in all Gateway and Key Manager components.
For more information on configuring JWT, see Generating JSON Web Token.

Configure the Gateway to communicate with the Traffic Manager.
You need to do this to enable Throttling for the Traffic Manager node(s).

Warning
These configurations vary based on whether you have a single Traffic Manager node or multiple Traffic Manager nodes.

Localtabgroup

Localtab

active	true
id	single-TM-GW
title	Single Traffic Manager

Configure the Gateway with a single Traffic Manager as follows:

Info
9611 and 9711 are the Traffic Manager receiver ports for the binary type.

Update the Throttling configurations as follows:

Code Block

language	xml

<ThrottlingConfigurations>
        <EnableAdvanceThrottling>true</EnableAdvanceThrottling>
		<TrafficManager>
			<Type>Binary</Type>
			<ReceiverUrlGroup>tcp://[Traffic-Manager-host]:9611</ReceiverUrlGroup>
            <AuthUrlGroup>ssl://[Traffic-Manager-host]:9711</AuthUrlGroup>
            <Username>${admin.username}</Username>
            <Password>${admin.password}</Password>
		</TrafficManager>
        <DataPublisher>
            <Enabled>true</Enabled>
		...
        </DataPublisher>
        <PolicyDeployer>
			<Enabled>false</Enabled>
			<ServiceURL>https://[Traffic-Manager-host]:9443/services/</ServiceURL>
		...
        </PolicyDeployer>
		...
        <JMSConnectionDetails>
            <Enabled>true</Enabled>
            <ServiceURL>tcp://[Traffic-Manager-host]:5672</ServiceURL>
		...
        </JMSConnectionDetails>
</ThrottlingConfigurations>

Warning
In the Gateway profile of WSO2 API Manager, disable the `<PolicyDeployer>` configuration to prevent blocking the API Publisher.

Configure JMSConnectionParameters to connect to the broker running within the Traffic Manager.

Code Block

title	Example

<JMSConnectionParameters>
   <transport.jms.ConnectionFactoryJNDIName>TopicConnectionFactory</transport.jms.ConnectionFactoryJNDIName>
   <transport.jms.DestinationType>topic</transport.jms.DestinationType>
   <java.naming.factory.initial>org.wso2.andes.jndi.PropertiesFileInitialContextFactory</java.naming.factory.initial>
	<connectionfactory.TopicConnectionFactory>amqp://${admin.username}:${admin.password}@clientid/carbon?brokerlist='tcp://[traffic-manager-hostname]:${jms.port}?retries='5'%26connectdelay='50''</connectionfactory.TopicConnectionFactory>   
</JMSConnectionParameters>

Localtab

id	TM-HA-GW
title	HA of Traffic Manager

Configure the Gateway with multiple Traffic Managers, which are fronted by a load balancer as follows:

The Gateway publishes all Throttling events to the two Traffic Manager instances, and it fetches the throttle decisions from the Traffic Manager instances. Follow the instructions below to configure the API Gateway worker to communicate with the Traffic Managers and to push throttle events to both Traffic Manager instances.

Configure the receiver URL group <ReceiverUrlGroup> and Authentication URL Group <AuthUrlGroup> values, which are under the <DataPublisher><TrafficManager> element in the <API-M_HOME>/repository/conf/api-manager.xml file, in order to contain all the Traffic Manager receiver URLs.
This is required when you have more than one Traffic Manager instance, and you are publishing to both as per the deployment pattern selected. As an example, if you are using two Traffic Manager instances and data should be published to both of them, the ReceiverUrlGroup and AuthUrlGroup should be configured as follows:

Code Block

title	Example

<ThrottlingConfigurations>
   <EnableAdvanceThrottling>true</EnableAdvanceThrottling>
	<TrafficManager>
		<Type>Binary</Type>
      	<ReceiverUrlGroup>{tcp://[Traffic-Manager-1-host]:9611}, {tcp://[Traffic-Manager-2-host]:9611}</ReceiverUrlGroup>
      	<!--ReceiverUrlGroup>tcp://${carbon.local.ip}:9612</ReceiverUrlGroup-->
      	<AuthUrlGroup>{ssl://[Traffic-Manager-1-host]:9711}, {ssl://[Traffic-Manager-2-host]:9711}</AuthUrlGroup>
      	<!--AuthUrlGroup>ssl://${carbon.local.ip}:9712</AuthUrlGroup-->
		<Username>${admin.username}</Username>
		<Password>${admin.password}</Password>
	</TrafficManager>


   <DataPublisher>
      <Enabled>true</Enabled>
		...
   </DataPublisher>
 	<PolicyDeployer>
			<Enabled>false</Enabled>
		...
        </PolicyDeployer>
...
</ThrottlingConfigurations>

[Traffic-Manager-1-host] and [Traffic-Manager-2-host] are the IPs/hostnames of two Traffic Manager nodes.

Based on the above configuration, the API Gateway publishes events to both the Traffic Managers.

Warning
In the Gateway profile of WSO2 API Manager, disable the `<PolicyDeployer>` configuration to prevent blocking the API Publisher.

Configure JMSConnectionParameters to connect to multiple brokers running within each Traffic Manager using fail over mechanism.

Code Block

title	Example

<JMSConnectionParameters>
   <transport.jms.ConnectionFactoryJNDIName>TopicConnectionFactory</transport.jms.ConnectionFactoryJNDIName>
   <transport.jms.DestinationType>topic</transport.jms.DestinationType>
   <java.naming.factory.initial>org.wso2.andes.jndi.PropertiesFileInitialContextFactory</java.naming.factory.initial>
   <connectionfactory.TopicConnectionFactory>amqp://${admin.username}:${admin.password}@clientid/carbon?failover='roundrobin'%26cyclecount='2'%26brokerlist='tcp://[Traffic-Manager-1-host]:${jms.port}?retries='5'%26connectdelay='50';tcp://[Traffic-Manager-2-host]:${jms.port}?retries='5'%26connectdelay='50''</connectionfactory.TopicConnectionFactory>
</JMSConnectionParameters>

Info
By default, WSO2 API Manager is shipped with a keystore (`wso2carbon.jks`) and a trust store (`client-truststore.jks`). For more information on how to create a new key store and a trust store with a private key and a self-signed certificate, see Configuring Keystore and Truststore and also see the Administration guide for recommendations on setting up keystores in WSO2 products.

Start the WSO2 API-M Gateway node(s).
Make sure to run the product optimizer either before starting the server or while starting the server, so that the resource utilization can be optimized on each of the nodes. For more information on product profile optimization, see Product Profiles.

Versions Compared

Old Version 29

New Version Current

Key