Migrate WebLogic Server applications to Azure Kubernetes Service (AKS)

This guide describes what you should be aware of when you want to migrate an existing WebLogic Server (WLS) application to run on Azure Kubernetes Service (AKS).

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 WLS application to Azure is selecting the most appropriate migration target. WLS runs well on Azure virtual machines (VMs) or Azure Kubernetes Service (AKS). 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 very analogous to what you have on-premises. The trade-off for this ease is economic cost. Generally speaking, the per-minute cost for a VM-based solution is higher compared with AKS. While an AKS-based solution costs less to run, you must constrain your application to fit within the requirements of AKS. If minimizing change is the most important factor for your migration effort, consider a VM-based migration. In this case, see Migrate WebLogic applications to Azure Virtual Machines. If you can tolerate converting your application to run within Kubernetes to reduce runtime cost, consider an AKS-based migration. In this case, continue with Migrate WebLogic Server applications to Azure Kubernetes Service.

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

Once you've decided that AKS is the appropriate deployment target, you must accept that the Oracle WLS Kubernetes operator (the operator) is the only way to run WLS 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.

• Oracle and Microsoft created this offer to allow you to quickly provision WLS on AKS using the Model in Image domain home source type. This concept is explained in more detail later in this article.
• At a high level, the offer automates the following steps for you.
  • Take an existing WAR or EAR deployment, if desired.
  • Wrap it in a container using the WebLogic Image Tool (WIT). For more information, see WebLogic Image Tool in the Oracle documentation.
  • Install and configure the WebLogic Kubernetes Operator on AKS.
  • Use the operator to run the whole thing. The operator invokes WebLogic Deploy Tooling (WDT) to stand up WebLogic environments and perform domain lifecycle operations in a repeatable fashion based on a metadata model. For more information, see WebLogic Deploy Tooling in the Oracle documentation.
• Though the prebuilt offer does provide numerous Azure service integrations, such as App Gateway, Elastic logging, Database integration, and more, it does make many simplifying assumptions. These assumptions make the offer not as flexible as mastering and using the operator yourself.

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 WLS Kubernetes Operator is available at Oracle.

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

Decide whether to use the prebuilt Azure Marketplace offer

First, you have to understand the concept of the WLS "domain". A domain is a logically related group of WLS resources. For the canonical definition of WLS domain, see the Oracle documentation. Running WLS on AKS requires deciding how AKS deals with domains. The various choices are referred to as "domain home source type". The WLS Kubernetes operator supports three choices of domain home source type. The prebuilt Azure Marketplace offer uses the first one in this table.

The operator documentation also includes a useful table comparing the various options. For more information, see Choose a domain home source type.

To get a feel for the prebuilt Azure Marketplace offer, see Quickstart: Deploy WebLogic Server on Azure Kubernetes Service using the Azure portal. For the reference documentation on the prebuilt Azure Marketplace offer, see Oracle.

To get a feel for using the operator directly, try the samples in the operator documentation.

Now that you've been introduced to the various ways to handle WLS domains on AKS, 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 WebLogic version is compatible

Your existing WLS version must be one of the versions supported by the operator. Oracle maintains these versions in the Oracle Container Registry (OCR). Use the following steps to see the list of supported versions.

1. Visit the Oracle Container Registry website and sign in. For more information, see https://container-registry.oracle.com/.
2. If you have a support entitlement, select Middleware, then search for weblogic_cpu. Select weblogic_cpu.
3. If you don't have a support entitlement from Oracle, select Middleware, then search for weblogic. Select weblogic.

The prebuilt Azure Marketplace offer allows you to select the WLS images from OCR and Azure Container Registry (ACR), and thus implicitly supports all of the versions available from OCR. If you direct the offer to pull an image from ACR, make sure it's derived from one of the supported versions listed in OCR.

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'll need this information regardless of the migration path you choose. It's useful, for example, to help guide selection of the size of the VMs in your node pool, the amount of memory to be used by the container, and how many CPU shares the container needs.

