Search

Chapter 9. Running a Camel service on Spring Boot with XA transactions

download PDF

The Spring Boot Camel XA transactions quickstart demonstrates how to run a Camel Service on Spring-Boot that supports XA transactions on two external transactional resources, a JMS resource (A-MQ) and a database (PostgreSQL). These external resources are provided by OpenShift which must be started before running this quickstart.

9.1. StatefulSet resources

This quickstart uses OpenShift StatefulSet resources to guarantee uniqueness of transaction managers and require a PersistentVolume to store transaction logs. The application supports scaling on the StatefulSet resource. Each instance will have its own in-process recovery manager. A special controller guarantees that when the application is scaled down, all instances, that are terminated, complete all their work correctly without leaving pending transactions. The scale-down operation is rolled back by the controller if the recovery manager is not been able to flush all pending work before terminating. This quickstart uses Spring Boot Narayana recovery controller.

9.2. Spring Boot Narayana recovery controller

The Spring Boot Narayana recovery controller allows to gracefully handle the scaling down phase of a StatefulSet by cleaning pending transactions before termination. If a scaling down operation is executed and the pod is not clean after termination, the previous number of replicas is restored, hence effectively canceling the scaling down operation.

All pods of the StatefulSet require access to a shared volume that is used to store the termination status of each pod belonging to the StatefulSet. The pod-0 of the StatefulSet periodically checks the status and scale the StatefulSet to the right size if there’s a mismatch.

In order for the recovery controller to work, edit permissions on the current namespace are required (role binding is included in the set of resources published to OpenShift). The recovery controller can be disabled using the CLUSTER_RECOVERY_ENABLED environment variable. In this case, no special permissions are required on the service account but any scale down operation may leave pending transactions on the terminated pod without notice.

9.3. Configuring Spring Boot Narayana recovery controller

Following example shows how to configure Narayana to work on OpenShift with the recovery controller.

Procedure

  1. This is a sample application.properties file. Replace the following options in the Kubernetes yaml descriptor.

    # Cluster
    cluster.nodename=1
    cluster.base-dir=./target/tx
    
    # Transaction Data
    spring.jta.transaction-manager-id=${cluster.nodename}
    spring.jta.log-dir=${cluster.base-dir}/store/${cluster.nodename}
    
    # Narayana recovery settings
    snowdrop.narayana.openshift.recovery.enabled=true
    snowdrop.narayana.openshift.recovery.current-pod-name=${cluster.nodename}
    # You must enable resource filtering in order to inject the Maven artifactId
    snowdrop.narayana.openshift.recovery.statefulset=${project.artifactId}
    snowdrop.narayana.openshift.recovery.status-dir=${cluster.base-dir}/status
  2. You need a shared volume to store both transactions and information related to termination. It can be mounted in the StatefulSet yaml descriptor as follows.

    apiVersion: apps/v1beta1
    kind: StatefulSet
    #...
    spec:
    #...
      template:
    #...
        spec:
          containers:
          - env:
            - name: CLUSTER_BASE_DIR
              value: /var/transaction/data
              # Override CLUSTER_NODENAME with Kubernetes Downward API (to use `pod-0`, `pod-1` etc. as tx manager id)
            - name: CLUSTER_NODENAME
              valueFrom:
                fieldRef:
                  apiVersion: v1
                  fieldPath: metadata.name
    #...
            volumeMounts:
            - mountPath: /var/transaction/data
              name: the-name-of-the-shared-volume
    #...

Camel Extension for Spring Boot Narayana Recovery Controller

If Camel is found in the Spring Boot application context, the Camel context is automatically stopped before flushing all pending transactions.

9.4. Running Camel Spring Boot XA quickstart on OpenShift

This procedure shows how to run the quickstart on a running single node OpenShift cluster.

Procedure

  1. Download Camel Spring Boot XA project.

    git clone --branch spring-boot-camel-xa-7.8.0.fuse-sb2-780031-redhat-00001 https://github.com/jboss-fuse/spring-boot-camel-xa
  2. Navigate to spring-boot-camel-xa directory and run following command.

    mvn clean install
  3. Log in to the OpenShift Server.

    oc login -u developer -p developer
  4. Create a new project namespace called test (assuming it does not already exist).

    oc new-project test

    If the test project namespace already exists, switch to it.

    oc project test
  5. Install dependencies.

    • Install postgresql using username as theuser and password as Thepassword1!.

      oc new-app --param=POSTGRESQL_USER=theuser --param=POSTGRESQL_PASSWORD='Thepassword1!' --env=POSTGRESQL_MAX_PREPARED_TRANSACTIONS=100 --template=postgresql-persistent
    • Install the A-MQ broker using username as theuser and password as Thepassword1!.

      oc new-app --param=MQ_USERNAME=theuser --param=MQ_PASSWORD='Thepassword1!' --template=amq63-persistent
  6. Create a persistent volume claim for the transaction log.

    oc create -f persistent-volume-claim.yml
  7. Build and deploy your quickstart.

    mvn fabric8:deploy -P openshift
  8. Scale it up to the desired number of replicas.

    oc scale statefulset spring-boot-camel-xa --replicas 3

    Note: The pod name is used as transaction manager id (spring.jta.transaction-manager-id property). The current implementation also limits the length of transaction manager ids. So please note that:

    • The name of the StatefulSet is an identifier for the transaction system, so it must not be changed.
    • You should name the StatefulSet so that all of its pod names have length lower than or equal to 23 characters. Pod names are created by OpenShift using the convention: <statefulset-name>-0, <statefulset-name>-1 and so on. Narayana does its best to avoid having multiple recovery managers with the same id, so when the pod name is longer than the limit, the last 23 bytes are taken as transaction manager id (after stripping some characters like -).
  9. Once the quickstart is running, get the base service URL using the following command.

    NARAYANA_HOST=$(oc get route spring-boot-camel-xa -o jsonpath={.spec.host})

9.5. Testing successful XA transactions

Following workflow shows how to test the successful XA transactions.

Procedure

  1. Get the list of messages in the audit_log table.

    curl -w "\n" http://$NARAYANA_HOST/api/
  2. The list is empty at the beginning. Now you can put the first element.

    curl -w "\n" -X POST http://$NARAYANA_HOST/api/?entry=hello

    After waiting for some time get the new list.

    curl -w "\n" http://$NARAYANA_HOST/api/
  3. The new list contains two messages, hello and hello-ok. The hello-ok confirms that the message has been sent to a outgoing queue and then logged. You can add multiple messages and see the logs.

9.6. Testing failed XA transactions

Following workflow shows how to test the failed XA transactions.

Procedure

  1. Send a message named fail.

    curl -w "\n" -X POST http://$NARAYANA_HOST/api/?entry=fail
  2. After waiting for some time get the new list.

    curl -w "\n" http://$NARAYANA_HOST/api/
  3. This message produces an exception at the end of the route, so that the transaction is always rolled back. You should not find any trace of the message in the audit_log table.
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.

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.

© 2024 Red Hat, Inc.