Chapter 5. Launching Clustered JBoss EAP

5.1. Launch Clustered JBoss EAP AMIs (without mod_cluster and VPC)

This topic lists the steps to launch clustered JBoss EAP AMIs without mod_cluster and VPC.

Note
  • You can use the example configuration scripts that are provided with the image.

See System Paths for more details about system paths.

See Configuring JBoss EAP Subsystems to Work on Cloud Platforms for information about configuring JBoss EAP subsystems for Amazon EC2.

To start clustered JBoss EAP AMI on a standalone server instance, you can use the example /opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs/standalone-ec2-ha.xml file that contains a preconfigured S3_PING JGroups stack. For more information, see S3_PING in the Reliable group communication with JGroups document. This standalone-ec2-ha.xml profile file must be copied from /opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs/ to the JBoss EAP configuration directory /opt/rh/eap7/root/usr/share/wildfly/standalone/configuration/. Then, you have to add the following line to the JBoss EAP service configuration file: 

WILDFLY_SERVER_CONFIG=standalone-ec2-ha.xml

A unique instance-id needs to be set for each standalone server instance in the undertow subsystem. A value for the instance-id can be set manually by editing the standalone-ec2-ha.xml file or by using the management CLI. For example, you can set the instance-id using the management CLI as follows: 

/subsystem=undertow:write-attribute(name=instance-id,value={${jboss.jvmRoute}})

A value for jboss.jvmRoute can then be specified in standalone.conf using the JAVA_OPTS variable.

The jgroups subsystem in the EC2 configuration file requires some S3_PING specific properties to discover cluster members. You must specify access key to S3, secret access key, and the S3 bucket to use for discovery. These properties can either be specified as Java options or put directly into the XML file by editing it or using CLI.

You need to create an S3 bucket for discovery. See Amazon Simple Storage Service Documentation for more information. You may also have to configure the required permissions. The JGroups stack needs to be bound to an IP address, which is used to communicate with other nodes. This can be done by adding Java options, along with S3 Java options to the /opt/rh/eap7/root/usr/share/wildfly/bin/standalone.conf file. For example, if the private IP address was 10.10.10.10, then you would add the following line to the standalone.conf file: 

JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address.private=10.10.10.10"

You can deploy a sample application: /opt/rh/eap7/root/usr/share/java/eap7-jboss-ec2-eap-samples/cluster-demo.war and observe the logs in /opt/rh/eap7/root/usr/share/wildfly/standalone/log/server.log to see that the JBoss EAP servers have created a cluster.

For Domain Controller Instance

  1. Copy the domain-ec2.xml file from /opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs to the JBoss EAP configuration directory.

  2. Set the following variables in the appropriate service configuration file: 

    WILDFLY_SERVER_CONFIG=domain-ec2.xml
WILDFLY_HOST_CONFIG=host-master.xml

  3. Add S3 domain controller discovery configuration to the host-master.xml file: 

    <local>
    <discovery-options>
        <discovery-option name="s3-discovery" module="org.jboss.as.host-controller" code="org.jboss.as.host.controller.discovery.S3Discovery">
            <property name="access-key" value="S3_ACCESS_KEY"/>
            <property name="secret-access-key" value="S3_SECRET_ACCESS_KEY"/>
            <property name="location" value="S3_BUCKET_NAME"/>
        </discovery-option>
    </discovery-options>
</local>
  4. Configure users and add the secret values for users to the host controller instances. For more information, see Create a Managed Domain on Two Machines in the JBoss EAP Configuration Guide.

For Host Controller Instance

  1. Set the following variable in the appropriate service configuration file: 

    WILDFLY_HOST_CONFIG=host-slave.xml

  2. Add S3 domain controller discovery configuration to the host-slave.xml file: 

    <remote security-realm="ManagementRealm">
    <discovery-options>
        <discovery-option name="s3-discovery" module="org.jboss.as.host-controller" code="org.jboss.as.host.controller.discovery.S3Discovery">
            <property name="access-key" value="S3_ACCESS_KEY"/>
            <property name="secret-access-key" value="S3_SECRET_ACCESS_KEY"/>
            <property name="location" value="S3_BUCKET_NAME"/>
        </discovery-option>
    </discovery-options>
