Using JBoss EAP in Microsoft Azure

Red Hat JBoss Enterprise Application Platform 7.4

Instructions for using Red Hat JBoss Enterprise Application Platform on Microsoft Azure, including configuring high availability.

Red Hat Customer Content Services

Abstract

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

Providing feedback on JBoss EAP documentation

To report an error or to improve our documentation, log in to your Red Hat Jira account and submit an issue. If you do not have a Red Hat Jira account, then you will be prompted to create an account.

Procedure

  1. Click the following link to create a ticket.
  2. Please include the Document URL, the section number and describe the issue.
  3. Enter a brief description of the issue in the Summary.
  4. Provide a detailed description of the issue or enhancement in the Description. Include a URL to where the issue occurs in the documentation.
  5. Clicking Submit creates and routes the issue to the appropriate documentation team.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

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.

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. Subscription models for JBoss EAP on Azure

You can choose between two subscription models for deploying JBoss EAP on Azure: bring your own subscription (BYOS) and pay-as-you-go (PAYG).

The following are the differences between the two offerings:

BYOS
If you already have an existing Red Hat subscription, you can use it for deploying JBoss EAP on Azure with the BYOS model. For more information, see About Red Hat Cloud Access.
PAYG
If you do not have an existing Red Hat subscription, you can choose to pay based on the number of computing resources you used by using the PAYG model.

1.2. About Red Hat Cloud Access

If you have an existing Red Hat subscription, Red Hat Cloud Access 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 cost-effectively move your subscriptions between traditional servers and public cloud-based resources.

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
  • Red Hat Enterprise Linux 8
  • Microsoft Windows Server 2016
  • Microsoft Windows Server 2019

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. JBoss EAP 7.4 OpenJDK images available in Microsoft Azure

In JBoss EAP 7.4, you can now use OpenJDK 8 images on Red Hat Enterprise Linux 8 virtual machines in Microsoft Azure via Azure Templates.

2.2. Unsupported Features

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

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.
Virtual Machine Scale Set

Transactions in Microsoft Azure Virtual Machine Scale Set (VMSS) is unsupported because the automatic scale down feature does not wait for all transactions to be completed during the scale down process. This could cause data integrity issues. Microsoft Azure VMSS destroys an EAP VM and does not support proper shutdown, which results in the following limitation for EAP clustering:

  • VMSS should be supported for the configurations, in which the server-side state for HA needs to be externalized to a third-party service, such as Red Hat Data Grid. JBoss EAP supports VMSS for HttpSessions externalization, but not for the stateful session bean.
Azure App Service

JTS is not supported in the JBoss EAP Azure App Service offering.

Note

Although JTS is not supported, Jakarta Transactions are supported under the following conditions:

  • The automatic removal of instances is disabled.
  • Instances are not removed manually, for example, by reducing the number of running instances using the Azure dashboard.

Also, transactions over Jakarta Enterprise Beans-remoting are not supported.

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.

Important

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

Chapter 4. Installing JBoss EAP

Important

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:127.0.0.1}, 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:

/subsystem=webservices:write-attribute(name=wsdl-host,value=PUBLIC_IP_ADDRESS)

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:

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=http-public:add(host=PUBLIC_IP_ADDRESS,port=${jboss.http.port:8080})
  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 Jakarta Enterprise Beans on a cloud platform, some extra configuration for the remoting subsystem is required to ensure Jakarta Enterprise Beans 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/multi-user.target.wants/eap7-standalone.service and add a dependency on waagent.service:

Replace the following line:

After=syslog.target network.target

with:

After=syslog.target network.target waagent.service
Requires=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.

Note

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

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")
/subsystem=modcluster/mod-cluster-config=configuration:list-add(name=proxies,value=proxy-one)

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.

Important

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.

Note

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/jboss-cli.sh
    [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:

    batch
    /subsystem=jgroups/stack=udp:remove
    /subsystem=jgroups/stack=udp:add()
    /subsystem=jgroups/stack=udp/transport=UDP:add(socket-binding=jgroups-udp,properties={ip_mcast=false})
    /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}"})
    /subsystem=jgroups/stack=udp/protocol=MERGE3:add
    /subsystem=jgroups/stack=udp/protocol=FD_SOCK:add(socket-binding=jgroups-udp-fd)
    /subsystem=jgroups/stack=udp/protocol=FD:add
    /subsystem=jgroups/stack=udp/protocol=VERIFY_SUSPECT:add
    /subsystem=jgroups/stack=udp/protocol=pbcast.NAKACK2:add(properties={use_mcast_xmit=false,use_mcast_xmit_req=false})
    /subsystem=jgroups/stack=udp/protocol=UNICAST3:add
    /subsystem=jgroups/stack=udp/protocol=pbcast.STABLE:add
    /subsystem=jgroups/stack=udp/protocol=pbcast.GMS:add
    /subsystem=jgroups/stack=udp/protocol=UFC:add
    /subsystem=jgroups/stack=udp/protocol=FRAG2:add
    run-batch
    Note

    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">
                false
            </property>
        </transport>
        <protocol type="azure.AZURE_PING">
            <property name="storage_account_name">
                ${jboss.jgroups.azure_ping.storage_account_name}
            </property>
            <property name="storage_access_key">
                ${jboss.jgroups.azure_ping.storage_access_key}
            </property>
            <property name="container">
                ${jboss.jgroups.azure_ping.container}
            </property>
        </protocol>
        <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">
                false
            </property>
            <property name="use_mcast_xmit_req">
                false
            </property>
        </protocol>
        <protocol type="UNICAST3"/>
        <protocol type="pbcast.STABLE"/>
        <protocol type="pbcast.GMS"/>
        <protocol type="UFC"/>
        <protocol type="FRAG2"/>
    </stack>
  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.

    Warning

    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/standalone.sh -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/standalone.sh -b 172.28.0.2 -bprivate 172.28.0.2 --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
Note

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.

/subsystem=jgroups/stack=udp/protocol=azure.AZURE_PING/property=remove_all_data_on_view_change:add(value=true)
Note

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:

/subsystem=jgroups/stack=udp/protocol=pbcast.GMS/property=max_join_attempts:add(value=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 2024-01-17 05:24:32 UTC

Legal Notice

Copyright © 2024 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 http://creativecommons.org/licenses/by-sa/3.0/. 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.