Manually deploy a Java application with Open Liberty/WebSphere Liberty on an Azure Red Hat OpenShift cluster

This article provides step-by-step manual guidance for running Open/WebSphere Liberty on an Azure Red Hat OpenShift cluster. It walks you through preparing a Liberty application, building the application Docker image and running the containerized application on an Azure Red Hat OpenShift cluster.

Specifically, you learn how to accomplish the following tasks:

For a more automated solution that accelerates your journey to Azure Red Hat OpenShift cluster, see Deploy IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift using Azure Marketplace offer.

For more information on Open Liberty, see the Open Liberty project page. For more information on WebSphere Liberty, see the WebSphere Liberty product page.

This article is intended to help you quickly get to deployment. Before going to production, you should explore Tuning Liberty.

If you're interested in providing feedback or working closely on your migration scenarios with the engineering team developing WebSphere on Azure solutions, fill out this short survey on WebSphere migration and include your contact information. The team of program managers, architects, and engineers will promptly get in touch with you to initiate close collaboration.

Prerequisites

• A local machine with Unix-like operating system installed - for example, Ubuntu, macOS, or Windows Subsystem for Linux.

• A Java Standard Edition (SE) implementation, version 17 - for example, Eclipse Open J9.

• Maven, version 3.9.8 or higher.

• Docker for your OS.

• Azure CLI, version 2.61.0 or later.

• An Azure Red Hat OpenShift 4 cluster. To create the cluster, follow the instructions in Create an Azure Red Hat OpenShift 4 cluster while using the following instructions:

  • Though the "Get a Red Hat pull secret" step is labeled as optional, it's required for this article. The pull secret enables your Azure Red Hat OpenShift cluster to find the Open Liberty Operator.

  • The following environment variables defined in Create an Azure Red Hat OpenShift 4 cluster are used later in this article:

    • RESOURCEGROUP - the name of the resource group in which the cluster is deployed.
    • CLUSTER- the name of the cluster.

  • If you plan to run memory-intensive applications on the cluster, specify the proper virtual machine size for the worker nodes using the --worker-vm-size parameter. For more information, see the following articles:

    • Azure CLI to create a cluster
    • Supported virtual machine sizes for memory optimized

• Connect to the cluster by following the steps in Connect to an Azure Red Hat OpenShift 4 cluster while using the following instructions:

  • Be sure to follow the steps in "Install the OpenShift CLI" because you use the oc command later in this article.
  • Save aside the cluster console URL. It should look like https://console-openshift-console.apps.<random>.<region>.aroapp.io/.
  • Take note of the kubeadmin credentials.
  • Be sure to follow the steps in "Connect using the OpenShift CLI" with the kubeadmin credentials.

Install the Open Liberty OpenShift Operator

After you create and connect to the cluster, use the following steps to install the Open Liberty Operator. The main starting page for the Open Liberty Operator is on GitHub.

1. Sign in to the OpenShift web console from your browser using the kubeadmin credentials.

2. Navigate to Operators > OperatorHub and search for Open Liberty.

3. Select Open Liberty from the search results.

4. Select Install.

5. On the Install Operator page, use the following steps:

   1. For Update channel, select the latest channel v1.4.
   2. For Installation mode, seelct All namespaces on the cluster (default).
   3. For Update approval, select Automatic.

   

6. Select Install and wait a few minutes until the installation completes.

7. Observe that the Open Liberty Operator is successfully installed and ready for use. If it isn't ready, diagnose and resolve the problem before continuing.

   

Create an OpenShift namespace for the Java app

Use the following steps to create an OpenShift namespace for use with your app:

1. Make sure you signed in to the OpenShift web console from your browser using the kubeadmin credentials.

2. Navigate to Administration > Namespaces > Create Namespace.

3. Fill in open-liberty-demo for Name and select Create, as shown next.

   

Create an Azure Database for MySQL Flexible Server

Azure Database for MySQL Flexible Server deployment model is a deployment mode designed to provide more granular control and flexibility over database management functions and configuration settings than the Azure Database for MySQL single server deployment mode. This section shows you how to create an Azure Database for MySQL Flexible Server instance using the Azure CLI. For more information, see Quickstart: Create an instance of Azure Database for MySQL - Flexible Server by using the Azure CLI.

