Chapter 3. Get Started

3.1. Deployment Considerations for the Decision Server xPaaS Image

3.1.1. Configuring Keystores

The Decision Server image requires two keystores:

  • An SSL keystore to provide private and public keys for https traffic encryption
  • A JGroups keystore to provide private and public keys for network traffic encryption between nodes in the cluster

These keystores are expected by the Decision Server image, even if the application uses only http on a single-node OpenShift instance. Note that self-signed certificates do not provide secure communication and are intended for internal testing purposes.

Warning

For production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS).

See Generate a SSL Encryption Key and Certificate for more information on how to create a keystore with self-signed or purchased SSL certificates.

3.1.2. Generating the Secret

OpenShift uses objects called Secrets to hold sensitive information, such as passwords or keystores. See the Secrets chapter in the OpenShift documentation for more information.

The Decision Server image requires a secret that holds the two keystores described earlier. This provides the necessary authorization to applications in the project.

Use the Java and JGroup keystore files to create a secret for the project: 

$ oc create secret generic <rds-secret-name> --from-file=<jgroups.jceks> --from-file=<keystore.jks>

After the secret has been generated, it can be associated with a service account.

3.1.3. Creating the Service Account

The service account allows users to associate certain secrets and roles with applications in a project namespace. This provides the application with the necessary authorization to run with all required privileges.

  1. Create a service account to be used for the Decision Server deployment: 

    $ oc create serviceaccount <service-account-name>

  2. Add the view role to the service account. This enables the service account to view all the resources in the application namespace in OpenShift, which is necessary for managing the cluster. 

    $ oc policy add-role-to-user view system:serviceaccount:<project-name>:<service-account-name>

  3. Add the secret created for the project to the service account: 

    $ oc secret add sa/<service-account-name> secret/<secret-name>

3.2. Preparing a JBoss BRMS Project Repository for OpenShift

3.2.1. Stateless Sessions

Note

The BRMS project must be configured to be stateless. OpenShift does not support stateful sessions on KIE servers.

A BRMS project running in JBoss BRMS could be configured to be stateless of stateful. A project that has already been deployed on a Decision Server xPaaS image will be configured to be stateless.

Ensuring a BRMS project is stateless:
The Knowledge Session (in the web console, Open Project Editor → Project Settings → Knowledge bases and sessions) displays whether the session is configured to be Stateless.

3.2.2. Configuring the Project Remote Repository

The project must be configured to use a remote repository so that BRMS can push changes and OpenShift can pull the repository to build the application. In the application repository files:

  1. The pom.xml must be configured to use a remote repository so that OpenShift can access it. 

    ...
<distributionManagement>
  <repository>
    <id>deployment</id>
    <name>OpenShift Maven repo</name>
    <url>http://maven.example/deployment/filepath/</url>
  </repository>

  <snapshotRepository>
    <id>deployment</id>
    <name>OpenShift Maven repo</name>
    <url>http://maven.example/snapshots/filepath/</url>
  </snapshotRepository>
</distributionManagement>
...

    For more information, see the Red Hat JBoss BRMS Administration and Configuration Guide.

  2. The configuration/settings.xml file must have the remote repository defined so that OpenShift can download the application artifacts. 

    ...
<profiles>
  <profile>
    <id>openshift-mirror-repositories</id>
    <repositories>
      <repository>
        <id>openshift-mirror</id>
        <url>http://maven.example/public/filepath/</url>
      </repository>
    </repositories>

    <pluginRepositories>
      <pluginRepository>
        <id>openshift-mirror</id>
        <url>http://maven.example/public/filepath/</url>
      </pluginRepository>
    </pluginRepositories>
  </profile>
</profiles>
...

    For more information, see the Red Hat JBoss BRMS Installation Guide.

  3. The hidden .s2i/environment file defines the KIE container deployment, including which KIE jars to use and the location from which to retrieve them. When OpenShift deploys the built image, the pod name is derived from the deployment alias defined in this file: 

    KIE_CONTAINER_DEPLOYMENT=<alias>=<group_id>:<artifact_id>:<version>

    For example: 

    KIE_CONTAINER_DEPLOYMENT=RulesTest=com.example.openshift:example_workflow:1.0
    Note

    Defining the container name here is necessary because the default behavior of the KIE server is to search for the default stateful session and fail if it does not find one.

