Chapter 3. Process Server clusters in a runtime environment

In a runtime environment, Process Server runs services that contain rules and processes that support business decisions. The primary benefit of clustering a Process Server runtime environment is load balancing. If activity on one node of the cluster increases, that activity can be shared among the other nodes of the cluster to improve performance.

To create a Process Server clustered runtime environment, you download and extract Red Hat JBoss EAP 7.2 and Process Server. Then, you configure Red Hat JBoss EAP 7.2 for a cluster, start the cluster, and install Process Server on each cluster node.

Optionally, you can then cluster the headless Process Automation Manager controller and Smart Router.

3.1. Downloading and extracting Red Hat JBoss EAP 7.2 and Process Server

Complete the steps in this section to download and install Red Hat JBoss EAP 7.2 and Process Server for installation in a clustered environment.

Procedure

  1. Download Red Hat JBoss EAP 7.2 on each node of the cluster:

    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: Red Hat JBoss EAP
      • Version: 7.2
    2. Click Download next to Red Hat JBoss Enterprise Application Platform 7.2.0. (jboss-eap-7.2.0.zip).
  2. Extract the jboss-eap-7.2.0.zip file. The jboss-eap-7.2/jboss-eap-7.2 directory is referred to as EAP_HOME.
  3. Download and apply the latest Red Hat JBoss EAP patch, if available.
  4. Download Process Server:

    1. Navigate to the Software Downloads page in the Red Hat Customer Portal and select the product and version from the drop-down options:

      • Product: Process Automation Manager
      • Version: 7.6
    2. Download Red Hat Process Automation Manager 7.6.0 Process Server for All Supported EE8 Containers (rhpam-7.6.0-kie-server-ee8.zip).
  5. Extract the rhpam-7.6.0-kie-server-ee8.zip archive to a temporary directory. In the following examples this directory is called TEMP_DIR.
  6. Copy the TEMP_DIR/rhpam-7.6.0-kie-server-ee8/rhpam-7.6.0-kie-server-ee8/kie-server.war directory to EAP_HOME/standalone/deployments/.

    Warning

    Ensure the names of the Red Hat Process Automation Manager deployments you copy do not conflict with your existing deployments in the Red Hat JBoss EAP instance.

  7. Copy the contents of the TEMP_DIR/rhpam-7.6.0-kie-server-ee8/rhpam-7.6.0-kie-server-ee8/SecurityPolicy/ to EAP_HOME/bin. When asked to overwrite files, click Replace.
  8. In the EAP_HOME/standalone/deployments/ directory, create an empty file named kie-server.war.dodeploy. This file ensures that Process Server is automatically deployed when the server starts.
  9. Download and apply the latest Red Hat Process Automation Manager patch, if available.
  10. Navigate to the EAP_HOME/bin directory.
  11. Create a user with the kie-server role that you will use to log in to Process Server.

    $ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server
  12. Make a note of your user names and passwords.

3.2. Configuring and running a Red Hat JBoss EAP 7.2 cluster for Process Server

Configure the Red Hat JBoss EAP cluster for Process Server, and then start the cluster.