Run the following command in your terminal to create an Azure Database for MySQL Flexible Server instance. Replace <server-admin-password> with a password that meets the password complexity requirements for Azure Database for MySQL Flexible Server.

az mysql flexible-server create \
    --name ${CLUSTER} \
    --resource-group ${RESOURCEGROUP} \
    --admin-user admin${RESOURCEGROUP} \
    --admin-password '<server-admin-password>' \
    --database-name ${RESOURCEGROUP}db \
    --public-access 0.0.0.0 \
    --yes

az mysql flexible-server list-skus --location <location>

It takes a few minutes to create the server, database, admin user, and firewall rule that accepts connections from all Azure resources. If the command is successful, the output looks similar to the following example:

{
  "connectionString": "mysql <database-name> --host <server-name>.mysql.database.azure.com --user <server-admin-username> --password=<server-admin-password>",
  "databaseName": "<database-name>",
  "firewallName": "AllowAllAzureServicesAndResourcesWithinAzureIps_2024-7-10_16-22-8",
  "host": "<server-name>.mysql.database.azure.com",
  "id": "/subscriptions/REDACTED/resourceGroups/<resource-group-of-the-OpenShift-cluster>/providers/Microsoft.DBforMySQL/flexibleServers/<server-name>",
  "location": "West US",
  "password": "<server-admin-password>",
  "resourceGroup": "<resource-group-of-the-OpenShift-cluster>",
  "skuname": "Standard_B1ms",
  "username": "<server-admin-username>",
  "version": "5.7"
}

Prepare the Liberty application

We use a Java EE 8 application as our example in this guide. Open Liberty is a Java EE 8 full profile compatible server, so it can easily run the application. Open Liberty is also Jakarta EE 8 full profile compatible.

Run the application on Open Liberty

To run the application on Open Liberty, you need to create an Open Liberty server configuration file so that the Liberty Maven plugin can package the application for deployment. The Liberty Maven plugin isn't required to deploy the application to OpenShift. However, we use it in this example with Open Liberty's developer (dev) mode. Developer mode lets you easily run the application locally. To learn more about the liberty-maven-plugin, see Building a web application with Maven.

Follow the steps in this section to prepare the sample application for later use in this article. These steps use Maven and the liberty-maven-plugin.

Check out the application

Use the following commands to clone the sample code for this guide. The sample is on GitHub.

git clone https://github.com/Azure-Samples/open-liberty-on-aro.git
cd open-liberty-on-aro
export BASE_DIR=$PWD
git checkout 20240920
cd ${BASE_DIR}/3-integration/connect-db/mysql

If you see a message about being in "detached HEAD" state, this message is safe to ignore. It just means you checked out a tag.

There are a few samples in the repository. We use open-liberty-on-aro/3-integration/connect-db/mysql. Here's the file structure of the application:

open-liberty-on-aro/3-integration/connect-db/mysql
├─ src/main/
│  ├─ aro/
│  │  ├─ db-secret.yaml
│  │  ├─ openlibertyapplication.yaml
│  ├─ liberty/config/
│  │  ├─ server.xml
│  ├─ java/
│  ├─ resources/
│  ├─ webapp/
├─ Dockerfile
├─ Dockerfile-wlp
├─ pom.xml

The directories java, resources, and webapp contain the source code of the sample application. The code declares and uses a data source named jdbc/JavaEECafeDB.

In the aro directory, we placed two deployment files. db-secret.xml is used to create Secrets with database connection credentials. The file openlibertyapplication.yaml is used to deploy the application image.

In the root directory, we placed two Dockerfiles. Dockerfile and Dockerfile-wlp are used for local debugging and to build the image for an Azure Red Hat OpenShift deployment, working with Open Liberty and WebSphere Liberty, respectively.

In the liberty/config directory, the server.xml is used to configure the database connection for the Open Liberty and WebSphere Liberty cluster.

Build the project

Using the environment variables defined previously, run the following commands in your terminal to build the project. The POM file for the project reads many properties from the environment.

cd ${BASE_DIR}/3-integration/connect-db/mysql

# The following variables are used for deployment file generation
export DB_SERVER_NAME=$CLUSTER.mysql.database.azure.com
export DB_PORT_NUMBER=3306
export DB_NAME=${RESOURCEGROUP}db
export DB_USER=admin${RESOURCEGROUP}
export DB_PASSWORD='<server-admin-password>'
export NAMESPACE=open-liberty-demo

mvn clean install

(Optional) Test your application locally

Optionally, you can run the application locally to verify that it works as expected. First, you need to add a firewall rule to allow your local machine to connect to the Azure Database for MySQL Flexible Server instance. Use the following steps to add the firewall rule:

1. Sign in to the Azure portal and navigate to the Azure Database for MySQL Flexible Server instance you created earlier.
2. In the left pane, select Settings > Networking.
3. Select Add current client IP address.
4. Select Save and wait for the firewall rule to be added.

Use the following steps to run the liberty:devc command to locally run and test the project and container image before dealing with any Azure complexity. For more information on liberty:devc, see the Liberty Plugin documentation.

1. Start your local Docker environment if needed. The instructions for doing this vary depending on the host operating system.

2. Use the following commands to start the application in liberty:devc mode:

   cd ${BASE_DIR}/3-integration/connect-db/mysql
   
   # If you are running with Open Liberty
   mvn liberty:devc -DcontainerRunOpts="-e DB_SERVER_NAME=${DB_SERVER_NAME} -e DB_PORT_NUMBER=${DB_PORT_NUMBER} -e DB_NAME=${DB_NAME} -e DB_USER=${DB_USER} -e DB_PASSWORD=${DB_PASSWORD}" -Dcontainerfile=Dockerfile
   
   # If you are running with WebSphere Liberty
   mvn liberty:devc -DcontainerRunOpts="-e DB_SERVER_NAME=${DB_SERVER_NAME} -e DB_PORT_NUMBER=${DB_PORT_NUMBER} -e DB_NAME=${DB_NAME} -e DB_USER=${DB_USER} -e DB_PASSWORD=${DB_PASSWORD}" -Dcontainerfile=Dockerfile-wlp
   

3. Verify the application works as expected. You should see a message similar to [INFO] [AUDIT] CWWKZ0003I: The application javaee-cafe updated in 1.930 seconds. in the command output if successful. Go to https://localhost:9443/ in your browser and verify the application is accessible and all functions are working.

4. To stop liberty:devc mode, press Control+C.

Prepare the application image

To deploy and run your Liberty application on an Azure Red Hat OpenShift cluster, containerize your application as a Docker image using Open Liberty container images or WebSphere Liberty container images.

Build the application and push to the image stream

Since you already successfully ran the app in the Liberty Docker container using the liberty:devc command, you're going to build the image remotely on the cluster by using the following steps:

1. Make sure you sign in to the OpenShift CLI using the kubeadmin credentials.

2. Use the following commands to identify the source directory and Dockerfile:

   cd ${BASE_DIR}/3-integration/connect-db/mysql
   
   # If you are building with the Open Liberty base image, the existing Dockerfile is ready for you
   
   # If you are building with the WebSphere Liberty base image, uncomment and execute the following two commands to rename Dockerfile-wlp to Dockerfile
   # mv Dockerfile Dockerfile.backup
   # mv Dockerfile-wlp Dockerfile
   

3. Use the following command to change project to open-liberty-demo:

   oc project open-liberty-demo
   

4. Use the following command to create an image stream:

   oc create imagestream javaee-cafe-mysql
   

5. Use the following command to create a build configuration that specifies the image stream tag of the build output:

   oc new-build --name javaee-cafe-mysql-config --binary --strategy docker --to javaee-cafe-mysql:v1
   

6. Use the following command to start the build to upload local contents, containerize, and output to the image stream tag specified before:

   oc start-build javaee-cafe-mysql-config --from-dir . --follow
   

Deploy application on the Azure Red Hat OpenShift cluster

Now you can deploy the sample Liberty application to the Azure Red Hat OpenShift cluster you created earlier when working through the prerequisites.

oc delete -f openlibertyapplication.yaml
oc delete -f db-secret.yaml

Clean up resources

Delete the Azure Red Hat OpenShift cluster by following the steps in Tutorial: Delete an Azure Red Hat OpenShift 4 cluster. Make sure the database and any associated resources are deleted too.

Next steps

You can learn more from references used in this guide:

• Open Liberty
• Azure Red Hat OpenShift
• Open Liberty Operator
• Open Liberty Server Configuration
• Liberty Maven Plugin
• Open Liberty Container Images
• WebSphere Liberty Container Images

To explore options to run WebSphere products on Azure, see What are solutions to run the WebSphere family of products on Azure?