It's possible to resize node pools in AKS. To learn how, see Resize node pools in Azure Kubernetes Service (AKS).

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 WebLogic Server, 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 weblogic.xml in your WARs. 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 operator documentation regarding secrets. For more information, see Secrets.

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 install them directly with the prebuilt Azure Marketplace offer. For more information, see TLS/SSL configuration. If you're using the operator directly, see Updating operator external certificates.

Validate that the supported Java version works correctly

All of the migration paths for WebLogic to Azure require a specific Java version, which varies for each path. You'll need to validate that your application is able to run correctly using that supported version.

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

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. Search for JNDI in the offer documentation. If you're using the operator directly, the JDNI resources can be defined depending on your chosen domain home source type. For Domain in PV, you can set them the usual way, with WLST or with the admin console. For Domain in Image or Model in Image, see Typical overrides.

Inspect your domain configuration

The main configuration unit in WebLogic Server is the domain. As such, the config.xml file contains a wealth of configuration that you must carefully consider for migration. The file includes references to additional XML files that are stored in subdirectories. Oracle advises that you should normally use the Administration Console to configure WebLogic Server's manageable objects and services and allow WebLogic Server to maintain the config.xml file. For more information, see Domain Configuration Files.

Inside your application

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

The prebuilt Azure Marketplace offer automatically creates a domain resource. If you're using the operator directly, you can completely customize how your domain is represented. For complete information, see Domain resource.

Determine whether session replication is used

If your application relies on session replication, with or without Oracle Coherence*Web, you have three options:

• Coherence*Web can run alongside a WebLogic Server in the Azure virtual machines, but you must manually configure this option after you provision the offer. If you are using standalone Coherence, you can also run it in an Azure virtual machine, but you must manually configure this option after you provision the offer.
• 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 WebLogic does HTTP Session State Replication. For more information, see HTTP Session State Replication in the Oracle documentation.

The prebuilt Azure Marketplace offer supports session affinity via the Application Gateway ingress controller. Cookie based affinity is enabled by default. You can select Disable cookie based affinity to disable it. Look for cookie based affinity in the documentation for the offer.

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

The prebuilt Azure Marketplace offer has support for most popular databases. For more information, see Database. For Domain in PV, you can set them the usual way, with WLST or with the admin console. For Domain in Image or Model in Image, see Typical overrides.

Determine whether WebLogic 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 setDomainEnv, commEnv, startWebLogic, and stopWebLogic.
• Are there any specific parameters passed to the JVM?
• Are there JARs added to the server classpath?

You need to capture these customizations in the container image run by AKS. For the prebuilt Azure Marketplace offer, such customizations are best handled by creating a custom container image and making it available in Azure Container Registry, then pointing to that registry at deployment time. For more information, see Image selection. If you're using the operator directly, see JVM memory and Java option environment variables.

Determine whether Management over REST is used

If the lifecycle of your application includes using Management over REST, you need to capture which ports are used to access the REST API and determine how they are authenticated and exposed. After migration, you'll need to ensure that these same ports and authentication mechanisms are exposed so your application lifecycle can operate in a similar fashion as before the migration. For more information, see Administering Oracle WebLogic Server with RESTful Management Services.

The only domain home source type where it makes sense to continue to use management over REST is Domain in PV. It's possible to use it with the other domain home source types, but changes made are ephemeral and don't persist across pod restarts.

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'll need 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.

If you're using Oracle Message Broker, you can migrate this software to Azure virtual machines and use it as-is.

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.

These libraries can be handled using the same techniques as described in Determine whether WebLogic has been customized.

Determine whether OSGi bundles are used

If you used OSGi bundles added to the WebLogic server, you'll need to add the equivalent JAR files directly to your web application.

You can include them in the WAR or EAR supplied to the prebuilt Azure Marketplace offer or using the operator directly.

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.

WLS on AKS runs on Oracle Linux. Any OS-specific code must be compatible with Oracle Linux. To learn how to discover specific OS information, follow the steps in Determine whether the WebLogic version is compatible.

Determine whether Oracle Service Bus is in use

If your application is using Oracle Service Bus (OSB), you'll need to capture how OSB is configured. For more information, see About the Oracle Service Bus Installation.

OSB isn't directly supported in the prebuilt Azure Marketplace offer. If you must use OSB, you must use the operator directly.

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 and weblogic-application.xml files and capture their configurations.

The prebuilt Azure Marketplace offer supports WARs and EARs. Using the operator directly also supports WARs and EARs.

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 WebLogic Scripting Tool (WLST) is used

If you currently use WLST to perform your deployment, you'll need to assess what it's doing. If WLST is changing any (runtime) parameters of your application as part of the deployment, you'll need to make sure that this behavior continues to work while testing your application after migration.

The only domain home source type that's compatible with use of WLST is Domain in PV. For more information, see Domain home on a PV.

Determine whether and how the file system is used

Kubernetes deals with filesystems with persistent volumes (PV). Mounting persistent volumes is supported in the prebuilt Azure Marketplace offer, and when using the operator directly. If you're using Domain in PV, the filesystem is a central aspect of configuration.

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 does not cover aspects of your architecture that you need to migrate, you'll need to capture the network topology of your existing deployment and reproduce that in Azure, even after standing up the basic offer with one of the solution templates.

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

• This reference enumerates the high level topics relevant to the migration of network topology to Azure: Fast Track Deployment Guide.
• This reference describes important concerns regarding clustering, which has an impact on network topology: WebLogic Server Clustering.
• Because data sources are separate servers in a WebLogic system, you must consider them as part of the network topology analysis. WebLogic Server Data Sources.
• Messaging sources are also separate servers. WebLogic Server Messaging
• Load balancing is a fundamental requirement. This reference covers the WebLogic Server side of load balancing: Load Balancing in a Cluster.

Account for the use of JCA Adapters and Resource Adapters

If your deployment relies on resource adapters, the most supported option is Domain home on a PV.

Account for the use of custom security providers and JAAS

If your application is using JAAS, you need to make sure the configuration of security providers is correctly migrated. For more information, see About Configuring WebLogic Security Providers in the Oracle documentation.

If your deployment relies security providers, the most supported option is Domain home on a PV.

Determine whether WebLogic clustering is used

The operator handles clustering for all possible ways of running WLS on AKS.

Inspect your EJB clustering

If your application is using local EJB, you need to migrate them to clustered EJB. For more information, see Clustered versus local EJB.

Account for load-balancing requirements

The best way to account for load balancing is to use the App Gateway integration provided by the built-in Azure Marketplace offer. For more information, see Tutorial: Migrate a WebLogic Server cluster to Azure with Azure Application Gateway as a load balancer.

Determine whether the Java EE Application Client feature is used

If your deployment relies on Java EE application clients, it's best to use the operator directly. For more information, see External Clients.

Determine whether multiple container images are needed

A WebLogic Server domain can contain multiple clusters. For example, a multi-tiered application can be represented in a single domain, but have two clusters, say "frontend" and "backend". It's useful to be able to update the frontend, without updating the backend, and vice versa. However, with the Model in Image domain home source type, the entire domain is represented in one container image. To accommodate this use case, you must separate the clusters into their own domains, each with their own container image. The operator can manage multiple domains in multiple namespaces. For more information, see Choose a domain namespace selection strategy

Adopting multiple domains may introduce T3 access problems between domains. To resolve these problems, enable a custom channel as described in Determine whether enabling unknown host access is needed.

Determine whether enabling unknown host access is needed

You may need to enable unknown host access by applying a patch to WebLogic for the following scenarios:

• Allow T3 access from external clients outside AKS to WLS clusters in AKS via a custom channel.
• Allow T3 access between different WLS domains in AKS via a custom channel.

For the details of the patch, follow the guidance in How to Use the Patch Search in My Oracle Support(MOS) and search for patch 30656708.

After the patch is applied, see Enabling unknown host access.

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 https://aka.ms/wlsaks. Select Create, and then follow the instructions in the documentation for the offer. Use the information you gathered in the preceding steps to aid in filling out the fields of the offer.

