README.md

JBoss EAP 7.2 on RHEL 7.7 (clustered, VMSS)

Tags: JBoss, Red Hat, EAP 7.2, Cluster, Load Balancer, RHEL 7.7, Azure, Azure VMSS, Java EE

1. Solution Overview
2. Template Solution Architecture
3. Subscriptions and Costs
4. Prerequisites
5. Deployment Steps
6. Deployment Time
7. Validation Steps
8. Scaling
9. Troubleshooting
10. Support

Solution Overview

JBoss Enterprise Application Platform (EAP) is an open source platform for highly transactional, web-scale Java applications. EAP combines the familiar and popular Jakarta EE specifications with the latest technologies, like MicroProfile, to modernize your applications from traditional Java EE into the new world of DevOps, cloud, containers, and microservices. EAP includes everything needed to build, run, deploy, and manage enterprise Java applications in a variety of environments, including on-premises, virtual environments, and in private, public, and hybrid clouds.

Red Hat Subscription Management (RHSM) is a customer-driven, end-to-end solution that provides tools for subscription status and management and integrates with Red Hat's system management tools. To obtain an RHSM account for JBoss EAP, go to: www.redhat.com.

Template Solution Architecture

This Azure Resource Manager (ARM) template creates all the Azure compute resources to run JBoss EAP 7.2 cluster running Red Hat Enterprise Linux (RHEL) 7.7 VMSS instances where the user can decide the number of instances to be deployed and scale it according to their requirement. The following resources are created by this template:

• RHEL 7.7 Virtual Machine Scale Set instances
• 1 Load Balancer
• Virtual Network with a single subnet
• JBoss EAP 7.2 cluster setup on the VMSS instances
• Sample Java application called eap-session-replication deployed on JBoss EAP 7.2
• Storage Account

Following is the Architecture:

To learn more about the JBoss Enterprise Application Platform, visit: Documentation for JBoss EAP 7.2

Subscriptions and Costs

This ARM template is designed with flexible operating system (OS) options:

• Red Hat Enterprise Linux OS as Pay-As-You-Go (PAYG) or Bring-Your-Own-Subscription (BYOS) via Red Hat Gold Image model.
• Red Hat JBoss EAP is available through BYOS only.

Using RHEL OS with PAYG Model

By default this template uses the on-demand Red Hat Enterprise Linux 7.7 PAYG image from the Azure Gallery. When using this on-demand image, there is an additional hourly RHEL subscription charge for using this image on top of the normal compute, network and storage costs. At the same time, the instance will be registered to your Red Hat subscription, therefore consuming one of your entitlements. This will lead to "double billing". To avoid this, you would need to build your own RHEL image, which is defined in this Red Hat KB article for uploading RHEL image to Azure or use RHEL Gold Image from the Azure Private Gallery offering.

Read Red Hat Enterprise Linux pricing for details on the RHEL VMs pricing with PAYG model. In order to use RHEL in PAYG model, you will need an Azure Subscription with the specified payment method (RHEL 7.7 is an Azure Marketplace product and requires a payment method to be specified in the Azure Subscription).

Using RHEL OS with BYOS Model

In order to use BYOS for RHEL OS Licensing, you need to have a valid Red Hat subscription with entitlements to use RHEL OS in Azure. Please complete the following prerequisites in order to use RHEL OS through BYOS model before you deploy this quickstart template.

1. Ensure you have RHEL OS and JBoss EAP entitlements attached to your Red Hat Subscription.

2. Authorize your Azure Subscription ID to use RHEL BYOS images. Please follow Red Hat Subscription Management (RHSM) documentation to complete this process. This includes multiple steps including:

   2.1 Enable Microsoft Azure as provider in your Red Hat Cloud Access Dashboard.

   2.2 Add your Azure Subscription IDs.

   2.3 Enable new products for Cloud Access on Microsoft Azure.

   2.4 Activate Red Hat Gold Images for your Azure Subscription. Refer to Red Hat Subscription Management for more details.

   2.5 Wait for Red Hat Gold Images to be available in your Azure subscription. These are typically available within 3 hours.

