Overview

Decision Server is available as a containerized xPaaS image that is designed for use with OpenShift as an execution environment for business rules. Developers can quickly build, scale, and test applications deployed across hybrid environments.

There are significant differences in supported configurations and functionality in the Decision Server xPaaS image compared to the regular release of JBoss BRMS.

This topic details the differences between the Decision Server xPaaS image and the full, non-PaaS release of JBoss BRMS, and provides instructions specific to running and configuring the Decision Server xPaaS image. Documentation for other JBoss BRMS functionality not specific to the Decision Server xPaaS image can be found in the JBoss BRMS documentation on the Red Hat Customer Portal.

EAP_HOME in this documentation, as in the JBoss BRMS documentation, is used to refer to the JBoss EAP installation directory where the decision server is deployed. The location of EAP_HOME inside a Decision Server xPaaS image is /opt/eap/, which the JBOSS_HOME environment variable is also set to by default.

Comparing the Decision Server xPaaS Image to the Regular Release of JBoss BRMS

Functionality Differences for OpenShift Decision Server xPaaS Images

There are several major functionality differences in the OpenShift Decision Server xPaaS image:

  • The Decision Server image extends the OpenShift EAP image, and any capabilities or limitations it has are also found in the Decision Server image.

  • Only stateless scenarios are supported.

  • Authoring of any content through the BRMS Console or API is not supported.

Managing OpenShift Decision Server xPaaS Images

As the Decision Server image is built off the OpenShift JBoss EAP xPaaS image, the JBoss EAP Management CLI is accessible from within the container for troubleshooting purposes.

  1. First open a remote shell session to the running pod:

    $ oc rsh <pod_name>
  2. Then run the following from the remote shell session to launch the JBoss EAP Management CLI:

    $ /opt/eap/bin/jboss-cli.sh
Any configuration changes made using the JBoss EAP Management CLI on a running container will be lost when the container restarts.

Making configuration changes to the JBoss EAP instance inside the JBoss EAP xPaaS image is different from the process you may be used to for a regular release of JBoss EAP.

Security in the OpenShift Decision Server xPaaS Image

Access is limited to users with the kie-server authorization role. A user with this role can be specified via the KIE_SERVER_USER and KIE_SERVER_PASSWORD environment variables.

The HTTP/REST endpoint is configured to only allow the execution of KIE containers and querying of KIE Server resources. Administrative functions like creating or disposing Containers, updating ReleaseIds or Scanners, etc. are restricted. The JMS endpoint currently does not support these restrictions. In the future, more fine-grained security configuration should be available for both endpoints.

Using the Decision Server xPaaS Image Streams and Application Templates

The Red Hat xPaaS middleware images were automatically created during the installation of OpenShift along with the other default image streams and templates.

Running and Configuring the Decision Server xPaaS Image

You can make changes to the Decision Server configuration in the xPaaS image using either the S2I templates, or by using a modified Decision Server image.

Using the Decision Server xPaaS Image Source-to-Image (S2I) Process

The recommended method to run and configure the OpenShift Decision Server xPaaS image is to use the OpenShift S2I process together with the application template parameters and environment variables.

The S2I process for the Decision Server xPaaS image works as follows:

  1. If there is a pom.xml file in the source repository, a Maven build is triggered with the contents of $MAVEN_ARGS environment variable.

    • By default, the package goal is used with the openshift profile, including the system properties for skipping tests (-DskipTests) and enabling the Red Hat GA repository (-Dcom.redhat.xpaas.repo.redhatga).

  2. The results of a successful Maven build are installed into the local Maven repository, /home/jboss/.m2/repository/, along with all dependencies for offline usage. The Decision Server xPaaS Image will load the created kjars from this local repository.

    • In addition to kjars resulting from the Maven build, any kjars found in the deployments source directory will also be installed into the local Maven repository. Kjars do not end up in the EAP_HOME/standalone/deployments/ directory.

  3. Any JAR (that is not a kjar) , WAR, and EAR in the deployments source repository directory will be copied to the EAP_HOME/standalone/deployments directory and subsequently deployed using the JBoss EAP deployment scanner.

  4. All files in the configuration source repository directory are copied to EAP_HOME/standalone/configuration.

    If you want to use a custom JBoss EAP configuration file, it should be named standalone-openshift.xml.
  5. All files in the modules source repository directory are copied to EAP_HOME/modules.

Using a Modified Decision Server xPaaS Image

An alternative method is to make changes to the image, and then use that modified image in OpenShift. The templates currently provided, along with the interfaces they support, are listed below:

Table 1. Provided Templates
Template Name Supported Interfaces

decisionserver62-basic-s2i.json

http-rest, jms-hornetq

decisionserver62-https-s2i.json

http-rest, https-rest, jms-hornetq

decisionserver62-amq-s2i.json

http-rest, https-rest, jms-activemq

