Edit

Migrate WebSphere applications to Azure Virtual Machines

  • Article

This guide describes what you should be aware of when you want to migrate an existing WebSphere Application Server (WAS) traditional application to run on Azure Virtual Machines. For an overview of available WAS traditional solutions in Azure Marketplace, see What are solutions to run the IBM WebSphere family of products on Azure?

Pre-migration

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

Define what you mean by "migration complete"

This guide, and the corresponding Azure Marketplace offers, are a starting point to accelerate the migration of your WAS traditional workloads to Azure. It's important to define the scope of your migration effort. For example, are you doing a strict "lift and shift" from your existing infrastructure to Azure Virtual Machines? If so, you may be tempted to work in some "lift and improve" as you migrate.

It's better to stick as close to pure "lift and shift" as possible, accounting for the necessary changes as detailed in this guide. Define what you mean by "migration complete" so that you know when you've reached this milestone. When you've reached your "migration complete", you can take a snapshot of your Virtual Machines as described in Create a snapshot of a virtual hard disk. After you've verified that you can successfully restore from your snapshot, you can do the improvements without fear of losing the migration progress you've achieved thus far.

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 offers are a good starting point

IBM and Microsoft have partnered to bring a set of Azure solution templates to Azure Marketplace to provide a solid starting point for migrating to Azure. For the list of offers, see Run the WebSphere family of products and Liberty on Microsoft Azure, and then choose the one that most closely matches your existing deployment. You can see the list of offers in the overview article What are solutions to run the IBM WebSphere family of products on Azure?

If none of the existing offers are a good starting point, you have to reproduce the deployment by hand using Azure Virtual Machine resources. You can find the step-by-step guidance in Tutorial: Manually install IBM WebSphere Application Server Network Deployment traditional on Azure Virtual Machines. For more information, see What is IaaS?

Determine whether the WAS traditional version is compatible

Your existing WAS traditional version must be compatible with the version in the IaaS offers. You can find the version information from the overview page of IBM WebSphere Application Server Single Instance on Azure VM and IBM WebSphere Application Server Cluster on Azure VMs. If your existing WAS traditional version isn't compatible with that version, you have to reproduce the deployment by hand using Azure IaaS resources. For more information, see What is IaaS?

Inventory server capacity

Document the hardware (memory, CPU, disk) of the current production server(s) as well as the average and peak request counts and resource utilization. This information must inform the choice of VM size. For more information, see Sizes for Cloud Services.

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.

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>

For more information, see the IBM document Certificate management in SSL

Validate that the supported Java version works correctly

Using WAS on Azure Virtual Machines requires a specific version of Java, so you need to confirm that your application runs correctly using that supported version.

IBM Java 8 comes with the WAS9 distribution. We recommend using the IBM-provided Java JRE. For more information, see Java SE 8 in WebSphere Application Server traditional V9.

If you want to switch to a different Java SDK, follow the IBM document Switching the Java SDK in WebSphere Application Server.

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.

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 more XML files that are stored in subdirectories. IBM advises that you should normally use the IBM Console to configure WAS's manageable objects and services, and allow WAS to maintain the profiles/profile-name folder. 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.

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 memory 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 memory-to-memory replication or a database.
  • 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 WAS does HTTP Session State Replication. For more information, see Administering session beans in the IBM 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 WAS, see Using JDBC Drivers with WebSphere Application Server.

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.

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 Choose a solution for connecting 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 JMS with Azure Service Bus 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.

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.

Determine whether your application contains OS-specific code

If your application contains any code with dependencies on the host OS, then you'll 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.

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.

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.

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

VM filesystems operate the same way as on-premises filesystems with respect to persistence, startup, and shutdown. Even so, it's important to be aware of your filesystem needs and ensure the VMs have adequate storage size and performance.

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. You can also directly deploy the static content to an app in the Azure Spring Apps Enterprise plan. For more information, see Deploy web static files.

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. You can also directly deploy the static content to an app in the Azure Spring Apps Enterprise plan. For more information, see Deploy web static files.

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 network 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 other resource adapters to connect to other enterprise systems, ensure that you apply the configuration for these artifacts to the WAS running in Azure Virtual Machines. For more information, see Relational resource adapters and JCA in the IBM documentation.

Account for authentication and authorization

Most applications have some kind of authentication and authorization. If you use OpenID for authentication, you can configure OpenID connect authentication with Microsoft Entra ID. For more information, see OpenID Connect authentication with Microsoft Entra ID.

Determine whether WAS clustering is used

Most likely, you've deployed your application on multiple WAS servers to achieve high availability. You can migrate these clusters directly from your on-premises installation to WAS running in Azure Virtual Machines. For more information, see WebSphere Application Server Network Deployment in the IBM documentation.

Account for load-balancing requirements

Load balancing is an essential part of migrating your WAS cluster to Azure. The easiest solution is to use the built-in support for Azure Application Gateway or IBM HTTP Server provided in the Azure Marketplace offer for IBM WebSphere Application Server Cluster.

For a summary of the capabilities of Azure Application Gateway compared to other Azure load-balancing solutions, see Load-balancing options.

Determine whether the Java EE Application Client feature is used

If your application uses the Java EE Application Client feature, it should continue to work unchanged after migrating to Azure Virtual Machines. For more information, see Using Java EE Client Application Modules.

Migration

Select a WAS traditional on Azure Virtual Machines offer

The following offers are available for WAS on Azure Virtual Machines.

During the deployment of an offer, you're asked to choose the virtual machine size for your WAS nodes. It's important to consider all aspects of sizing (memory, processor, disk) in your choice of VM size. For more information, see Sizes for Cloud Services (classic).

Provision the offer

After you've selected which offer to start with, provision that offer by following the instructions in Deploy WebSphere Application Server (traditional) Cluster on Azure Virtual Machines.

Migrate the profiles

After you've provisioned the offer, you can examine the profile configuration. For more information, see Profile concepts in the IBM documentation.

Connect the databases

After you've migrated the profiles, you can connect the databases by following the instructions in Configuring the WebSphere Application Server data source in the IBM documentation.

Account for KeyStores

You must account for the migration of any SSL KeyStores used by your application. For more information, see Keystore configurations for SSL in the IBM documentation.

Connect the JMS sources

After you've connected the databases, you can configure JMS by following the instructions at Setting up JMS in IBM WebSphere Application Server in the IBM documentation.

Account for authentication and authorization

Most applications have some kind of authentication and authorization. If you use OpenID for authentication, you can configure OpenID connect authentication with Microsoft Entra ID. For more information, see OpenID Connect authentication with Microsoft Entra ID.

Account for logging

You can configure Elastic Stack by following the instructions at Analyzing WebSphere Application Server logs with Elastic Stack in the IBM documentation. Azure provides support for Elastic. For more information, see What is Elastic integration with Azure? You can combine the knowledge in these two resources to achieve an Azure-optimized logging solution for WAS on VMs.

Migrating your applications

The techniques used to deploy applications from the development team into test, staging, and production servers vary greatly from case to case. In some cases, there's a highly evolved CI/CD platform that results in the applications being deployed to the WebSphere Application Server. In other cases, the process can be more manual. One benefit of using Azure Virtual Machines to migrate WAS traditional applications to the cloud is that your existing processes continue to work.

You have to configure the Network Security Group that the offer provisions to allow access from your CI/CD pipeline, or manual deployment system. For more information, see Network security groups.

Testing

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 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. For guidance on some potential post-migration enhancements, see the following recommendations: