Using JBoss EAP in Microsoft Azure

download PDF
Red Hat JBoss Enterprise Application Platform 7.2

For Use with Red Hat JBoss Enterprise Application Platform 7.2

Red Hat Customer Content Services


This book is a guide for using Red Hat JBoss Enterprise Application Platform in Microsoft Azure, including high-availability configuration.

Chapter 1. Introduction

JBoss EAP 7 can be used with the Microsoft Azure platform, as long as you use it within the specific supported configurations for running JBoss EAP in Azure. If you are configuring a clustered JBoss EAP environment, you must apply the specific configurations necessary to use JBoss EAP clustering features in Azure.


You can also run JBoss EAP 7.2 on Azure App Service, a managed hosting service for web and API applications, as public preview. For more information, see Public Preview: A managed JBoss EAP experience on Azure.

This guide details the supported configurations of using JBoss EAP in Microsoft Azure, as well as the specific JBoss EAP configuration required to enable JBoss EAP clustering in Azure. All other JBoss EAP features not mentioned in this guide operate normally in Azure as with any other JBoss EAP installation. See the other JBoss EAP documentation for non-Azure-specific configuration instructions.

1.1. About Red Hat Cloud Access

Red Hat Cloud Access is a Red Hat subscription feature that provides support for JBoss EAP on Red Hat certified cloud infrastructure providers, such as Amazon EC2 and Microsoft Azure. Red Hat Cloud Access allows you to move your subscriptions between traditional servers and public cloud-based resources in a simple and cost-effective manner.

You can find more information about Red Hat Cloud Access on the Customer Portal.

Chapter 2. Supported Configurations

The only virtual machine operating systems supported for using JBoss EAP in Microsoft Azure are:

  • Red Hat Enterprise Linux 7
  • Microsoft Windows Server 2012 R2
  • Microsoft Windows Server 2016

The Red Hat Cloud Access program allows you to use a JBoss EAP subscription to install JBoss EAP on your own Azure virtual machine or one of the above On-Demand operating systems from the Microsoft Azure Marketplace. Note that virtual machine operating system subscriptions are separate from a JBoss EAP subscription.

Other than the above operating system restrictions, see the Customer Portal for further information on supported configurations for JBoss EAP, such as supported Java Development Kit (JDK) vendors and versions.

2.1. Unsupported Features

There are some unsupported features when using JBoss EAP in a Microsoft Azure environment.

Managed Domains
JBoss EAP managed domains are not supported in Microsoft Azure. Only standalone JBoss EAP server instances are supported. Note that configuring JBoss EAP clusters using standalone JBoss EAP servers is supported in Azure.
ActiveMQ Artemis High Availability Using a Shared Store
JBoss EAP messaging high availability using Artemis shared stores is not supported in Microsoft Azure. To configure JBoss EAP messaging high availability in Azure, see the instructions in the ActiveMQ Artemis High Availability section.
mod_custer Advertising
If you want to use JBoss EAP as an Undertow mod_cluster proxy load balancer, the mod_cluster advertisement functionally is unsupported because of Azure UDP multicast limitations. You must configure mod_cluster load balancing to use a proxy list instead of advertising.

Chapter 3. Creating Your Microsoft Azure Environment

Create the virtual machines that will host your JBoss EAP instances in your Microsoft Azure environment. The virtual machines must use an Azure size of Standard_A2 or higher.

You can use either the Azure On-Demand premium images to create your virtual machines or create your own virtual machines manually.


If you are configuring JBoss EAP high availability, you must create your virtual machines inside the same virtual network.

Chapter 4. Installing JBoss EAP


If you are using a Red Hat Enterprise Linux On-Demand virtual machine from the Microsoft Azure Marketplace, you must install JBoss EAP using the ZIP or installer methods. You must not register a Red Hat Enterprise Linux On-Demand virtual machine to Red Hat Subscription Management, as you will be billed twice for that virtual machine.

Installing JBoss EAP on a virtual machine in a Microsoft Azure environment is no different from a normal JBoss EAP installation. See the JBoss EAP Installation Guide for instructions.

Chapter 5. Configuring JBoss EAP Subsystems to Work on Cloud Platforms

Some JBoss EAP subsystems must be configured to work properly on cloud platforms, such as Amazon EC2 and Microsoft Azure. This is required because a JBoss EAP server is usually bound to a cloud virtual machine’s private IP address, for example: 10.x.x.x, which is only visible from within the cloud platform. For certain subsystems, this address must also be mapped to a server’s public IP address, which is visible from outside the cloud.

5.1. Web Services

When a client makes a web service request using Service.create(wsdlURL, serviceName);, the user connects to the server public IP address, but is subsequently redirected to an address defined in the server configuration files in the webservices subsystem. By default, this address is ${jboss.bind.address:}, which means that on a cloud platform, the caller will be redirected to the server’s private IP address and will be unable to resolve the request. The server’s public IP address has to be configured in the wsdl-host element, using the following command:


5.2. Messaging

When using messaging on a cloud platform, the connection factory that the client uses must have a connector pointing to the server’s public IP address.

For this reason a new connector and socket binding must be created for JBoss EAP servers running a full profile.

  1. The referenced http-public socket binding must be created within the socket-binding-group:

  2. Create the new http-connector element in the messaging subsystem:

    /subsystem=messaging-activemq/server=default/http-connector=http-public-connector:add(endpoint=http-acceptor, socket-binding=http-public)
  3. Set the connectors in the connection-factory, which will be used by clients. For example, configuration of RemoteConnectionFactory as the default connection will be:

    /subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=connectors, value=["http-public-connector"]

5.3. Remoting Configuration for High Availability

If you are using JBoss EAP HA features with clustered EJBs on a cloud platform, some extra configuration for the remoting subsystem is required to ensure EJB clients can receive cluster view updates.

This is done by configuring client-mappings for the remoting subsystem socket binding:

/socket-binding-group=standard-sockets/socket-binding=http:write-attribute(name=client-mappings,value=[{ "destination-address" => "PUBLIC_IP_ADDRESS", "destination-port" => "8080" }])

Chapter 6. Configuring JBoss EAP for Microsoft Azure

Starting JBoss EAP as a Service at Boot on Red Hat Enterprise Linux

If you are starting JBoss EAP as a service on Red Hat Enterprise Linux in Microsoft Azure, you must change the following configuration of the JBoss EAP service to ensure that it starts after the Azure virtual machine host name has been initialized.

Open /etc/systemd/system/ and add a dependency on waagent.service:

Replace the following line:

with: waagent.service

Load Balancing with mod_cluster

As a result of mod_cluster advertising not being supported in Azure, if you are configuring a JBoss EAP load balancing environment, you must ensure that all balancers and workers are bound to IP addresses that are accessible on your internal Microsoft Azure virtual network.


Balancers and workers must be bound to the actual internal Azure virtual IP address, for example, and not

Additionally, because of the unavailability of mod_cluster advertising, if you are using JBoss EAP as an Undertow mod_cluster proxy load balancer, you must configure each worker node to use a proxy list containing each balancer’s IP address and port, as shown below:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=proxy-one:add(host="BALANCER_IP_ADDRESS", port="BALANCER_PORT")

ActiveMQ Artemis High Availability

JBoss EAP messaging high availability using Artemis shared stores is not supported in Microsoft Azure. To configure JBoss EAP messaging high availability in Azure, you must use a replicated journal with the AZURE_PING JGroups discovery protocol using a TCP JGroups stack. For more information on using a replicated journal, see Data Replication in Configuring Messaging for JBoss EAP.

After configuring the TCP JGroups stack with AZURE_PING, you must add the JGroups stack to the discovery-group and broadcast-group jgroups-cluster configurations in the messaging-activemq subsystem. For details, see Server Discovery in Configuring Messaging for JBoss EAP.

Chapter 7. Using JBoss EAP High Availability in Microsoft Azure

Microsoft Azure does not support JGroups discovery protocols that are based on UDP multicast. Although you may use other JGroups discovery protocols (such as a static configuration (TCPPING), a shared database (JDBC_PING), shared file system-based ping (FILE_PING), or TCPGOSSIP), we strongly recommend that you use the shared file discovery protocol specifically developed for Azure: AZURE_PING.

7.1. Configuring AZURE_PING for JBoss EAP High Availability

This section describes configuring your JBoss EAP cluster to use the AZURE_PING JGroups discovery protocol. Ensure that you meet the prerequisites when creating your virtual machines.

AZURE_PING uses a common blob container in a Microsoft Azure storage account. If you do not already have a blob container that AZURE_PING can use, create one that your virtual machines can access.

After creating your blob container, you will need the following information to configure AZURE_PING:

  • storage_account_name: the name of the Microsoft Azure storage account that contains your blob container.
  • storage_access_key: the secret access key of the storage account.
  • container: the name of the blob container to use for PING data.

To configure JBoss EAP to use AZURE_PING as the JGroups discovery protocol, you can either use a preconfigured example JBoss EAP configuration file, or modify an existing configuration.


The following instructions configure AZURE_PING using a UDP JGroups stack. If you will be configuring JBoss EAP messaging high availability in Azure, you must configure AZURE_PING in a TCP JGroups stack instead.

7.1.1. Using the Example Configuration File

JBoss EAP includes example configuration files for configuring clustering of standalone servers in Microsoft Azure. These files are located in EAP_HOME/docs/examples/configs/ and are standalone-azure-ha.xml and standalone-azure-full-ha.xml.


See the JBoss EAP Configuration Guide for an explanation of the differences between the server profiles.

These sample configuration files are preconfigured for using clustering in Microsoft Azure, and all that is needed is to specify the values for your Azure storage account and blob container.

Copy your desired example configuration file to EAP_HOME/standalone/configuration/.

7.1.2. Modifying an Existing Configuration

If you are modifying an existing JBoss EAP high availability configuration, the following changes to the jgroups subsystem are required.

  1. Launch the management CLI and embed a server to make offline changes to your chosen configuration file. For example:

    $ EAP_HOME/bin/
    [disconnected /] embed-server --server-config=standalone-ha.xml
  2. By default, JGroups uses the UDP stack. If you were using another stack, change back to using the UDP stack:

    [standalone@embedded /] /subsystem=jgroups/channel=ee:write-attribute(name=stack,value=udp)
  3. Execute the following batch of commands to remove the existing UDP stack and insert a new UDP stack configured for Microsoft Azure:

    /subsystem=jgroups/stack=udp/protocol=azure.AZURE_PING:add(properties={storage_account_name="${jboss.jgroups.azure_ping.storage_account_name}", storage_access_key="${jboss.jgroups.azure_ping.storage_access_key}", container="${jboss.jgroups.azure_ping.container}"})

    If you want to store the values of your Microsoft Azure storage account and blob container in your configuration file, replace the system property references in the above configuration with the values from your Azure environment. In the following command, examples for starting JBoss EAP, the system properties are used.

    The stack XML in your configuration file should look like the following:

    <stack name="udp">
        <transport type="UDP" socket-binding="jgroups-udp">
            <property name="ip_mcast">
        <protocol type="azure.AZURE_PING">
            <property name="storage_account_name">
            <property name="storage_access_key">
            <property name="container">
        <protocol type="MERGE3"/>
        <protocol type="FD_SOCK" socket-binding="jgroups-udp-fd"/>
        <protocol type="FD"/>
        <protocol type="VERIFY_SUSPECT"/>
        <protocol type="pbcast.NAKACK2">
            <property name="use_mcast_xmit">
            <property name="use_mcast_xmit_req">
        <protocol type="UNICAST3"/>
        <protocol type="pbcast.STABLE"/>
        <protocol type="pbcast.GMS"/>
        <protocol type="UFC"/>
        <protocol type="FRAG2"/>
  4. Stop the embedded server and exit the management CLI:

    [standalone@embedded /] stop-embedded-server
    [disconnected /] exit

