Chapter 6. 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=ApplicationTest=com.example.openshift:example_workflow:1.0|ApplicationTest=com.example.openshift:example_workflow:1.1

would create the following:

KIE_CONTAINER_DEPLOYMENT=ApplicationTest=com.example.openshift:example_workflow:1.0|ApplicationTest=com.example.openshift:example_workflow:1.1
KIE_CONTAINER_DEPLOYMENT_ORIGINAL:
KIE_CONTAINER_DEPLOYMENT_OVERRIDE: ApplicationTest=com.example.openshift:example_workflow:1.0|ApplicationTest=com.example.openshift:example_workflow:1.1
KIE_CONTAINER_DEPLOYMENT_COUNT: 2
KIE_CONTAINER_ID_0: be690712c7a5808a0696926088ff18b2
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: 72978ef7154f52df289ef01cbdb51c4d
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>be690712c7a5808a0696926088ff18b2</containerId>
      <releaseId>
        <groupId>com.example.openshift</groupId>
        <artifactId>example_workflow</artifactId>
        <version>1.0</version>
      </releaseId>
      <status>STARTED</status>
      <configItems/>
      <messages/>
    </container>
    <container>
      <containerId>72978ef7154f52df289ef01cbdb51c4d</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.

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

6.2. Adding, Overriding, or Updating Multiple Versions

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 ApplicationTest application example:

KIE_CONTAINER_DEPLOYMENT=ApplicationTest=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=ApplicationTest=com.example.openshift:example_workflow:1.0|ApplicationTest=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.

6.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: ApplicationTest=com.example.openshift:example_workflow:1.0
  • Container ID Hash: be690712c7a5808a0696926088ff18b2
  • Deployment Alias: ApplicationTest

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.

6.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. Process Instance ID (specific to IPS/BPM)
  2. Correlation Key (specific to IPS/BPM)
  3. Task Instance ID (specific to IPS/BPM)
  4. Work Item ID (specific to IPS/BPM)
  5. Job Request ID (specific to IPS/BPM)
  6. Conversation ID
  7. 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

Intelligent Process Server interaction

org.kie.server.client.ProcessServicesClient
org.kie.server.client.JobServicesClient
org.kie.server.client.QueryServicesClient
org.kie.server.client.UserTaskServicesClient

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.

Warning

Due to a bug in the KIE client, client classes do not share the conversation ID for all services and therefore, users will be unable to complete the conversation. This issue is fixed in BPM Suite 6.3.1 or higher. It is recommended that you use this version of BPM Suite in your BOM file, as shown here:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.jboss.bom.brms</groupId>
        <artifactId>jboss-brms-bpmsuite-platform-bom</artifactId>
          <version>6.3.1.GA-redhat-2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Default Container ID

The final stage in the process hierarchy is the 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>).