3. Accept the Marketplace Terms and Conditions in Azure for the RHEL BYOS Images. You can complete this by running Azure CLI commands, as instructed below. Refer to RHEL BYOS Gold Images in Azure documentation for more details.

   3.1 Launch an Azure CLI session and make sure your CLI version is updated to version 2.8 or newer before running these commands. Check the CLI version by running the following command and if your CLI version requires updating.

   az version

   3.2 Once your CLI session is ready, authenticate with your Azure account. Refer to Signing in with Azure CLI for assistance.

   3.3 Verify the RHEL BYOS images are available in your subscription by running the following CLI command. If your RHEL BYOS is not listed, please refer to #2 and ensure that your Azure subscription is activated for RHEL BYOS images.

   az vm image list --offer rhel-byos --all

   3.4 Run the following command to accept the Marketplace Terms for RHEL 7.7 BYOS.

   az vm image terms accept --publisher redhat --offer rhel-byos --plan rhel-lvm77

4. Your subscription is now ready to deploy RHEL 7.7 BYOS VMSS instances.

Using JBoss EAP with BYOS Model

JBoss EAP is available on Azure through BYOS model only; you need to supply your RHSM credentials along with RHSM Pool ID showing valid EAP entitlements when deploying this template. If you do not have EAP entitlement, you must obtain a JBoss EAP evaluation subscription or contact Red Hat for a production subscription before you get started.

Prerequisites

1. Ensure you have an Azure subscription compliant with licensing requirements specified in 'Subscriptions and Costs' section.

2. To deploy the template, you will need:

   • Admin Username and password or SSH key data which is an SSH RSA public key for the VMSS instance

   • JBoss EAP Username and password

   • RHSM Username and password

   • RHSM Pool ID for JBoss EAP and/or RHEL OS

Deployment Steps

Build your environment with JBoss EAP 7.2 cluster setup on RHEL 7.7 VMSS instances where the user can decide the number of instances to be deployed and scale it according to their requirement on Azure in a few simple steps:

1. Launch the template by clicking the Deploy to Azure button.

2. Complete the following parameter values and accept the Terms and Conditions before clicking on the Purchase button.

   • Subscription - Choose the appropriate subscription for deployment.

   • Resource Group - Create a new Resource Group or select an existing one.

   • Location - Choose the appropriate location for deployment.

   • Admin Username - User account name for logging into the RHEL VMSS instance.

   • Authentication Type - Type of authentication to use on the VMSS instance (password or SSH key).

   • Admin Password or SSH key - User account password or SSH key data which is an SSH RSA public key for logging into the RHEL VMSS instance.

   • JBoss EAP Username - Username for JBoss EAP Admin Console.

   • JBoss EAP Password - User account password for JBoss EAP Admin Console.

   • RHEL OS Subscription Type - Select the type of RHEL OS license from the dropdown options for deploying the VMSS. You will have either the option of PAYG (by default) or BYOS.

   • RHSM Username - Username for the Red Hat Subscription Manager account.

   • RHSM Password - User account password for your RHSM account.

   • RHSM Pool ID for JBoss EAP - RHSM Pool ID (ensure you have EAP entitlement)

   • RHSM Pool ID for RHEL - RHSM Pool ID (ensure you have RHEL entitlement). This is mandatory when selecting BYOS RHEL OS as Subscription Type. This should be left blank when selecting RHEL OS PAYG Subscription Type.

   • Storage Replication - Select the Replication Strategy for the Storage account.

   • VMSS Name - Enter the string to be used as a base for naming resources

   • Instance Count - Enter the VMSS instance count (100 or less)

   • VMSS Instance Size - Select the appropriate size of the VMSS instance from the dropdown options.

   • Leave the rest of the parameter values (Artifacts and Location) as is, accept the Terms and Conditions, and proceed to purchase.

Deployment Time

The deployment takes approximately 10 minutes to complete.

Validation Steps

Once the deployment is successful, go to the outputs section of the deployment to obtain the app URL. You can access the RHEL VMSS instance and the application by following one of the 3 options:

1. Create a Jump VM in a different subnet (new subnet) in the same Virtual Network and access the Load Balancer and RHEL VMSS instance via Jump VM.
2. Create a Jump VM in a different Virtual Network and access the Load Balancer and RHEL VMSS instance using Virtual Network Peering. (recommended method)
3. Using an Application Gateway.