Migrate the domains

After you've provisioned the offer, output the domain by following these steps.

If you navigated away from the Deployment is in progress page, the following steps show you how to get back to that page. If you're still on the page that shows Your deployment is complete, you can skip to step 5.

1. In the upper left of any portal page, select the hamburger menu and select Resource groups.

2. In the box with the text Filter for any field, enter the first few characters of the resource group you created previously. If you followed the recommended convention, enter your initials, then select the appropriate resource group.

3. In the left navigation pane, in the Settings section, select Deployments to see an ordered list of the deployments to this resource group, with the most recent one first.

4. Scroll to the oldest entry in this list. This entry corresponds to the deployment you started in the preceding section. Select the oldest deployment, as shown in the following screenshot.

   

5. In the left panel, select Outputs. This list shows the output values from the deployment. Useful information is included in the outputs. We're interested in the outputs that allow us to inspect the domain and interact with the operator. The other values in the outputs are explained in detail in the WebLogic on AKS user guide.

6. Locate the output named shellCmdtoConnectAks. Paste the value of the output in a Bash shell and run the command. This command enables you to use kubectl as described in Connect to the cluster.

7. Locate the output named shellCmdtoOutputWlsDomainYaml. Paste the value of the output in a Bash shell and run the command. This command outputs the domain resource as a YAML file.

8. Now that you have the domain YAML of the current deployment, you can apply the knowledge in Deploying domain resource YAML files and review this guidance for more clues on how to migrate the domains. This guidance requires adaptation to apply to the Kubernetes way of doing things, but it's still useful to know about.

Account for KeyStores

You must account for the migration of any SSL 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 Fusion Middleware Administering JMS Resources for Oracle WebLogic Server in the WebLogic documentation.

Account for logging

You can't do cloud without mastering logging. The operator provides samples for using Elasticsearch and Kibana. For more information, see the operator documentation. Azure provides great support for Elastic. For complete details, see What is Elastic integration with Azure?. You can combine the knowledge in these two resources to achieve an Azure-optimized logging solution for WLS on AKS.

Migrating your applications

Whether or not you chose to provide a WAR or EAR file at deployment time, you need to update the application via CI/CD. The operator documentation has a sample that shows how to do this update. For more information, see Update 3. The other update samples are relevant to migration and are worth exploring.

Testing

Any in-container tests against applications must be configured 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:

• Scaling. Dynamic scaling is a key value proposition to justify the complexity of using Kubernetes. Combine the knowledge in Tutorial: Scale applications in Azure Kubernetes Service (AKS) with the operator documentation section Scaling to achieve a WLS-native Kubernetes optimized scaling solution. It's perfectly possible to use popular off-the shelf solutions such as Prometheus and Grafana for scaling with WLS on AKS. For more information, see Using Prometheus and Grafana to Monitor WebLogic Server on Kubernetes. Azure has a managed Grafana service. For details, see What is Azure Managed Grafana?.

• If you deployed WebLogic Server with Azure Application Gateway by following the steps in the offer, you may want to do more configuration on the Application Gateway. For more information, see Application Gateway configuration overview.

• Enhance your network topology with advanced load balancing services. For more information, see Using load-balancing services in Azure.

• Get Java-optimized application performance monitoring with Azure Monitor and Application Insights. For more information, see Zero instrumentation application monitoring for Kubernetes - Azure Monitor Application Insights.

• Use Azure Storage to serve static content mounted to AKS. For more information, see Storage options for applications in Azure Kubernetes Service (AKS). Combine this knowledge with the operator documentation section Providing Access To A Persistent Volume Claim.

• Deploy your applications to your migrated WebLogic cluster with Azure DevOps. For more information, see Azure DevOps getting started documentation.

• Use Azure Managed Identities to managed secrets and assign role based access to Azure resources. For more information, see What are managed identities for Azure resources?.

• Integrate WebLogic Java EE authentication and authorization with Microsoft Entra ID. For more information, see Integrating Microsoft Entra getting started guide.