Migrate JBoss EAP applications to Azure Red Hat OpenShift

  • Article

This guide describes what you should be aware of when you want to migrate an existing JBoss EAP application to run on Azure Red Hat OpenShift.

Pre-migration

To ensure a successful migration, before you start, complete the assessment and inventory steps described in the following sections.

Ensure that the target is the appropriate target for your migration effort

The first step in a successful migration of a JBoss EAP application to Azure is selecting the most appropriate migration target. JBoss EAP runs well on Azure virtual machines (VMs) or Azure Red Hat OpenShift.

The VM target is the easiest choice, because it most closely resembles an on-premises deployment. The administrative and deployment experience for virtual machines is analogous to what you have on-premises. Selecting VMs allows you to defer modernization.

Red Hat OpenShift brings together tested and trusted services to reduce the friction of developing, modernizing, deploying, running, and managing applications. Azure Red Hat OpenShift is built on Kubernetes. Azure Red Hat OpenShift delivers a consistent experience across public cloud, on-premises, hybrid cloud, or edge architecture.

If minimizing change is the most important factor for your migration effort, consider a VM-based migration. In this case, see Migrate JBoss EAP applications to JBoss EAP on Azure VMs. If you can tolerate converting your application to run within Red Hat OpenShift to reduce runtime cost, consider an Azure Red Hat OpenShift-based migration. In this case, continue with Migrate JBoss EAP applications to JBoss EAP on Azure Red Hat OpenShift. To understand the differences between JBoss EAP and JBoss EAP for OpenShift, see Comparison: JBoss EAP and JBoss EAP for OpenShift.

Determine whether the prebuilt Azure Marketplace offer is a good starting point

First, decide that Azure Red Hat OpenShift is the appropriate deployment target. Next, decide whether or not the prebuilt Azure Marketplace offer is a good starting point. Consider the following points about the prebuilt Azure Marketplace offer:

  • Red Hat and Microsoft created this offer to enable quickly provisioning JBoss EAP on Azure Red Hat OpenShift.
  • At a high level, the offer automates the following steps for you.
    • Install the EAP Operator on Azure Red Hat OpenShift.
    • Build an application image using eap-s2i-build template. For more information about Source-to-image (S2I), see Using OpenJDK 11 source-to-image for OpenShift.
    • Deploy the Java application using the EAP Operator. For more information, see the reference documentation for EAP Operator at Red Hat.

If you don't use the prebuilt Azure Marketplace offer, you must learn how to use the EAP Operator directly. Mastering the operator is beyond the scope of this article. The complete documentation for the EAP Operator is available at Red Hat.

The remainder of this section provides some considerations for deciding to use the prebuilt Azure Marketplace offer or using the operator directly.

Determine whether the JBoss EAP version is compatible

Your existing JBoss EAP version must be one of the versions supported by the operator. For more information, see Version Compatibility and Support in the Red Hat documentation.

Inventory server capacity

Document the hardware (memory, CPU, disk) of the current production server(s) and the average and peak request counts and resource utilization. You need this information regardless of the migration path you choose. The following aspects, and more, benefit from having a detailed inventory of server capacity.

  • To help guide selection of the size of the VMs in your node pool.
  • To understand the amount of memory to be used by the container.
  • To know how many CPU shares the container needs.

It's possible to resize node pools in Azure Red Hat OpenShift. For more information, see Resizing a cluster--Microsoft Azure in the Red Hat documentation.

Inventory all secrets

Before the advent of "configuration as a service" technologies such as Azure Key Vault, there wasn't a well-defined concept of "secrets". Instead, you had a disparate set of configuration settings that effectively functioned as what we now call "secrets". With app servers such as JBoss EAP, these secrets are in many different config files and configuration stores. Check all properties and configuration files on the production server(s) for any secrets and passwords. Be sure to check configuration files like custom-config.xml or jboss-web.xml in your applications. Configuration files containing passwords or credentials may also be found inside your application. For more information, see Azure Key Vault basic concepts.

Once you have a solid inventory of secrets, consult the EAP Operator documentation regarding secrets. For more information, see Creating a Secret in the Red Hat documentation.

Inventory all certificates

Document all the certificates used for public SSL endpoints. You can view all certificates on the production server(s) by running the following command:

keytool -list -v -keystore <path to keystore>

Once you have a solid inventory of certificates, you can configure them in Azure Red Hat OpenShift. For more information, see TLS configuration in OpenShift Container Platform(replace) in the Red Hat documentation.

Validate that the supported Java version works correctly

All of the migration paths for JBoss EAP to Azure Red Hat OpenShift require a specific Java version, which varies for each path. You need to validate that your application is able to run correctly using that supported version.

Note

This validation is especially important if your current server is running on an unsupported JDK (such as Oracle JDK or IBM OpenJ9).

To obtain your current Java version, sign in to your production server and run the following command:

java -version

Inventory JNDI resources

