Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 7. Advanced Tutorials

Important

This feature is provided as Technology Preview only. It is not supported for use in a production environment, and it might be subject to significant future changes. See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

Note

This tutorial is applicable only for OpenShift 3 and for recovering transactions without the use of the EAP operator.

This tutorial demonstrates the automated transaction recovery feature of the JBoss EAP for OpenShift image when scaling down a cluster. This tutorial uses the jta-crash-rec-eap quickstart example and the eap73-tx-recovery-s2i application template to show how XA transactions issued on the OpenShift pod, when terminated within the cluster’s scale down, are recovered by the dedicated migration pod. The equivalent application template for the JDK 11 image is eap73-openjdk11-tx-recovery-s2i.

This tutorial uses the amq-broker-72-openshift:1.1 imagestream to provide a message broker that is JMS-compliant. After you have set up the initial broker pod, you can quickly deploy the quickstart by using OpenShift Container Platform features.

Note

As a prerequisite to using the quickstarts, you must create an imagestream from the AMQ Long Term Support (LTS) image and name the imagestream amq-broker-72-openshift:1.1. You can access the LTS Image by downloading the amq7/amq-broker-lts-rhel7:7.4 container image from the Red Hat Ecosystem Catalog. For more information about installing the AMQ Broker, see Deploying a basic broker.

Note

The jta-crash-rec-eap7 quickstart uses the H2 database that is included with JBoss EAP. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should not be used in a production environment.

Additional resources

  • See Deploying a basic broker in the Deploying AMQ Broker on OpenShift Container Platform guide for information about creating a basic AMQ Broker.

7.1.1. Prepare for Deployment
Copy link

  1. Log in to your OpenShift instance using the oc login command.

  2. Create a new project. 

    $ oc new-project eap-tx-demo
    Copy to Clipboard Toggle word wrap

  3. Add the view role to the default service account, which will be used to run the underlying pods. This enables the service account to view all the resources in the eap-tx-demo namespace, which is necessary for managing the cluster. 

    $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
    Copy to Clipboard Toggle word wrap

  4. For automated transaction recovery to work, the JBoss EAP application must use a ReadWriteMany persistent volume.

    Provision the persistent volume expected by the eap73-tx-recovery-s2i application template to hold the data for the ${APPLICATION_NAME}-eap-claim persistent volume claim.

    This example uses a persistent volume object provisioned using the NFS method with the following definition: 

    $ cat txpv.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: txpv
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  nfs:
    path: /mnt/mountpoint
    server: 192.168.100.175
    Copy to Clipboard Toggle word wrap

  5. Update the path and server fields in the above definition for your environment, and provision the persistent volume with the following command: 

    $ oc create -f txpv.yaml
persistentvolume "txpv" created
    Copy to Clipboard Toggle word wrap 
    $ oc get pv
NAME      CAPACITY   ACCESSMODES   RECLAIMPOLICY   STATUS      CLAIM     STORAGECLASS   REASON    AGE
txpv      1Gi        RWX           Retain         Available                                      26s
    Copy to Clipboard Toggle word wrap
    Important

    When using the NFS method to provision persistent volume objects for the eap73-tx-recovery-s2i application template, ensure the mount point is exported with sufficient permissions. On the host from which the mount point is exported, perform the following: 

    # chmod -R 777 /mnt/mountpoint
    Copy to Clipboard Toggle word wrap 
    # cat /etc/exports
/mnt/mountpoint *(rw,sync,anonuid=185,anongid=185)
    Copy to Clipboard Toggle word wrap 
    # exportfs -va
exporting *:/mnt/mountpoint
    Copy to Clipboard Toggle word wrap 
    # setsebool -P virt_use_nfs 1
    Copy to Clipboard Toggle word wrap

    Replace /mnt/mountpoint path above as appropriate for your environment.

7.1.2. Deployment
Copy link

  1. Deploy the jta-crash-rec-eap7 quickstart using the eap73-tx-recovery-s2i application template. Specify the following:

    Example: eap73-tx-recovery-s2i application template (JDK 8)

    $ oc new-app --template=eap73-tx-recovery-s2i \
--name=eap-app
    Copy to Clipboard Toggle word wrap

    Example: eap73-openjdk11-tx-recovery-s2i application template (JDK 11)

    $ oc new-app --template=eap73-openjdk11-tx-recovery-s2i \
--name=eap-app
    Copy to Clipboard Toggle word wrap

  2. Wait for the build to finish. You can see the status of the build using the oc logs -f bc/eap-app command.

  3. Modify the eap-app deployment configuration with the definition of JAVA_OPTS_APPEND and JBOSS_MODULES_SYSTEM_PKGS_APPEND environment variables. 

    $ oc get dc
NAME                REVISION   DESIRED   CURRENT   TRIGGERED BY
eap-app             1          1         1         config,image(eap-app:latest)
eap-app-amq         1          1         1     config,image(amq-broker-72-openshift:1.1)
eap-app-migration   1          1         1         config,image(eap-app:latest)
    Copy to Clipboard Toggle word wrap 
    $ oc set env dc/eap-app \
-e JBOSS_MODULES_SYSTEM_PKGS_APPEND="org.jboss.byteman" \
-e JAVA_OPTS_APPEND="-javaagent:/tmp/src/extensions/byteman/byteman.jar=script:/tmp/src/src/main/scripts/xa.btm"
deploymentconfig "eap-app" updated
    Copy to Clipboard Toggle word wrap

    This setting will notify the Byteman tracing and monitoring tool to modify the XA transactions processing in the following way:

    • The first transaction is always allowed to succeed.
    • When an XA resource executes phase 2 of the second transaction, the JVM process of the particular pod is halted.

7.1.3. Using the JTA Crash Recovery Application
Copy link

  1. List running pods in the current namespace: 

    $ oc get pods | grep Running
NAME                        READY     STATUS      RESTARTS   AGE
eap-app-2-r00gm             1/1       Running     0          1m
eap-app-amq-1-mws7x         1/1       Running     0          2m
eap-app-migration-1-lvfdt   1/1       Running     0          2m
    Copy to Clipboard Toggle word wrap

  2. Issue a new XA transaction.

    1. Launch the application by opening a browser and navigating to http://eap-app-eap-tx-demo.openshift.example.com/jboss-jta-crash-rec.
    2. Enter Mercedes into the Key field, and Benz into the Value field. Click the Submit button.
    3. Wait for a moment, then click the Refresh Table link.

    4. Notice how the table row containing the Mercedes entry is updated with updated via JMS. If it has not yet updated, click the Refresh Table link couple of times. Alternatively, you can inspect the log of the eap-app-2-r00gm pod to verify the transaction was handled properly: 

      $ oc logs eap-app-2-r00gm | grep 'updated'
INFO  [org.jboss.as.quickstarts.xa.DbUpdaterMDB] (Thread-0 (ActiveMQ-client-global-threads-1566836606)) JTA Crash Record Quickstart: key value pair updated via JMS.
      Copy to Clipboard Toggle word wrap

  3. Issue a second XA transaction using your browser at http://eap-app-eap-tx-demo.openshift.example.com/jboss-jta-crash-rec.

    1. Enter Land into the Key field, and Rover into the Value field. Click the Submit button.
    2. Wait for a moment, then click the Refresh Table link.
    3. Notice how the Land Rover entry was added without the updated via …​ suffix.

  4. Scale the cluster down. 

    $ oc scale --replicas=0 dc/eap-app
deploymentconfig "eap-app" scaled
    Copy to Clipboard Toggle word wrap

    1. Notice how the eap-app-2-r00gm pod was scheduled for termination. 

      $ oc get pods
NAME                        READY     STATUS        RESTARTS   AGE
eap-app-1-build             0/1       Completed     0          4m
eap-app-2-r00gm             1/1       Terminating   0          2m
eap-app-amq-1-mws7x         1/1       Running       0          3m
eap-app-migration-1-lvfdt   1/1       Running       0          3m
      Copy to Clipboard Toggle word wrap

  5. Watch the log of the migration pod and notice how transaction recovery is performed. Wait for the recovery to finish: 

    $ oc logs -f eap-app-migration-1-lvfdt
Finished Migration Check cycle, pausing for 30 seconds before resuming
...
Finished, recovery terminated successfully
Migration terminated with status 0 (T)
Releasing lock: (/opt/eap/standalone/partitioned_data/split-1)
Finished Migration Check cycle, pausing for 30 seconds before resuming
...
    Copy to Clipboard Toggle word wrap

  6. Scale the cluster back up. 

    $ oc scale --replicas=1 dc/eap-app
deploymentconfig "eap-app" scaled
    Copy to Clipboard Toggle word wrap
  7. Using the browser navigate back to http://eap-app-eap-tx-demo.openshift.example.com/jboss-jta-crash-rec.

  8. Notice the table contains entries for both transactions. It looks similar to the following output:

    Expand
    Table 7.1. Example: Database Table Contents
    Database Table Contents 

    Key

    Value

    Mercedes

    Benz updated via JMS.

    Land

    Rover updated via JMS.

    The content in the above table indicates that, although the cluster was scaled down before the second XA transaction had chance to finish, the migration pod performed the transaction recovery and the transaction was successfully completed.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

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

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.

Theme

© 2026 Red HatBack to top