ha-singleton-deployment: Deploying Cluster-wide Singleton Services Using Singleton Deployments

The ha-singleton-deployment quickstart demonstrates the recommended way to deploy any service packaged in an application archive as a cluster-wide singleton.

What is it?

The ha-singleton-deployment quickstart demonstrates the deployment of a service packaged in an application as a cluster-wide singleton using singleton deployments. In this example, the service is a timer that is initialized by a @Startup @Singleton Jakarta Enterprise Beans bean. The example is built and packaged as a single web archive.

For more information about singleton deployments, see HA Singleton Deployments in the Development Guide for Red Hat JBoss Enterprise Application Platform located on the Red Hat Customer Portal.

Browse the source

System Requirements

The application this project produces is designed to be run on WildFly Application Server 33 or later.

All you need to build this project is Java 11.0 (Java SDK 11) or later and Maven 3.6.0 or later. See Configure Maven to Build and Deploy the Quickstarts to make sure you are configured correctly for testing the quickstarts.

Use of the WILDFLY_HOME_1, WILDFLY_HOME_2, and QUICKSTART_HOME Variables

This quickstart requires that you clone your WILDFLY_HOME installation directory and run two servers. The installation path is described in detail here: Use of WILDFLY_HOME and JBOSS_HOME Variables.

In the following instructions, replace WILDFLY_HOME_1 with the path to your first WildFly server and replace WILDFLY_HOME_2 with the path to your second cloned WildFly server.

When you see the replaceable variable QUICKSTART_HOME, replace it with the path to the root directory of all of the quickstarts.

Setting Up the Test Environment

To demonstrate the singleton behavior, at least two application server instances must be started. Begin by making a copy of the entire WildFly directory to be used as second cluster member. Note that the example can be run on a single node as well, but without observation of the singleton properties.

Start the two WildFly servers with the same HA profile using the following commands. Note that a socket binding port offset and a unique node name must be passed to the second server if the servers are binding to the same host.

$ WILDFLY_HOME_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1
$ WILDFLY_HOME_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100

Note	For Windows, use the `WILDFLY_HOME_1\bin\standalone.bat` and `WILDFLY_HOME_2\bin\standalone.bat` scripts.

This example is not limited to two servers. Additional servers can be started by specifying a unique port offset for each one.

Running the Quickstart

Start the WildFly servers as described in the above section.
Navigate to the root directory of this quickstart in the terminal.
Use the following command to clean up previously built artifacts, and build and deploy the EJB archive:
```
$ mvn clean install wildfly:deploy
```

Ensure the target/ha-singleton-deployment.war archive is deployed to node1 (the one without port offset) by observing the log.

INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.war" (runtime-name: "ha-singleton-deployment.war")
...
INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node1 elected as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.war".FIRST_MODULE_USE service
INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.war".FIRST_MODULE_USE service
INFO [org.jboss.as.server] (management-handler-thread - 4) WFLYSRV0010: Deployed "ha-singleton-deployment.war" (runtime-name : "ha-singleton-deployment.war")
...
WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 68) SingletonTimer is initializing.
INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World!

The following warnings might appear in the server output after the applications are deployed. These warnings can be safely ignored in a development environment.

WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)

Use the following command to deploy the already built archive to the second server. Note that since the default socket binding port is 9990 and the second server has ports offsetted by 100, the sum, 10090 must be passed as an argument to the deploy maven goal.
```
mvn wildfly:deploy -Dwildfly.port=10090
```

Ensure the service/target/ha-singleton-deployment.war archive is deployed to node2 by observing the log. Note that even though the logs indicate "Deployed", the deployment does not actually deploy completely and the timer is not operating on this node.

INFO  [org.jboss.as.server.deployment] (MSC service thread 1-6) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.war" (runtime-name: "ha-singleton-deployment.war")
INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000078: Starting JGroups channel server
...
INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2]
...
INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000079: Channel server local address is node2, physical addresses are [127.0.0.1:55300]
INFO  [org.infinispan.factories.GlobalComponentRegistry] (MSC service thread 1-6) ISPN000128: Infinispan version: Infinispan 'Chakra' 8.2.7.Final
INFO  [org.jboss.as.clustering.infinispan] (ServerService Thread Pool -- 68) WFLYCLINF0002: Started default cache from server container
INFO  [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "ha-singleton-deployment.war" (runtime-name : "ha-singleton-deployment.war")

Verify the timer is running only on one instance by observing the logs. The node running the timer will output the following every 5 seconds:

INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World!

While the instance not running, the timer will display the following as the last log line:

INFO  [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "ha-singleton-deployment.war" (runtime-name : "ha-singleton-deployment.war")

Verify failover of the singleton deployment. Shutdown the server operating as the primary provider of the singleton, for instance by using the Ctrl + C key combination in the terminal. Observe the following messages on the node being shutdown:

INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 3) SingletonTimer: Hello World!
INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 4) SingletonTimer: Hello World!
INFO  [org.jboss.as.server] (Thread-2) WFLYSRV0220: Server shutdown has been requested via an OS signal
WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 31) SingletonTimer is stopping: the server is either being shutdown or another node has become elected to be the primary provider of the singleton.
...
INFO  [org.jboss.as] (MSC service thread 1-6) WFLYSRV0050: WildFly Core 3.0.0.Final stopped in 88ms