3.3. Updating Rules

Each image is built from a snapshot of a specific Maven repository. When 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.

Updating the Application
The KIE_CONTAINER_DEVELOPMENT_OVERRIDE variable can be used to explicitly override the KIE_CONTAINER_DEPLOYMENT variable set in the original deployment.
When an application has been modified and is ready to be deployed, include the updated version details for the KIE_CONTAINER_DEPLOYMENT_OVERRIDE variable in the .s2i/environment file. This can then be pushed to your repository to be built as an image.
Alternatively, start a binary build from the local repo:

$ oc start-build <RulesTest> --from-repo=</repository/filepath>

This sends the contents of the Git repository directly to OpenShift. If Incremental Builds has been configured, the new build pulls the image previously used, extracts the Maven repository for the new pod, and downloads the missing content.

3.3.1. Recreate Update Strategy

Use the Recreate Update Strategy for the Decision Server deployment. This update strategy automatically scales down the old deployment to 0 and deploys the new version. After the new version is validated, the new deployment is automatically scaled up to the replica size of the old deployment.

The Recreate update strategy supports Lifecycle Hooks and is set as the default update strategy in the Decision Server application templates.

Note

The Decision Server will be inactive during the Recreate update process, until the new deployment has been validated and scaled. During this period, REST clients may return 503 service unavailable errors and A-MQ clients may experience timeouts.

Important

The Rolling Update Strategy is not supported for the Decision Server xPaaS image. Although multiple concurrent versions of an application are supported in a deployment, a cluster can only support valid routing to pods of the same version.

3.4. Multiple Concurrent Versions

An application may contain multiple concurrent KIE containers of different versions. Each container has a classloader environment and a unique identifier. The unique identifier is one of either a container ID or a deployment ID, which are synonymous.

Multiple versions are deployed using the KIE_CONTAINER_DEPLOYMENT variable, specifying the <alias>=<group_id>:<artifact_id>:<version> for each version of the application, separated by a pipe ( | ) in the .s2i/environment file. For example: 

KIE_CONTAINER_DEPLOYMENT=RulesTest=com.example.openshift:example_workflow:1.0|RulesTest=com.example.openshift:example_workflow:1.1

creates the following: 

KIE_CONTAINER_DEPLOYMENT=RulesTest=com.example.openshift:example_workflow:1.0|RulesTest=com.example.openshift:example_workflow:1.1
KIE_CONTAINER_DEPLOYMENT_ORIGINAL:
KIE_CONTAINER_DEPLOYMENT_OVERRIDE: RulesTest=com.example.openshift:example_workflow:1.0|RulesTest=com.example.openshift:example_workflow:1.1
KIE_CONTAINER_DEPLOYMENT_COUNT: 2
KIE_CONTAINER_ID_0: df729302a0b7293c0729384710dd82a1
KIE_CONTAINER_KJAR_GROUP_ID_0: com.example.openshift
KIE_CONTAINER_KJAR_ARTIFACT_ID_0: example_workflow
KIE_CONTAINER_KJAR_VERSION_0: 1.0
KIE_CONTAINER_ID_1: 01932fc2931b02cb042ab29d9fc82a8a
KIE_CONTAINER_KJAR_GROUP_ID_1: com.example.openshift
KIE_CONTAINER_KJAR_ARTIFACT_ID_1: example_workflow
KIE_CONTAINER_KJAR_VERSION_1: 1.0
KIE_CONTAINER_REDIRECT_ENABLED: true

or, as represented in XML format: 

<kie-server-state>
  <containers>
    <container>
      <containerId>df729302a0b7293c0729384710dd82a1</containerId>
      <releaseId>
        <groupId>com.example.openshift</groupId>
        <artifactId>example_workflow</artifactId>
        <version>1.0</version>
      </releaseId>
      <status>STARTED</status>
      <configItems/>
      <messages/>
    </container>
    <container>
      <containerId>01932fc2931b02cb042ab29d9fc82a8a</containerId>
      <releaseId>
        <groupId>com.example.openshift</groupId>
        <artifactId>example_workflow</artifactId>
        <version>1.1</version>
      </releaseId>
      <status>STARTED</status>
      <configItems/>
      <messages/>
    </container>
  </containers>
</kie-server-state>
Important

