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.

    Note

    You 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

  1. 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
  2. Download Red Hat Process Automation Manager 7.8.0 Add-Ons.
  3. Extract the downloaded rhpam-7.8.0-add-ons.zip file to a temporary directory. The rhpam-7.8.0-smart-router.jar file is in the extracted rhpam-7.8.0-add-ons directory.
  4. Copy the rhpam-7.8.0-smart-router.jar file to the location where you will run the file.
  5. 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.

  6. 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.
  7. 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, and USERNAME and PASSWORD are the log in credentials for the Smart Router configuration.

Note

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

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 is 9443.

4.3. Configuring Smart Router for endpoint authentication

You can configure Smart Router (KIE Server Router) for endpoint authentication.

Prerequisites

Procedure

  • To start Smart Router with endpoint authentication enabled, configure the management credentials:

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

    2. Add the following property to your Smart Router configuration:

      `org.kie.server.router.management.password`

      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.

    1. Optionally, you can add users to Smart Router. For example:

      java -jar rhpam-7.8.0-smart-router.jar -addUser <USERNAME> <PASSWORD>
    2. 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 NameKJAR versionHosts

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