Now observe the log messages on the second server. The node will now be elected as the primary provider of the singleton, deployment will complete, and the timer will start operating:

INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.war".FIRST_MODULE_USE service
INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.war".FIRST_MODULE_USE service
INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-4) ISPN000094: Received new cluster view for channel server: [node2|2] (1) [node2]
...
WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 68) SingletonTimer is initializing.
INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World!
INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 2) SingletonTimer: Hello World!

Determining the primary provider of Singleton deployment using CLI

The JBoss CLI tool can be used to determine the primary provider and the complete list of providers of any singleton service. This is generally useful for operations team or tooling.

Once the server is running and the application is deployed, the server exposes runtime resources corresponding to the deployment. Note the include-runtime flag on the read-resource operation.

[standalone@localhost:9990 /] /subsystem=singleton/singleton-policy=default/deployment=ha-singleton-deployment.war:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "is-primary" => true,
        "primary-provider" => "node1",
        "providers" => [
            "node1",
            "node2"
        ]
    }
}

The typical use case for scripting to determine the primary provider of a service and potentially act upon it, is to run the jboss-cli with a given operation and receive a JSON formatted output as shown here:

[rhusar@ribera bin]$ ./jboss-cli.sh --output-json --connect "/subsystem=singleton/singleton-policy=default/deployment=ha-singleton-deployment.war:read-attribute(name=primary-provider)"
{
    "outcome" : "success",
    "result" : "node1"
}

Note that the include-runtime flag is not required when a specific attribute is queried. Please refer to the documentation for more information on using the CLI.

Troubleshooting

Should the singleton be running on multiple nodes, the most common causes are accidentally starting with the standalone.xml or standalone-full.xml profile instead of with the standalone-ha.xml or standalone-full-ha.xml profile. Make sure to start the server with an HA profile using -c standalone-ha.xml.

Another common cause is that the server instances did not discover each other and each server is operating as a singleton cluster. Ensure that multicast is enabled or change the jgroups subsystem configuration to use a different discovery mechanism. Observe the following log line to ensure that the discovery was successful:

INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2]

Making Existing Deployments Singleton

In this quickstart, the deployment is made singleton by a configuration file bundled in the archive. Inspect the content in src/main/resources/META-INF/singleton-deployment.xml. Any existing deployment can be made singleton by using deployment overlays mechanism. To demonstrate how to use deployment overlays, follow these steps:

Move the src/main/resources/META-INF/singleton-deployment.xml file into root directory of this quickstart.
Rebuild the project. Ensure that the servers are started, and redeploy the application, which will no longer be configured by singleton deployment by the archive:
```
$ mvn clean install
$ mvn wildfly:deploy
$ mvn wildfly:deploy -Dwildfly.port=10090
```

Start the management CLI and set up a deployment overlay on both servers. Make sure you use the port offset for the second server.

$ WILDFLY_HOME_1/bin/jboss-cli.sh --connect
deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.war --content=META-INF/singleton-deployment.xml=singleton-deployment.xml
deployment-overlay redeploy-affected --name=singleton-deployment
$ WILDFLY_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.war --content=META-INF/singleton-deployment.xml=singleton-deployment.xml deployment-overlay redeploy-affected --name=singleton-deployment

Note	For Windows, use the ` WILDFLY_HOME_1\bin\jboss-cli.bat` and ` WILDFLY_HOME_2\bin\jboss-cli.bat` scripts.

Review the deployment overlay changes in the standalone-ha.xml server profile:

<deployment-overlays>
    <deployment-overlay name="singleton-deployment">
        <content path="META-INF/singleton-deployment.xml" content="60a35e2bb6a1886f0a4abe499c7af16833d2a533"/>
        <deployment name="ha-singleton-deployment.war"/>
    </deployment-overlay>
</deployment-overlays>

Observe the server output. The deployments are now set up as singleton deployments.

To remove the deployment overlay run the following CLI command:

deployment-overlay remove --name=singleton-deployment
deployment-overlay redeploy-affected --name=singleton-deployment

For convenience, the management CLI scripts to add the deployment overlay, singleton-deployment-overlay-add.cli, and to remove the deployment overlay, singleton-deployment-overlay-remove.cli, are located in the root directory of this quickstart.

Undeploy the Archives

Ensure all WildFly servers are started.
Navigate to the root directory of this quickstart in the terminal.

Use the following commands to undeploy the artifacts:

$ mvn wildfly:undeploy
$ mvn wildfly:undeploy -Dwildfly.port=10090

Debug the Application

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

$ mvn dependency:sources

WildFly for OpenShift Incompatibility

This quickstart is not compatible with WildFly for OpenShift.