Chapter 30. 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. 30.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. Note You do not need to configure KIE Server as unmanaged for Smart Router. An unmanaged KIE Server instance does not connect to the controller. For example, if you connect an unmanaged KIE Server instance to Smart Router and register Smart Router with the controller, then Business Central contacts the unmanaged KIE Server instance 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.13.5 Download Red Hat Process Automation Manager 7.13.5 Add-Ons . Extract the downloaded rhpam-7.13.5-add-ons.zip file to a temporary directory. The rhpam-7.13.5-smart-router.jar file is in the extracted rhpam-7.13.5-add-ons directory. Copy the rhpam-7.13.5-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.13.5-smart-router.jar The properties in the preceding command have the following default values: org.kie.server.controller is the URL of the server controller, for example: org.kie.server.router.config.watcher.enabled is an optional settings to enable the watcher service system property. Note Instead of specifying configuration properties in the command line, you can use a configuration file. For information about configuring Smart Router using a file, see Section 30.5, "Configuring Smart Router settings using a configuration file" . 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: In this example, smartrouter.example.com is the Smart Router URL, and USERNAME and PASSWORD are the log in credentials for the Smart Router configuration. To create a new container in an umanaged KIE Server so that you can fill it with example data, send the following HTTP request: Review the contents the create-container.xml file: A message about the deployed container is displayed in the Smart Router console. For example: To display a list of containers, enter the following command: The list of containers is displayed: To initiate a process using the Smart Router URL, enter the following command: 30.2. Configuring Smart Router for TLS support You can configure Smart Router (KIE Server Router) for Transport Layer Security (TLS) support to allow HTTPS traffic. In addition, you can disable unsecure HTTP connections to Smart Router. Prerequisites KIE Server is installed on each node of a Red Hat JBoss EAP 7.4 cluster. Smart Router is installed and configured. For more information, see Section 30.1, "Load-balancing KIE Server instances with Smart Router" . Procedure To start Smart Router, use one of the following methods: To start Smart Router with TLS support and HTTPS enabled as well as allowing HTTP connections, enter the following command: java -Dorg.kie.server.router.tls.keystore = <KEYSTORE_PATH> -Dorg.kie.server.router.tls.keystore.password = <KEYSTORE_PASSWORD> -Dorg.kie.server.router.tls.keystore.keyalias = <KEYSTORE_ALIAS> -Dorg.kie.server.router.tls.port = <HTTPS_PORT> -jar rhpam-7.13.5-smart-router.jar In this example, replace the following variables: <KEYSTORE_PATH> : The path where the keystore will be stored. <KEYSTORE_PASSWORD> : The keystore password. <KEYSTORE_ALIAS> : The alias name used to store the certificate. <HTTPS_PORT> : The HTTPS port. The default HTTPS port is 9443 . To start Smart Router with TLS support and HTTPS enabled and with HTTP connections disabled, enter the following command: java -Dorg.kie.server.router.tls.keystore = <KEYSTORE_PATH> -Dorg.kie.server.router.tls.keystore.password = <KEYSTORE_PASSWORD> -Dorg.kie.server.router.tls.keystore.keyalias = <KEYSTORE_ALIAS> -Dorg.kie.server.router.tls.port = <HTTPS_PORT> -Dorg.kie.server.router.port=0 -jar rhpam-7.13.5-smart-router.jar When the org.kie.server.router.port system property is set to 0 , then the HTTP listener is not registered. If TLS is configured and the HTTP listener is not registered, then Smart Router listens only on the HTTPS port. Note If TLS is not configured and you disable HTTP by setting org.kie.server.router.port to 0 , then an error occurs and Smart Router stops. 30.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.4 cluster. Smart Router is installed and configured. For more information, see Section 30.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: The default username is the KIE Server ID. Add the following property to your Smart Router configuration: The password property values are true or false (default). Note Enabling endpoint authentication means any any operation that lists, adds or removes containers must be authenticated. Optional: Add users to Smart Router. For example: java -jar rhpam-7.13.5-smart-router.jar -addUser <USERNAME> <PASSWORD> Optional: Remove users from Smart Router. For example: java -jar rhpam-7.13.5-smart-router.jar -removeUser <USERNAME> 30.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 30.1. Example environment Server Name KJAR version Hosts kie-server1 kjar:1.0 (alias=kjar, group-id=com.example, artifact-id=sample-kjar, version=1.0) 129.0.1.1, 129.0.1.2, 129.0.1.3 kie-server2 kjar:2.0 (alias=kjar, group-id=com.example, artifact-id=sample-kjar, version=2.0) 129.0.2.1, 129.0.2.2, 129.0.2.3 kie-server3 kjar:3.0 (alias=kjar, group-id=com.example, artifact-id=sample-kjar, version=3.0) 129.0.3.1, 129.0.3.2, 129.0.3.3 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 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.13.5.redhat-00002.jar:rhpam-7.13.5-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: 30.5. Configuring Smart Router settings using a configuration file Instead of configuring Smart Router settings in the command line, you can use a configuration file. In this case, settings, including any passwords, are not visible in the command line terminal and server logs. Procedure Create a configuration file. This file can contain any number of lines in the property = value format. The file can include any of the following properties. All of the properties are optional. Table 30.2. Supported properties in the Smart Router configuration file Property name Description Default value org.kie.server.router.id Identifier of the Smart Router, for identification to other components. N/A org.kie.server.router.name Name of the Smart Router, for identification to other components. N/A org.kie.server.router.host The host name for the machine that runs the Smart Router localhost org.kie.server.router.port The port for incoming HTTP connections. If you configure TLS connections, you can set this property to 0 to disable HTTP connections. 9000 org.kie.server.router.url.external The external URL for access to the Smart Router N/A org.kie.server.router.tls.port The port for incoming TLS connections N/A org.kie.server.router.tls.keystore The keystore file for TLS connections N/A org.kie.server.router.tls.keystore.password The password for the keystore for TLS connections N/A org.kie.server.router.tls.keystore.keyalias The alias name that refers to the TLS certificate in the keystore N/A org.kie.server.router.repo The directory for storing the current repository The current working directory org.kie.router.identity.provider The optional custom provider class for authenticating KIE Server instances with Smart Router. This class must implement the org.kie.server.router.identity.IdentityManager interface, For the source code of this interface, see the GitHub repository . N/A org.kie.server.controller The URL for connecting to the controller N/A org.kie.server.controller.user The user name for connecting to the controller kieserver org.kie.server.controller.pwd The password for connecting to the controller kieserver1! org.kie.server.controller.token The authentication token for connecting to the controller N/A org.kie.server.controller.retry.interval The interval, in seconds, for retrying connection to the controller if it failed 10 org.kie.server.controller.retry.limit The maximum number of retries for connection to the controller if it failed infinite org.kie.server.router.config.watcher.enabled If set to true , Smart Router periodically scans the configuration file and applies any changes false org.kie.server.router.config.watcher.interval The interval, in seconds, for rescanning the configuration file 5 org.kie.server.router.management.password If set to true , Smart Router requires a password to authenticate a connection from KIE Server false Start Smart Router using the following command line: java -Dorg.kie.server.router.config.file=<CONFIG_FILE> -jar rhpam-7.13.5-smart-router.jar Replace <CONFIG_FILE> with the name of the configuration file.