To deploy multiple concurrent versions, the KIE_CONTAINER_REDIRECT_ENABLED variable must be set to true. This variable defaults to true and only needs to be explicitly included in the .s2i/environment file if setting to false.

The KIE_CONTAINER_REDIRECT_ENABLED variable enables override of the container ID. When set to true, a unique md5 sum hash is generated from the <alias>=<group_id>:<artifact_id>:<version> for each version of the application. It also enables alias redirection so that client requests using the deployment alias are redirected to the container of the correct version.

If set to false, the deployment alias is used as the container ID and multiple concurrent versions are not possible. If multiple versions of an application are specified for KIE_CONTAINER_DEPLOYMENT, and KIE_CONTAINER_REDIRECT_ENABLED is set to false, only the latest version of the application will be deployed and alias redirection will be disabled.

Changing the KIE_CONTAINER_REDIRECT_ENABLED variable in the .s2i/environment file of a running application generates a new container ID for the running application, which may make it incompatible with any clients using the old container ID.

3.4.1. Container ID

The container ID is an md5 sum hash generated from the <alias>=<group_id>:<artifact_id>:<version> of the application, and is used for client communication. In the case of multiple versions, each version of the application will have a unique container ID, but share the deployment alias name.

3.4.2. Adding, Overriding, or Updating Multiple Versions of the Application

If an application has already been deployed, use the KIE_CONTAINER_DEPLOYMENT_OVERRIDE variable in the .s2i/environment file, and specify the <alias>=<group_id>:<artifact_id>:<version> for each version of the application to override the KIE_CONTAINER_DEPLOYMENT variable in the json application template. This is useful for preserving older versions of an application that are still in use.

For example, The RulesTest application example: 

KIE_CONTAINER_DEPLOYMENT=RulesTest=com.example.openshift:example_workflow:1.0

To maintain this version of the application, but to add an updated version, update the .s2i/environment file: 

KIE_CONTAINER_DEPLOYMENT_OVERRIDE=RulesTest=com.example.openshift:example_workflow:1.0|RulesTest=com.example.openshift:example_workflow:1.1

See Example Workflow: Deploying an Updated Version Concurrently with Original Application for an example on deploying an updated application alongside the older version.

3.4.3. Request Targeting for Multiple Versions

In most cases, clients must target a particular container by name to execute server-side functions. This can be done by specifying the full deployment name, the container ID hash, or the deployment alias.

For example:

  • Full Deployment Name: RulesTest=com.example.openshift:example_workflow:1.0
  • Container ID Hash: df729302a0b7293c0729384710dd82a1
  • Deployment Alias: RulesTest

Specifying either the full deployment name or the container ID targets the appropriate container. Specifying the deployment alias, which is used by all the containers in the KIE server, requires a multi-stage resolution process to target the correct version container.

3.4.4. Alias Redirection

In a multi-version deployment, all applications share the same deployment alias. Requests that use the deployment alias of the application require a resolution process in order to redirect the request to the container of the correct version.

Resolution Process Hierarchy

The multi-stage resolution process depends on the method invoked by the client, and the ID associated with the request:

Process Hierarchy (in descending order):

  1. Conversation ID
  2. Default Container ID

Clients

Multiple clients can be used to invoke the server, depending on the client interaction type:

ClientInteraction

KIE interaction

org.kie.server.client.KieServicesClient

Decision Server interaction

org.kie.server.client.RuleServicesClient

Conversation ID

A conversation represents interactions between KIE Services java clients and the server. When a client initiates a conversation, the response from the server includes an encoded multi-part heading. The client will then use this heading in subsequent requests to the server. This conversation header contains the conversation ID, which is used by the Servlet Filter in the REST interface, or the EJB Interceptor in the JMS interface, to determine the correct version of the application to invoke.

Default Container ID

If a specific container ID cannot be resolved, the default container ID is determined as the application with the latest version (based on <alias>=<group_id>:<artifact_id>:<version>).

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

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

    Note

    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.

3.5.2. 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 3.1. Provided Templates

Template NameSupported Interfaces

decisionserver63-basic-s2i.json

http-rest, jms-hornetq

decisionserver63-https-s2i.json

http-rest, https-rest, jms-hornetq

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

Important

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.

Note

Ensure that you follow the guidelines for creating images.