Chapter 4. Installing and configuring Smart Router
Smart Router (KIE Server router) is a lightweight Java component that you can use as an integration layer between multiple KIE Servers, client applications, and other components. Depending on your deployment and execution environment, Smart Router can aggregate multiple independent KIE Server instances as though they are a single server. Smart Router provides the following features:
- Data aggregation
- Collects data from all KIE Server instances (one instance from each group) when there is a client application request and aggregates the results in a single response.
- Routing
- Functions as a single endpoint that receives calls from client applications to any of your services and routes each call automatically to the KIE Server that runs the specific service. This means that KIE Servers do not need to have the same services deployed.
- Load balancing
- Provides efficient load balancing. Load balancing requests for a Smart Router cluster must be managed externally with standard load balancing tools.
- Authentication
- Authenticates KIE Server instances by using a system property flag and can enable HTTPS traffic.
- Environment Management
- Manages the changing environment, for example adding or removing server instances.
4.1. Load-balancing KIE Server instances with Smart Router
You can use Smart Router to aggregate multiple independent KIE Server instances as though they are a single server. It performs the role of an intelligent load balancer because it can route requests to individual KIE Server instances and aggregate data from different KIE Server instances. Smart Router uses aliases to perform as a proxy.
Prerequisites
Multiple KIE Server instances are installed.
NoteYou do not need to configure KIE Server as unmanaged for Smart Router.
An unmanaged KIE Server does not connect to the controller.
For example, if you connect an unmanaged KIE Server to Smart Router and register Smart Router with the controller, then Business Central contacts the unmanaged KIE Server by using Smart Router.
Procedure
Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:
- Product: Process Automation Manager
- Version: 7.8
- Download Red Hat Process Automation Manager 7.8.0 Add-Ons.
-
Extract the downloaded
rhpam-7.8.0-add-ons.zip
file to a temporary directory. Therhpam-7.8.0-smart-router.jar
file is in the extractedrhpam-7.8.0-add-ons
directory. -
Copy the
rhpam-7.8.0-smart-router.jar
file to the location where you will run the file. Enter the following command to start Smart Router:
java -Dorg.kie.server.router.host=<ROUTER_HOST> -Dorg.kie.server.router.port=<ROUTER_PORT> -Dorg.kie.server.controller=<CONTROLLER_URL> -Dorg.kie.server.controller.user=<CONTROLLER_USER> -Dorg.kie.server.controller.pwd=<CONTROLLER_PWD> -Dorg.kie.server.router.config.watcher.enabled=true -Dorg.kie.server.router.repo=<NFS_STORAGE> -jar rhpam-7.8.0-smart-router.jar
The properties in the preceding command have the following default values:
org.kie.server.router.host=localhost org.kie.server.router.port=9000 org.kie.server.controller= N/A org.kie.server.controller.user=kieserver org.kie.server.controller.pwd=kieserver1! org.kie.server.router.repo= <CURRENT_WORKING_DIR> org.kie.server.router.config.watcher.enabled=false
org.kie.server.controller
is the URL of the server controller, for example:org.kie.server.controller=http://<HOST>:<PORT>/controller/rest/controller
org.kie.server.router.config.watcher.enabled
is an optional settings to enable the watcher service system property.-
On every KIE Server instance that must connect to the Smart Router, set the
org.kie.server.router
system property to the Smart Router URL. To access Smart Router from the client side, use the Smart Router URL instead of the KIE Server URL, for example:
KieServicesConfiguration config = KieServicesFactory.newRestConfiguration("http://smartrouter.example.com:9000", "USERNAME", "PASSWORD");
In this example,
smartrouter.example.com
is the Smart Router URL, andUSERNAME
andPASSWORD
are the log in credentials for the Smart Router configuration.
You must create containers directly against the kie-server
. For example:
$ curl -v -X POST -H 'Content-type: application/xml' -H 'X-KIE-Content-Type: xstream' -d @create-container.xml -u ${KIE_CRED} http://${KIE-SERVER-HOST}:${KIE-SERVER-PORT}/kie-server/services/rest/server/config/
$ cat create-container.xml <script> <create-container> <container container-id="example:timer-test:1.1"> <release-id> <group-id>example</group-id> <artifact-id>timer-test</artifact-id> <version>1.1</version> </release-id> <config-items> <itemName>RuntimeStrategy</itemName> <itemValue>PER_PROCESS_INSTANCE</itemValue> <itemType></itemType> </config-items> </container> </create-container> </script>
A message about the deployed container is displayed in the smart-router console. For example:
INFO: Added http://localhost:8180/kie-server/services/rest/server as server location for container example:timer-test:1.1
To display a list of containers, enter the following command:
$ curl http://localhost:9000/mgmt/list
The list of containers is displayed:
{ "containerInfo": [{ "alias": "timer-test", "containerId": "example:timer-test:1.1", "releaseId": "example:timer-test:1.1" }], "containers": [ {"example:timer-test:1.1": ["http://localhost:8180/kie-server/services/rest/server"]}, {"timer-test": ["http://localhost:8180/kie-server/services/rest/server"]} ], "servers": [ {"kieserver2": []}, {"kieserver1": ["http://localhost:8180/kie-server/services/rest/server"]} ] }
To initiate a process using the Smart Router URL, enter the following command:
$ curl -s -X POST -H 'Content-type: application/json' -H 'X-KIE-Content-Type: json' -d '{"timerDuration":"9s"}' -u kieserver:kieserver1! http://localhost:9000/containers/example:timer-test:1.1/processes/timer-test.TimerProcess/instances
4.2. Configuring Smart Router for TLS support
You can configure Smart Router (KIE Server Router) for TLS support to allow HTTPS traffic.
Prerequisites
- KIE Server is installed on each node of a Red Hat JBoss EAP 7.3 cluster.
- Smart Router is installed and configured. For more information, see Section 4.1, “Load-balancing KIE Server instances with Smart Router”.
Procedure
To start Smart Router with TLS support and HTTPS enabled, use the TLS keystore properties, for example:
java -Dorg.kie.server.router.tls.keystore = <KEYSTORE_PATH> -Dorg.kie.server.router.tls.keystore.password = <KEYSTORE_PWD> -Dorg.kie.server.router.tls.keystore.keyalias = <KEYSTORE_ALIAS> -Dorg.kie.server.router.tls.port = <HTTPS_PORT> -jar rhpam-7.8.0-smart-router.jar
org.kie.server.router.tls.port
is a property used to configure the HTTPS port. The default HTTPS port value is9443
.
4.3. Configuring Smart Router for endpoint authentication
You can configure Smart Router (KIE Server Router) for endpoint authentication.
Prerequisites
- KIE Server is installed on each node of a Red Hat JBoss EAP 7.3 cluster.
- Smart Router is installed and configured. For more information, see Section 4.1, “Load-balancing KIE Server instances with Smart Router”.
Procedure
To start Smart Router with endpoint authentication enabled, configure the management credentials:
Add the following properties to your KIE Server configuration:
`org.kie.server.router.management.username` `org.kie.server.router.management.password`
The default
username
is the KIE Server ID.Add the following property to your Smart Router configuration:
`org.kie.server.router.management.password`
The
password
property values aretrue
orfalse
(default).
NoteEnabling endpoint authentication means any any operation that lists, adds or removes containers must be authenticated.
Optionally, you can add users to Smart Router. For example:
java -jar rhpam-7.8.0-smart-router.jar -addUser <USERNAME> <PASSWORD>
Optionally, you can remove users from Smart Router. For example:
java -jar rhpam-7.8.0-smart-router.jar -removeUser <USERNAME>
4.4. Configuring Smart Router behavior
In a clustered environment with multiple KIE Servers, the default behavior is to send requests to each KIE Server in parallel and a host of each KIE Server is sent the request using the "round-robin" method. In the following example environment, each KIE Server is deployed with the same KJAR but each KJAR version is different:
Table 4.1. Example environment
Server Name | KJAR version | Hosts |
---|---|---|
|
|
|
|
|
|
|
|
|
If you send a request, the request is sent to kie-server1 (129.0.1.2)
, kie-server2 (129.0.2.3)
, and kie-server3 (129.0.3.1)
.
If you send a second request, that request is sent to the next host of each KIE Server. For example, kie-server1 (129.0.1.3)
, kie-server2 (129.0.2.1)
, and kie-server3 (129.0.3.2)
.
Smart Router has three components that you can modify to change this behavior:
- ContainerResolver
- The component responsible for finding the container id to use when interacting with servers.
- RestrictionPolicy
- The component responsible for disallowing Smart Router to use specific endpoints.
- ConfigRepository
- The component responsible for maintaining the Smart Router configuration. This is mainly related to the routing table.
- IdentityService
- The component responsible for allowing you to use your own identity provider. This is for KIE Server instances.
Smart Router uses the ServiceLoader
utility to implement these components:
- ContainerResolver
-
META-INF/services/org.kie.server.router.spi.ContainerResolver
- RestrictionPolicy
-
META-INF/services/org.kie.server.router.spi.RestrictionPolicy
- ConfigRepository
-
META-INF/services/org.kie.server.router.spi.ConfigRepository
- IdentityService
-
META-INF/services/org.kie.server.router.identity.IdentityService
For example, for the above scenario, you can customize the ContainerResolver
to make Smart Router search for the latest version of the KJAR process across all available KIE Servers and to always start with that process. This scenario would mean that each KIE Server hosts a single KJAR and each version will share the same alias.
Since Smart Router is an executable jar, to include extensions, you need to modify the command. For example:
java -cp LOCATION/router-ext-7.7.1.redhat-00002.jar:rhpam-7.8.0-smart-router.jar org.kie.server.router.KieServerRouter
Once the service is started you will see log output stating the implementation that is used for the components:
Mar 01, 2017 1:47:10 PM org.kie.server.router.KieServerRouter <init> INFO: KIE Server router repository implementation is InMemoryConfigRepository Mar 01, 2017 1:47:10 PM org.kie.server.router.proxy.KieServerProxyClient <init> INFO: Using 'LatestVersionContainerResolver' container resolver and restriction policy 'ByPassUserNotAllowedRestrictionPolicy' Mar 01, 2017 1:47:10 PM org.xnio.Xnio <clinit> INFO: XNIO version 3.3.6.Final Mar 01, 2017 1:47:10 PM org.xnio.nio.NioXnio <clinit> INFO: XNIO NIO Implementation Version 3.3.6.Final Mar 01, 2017 1:47:11 PM org.kie.server.router.KieServerRouter start INFO: KieServerRouter started on localhost:9000 at Wed Mar 01 13:47:11 CET 2017