Chapter 30. Installing and configuring Smart Router

download PDF

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


  • Multiple KIE Server instances are installed.


    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.


  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.12
  2. Download Red Hat Process Automation Manager 7.12.0 Add-Ons.
  3. Extract the downloaded file to a temporary directory. The rhpam-7.12.0-smart-router.jar file is in the extracted rhpam-7.12.0-add-ons directory.
  4. Copy the rhpam-7.12.0-smart-router.jar file to the location where you will run the file.
  5. Enter the following command to start Smart Router:

    -jar rhpam-7.12.0-smart-router.jar

    The properties in the preceding command have the following default values:
    org.kie.server.controller= N/A
    org.kie.server.router.repo= <CURRENT_WORKING_DIR>

    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.


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

  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("", "USERNAME", "PASSWORD");

    In this example, is the Smart Router URL, and USERNAME and PASSWORD are the log in credentials for the Smart Router configuration.

  8. To create a new container in an umanaged KIE Server so that you can fill it with example data, send the following HTTP request:

    $ 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/
  9. Review the contents the create-container.xml file:

        <container container-id="example:timer-test:1.1">

    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
  10. 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"]}
  11. 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

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.



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.12.0-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>
          -jar rhpam-7.12.0-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.


    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.



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

    1. Add the following properties to your KIE Server configuration:


      The default username is the KIE Server ID.

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


      The password property values are true or false (default).


    Enabling endpoint authentication means any any operation that lists, adds or removes containers must be authenticated.

    1. Optional: Add users to Smart Router. For example:

      java -jar rhpam-7.12.0-smart-router.jar -addUser <USERNAME> <PASSWORD>
    2. Optional: Remove users from Smart Router. For example:

      java -jar rhpam-7.12.0-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 NameKJAR versionHosts


kjar:1.0 (alias=kjar, group-id=com.example, artifact-id=sample-kjar, version=1.0),,


kjar:2.0 (alias=kjar, group-id=com.example, artifact-id=sample-kjar, version=2.0),,


kjar:3.0 (alias=kjar, group-id=com.example, artifact-id=sample-kjar, version=3.0),,

If you send a request, the request is sent to kie-server1 (, kie-server2 (, and kie-server3 (

If you send a second request, that request is sent to the next host of each KIE Server. For example, kie-server1 (, kie-server2 (, and kie-server3 (

Smart Router has three components that you can modify to change this behavior:

The component responsible for finding the container id to use when interacting with servers.
The component responsible for disallowing Smart Router to use specific endpoints.
The component responsible for maintaining the Smart Router configuration. This is mainly related to the routing table.
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:


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.12.0.redhat-00008.jar:rhpam-7.12.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

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.


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

    Identifier of the Smart Router, for identification to other components.


    Name of the Smart Router, for identification to other components.


    The host name for the machine that runs the Smart Router



    The port for incoming HTTP connections. If you configure TLS connections, you can set this property to 0 to disable HTTP connections.



    The external URL for access to the Smart Router



    The port for incoming TLS connections



    The keystore file for TLS connections



    The password for the keystore for TLS connections



    The alias name that refers to the TLS certificate in the keystore



    The directory for storing the current repository

    The current working directory


    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.



    The URL for connecting to the controller



    The user name for connecting to the controller



    The password for connecting to the controller



    The authentication token for connecting to the controller



    The interval, in seconds, for retrying connection to the controller if it failed



    The maximum number of retries for connection to the controller if it failed



    If set to true, Smart Router periodically scans the configuration file and applies any changes



    The interval, in seconds, for rescanning the configuration file


    If set to true, Smart Router requires a password to authenticate a connection from KIE Server


  2. Start Smart Router using the following command line:

    java -Dorg.kie.server.router.config.file=<CONFIG_FILE> -jar rhpam-7.12.0-smart-router.jar

    Replace <CONFIG_FILE> with the name of the configuration file.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.