Commands:
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.13.5-smart-router.jar
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=http://<HOST>:<PORT>/controller/rest/controller
KieServicesConfiguration config = KieServicesFactory.newRestConfiguration("http://smartrouter.example.com:9000", "USERNAME", "PASSWORD");
curl -v -X POST -H 'Content-type: application/xml' -H 'X-KIE-Content-Type: xstream' -d @create-container.xml -u USD{KIE_CRED} http://USD{KIE-SERVER-HOST}:USD{KIE-SERVER-PORT}/kie-server/services/rest/server/config/
<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>
INFO: Added http://localhost:8180/kie-server/services/rest/server as server location for container example:timer-test:1.1
curl http://localhost:9000/mgmt/list
{ "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"]} ] }
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
java -Dorg.kie.server.router.tls.keystore = <KEYSTORE_PATH> -Dorg.kie.server.router.tls.keystore.password = <KEYSTORE_PASSWORD> -Dorg.kie.server.router.tls.keystore.keyalias = <KEYSTORE_ALIAS> -Dorg.kie.server.router.tls.port = <HTTPS_PORT> -jar rhpam-7.13.5-smart-router.jar
java -Dorg.kie.server.router.tls.keystore = <KEYSTORE_PATH> -Dorg.kie.server.router.tls.keystore.password = <KEYSTORE_PASSWORD> -Dorg.kie.server.router.tls.keystore.keyalias = <KEYSTORE_ALIAS> -Dorg.kie.server.router.tls.port = <HTTPS_PORT> -Dorg.kie.server.router.port=0 -jar rhpam-7.13.5-smart-router.jar
`org.kie.server.router.management.username` `org.kie.server.router.management.password`
`org.kie.server.router.management.password`
java -jar rhpam-7.13.5-smart-router.jar -addUser <USERNAME> <PASSWORD>
java -jar rhpam-7.13.5-smart-router.jar -removeUser <USERNAME>
java -cp LOCATION/router-ext-7.13.5.redhat-00002.jar:rhpam-7.13.5-smart-router.jar org.kie.server.router.KieServerRouter
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
java -Dorg.kie.server.router.config.file=<CONFIG_FILE> -jar rhpam-7.13.5-smart-router.jar