</remote>
    Note

    For information about S3 domain controller discovery, see Launch One or More Instances to Serve as Host Controllers.

Warning

Running a JBoss EAP 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.

Important

The auto-scaling Amazon EC2 feature can be used with JBoss EAP cluster nodes. However, ensure it is tested before deployment. You should ensure that your particular workloads scale to the required 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 may affect cluster performance. Test with your expected real-life loads and try to account for unexpected conditions.

Warning

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 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 instance gracefully using SSH access to the instance or Red Hat JBoss Operations Network.

Test your 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.

5.2. Launch Clustered JBoss EAP AMIs (with mod_cluster and VPC)

This topic lists the steps to launch an Apache HTTP server instance to serve as a mod_cluster proxy and a NAT instance for the Virtual Private Cloud (VPC).

See System Paths for more details about system paths.

See Configuring JBoss EAP Subsystems to Work on Cloud Platforms for information about configuring JBoss EAP subsystems for Amazon EC2.

Note
  • You can use the example configuration scripts that are provided with the image.

An Amazon Virtual Private Cloud (Amazon VPC) is a feature of Amazon Web Services (AWS) that allows you to isolate a set of AWS resources in a private network. The topology and configuration of this private network can be customized to your needs.

See Amazon Virtual Private Cloud for more information about Amazon VPC.

Note

If you start a cluster with a mod_cluster load balancer inside a VPC, the JBoss EAP servers are inaccessible to public. The mod_cluster load balancer can be the only endpoint that is connected to the Internet.

See Launch an Instance to Serve as a Domain Controller for setting up domain controller instance.

See Launch One or More Instances to Serve as Host Controllers for setting up host controller instance.

See Launch One or More Instances to Serve as Host Controllers for information about S3 domain controller discovery.

5.2.1. To launch clustered AMIs with VPC and mod_cluster

Note

Configuring the VPC is optional. See the Detecting Your Supported Platforms and Whether You Have a Default VPC section in the Amazon VPC user guide for more information.

  1. Install jbcs-httpd24-mod_cluster-native package and all of its dependencies. The mod_cluster configuration file is installed in /opt/rh/jbcs-httpd24/root/etc/httpd/conf.d/mod_cluster.conf.

See the Apache HTTP Server Installation Guide for more information about installation of Red Hat JBoss Core Services Apache HTTP Server.

  1. Disable advertising for mod_cluster. Add the following to VirtualHost in the /opt/rh/jbcs-httpd24/root/etc/httpd/conf.d/mod_cluster.conf configuration file. 

    ServerAdvertise Off
EnableMCPMReceive
# AdvertiseFrequency # comment out AdvertiseFrequency if present
  2. Allow ports in SELinux. If required, configure the iptables. Ports can be allowed in SELinux by using the semanage port -a -t http_port_t -p tcp $PORT_NR command.

  3. Configure JBoss EAP to look for mod_cluster proxy on the address that mod_cluster listens on.

    Note

    An /opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs/standalone-ec2-ha.xml example configuration file is provided. You need to configure a list of proxies in the modcluster subsystem.

    You can define a list of proxies using one of the following methods:

    • Define an outbound-socket-binding called mod-cluster-proxy1 with an appropriate host and port: 

      <outbound-socket-binding name="mod-cluster-proxy1">
    <remote-destination host="${jboss.modcluster.proxy1.host}" port="${jboss.modcluster.proxy1.port}"/>
</outbound-socket-binding>

    • Set the proxies attribute in the modcluster subsystem to mod-cluster-proxy1 with an appropriate host and port: 

      /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=mod-cluster-proxy1:add(host={${jboss.modcluster.proxy1.host}}, port={${jboss.modcluster.proxy1.port}})