Inventory all JNDI resources. For example, datasources such as databases may have an associated JNDI name that allows JPA to correctly bind instances of EntityManager to a particular database. For more information on JNDI resources and databases, see Datasource Management in the Red Hat documentation. Other JNDI-related resources, such as ActiveMQ Artemis message brokers, may require migration or reconfiguration. For more information on ActiveMQ Artemis configuration, see Configuring Messaging in the Red Hat documentation.

Determine whether session replication is used

If your application relies on session replication, with or without Infinispan, you have three options:

  • Infinispan works well in Azure virtual machines, but if you're using a profile that provides high availability capabilities, be aware of the JGroups configuration. Determine whether your system is operating as a managed domain or standalone server.
    • If in a managed domain, the ha or full-ha profiles deal with JGroups.
    • If in a standalone server, the standalone-ha.xml or standalone-full-ha.xml configuration files deal with JGroups.
    • Microsoft Azure doesn't support JGroups discovery protocols that are based on UDP multicast. For more information, see Using JBoss EAP High Availability in Microsoft Azure in the Red Hat documentation.
  • Refactor your application to use a database for session management.
  • Refactor your application to externalize the session to Azure Redis Service. For more information, see Azure Cache for Redis.

For all of these options, it's a good idea to master how JBoss EAP does HTTP Session State Replication. For more information, see About HTTP Session Replication in the Red Hat documentation.

Document datasources

If your application uses any databases, you need to capture the following information:

  • What is the datasource name?
  • What is the connection pool configuration?
  • Where can I find the JDBC driver JAR file?

For more information on JDBC drivers in JBoss EAP, see Datasource Management in the Red Hat documentation.

Determine whether JBoss EAP has been customized

Determine which of the following customizations have been made, and capture what's been done.

  • Have the startup scripts been changed? Such scripts include host, eap_env, standalone, and domain.
  • Are there any specific parameters passed to the JVM?
  • Are there JARs added to the server classpath?

These customizations need to be captured in the container image running on Azure Red Hat OpenShift. For more information, see Configuring the JBoss EAP for OpenShift Image for Your Java Application in the Red Hat documentation.

Determine whether a connection to on-premises is needed

If your application needs to access any of your on-premises services, you'll need to provision one of Azure's connectivity services. For more information, see Connect an on-premises network to Azure. Alternatively, you'll need to refactor your application to use publicly available APIs that your on-premises resources expose.

Determine whether Java Message Service (JMS) Queues or Topics are in use

If your application is using JMS Queues or Topics, you may want to migrate them to an externally hosted JMS server. Azure Service Bus and the Advanced Message Queuing Protocol can be a great migration strategy for those using JMS. For more information, see Use Java Message Service 1.1 with Azure Service Bus standard and AMQP 1.0.

If JMS persistent stores have been configured, you must capture their configuration and apply it after the migration.

For more information, see Configuring Messaging in the Red Hat documentation.

Determine whether you are using your own custom created Shared Java EE Libraries

If you're using the Shared Java EE library feature, you have two options:

  • Refactor your application code to remove all dependencies on your libraries, and instead incorporate the functionality directly into your application.
  • Add the libraries to the server classpath.

You can handle these libraries using the same techniques as described in the Determine whether JBoss EAP has been customized section.

Determine whether your application contains OS-specific code

If your application contains any code with dependencies on the host OS, then you need to refactor it to remove those dependencies. For example, you may need to replace any use of / or \ in file system paths with File.Separator or Paths.get if your application is running on Windows.

Azure Red Hat OpenShift runs on OpenShift 4 using Red Hat Enterprise Linux CoreOS (RHCOS) as the operating system for all control plane and worker nodes. Any OS-specific code must be compatible with RHCOS.

Determine whether your application is composed of multiple WARs

If your application is composed of multiple WARs, you should treat each of those WARs as separate applications and go through this guide for each of them.

Determine whether your application is packaged as an EAR

If your application is packaged as an EAR file, be sure to capture their configurations.

Identify all outside processes and daemons running on the production servers

If you have any processes running outside the application server, such as monitoring daemons, you'll need to eliminate them or migrate them elsewhere.

Account for load-balancing requirements

The best way to account for load balancing is to use the App Gateway integration. For more information, see What is Azure Application Gateway?

Migration

The steps in this section assume that your analysis has lead you to decide to use the prebuilt Azure Marketplace offer.

Provision the offer

To open the offer in the Azure portal, see JBoss EAP on Azure Red Hat OpenShift. Select Create, and then follow the instructions in the offer.

Migrating your applications

The offer supports the Source-to-Image (S2I) process to build and run a Java application on the JBoss EAP for OpenShift image. Red Hat has a sample that shows how to do it manually if you'd like to deploy later by yourself. For more information, see Chapter 2. Build and Run a Java Application on the JBoss EAP for OpenShift Image in the Red Hat documentation.

Post-migration

After you've reached the migration goals you defined in the pre-migration step, perform some end-to-end acceptance testing to verify that everything works as expected. For information about some potential post-migration enhancements, see the following articles: