Migrate WebSphere applications to Azure Red Hat OpenShift

  • Article

This guide describes what you should be aware of when you want to migrate an existing WebSphere Application Server (WAS) workload to IBM WebSphere Liberty or Open Liberty that runs 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 WAS application to Azure is selecting the most appropriate migration target.

WAS traditional runs well on Azure Virtual Machines. The virtual machine (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.

Another option is to migrate to containers by converting WAS traditional workload to application containers. You can run the container target on Azure Kubernetes Service (AKS) and Azure Red Hat OpenShift. The trade-off for this ease is economic cost.

Generally speaking, the per-minute cost for a VM-based solution is higher compared with containers. While a container-based solution costs less to run, you must constrain your application to fit within the requirements of the container orchestration platform.

If minimizing change is the most important factor for your migration effort, consider a VM-based migration. In this case, see Migrate WebSphere applications to Azure Virtual Machines.

If you can tolerate converting your application to run within containers to reduce runtime cost, consider an AKS-based or Azure Red Hat OpenShift-based migration.

For AKS-based migration, you can start using the Free tier. Get free cluster management and pay for only the virtual machines, associated storage, and networking resources consumed. In this case, see Migrate WebSphere applications to Azure Kubernetes Service.

For Azure Red Hat OpenShift-based migration, in addition to the compute and infrastructure costs, application nodes have another cost for the OpenShift license component. This cost is billed based on the number of application nodes and the instance type. Use on-demand pricing or reserved instances, whichever best meets the need of your workload and business. In this case, see Migrate WebSphere applications to Azure Red Hat OpenShift.

The how-to guides in the Azure Red Hat OpenShift documentation cover some aspects that are relevant to migration. For the complete list of how-to guides, see the Azure Red Hat OpenShift documentation.

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

After you've decided that Azure Red Hat OpenShift is the appropriate deployment target, you must accept that the IBM WebSphere Liberty operator or Open Liberty Operator (the operator) is the only way to run Liberty on Kubernetes. After accepting this fact, you must decide whether or not the prebuilt Azure Marketplace offer is a good starting point. Here are some things to consider about the prebuilt Azure Marketplace offer:

  • IBM and Microsoft created this offer to allow you to quickly provision Liberty on Azure Red Hat OpenShift. This concept is explained in more detail in the following content.
  • At a high level, the offer automates the following steps for you.
    • Take an existing application image, if desired.
    • Provision an Azure Red Hat OpenShift cluster, if desired.
    • Install and configure the IBM WebSphere Liberty operator or Open Liberty operator on Azure Red Hat OpenShift.
    • Use the operator to run the whole thing. The operator deploys and manages containerized Liberty applications in Azure Red Hat OpenShift. You can find the reference documentation at IBM WebSphere Liberty operator and Open Liberty operator.

If you don't use the prebuilt Azure Marketplace offer, you must learn how to use the operator directly. Mastering the operator is beyond the scope of this article. The complete documentation for the operator is available at IBM WebSphere Liberty operator and Open Liberty operator.

Now that you've been introduced to the various ways to handle Liberty on Azure Red Hat OpenShift, you're better able to choose whether to use the prebuilt Azure Marketplace offer or to do it yourself using the operator directly.

Determine whether the Liberty version is compatible

You need the Open Liberty Operator or the WebSphere Liberty operator to deploy and manage applications on Kubernetes-based clusters. Make sure your existing Liberty version is one of the versions supported by the operator. Versions of Open Liberty are maintained in GitHub OpenLiberty/open-liberty. IBM maintains versions of IBM WebSphere Application Server Liberty. For more information, see WebSphere Application Server Liberty.

The prebuilt Azure Marketplace offer allows you to select your application images from public registry, and thus implicitly supports all of the versions.

Determine whether a license is needed

For IBM WebSphere Liberty, you must accept the terms on the license agreement corresponding to the version of the IBM Program in the application container. For the license agreement applicable to this IBM Program, see Viewing license information for WebSphere Liberty operator. For more information, see Running WebSphere Liberty on Microsoft Azure.

If your product edition is something other than the default IBM WebSphere Application Server (base), the .spec.license.edition value must specify your product edition. Other available values are IBM WebSphere Application Server Liberty Core and IBM WebSphere Application Server Network Deployment. The prebuilt Azure Marketplace offer allows you to select the supported product edition.

Inventory differences using IBM migration tools

To move your applications to WebSphere Application Server Liberty or Open Liberty, you need to plan your migration, analyze your applications, and update your source code. IBM provides migration tools to help identify any differences between your current environment and the technologies in your new Liberty environment, such as Java EE 7 or Java EE 8, and Java SE 8 or Java SE 11. For more information, see Migrating applications to Liberty.

Inventory server capacity

Document the hardware (memory, CPU, disk) of the current production servers and the average and peak request counts and resource utilization. You need this information regardless of the migration path you choose. This information is useful, for example, to help guide selection of the size of the VMs in your node, the amount of memory to be used by the container, and how many CPU shares the container would need.

To take advantage of unused capacity at a significant cost savings, it's possible to use Azure Spot Virtual Machines in Azure Red Hat OpenShift. To learn how, see Use Azure Spot Virtual Machines in an Azure Red Hat OpenShift cluster.

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 WAS, 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. Configuration files containing passwords or credentials may also be found inside your application. WAS stores configuration data in several documents in a cascading hierarchy of directories. Most configuration documents have XML content. For more information, see Configuration documents and Azure Key Vault basic concepts.

After you have a solid inventory of secrets, consult the operator documentation regarding secrets. For more information, see the following articles:

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>

After you have a solid inventory of certificates, configure them by using the following articles:

Validate that the supported Java version works correctly

Using Liberty requires a specific version of Java, so you need to confirm that your application runs correctly using that supported version.

The runtime of WebSphere Application Server Liberty has specific requirements for the minimum level of the Java Runtime Environment (JRE). For more information, see Java version dependencies for features.

Open Liberty requires a Java SE runtime. It can run by using either a Java Runtime Environment (JRE) or a Java SE Development Kit (JDK) distribution. For more information, see Supported Java SE releases.

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 WebSphere Data Sources in the IBM documentation. Other JNDI-related resources, such as JMS message brokers, may require migration or reconfiguration. For more information on JMS configuration, see Using JMS resources.

If you're using the prebuilt Azure Marketplace offer, the set of JNDI resources you can customize at deployment time is limited to what the offer supports. For WebSphere Liberty on Azure Kubernetes Service (AKS), you can make an object available in the default Java Naming and Directory Interface (JNDI) namespace. For more information, see Developing with the JNDI default namespace in a Liberty feature. For Open Liberty, see Java Naming and Directory Interface.

Inspect your profile configuration

The main configuration unit in WAS is the profile. As such, the resources.xml file contains a wealth of configuration that you must carefully consider for migration. The file includes references to other XML files that are stored in subdirectories. For more information, see Managing profiles on distributed and IBM i operating systems.

Inside your application

Inspect the deployment.xml file and/or the WEB-INF/web.xml file.

You need to capture these customizations in the container image that Azure Red Hat OpenShift runs. When you use the prebuilt Azure Marketplace offer, such customizations are best handled by creating a custom container image and making it available in a public registry, then pointing to that registry at deployment time.

If you're using a WebSphere Application Server Network Deployment cell, each cluster member runs in an installation of traditional WAS. Liberty is lightweight profile of WebSphere Application Server. It's a flexible and dynamic profile of WAS, which enables the WAS server to deploy only required custom features instead of deploying a large set of available JEE components.

Determine whether session replication is used

If your application relies on session replication, you have the following options:

  • For HTTP sessions, according to the level of session management, you can use cache or a database to collect session data.
  • For Distributed sessions, you can save sessions in a database using database session persistence.
  • For Dynamic cache, you can manage session data in cache or a database.
  • You can refactor your application to use a database for session management.
  • You can 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 Liberty does HTTP Session State Replication. The following documents help you understand how to manage HTTP Sessions in Liberty:

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 WAS, see Using JDBC Drivers with WebSphere Application Server.

JDBC configuration is a core server configuration in Liberty. For more information, see JDBC Driver.

The prebuilt Azure Marketplace offer has limited support for databases. You can handle the configuration in the application images and use the image when you deploy the offer.

Determine whether WAS 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 wsadmin, AdminControl, AdminConfig, AdminApp, and AdminTask.
  • Are there any specific parameters passed to the JVM?
  • Are there JARs added to the server classpath?
  • Have OS-level facilities such as systemd been used to cause WAS components to start automatically after a server restart?

You need to account for migration considerations depending on the answers to these questions.

You need to capture these customizations in the container image that Azure Red Hat OpenShift runs. When you use the prebuilt Azure Marketplace offer, such customizations are best handled by creating a custom container image and making it available in a public registry, then pointing to that registry at deployment time.

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 need to migrate them to an externally hosted JMS server. One strategy for those using JMS is to use Azure Service Bus and the Advanced Message Queuing Protocol. For more information, see Use Java Message Service 1.1 with Azure Service Bus standard and AMQP 1.0.

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

If you're using IBM MQ, you can migrate this software to Azure Virtual Machines and use it as-is.

Microsoft has a solution to integrate IBM MQ with Logic Apps. For more information, see Connect to an IBM MQ server from a workflow in Azure Logic Apps.

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 Accessing third-party APIs from a Java EE application.

Determine whether OSGi bundles are used

If you used OSGi bundles added to the WAS, you need to add the equivalent JAR files directly to your web application.

You can include the bundles in the image supplied to the prebuilt Azure Marketplace offer. For more information, see Configuring libraries for OSGi applications.

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.

Liberty on Azure Red Hat OpenShift runs on Linux x86_64. Any OS-specific code must be compatible with Linux. To learn how to discover specific OS information, follow the steps in the Determine whether the Liberty version is compatible section.

Determine whether IBM Integration Bus is in use

If your application is using IBM Integration Bus, you need to capture how IBM Integration Bus is configured. For more information, see IBM Integration Bus documentation.

IBM Integration Bus isn't directly supported in the prebuilt Azure Marketplace offer. To enable the feature, follow the instructions in Enabling the JMS application on Liberty to connect to the service integration bus in the IBM documentation.

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 examine the application.xml, ibm-application-bnd.xmi, and ibm-application-ext.xmi files and capture their configurations. For more information, see Building the enterprise archive (EAR) package on WebSphere.

The prebuilt Azure Marketplace offer allows you to use an existing container image. You can prepare the application according to your business requirements.

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.

Determine whether and how the file system is used

Kubernetes deals with file systems with persistent volumes (PV). Mounting persistent volumes isn't supported in the prebuilt Azure Marketplace offer. To create an Azure Files StorageClass, follow the instructions at Create an Azure Files StorageClass on Azure Red Hat OpenShift 4.

Read-only static content

If your application currently serves static content, you'll need an alternate location for it. You may wish to consider moving static content to Azure Blob Storage and adding Azure CDN for lightning-fast downloads globally. For more information, see Static website hosting in Azure Storage and Quickstart: Integrate an Azure storage account with Azure CDN.

Dynamically published static content

If your application allows for static content that is uploaded/produced by your application but is immutable after its creation, you can use Azure Blob Storage and Azure CDN as described above, with an Azure Function to handle uploads and CDN refresh. We've provided a sample implementation for your use at Uploading and CDN-preloading static content with Azure Functions.

Determine the network topology

The current set of Azure Marketplace offers is a starting point for your migration. If the offer doesn't cover aspects of your architecture that you need to migrate, you need to capture the network topology of your existing deployment. Then, you need to reproduce that topology in Azure, even after standing up the basic offer with one of the solution templates.

Network topology is a broad topic, but the following references can give some direction to your migration efforts:

Account for the use of JCA adapters and resource adapters

If your existing application uses JCA adapters or resource adapters to connect to other enterprise systems, ensure that you apply the configuration for these artifacts to the Liberty server running on Azure Kubernetes Service (AKS). For more information, see Overview of JCA configuration elements and Java Connector Architecture.

Determine whether clustering is used

The operator handles clustering for all possible ways of running a WAS workload on Azure Red Hat OpenShift.

Inspect your EJB clustering

If your application is using local Enterprise Java Beans (EJB), you may need to migrate them to a clustered EJB. For more information, see Developing EJB applications on Liberty.

Account for load-balancing requirements

The prebuilt Azure Marketplace offer uses an OpenShift built-in route to host the application at a public URL and account for load balancing. For more information, see OpenShift Route configuration.

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 IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift. Select Create, then use the information you gathered in the preceding steps to help in filling out the fields of the offer.

Account for KeyStores

You must account for the migration of any SSL/TLS KeyStores used by your application. For more information, see Configuring Keystores.

Connect the JMS sources

After you've connected the databases, you can configure JMS by following the instructions at Overview of JCA configuration elements in the IBM documentation.

Account for logging

You can't do cloud without mastering logging. The operator provides different approaches for monitoring. For more information, see Monitoring the Liberty server runtime environment. It's helpful to master logging and monitoring system in Red Hat OpenShift. For more information, see Understanding the logging subsystem for Red Hat OpenShift and About OpenShift Container Platform monitoring. You can configure Azure Monitor container insights for Azure Red Hat OpenShift. For more information, see Configure Azure Monitor container insights for Azure Red Hat OpenShift. If you prefer using Elastic Stack, Azure provides great support for Elastic. For complete details, see What is Elastic integration with Azure? You can combine the knowledge in these resources to achieve an Azure-optimized logging solution for Liberty on Azure Red Hat OpenShift.

Migrate your applications

Whether or not you chose to provide an application image at deployment time, you need to update the application via CI/CD. The OpenShift documentation has samples that show how to do this update. For more information, see OpenShift Container Platform CI/CD overview.

Configure tests

You must configure any in-container tests against applications to access the new servers running within Azure. As with the CI/CD concerns, you must ensure that the necessary network security rules allow your tests to access the applications deployed to Azure. For more information, see Network security groups.

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. The following articles provide information on post-migration enhancements: