24.7. Clustered Instances

24.7.1. Launch Clustered JBoss EAP 6 AMIs


This topic covers the steps required to launch clustered JBoss EAP 6 AMIs.


Running a JBoss EAP 6 cluster in a subnet with network mask smaller than 24 bits or spanning multiple subnets complicates acquiring a unique server peer ID for each cluster member.
Refer to the JBOSS_CLUSTER_ID variable for information on how to make such a configuration work reliably: Section 24.10.1, “Permanent Configuration Parameters”.


The auto-scaling Amazon EC2 feature can be used with JBoss EAP 6 cluster nodes. However, ensure it is tested before deployment. You should ensure that your particular workloads scale to the desired number of nodes, and that the performance meets your needs for the instance type you are planning to use (different instance types receive a different share of the EC2 cloud resources).
Furthermore, instance locality and current network/storage/host machine/RDS utilization can affect performance of a cluster. Test with your expected real-life loads and try to account for unexpected conditions.


The Amazon EC2 scale-down action terminates the nodes without any chance to gracefully shut down, and, as some transactions might be interrupted, other cluster nodes (and load balancers) will need time to fail over. This is likely to impact your application users' experience.
It is recommended that you either scale down the application cluster manually by disabling the server from the mod_cluster management interface until processed sessions are completed, or shut down the JBoss EAP 6 instance gracefully (SSH access to the instance or JON can be used).
Test that your chosen procedure for scaling-down does not lead to adverse effects on your users' experience. Additional measures might be required for particular workloads, load balancers and setups.

Procedure 24.12. Launch Clustered JBoss EAP 6 AMIs

  1. Select an AMI.
  2. Define the desired number of instances (the cluster size).
  3. Select the VPC and instance type.
  4. Click on Security Group.
  5. Ensure that all traffic from the JBoss EAP 6 cluster subnet is allowed.
  6. Define other restrictions as desired.
  7. Add the following into the User Data field:

    Example 24.7. Example User Data Field

    ## mod cluster proxy addresses
    ## clustering setup
    JBOSS_JGROUPS_S3_PING_ACCESS_KEY=<your access key>
    JBOSS_JGROUPS_S3_PING_BUCKET=<your bucket name>
    ## password to access admin console
    JBOSSAS_ADMIN_PASSWORD=<your password for opening admin console>
    ## database credentials configuration
    JAVA_OPTS="$JAVA_OPTS -Ddb.host=instancename.something.rds.amazonaws.com -Ddb.database=mydatabase -Ddb.user=<user> -Ddb.passwd=<pass>"
    ## subnet prefix this machine is connected to
    #### to run the example no modifications below should be needed ####
    JBOSS_IP=`hostname | sed -e 's/ip-//' -e 'y/-/./'` #listen on public/private EC2 IP address
    cat > $USER_SCRIPT << "EOF"
    ## Get the application to be deployed from an Internet URL
    # mkdir -p /usr/share/java/jboss-ec2-eap-applications
    # wget https://<your secure storage hostname>/<path>/<app name>.war -O /usr/share/java/jboss-ec2-eap-applications/<app name>.war
    ## install the JDBC driver as a core module
    yum -y install mysql-connector-java
    mkdir -p /usr/share/jbossas/modules/com/mysql/main
    cp -v /usr/share/java/mysql-connector-java-*.jar /usr/share/jbossas/modules/com/mysql/main/mysql-connector-java.jar
    cat > /usr/share/jbossas/modules/com/mysql/main/module.xml <<"EOM"
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
          <resource-root path="mysql-connector-java.jar"/>
          <module name="javax.api"/>
    cat > $USER_CLI_COMMANDS << "EOC" 
    ## Deploy sample application from local filesystem
    deploy --force /usr/share/java/jboss-ec2-eap-samples/cluster-demo.war
    ## ExampleDS configuration for MySQL database
    data-source remove --name=ExampleDS
    data-source add --name=ExampleDS --connection-url="jdbc:mysql://${db.host}:3306/${db.database}" --jndi-name=java:jboss/datasources/ExampleDS --driver-name=mysql --user-name="${db.user}" --password="${db.passwd}"
    ## this will workaround the problem that in a VPC, instance hostnames are not resolvable
    echo -e "\tlocalhost.localdomain localhost" > /etc/hosts
    echo -e "::1\tlocalhost6.localdomain6 localhost6" >> /etc/hosts
    for (( i=1 ; i<255 ; i++ )); do
       echo -e "$SUBNET$i\tip-${SUBNET//./-}$i" ;
    done >> /etc/hosts

The clustered JBoss EAP 6 AMIs have been configured and launched successfully.

24.7.2. Test the Clustered JBoss EAP 6 Instance


This topic covers the steps to confirm that the clustered JBoss EAP 6 instances are running correctly.

Procedure 24.13. Testing the Clustered Instance

  1. Navigate to http://ELASTIC_IP_OF_APACHE_HTTPD in a browser to confirm the web server is running successfully.
  2. Test the Clustered Nodes

    1. Verify that one of the cluster nodes logs the following message:
      Putting date now
    2. Stop the cluster node that logged the message in the previous step.
    3. Verify that the time shown is the same as the time that was PUT using put.jsp in Step 2-a.
    4. Verify that one of the running cluster nodes logs the following message:
      Getting date now
    5. Restart the stopped clustered node.
    6. Connect to the Apache HTTP server instance:
      ssh -L7654:localhost:7654 <ELASTIC_IP_OF_APACHE_HTTPD>
    7. Navigate to http://localhost:7654/mod_cluster-manager to confirm all instances are running correctly.

The clustered JBoss EAP 6 instances have been tested, and confirmed to be working correctly.