Option 1 of 3. Create a Jump VM in a different subnet (new subnet) in the same Virtual Network and access the Load Balancer and RHEL VMSS instance via Jump VM.

• Add a new subnet in the existing Virtual Network which contains the RHEL VMSS.

• Create a Windows Virtual Machine in Azure in the same Resource Group you deployed the template. Provide the required details and leave other configurations as default except for the Virtual Network and subnet. Make sure you select the existing Virtual Network in the Resource Group and select the subnet you just created in the step above. This will be your Jump VM.

• Access Jump VM Public IP - once the Jump VM is successfully deployed, go to the VM details page and copy the Public IP. Log into the Jump VM using this Public IP.

• To obtain the Private IP of a RHEL VMSS instance, go to the VMSS details page and under settings section select Instances. Select the instance from here and copy the Private IP address. Open a web browser inside the Jump VM, go to http://<PRIVATE_IP_Address>:8080 and you should see the web page as follows. Use the same Private IP to login to the VMSS instance.

  

• To access the administration console, click on the Administration Console shown in the above image and enter JBoss EAP username and password to access the console of the respective VMSS instance.

  

• To access the App UI console - copy the app URL from the output page of the deployment and paste it in a browser inside the Jump VM. The web application displays the Session ID, Session counter and Timestamp (these are variables stored in the session that are replicated) and the VMSS instance Private IP address that the web page and session is being hosted from. Clicking on the Increment Counter updates the session counter and clicking on Refresh will refresh the page.

  

  

• Note that in the EAP Session Replication page of Load Balancer, the Private IP displayed is that of one of the VMSS instance. If you click on Increment Counter or Refresh button when the service of the VMSS instance corresponding to the Private IP displayed is down (can be due to various reasons like the instance in stopped state or instance restarting), the Private IP displayed will change to that of another VMSS instance Private IP but the Session ID remains the same. This validates that the Session was replicated.

  

Option 2 of 3. Create a Jump VM in a different Virtual Network and access the Load Balancer and RHEL VMSS instance using Virtual Network Peering.

• Create a Windows Virtual Machine - in a new Azure Resource Group, create a Windows VM. This should be the same location as the Resource Group you deployed the template. Provide the required details and leave other configurations as default. This will create the Jump VM in a new Virtual Network.

• Peer the Virtual Networks - this is how you associate the Load Balancer with the Jump VM. Once the Virtual Network peering is successful, they can communicate with each other.

• Go to the Jump VM details page and copy the Public IP. Log into the Jump VM using this Public IP.

• To obtain the Private IP of a RHEL VMSS instance, go to the VMSS details page and under settings section select Instances. Select the instance from here and copy the Private IP address. Open a web browser inside the Jump VM, go to http://<PRIVATE_IP_Address>:8080 and you should see the web page as follows. Use the same Private IP to login to the VMSS instance.

  

• To access the administration console, click on the Administration Console shown in the above image and enter JBoss EAP username and password to access the console of the respective VMSS instance.

  

• To access the App UI console, copy the app URL from the output page and paste it in a browser inside the Jump VM. The web application displays the Session ID, Session counter and Timestamp (these are variables stored in the session that are replicated) and the VMSS instance Private IP address that the web page and session is being hosted from. Clicking on the Increment Counter updates the session counter and clicking on Refresh will refresh the page.

  

  

• Note that in the EAP Session Replication page of Load Balancer, the Private IP displayed is that of one of the VMSS instance. If you click on Increment Counter or Refresh button when the service of the VMSS instance corresponding to the Private IP displayed is down (can be due to various reasons like the instance in stopped state or instance restarting), the Private IP displayed will change to that of another VMSS instance Private IP but the Session ID remains the same. This validates that the Session was replicated.

  

Option 3 of 3. Using an Application Gateway

• Create an Application Gateway - to access the ports of the Load Balancer and the RHEL VMSS instances, create an Application Gateway in a different subnet. This subnet must only contain Application Gateway.

• Set Frontends parameters - make sure you select Public IP or both and provide the required details. Under Backends section, select Add a backend pool option and add the Load Balancer Private IP and RHEL VMSS instance Private IPs to different backend pools of the Application Gateway.