7.2. Starting JBoss EAP High Availability

To start JBoss EAP using high availability in Microsoft Azure, you must:

  • use a configuration file that has been configured with the AZURE_PING discovery protocol and specify the required values of your Microsoft Azure storage account and blob container.
  • bind the private interface to the Microsoft Azure internal IP address that is used for clustering traffic. You can do this at startup, as shown below, or as a set configuration shown in the JBoss EAP Configuration Guide.


    For security reasons, you must ensure that you do not expose clustering traffic to unintended networks.

    You can do this by restricting the endpoints to your Microsoft Azure virtual network or by creating a dedicated virtual network and dedicated virtual machine NICs for clustering traffic.

Start your JBoss EAP high availability instance using the following command. If you stored your Microsoft Azure storage account and blob container values in your configuration file, you can omit the -Djboss.jgroups.azure_ping system property definitions.

EAP_HOME/bin/ -b IP_ADDRESS -bprivate IP_ADDRESS --server-config=EAP_CONFIG_FILE.xml -Djboss.jgroups.azure_ping.storage_account_name=STORAGE_ACCOUNT_NAME -Djboss.jgroups.azure_ping.storage_access_key=STORAGE_ACCESS_KEY -Djboss.jgroups.azure_ping.container=CONTAINER_NAME

For example:

EAP_HOME/bin/ -b -bprivate --server-config=standalone-azure-ha.xml -Djboss.jgroups.azure_ping.storage_account_name=my_storage_account -Djboss.jgroups.azure_ping.storage_access_key=y7+2x7P68pQse9MNh58Bkk5po9OGzeJc+0IRqYcQ9Cr/Sp4xiUFJVlbY+MGXJRNx3syksikwm4tOYlFgjvoCmw== -Djboss.jgroups.azure_ping.container=my_blob_container

As JBoss EAP subsystems only start when needed, you must deploy a distributable application to your JBoss EAP servers to start the high availability JBoss EAP subsystems.

After you start a second JBoss EAP instance in a cluster, you should see logs similar to the following in the console log of the first server in the cluster:

INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-2,ee,eap-server-1) ISPN000094: Received new cluster view for channel server: [eap-server-1|1] (2) [eap-server-1, eap-server-2]

7.3. Troubleshooting JBoss EAP High Availability

If you are having trouble getting clustering to work in Microsoft Azure, verify that you have completed all the requirements in the following list.

  • Ensure that the Microsoft Azure virtual machines hosting your JBoss EAP servers are using the same virtual network.
  • Ensure that you have a blob container for AZURE_PING to use.
  • Ensure that you are using a JBoss EAP configuration file with the AZURE_PING discovery protocol configured in the jgroups subsystem.
  • Ensure that you are binding both the public and private interfaces to the correct Microsoft Azure IP addresses.
  • Ensure that you have the correct values for your Microsoft Azure storage account and blob container and that you are either:

    • storing them in your configuration file, or
    • setting the correct system properties when starting JBoss EAP.
  • Ensure that you have your distributable Java application deployed to all the JBoss EAP servers in your cluster.

7.3.1. Cleaning Stale Discovery Files in Your Blob Container

If a JBoss EAP cluster that uses AZURE_PING is shut down abnormally, for example, using kill -9 to end the JBoss EAP process, some stale discovery files may be left in your blob container.

These files are usually cleaned up in a graceful cluster shutdown, but if left there from an abnormal shutdown, it may impact startup performance of cluster members attempting to contact nodes that are no longer online.

If this is a problem for you, you can set the following configuration to make the cluster coordinator remove and refresh all discovery files whenever the cluster view changes.


Alternatively, if cleaning your container on each view change is not ideal, you can reduce the number of join attempts for a node attempting to join a cluster. The default number of join attempts is 10. For example, to set the number of join attempts to 3:


The stale discovery files will still be present, but a node attempting to join a cluster will not spend as much time attempting to contact nodes that are no longer online.

Revised on 2020-10-09 09:38:41 UTC

Legal Notice

Copyright © 2020 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


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.