You can run the Decision Server xPaaS image in Docker, make the required configuration changes using the JBoss EAP Management CLI (EAP_HOME/bin/jboss-cli.sh) included in the Decision Server xPaaS image, and then commit the changed container as a new image. You can then use that modified image in OpenShift.

It is recommended that you do not replace the OpenShift placeholders in the JBoss EAP xPaaS configuration file, as they are used to automatically configure services (such as messaging, datastores, HTTPS) during a container’s deployment. These configuration values are intended to be set using environment variables.
Ensure that you follow the guidelines for creating images.

Updating Rules

As each image is built from a snapshot of a specific Maven repository, whenever a new rule is added, or an existing rule modified, a new image must be created and deployed for the rule modifications to take effect.

Endpoints

Clients can access the Decision Server xPaaS Image via multiple endpoints; by default the provided templates include support for REST, HornetQ, and ActiveMQ.

REST

Clients can use the REST API in various ways:

Java

// HelloRulesClient.java
KieServicesConfiguration config = KieServicesFactory.newRestConfiguration(
  "http://host/kie-server/services/rest/server", "kieserverUser", "kieserverPassword");
config.setMarshallingFormat(MarshallingFormat.XSTREAM);
RuleServicesClient client =
  KieServicesFactory.newKieServicesClient(config).getServicesClient(RuleServicesClient.class);
ServiceResponse<String> response = client.executeCommands("HelloRulesContainer", myCommands);

Command Line

# request.sh
#!/bin/sh
curl -X POST \
  -d @request.xml \
  -H "Accept:application/xml" \
  -H "X-KIE-ContentType:XSTREAM" \
  -H "Content-Type:application/xml" \
  -H "Authorization:Basic a2llc2VydmVyOmtpZXNlcnZlcjEh" \
  -H "X-KIE-ClassType:org.drools.core.command.runtime.BatchExecutionCommandImpl" \
http://host/kie-server/services/rest/server/containers/instances/HelloRulesContainer
<!-- request.xml -->
<batch-execution lookup="HelloRulesSession">
  <insert>
    <org.openshift.quickstarts.decisionserver.hellorules.Person>
      <name>errantepiphany</name>
    </org.openshift.quickstarts.decisionserver.hellorules.Person>
  </insert>
  <fire-all-rules/>
  <query out-identifier="greetings" name="get greeting"/>
</batch-execution>

JMS

Client can also use the Java Messaging Service, as demonstrated below:

Java (HornetQ)

// HelloRulesClient.java
Properties props = new Properties();
props.setProperty(Context.INITIAL_CONTEXT_FACTORY,
  "org.jboss.naming.remote.client.InitialContextFactory");
props.setProperty(Context.PROVIDER_URL, "remote://host:4447");
props.setProperty(Context.SECURITY_PRINCIPAL, "kieserverUser");
props.setProperty(Context.SECURITY_CREDENTIALS, "kieserverPassword");
InitialContext context = new InitialContext(props);
KieServicesConfiguration config =
  KieServicesFactory.newJMSConfiguration(context, "hornetqUser", "hornetqPassword");
config.setMarshallingFormat(MarshallingFormat.XSTREAM);
RuleServicesClient client =
  KieServicesFactory.newKieServicesClient(config).getServicesClient(RuleServicesClient.class);
ServiceResponse<String> response = client.executeCommands("HelloRulesContainer", myCommands);

Java (ActiveMQ)

// HelloRulesClient.java
props.setProperty(Context.INITIAL_CONTEXT_FACTORY,
  "org.apache.activemq.jndi.ActiveMQInitialContextFactory");
props.setProperty(Context.PROVIDER_URL, "tcp://host:61616");
props.setProperty(Context.SECURITY_PRINCIPAL, "kieserverUser");
props.setProperty(Context.SECURITY_CREDENTIALS, "kieserverPassword");
InitialContext context = new InitialContext(props);
ConnectionFactory connectionFactory = (ConnectionFactory)context.lookup("ConnectionFactory");
Queue requestQueue = (Queue)context.lookup("dynamicQueues/queue/KIE.SERVER.REQUEST");
Queue responseQueue = (Queue)context.lookup("dynamicQueues/queue/KIE.SERVER.RESPONSE");
KieServicesConfiguration config = KieServicesFactory.newJMSConfiguration(
  connectionFactory, requestQueue, responseQueue, "activemqUser", "activemqPassword");
config.setMarshallingFormat(MarshallingFormat.XSTREAM);
RuleServicesClient client =
  KieServicesFactory.newKieServicesClient(config).getServicesClient(RuleServicesClient.class);
ServiceResponse<String> response = client.executeCommands("HelloRulesContainer", myCommands);

Troubleshooting

In addition to viewing the OpenShift logs, you can troubleshoot a running Decision Server xPaaS Image container by viewing its logs. These are outputted to the container’s standard out, and are accessible with the following command:

$ oc logs -f <pod_name> <container_name>
By default, the OpenShift Decision Server xPaaS image does not have a file log handler configured. Logs are only sent to the container’s standard out.