Procedure

  1. Install the JDBC driver on all Red Hat JBoss EAP instances that are part of this cluster. For more information, see the "JDBC Drivers" section of the Red Hat JBoss EAP 7.2 Configuration Guide.
  2. Open the EAP_HOME/standalone/configuration/standalone-full.xml file in a text editor.
  3. Edit the data-stores property and the timer-service thread-pool-name above it:

    • The datasource-jndi-name is the JNDI name of the database specified at the beginning of this procedure.
    • You can enter any name for the value of the partition property. However, a node will only see timers from other nodes that have the same partition name. Grouping nodes into partitions by assigning partition names enables you to break a large cluster up into several smaller clusters. Doing this improves performance. For example, instead of having a cluster of 100 nodes, where all 100 nodes are trying to execute and refresh the same timers, you can create 20 clusters of 5 nodes by giving every group of 5 a different partition name.
    • Replace the default-data-store attribute value with ejb_timer_ds.
    • Set the value of refresh-interval in milliseconds to specify how often the EJB timer connects to the database to synchronize and load tasks to be processed.

      <timer-service thread-pool-name="default" default-data-store="ejb_timer_ds">
      <data-stores>
          <database-data-store name="ejb_timer_ds" datasource-jndi-name="java:jboss/datasources/ejb_timer" database="postgresql" partition="ejb_timer_part" refresh-interval="30000"/>
      </data-stores>
      </timer-service>

      The following table lists the supported databases and the corresponding database attribute value:

      Table 3.1. Supported databases

      DatabaseAttribute value

      Hyper SQL (for demonstration purposes only, not supported)

      hsql

      PostgreSQL

      postgresql

      Oracle

      oracle

      IBM DB2

      db2

      Microsoft SQL Server

      mssql

      MySQL and MariaDB

      mysql

  4. Add the Process Server and EJB timer data sources to the standalone-full.xml file. In these examples, <DATABASE> is the name of the database, <SERVER_NAME> is the host name of the JNDI database, and <USER_NAME> and <USER_PWD> are the credentials for that database.

    • Add the data source to allow Process Server to connect to the database, for example:

      <xa-datasource jndi-name="java:/jboss/datasources/rhpam" pool-name="rhpam-RHPAM" use-java-context="true" enabled="true">
        <xa-datasource-property name="DatabaseName"><DATABASE></xa-datasource-property>
        <xa-datasource-property name="PortNumber">5432</xa-datasource-property>
        <xa-datasource-property name="ServerName"><SERVER_NAME></xa-datasource-property>
        <driver>postgresql</driver>
        <security>
          <user-name><USER_NAME></user-name>
          <password><USER_PWD></password>
      </security>
      </xa-datasource>
    • Add the data source to enable the EJB timer, for example:

      <xa-datasource jndi-name="java:jboss/datasources/ejb_timer" pool-name="ejb_timer" use-java-context="true" enabled="true">
          <xa-datasource-property name="DatabaseName"><DATABASE></xa-datasource-property>
          <xa-datasource-property name="PortNumber">5432</xa-datasource-property>
          <xa-datasource-property name="ServerName"><SERVER_NAME></xa-datasource-property>
          <driver>postgresql</driver>
          <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
          <security>
              <user-name><USER_NAME></user-name>
              <password><USER_PWD></password>
          </security>
      </xa-datasource>
      Warning

      You must use two different databases for Process Server runtime data and EJB timer data.

  5. Add the following properties to the <system-properties> element and replace the following placeholders:

    • <JNDI_NAME> is the JNDI name of your data source. For Red Hat Process Automation Manager, this is java:/jboss/datasources/rhpam.
    • <DIALECT> is the hibernate dialect for your database.

      The following dialects are supported:

      • DB2: org.hibernate.dialect.DB2Dialect
      • MSSQL: org.hibernate.dialect.SQLServer2012Dialect
      • MySQL: org.hibernate.dialect.MySQL5InnoDBDialect
      • MariaDB: org.hibernate.dialect.MySQL5InnoDBDialect
      • Oracle: org.hibernate.dialect.Oracle10gDialect
      • PostgreSQL: org.hibernate.dialect.PostgreSQL82Dialect
      • PostgreSQL plus: org.hibernate.dialect.PostgresPlusDialect

        <system-properties>
          <property name="org.kie.server.persistence.ds" value="<JNDI_NAME>"/>
          <property name="org.kie.server.persistence.dialect" value="<DIALECT>"/>
          <property name="org.jbpm.ejb.timer.tx" value="true"/>
        </system-properties>
  6. Save the standalone-full.xml file.
  7. To start the cluster, navigate to EAP_HOME/bin and enter one of the following commands:

    • On Linux or UNIX-based systems:

      $ ./standalone.sh -c standalone-full.xml
    • On Windows:

      standalone.bat -c standalone-full.xml

3.3. Clustering Process Servers with the headless Process Automation Manager controller

The Process Automation Manager controller is integrated with Business Central. However, if you do not install Business Central, you can install the headless Process Automation Manager controller and use the REST API or the Process Server Java Client API to interact with it.