• Set access ports - under Configuration section add routing rules to access the ports 80 of the Load Balancer and different rules to access port 9990 (admin console) of each RHEL VMSS instances.

• Copy Public IP of Application Gateway - once the Application Gateway is created with the required configurations, go to the Application Gateway overview page and copy the Public IP of the Application Gateway.

• To view the EAP Session Replication web page - open a web browser and go to http://<PUBLIC_IP_AppGateway>/eap-session-replication/ and you should see the application running. The web application displays the Session ID, Session counter and Timestamp (these are variables stored in the session that are replicated) and the VMSS instance Private IP address that the web page and session is being hosted from. Clicking on the Increment Counter updates the session counter and clicking on Refresh will refresh the page.

  

  

• Note that in the EAP Session Replication page of Load Balancer, the Private IP displayed is that of one of the VMSS instance. If you click on Increment Counter or Refresh button when the service of the VMSS instance corresponding to the Private IP displayed is down (can be due to various reasons like the instance in stopped state or instance restarting), the Private IP displayed will change to that of another VMSS instance Private IP but the Session ID remains the same. This validates that the Session was replicated.

  

• To log into the JBoss EAP Admin Console of a VMSS instance - open a web browser and go to http://<PUBLIC_IP_AppGateway>:listener_port. Enter the JBoss EAP username and password to login. The listener port should be the port of the listener which you have configured in routing rule associated with the particular RHEL VMSS instance.

  

Scaling

There are two scaling options for VMSS: Manual Scale or Custom Autoscale. After deployment, you can manually increase or decrease VMSS instances in the Azure Portal or using Azure CLI commmand. You can also switch to Custom Autoscale. This automated and elastic behavior reduces the management overhead to monitor and optimize for performance and cost effectiveness. With Custom Autoscale you can set rules to automatically scale your deployment by adding instances based on a schedule or host metrics.

Using Azure portal - To change the VMSS scaling options, go to 'Settings' and click on 'Scaling' on the left menu. In 'Scaling' blade, select your scaling configuration and follow the instructions or learn more about Azure Autoscale.

Using Azure CLI - To create the autoscale resource, use az monitor autoscale create and to create the rule, use az monitor autoscale rule.

Troubleshooting

This section includes common errors faced during deployments and details on how you can troubleshoot these errors.

Azure Platform

• If the parameter criteria are not fulfilled (ex - the admin password criteria was not met) or if any mandatory parameters are not provided in the parameters section then the deployment will not start. The Terms & Conditions must be accepted before clicking on Purchase.

• Once the deployment starts the resources being deployed will be visible on the deployment page. In the case of any deployment failure, after parameter validation process, a more detailed failure message is available.

• If your deployment fails at the VMSS Custom Script Extension resource, a more detailed failure message is available in the VMSS instance log file. Please refer to the next section for further troubleshooting.

Troubleshooting EAP deployment extension

This quickstart template uses VMSS Custom Script Extension to deploy and configure JBoss EAP with a sample application. Your deployment can fail at this stage due to several reasons such as:

• Invalid RHSM or EAP entitlement
• Invalid JBoss EAP or RHEL OS entitlement Pool ID

Follow the steps below to troubleshoot this further:

1. Log into the provisioned VMSS instance through SSH as mentioned in the 'Validation section'.

2. Switch to root user

   sudo su -

3. Enter the VMSS instance admin password if prompted.

4. Change directory to logging directory

   cd /var/lib/waagent/custom-script/download/1

5. Review the logs in jbosseap.install.log log file.

   more jbosseap.install.log

This log file will have details that include deployment failure reason and possible solutions. If your deployment failed due to RHSM account or entitlements, please refer to 'Subscriptions and Costs' section to complete the prerequisites and try again. Note that after your Azure subscription receives access to Red Hat Gold Images, you can locate them in the Azure portal. Go to Create a Resource > See all. At the top of the page, you'll see that You have private offers available bar, click on View private offers link to view your private offers.

Your Private Offer will be tagged with Private as seen below.

Please refer to Using the Azure Custom Script Extension Version 2 with Linux VMs for more details on troubleshooting VM custom script extensions.

Support

For any support related questions, issues or customization requirements with the GitHub template please contact Spektra Systems.

If you are experiencing production deployment issues please contact Red Hat Support.