Prerequisites

  • A backed-up Red Hat JBoss EAP installation version 7.2 or later is available. The base directory of the Red Hat JBoss EAP installation is referred to as EAP_HOME.
  • Sufficient user permissions to complete the installation are granted.
  • An NFS server with a mounted partition is available as described in Section 2.3, “Configuring an NFS server”.

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.6
  2. Download Red Hat Process Automation Manager 7.6.0 Add Ons (the rhpam-7.6.0-add-ons.zip file).
  3. Unzip the rhpam-7.6.0-add-ons.zip file. The rhpam-7.6.0-controller-ee7.zip file is in the unzipped directory.
  4. Extract the rhpam-7.6.0-controller-ee7 archive to a temporary directory. In the following examples this directory is called TEMP_DIR.
  5. Copy the TEMP_DIR/rhpam-7.6.0-controller-ee7/controller.war directory to EAP_HOME/standalone/deployments/.

    Warning

    Ensure that the names of the headless Process Automation Manager controller deployments you copy do not conflict with your existing deployments in the Red Hat JBoss EAP instance.

  6. Copy the contents of the TEMP_DIR/rhpam-7.6.0-controller-ee7/SecurityPolicy/ directory to EAP_HOME/bin. When asked to overwrite files, select Yes.
  7. In the EAP_HOME/standalone/deployments/ directory, create an empty file named controller.war.dodeploy. This file ensures that the headless Process Automation Manager controller is automatically deployed when the server starts.
  8. Open the EAP_HOME/standalone/configuration/standalone.xml file in a text editor.
  9. Add the following properties to the <system-properties> element and replace <NFS_STORAGE> with the absolute path to the NFS storage where the template configuration is stored:

    <system-properties>
      <property name="org.kie.server.controller.templatefile.watcher.enabled" value="true"/>
      <property name="org.kie.server.controller.templatefile" value="<NFS_STORAGE>"/>
    </system-properties>

    Template files contain default configurations for specific deployment scenarios.

    If the value of the org.kie.server.controller.templatefile.watcher.enabled property is set to true, a separate thread is started to watch for modifications of the template file. The default interval for these checks is 30000 milliseconds and can be further controlled by the org.kie.server.controller.templatefile.watcher.interval system property. If the value of this property is set to false, changes to the template file are detected only when the server restarts.

  10. To start the headless Process Automation Manager controller, navigate to EAP_HOME/bin and enter the following command:

    • On Linux or UNIX-based systems:

      $ ./standalone.sh
    • On Windows:

      standalone.bat

3.4. Clustering Process Servers with Smart Router

You can use Smart Router to aggregate multiple independent Process 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 Process Servers and aggregate data from different Process Servers. Smart Router uses aliases to perform as a proxy. Smart Router performs the following tasks:

  • Collects information from various server instances in a single client request
  • Finds the correct server for a specific request
  • Aggregates responses from different servers
  • Provides efficient load balancing
  • Manages changing environments, for example adding and removing server instances
  • Manages registration with the Process Automation Manager controller

This section describes how to install Smart Router and configure it for a Red Hat Process Automation Manager runtime environment.

Note

Load balancing requests for Smart router cluster must be managed externally, using standard load balancing tools.

Prerequisites

  • Process Server is installed on each node of a Red Hat JBoss EAP 7.2 cluster.

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

    The router is capable of providing an aggregate sort, however the data returned when used through the management console is in raw format. Therefore, sorting is in whatever way individual servers return.

    Paging is supported in its standard format.

  6. Optional: To start Smart Router from the client side, use the Smart Router URL instead of the Process 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.

    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 setting to enable the watcher service system property.

  7. Optional: To start Smart Router with HTTPS enabled, use the TLS keystore properties, for example:

    org.kie.server.router.tls.keystore = <KEYSTORE_PATH>
    org.kie.server.router.tls.keystore.password = <KEYSTORE_PWD>
    org.kie.server.router.tls.keystore.keyalias = <KEYSTORE_ALIAS>
    org.kie.server.router.tls.port = <HTTPS_PORT>
    -jar kie-server-router-proxy-7.10.0-SNAPSHOT.jar

    org.kie.server.router.tls.port is a property used to configure the HTTPS port. The default HTTPS port value is 9443.

Note

You must create the container 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