Edit

Deploy IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift

  • Article

This article shows you how to quickly stand up IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift (ARO) using the Azure portal.

This article uses the Azure Marketplace offer for Open/WebSphere Liberty to accelerate your journey to ARO. The offer automatically provisions several resources including an ARO cluster with a built-in OpenShift Container Registry (OCR), the Liberty Operators, and optionally a container image including Liberty and your application. To see the offer, visit the Azure portal. If you prefer manual step-by-step guidance for running Liberty on ARO that doesn't utilize the automation enabled by the offer, see Deploy a Java application with Open Liberty/WebSphere Liberty on an Azure Red Hat OpenShift cluster.

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

Important

While ARO is jointly engineered, operated, and supported by Red Hat and Microsoft to provide an integrated support experience, the software you run on top of ARO, including that described in this article, is subject to its own support and license terms. For details about support of ARO, see Support lifecycle for Azure Red Hat OpenShift 4. For details about support of the software described in this article, see the main pages for that software as listed in the article.

Note

Azure Red Hat OpenShift requires a minimum of 40 cores to create and run an OpenShift cluster. The default Azure resource quota for a new Azure subscription doesn't meet this requirement. To request an increase to your resource limit, see the section Request an increase for non-adjustable quotas in Increase VM-family vCPU quotas. Because the kind of quota for which you need to request an increase is "non-adjustable", you must file a support ticket. The steps in Request an increase for non-adjustable quotas show you exactly how to file the ticket with the correct content.

The free trial subscription isn't eligible for a quota increase. Upgrade to a Pay-As-You-Go subscription before you request a quota increase. For more information, see Upgrade your Azure free account or Azure for Students Starter account.

Prerequisites

  • A local machine with a Unix-like operating system installed (for example, Ubuntu, macOS, or Windows Subsystem for Linux).
  • The Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
  • Sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade. This article requires at least version 2.31.0 of Azure CLI.

Note

You can also execute this guidance from the Azure Cloud Shell. This approach has all the prerequisite tools pre-installed, with the exception of Docker.

Get a Red Hat pull secret

The Azure Marketplace offer you're going to use in this article requires a Red Hat pull secret. This section shows you how to get a Red Hat pull secret for Azure Red Hat OpenShift. To learn about what a Red Hat pull secret is and why you need it, see the Get a Red Hat pull secret section of Tutorial: Create an Azure Red Hat OpenShift 4 cluster. To get the pull secret for use, follow the steps in this section.

Use your Red Hat account to sign in to the OpenShift cluster manager portal, by visiting the Red Hat OpenShift Hybrid Cloud Console. You might need to accept more terms and update your account as shown in the following screenshot. Use the same password as when you created the account.

Screenshot of Red Hat Update Your Account page.

After you sign in, select OpenShift then Downloads. Select the All categories dropdown list and then select Tokens. Under Pull secret, select Copy or Download to get the value, as shown in the following screenshot.

Screenshot of Red Hat console portal showing the pull secret.

The following content is an example that was copied from the Red Hat console portal, with the auth codes replaced with xxxx...xxx.

{"auths":{"cloud.openshift.com":{"auth":"xxxx...xxx","email":"contoso-user@contoso.com"},"quay.io":{"auth":"xxx...xxx","email":"contoso-user@test.com"},"registry.connect.redhat.com":{"auth":"xxxx...xxx","email":"contoso-user@contoso.com"},"registry.redhat.io":{"auth":"xxxx...xxx","email":"contoso-user@contoso.com"}}}

Save the secret to a file so you can use it later.

Create a Microsoft Entra service principal from the Azure portal

The Azure Marketplace offer you're going to use in this article requires a Microsoft Entra service principal to deploy your Azure Red Hat OpenShift cluster. The offer assigns the service principal with proper privileges during deployment time, with no role assignment needed. If you have a service principal ready to use, skip this section and move on to the next section, where you deploy the offer.

Use the following steps to deploy a service principal and get its Application (client) ID and secret from the Azure portal. For more information, see Create and use a service principal to deploy an Azure Red Hat OpenShift cluster.

Note

You must have sufficient permissions to register an application with your Microsoft Entra tenant. If you run into a problem, check the required permissions to make sure your account can create the identity. For more information, see the Permissions required for registering an app section of Use the portal to create a Microsoft Entra application and service principal that can access resources.

  1. Sign in to your Azure account through the Azure portal.

  2. Select Microsoft Entra ID.

  3. Select App registrations.

  4. Select New registration.

  5. Name the application, for example "liberty-on-aro-app". Select a supported account type, which determines who can use the application. After setting the values, select Register, as shown in the following screenshot. It takes several seconds to provision the application. Wait for the deployment to complete before proceeding.

    Screenshot of Azure portal showing the Register an application page.

  6. Save the Application (client) ID from the overview page, as shown in the following screenshot. Hover the pointer over the value (redacted in the screenshot) and select the copy icon that appears. The tooltip says Copy to clipboard. Be careful to copy the correct value, since the other values in that section also have copy icons. Save the Application ID to a file so you can use it later.

    Screenshot of Azure portal showing service principal client ID.

  7. Create a new client secret by following these steps:

    1. Select Certificates & secrets.
    2. Select Client secrets, then New client secret.
    3. Provide a description of the secret and a duration. When you're done, select Add.
    4. After the client secret is added, the value of the client secret is displayed. Copy this value because you can't retrieve it later.

You now have a Microsoft Entra application, service principal, and client secret.

Deploy IBM WebSphere Liberty or Open Liberty on Azure Red Hat OpenShift

The steps in this section direct you to deploy IBM WebSphere Liberty or Open Liberty on Azure Red Hat OpenShift.

The following steps show you how to find the offer and fill out the Basics pane.

  1. In the search bar at the top of the Azure portal, enter Liberty. In the auto-suggested search results, in the Marketplace section, select IBM Liberty on ARO, as shown in the following screenshot.

    Screenshot of Azure portal showing IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift in search results.

    You can also go directly to the offer with this portal link.

  2. On the offer page, select Create.

  3. On the Basics pane, ensure that the value shown in the Subscription field is the same one that has the roles listed in the prerequisites section.

  4. The offer must be deployed in an empty resource group. In the Resource group field, select Create new and fill in a value for the resource group. Because resource groups must be unique within a subscription, pick a unique name. An easy way to have unique names is to use a combination of your initials, today's date, and some identifier. For example, abc1228rg.

  5. Create an environment variable in your shell for the resource group name.

    export RESOURCE_GROUP_NAME=<your-resource-group-name>

  6. Under Instance details, select the region for the deployment. For a list of Azure regions where OpenShift operates, see Regions for Red Hat OpenShift 4.x on Azure.

  7. After selecting the region, select Next.

The following steps show you how to fill out the ARO pane shown in the following screenshot:

Screenshot of Azure portal showing IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift ARO pane.

  1. Under Create a new cluster, select Yes.

  2. Under Provide information to create a new cluster, for Red Hat pull secret, fill in the Red Hat pull secret that you obtained in the Get a Red Hat pull secret section. Use the same value for Confirm secret.

  3. Fill in Service principal client ID with the service principal Application (client) ID that you obtained in the Create a Microsoft Entra service principal from the Azure portal section.

  4. Fill in Service principal client secret with the service principal Application secret that you obtained in the Create a Microsoft Entra service principal from the Azure portal section. Use the same value for Confirm secret.

  5. After filling in the values, select Next.

The following steps show you how to fill out the Operator and application pane shown in the following screenshot, and start the deployment.

Screenshot of Azure portal showing IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift Operator and application pane.

  1. Under IBM supported?, select Yes.

    Note

    This quickstart deploys the IBM-supported WebSphere Liberty Operator, but you can select No to deploy the Open Liberty Operator instead.

  2. Leave the default option of No for Deploy an application?.

    Note

    This quickstart manually deploys a sample application later, but you can select Yes for Deploy an application? if you prefer.

  3. Select Review + create. Ensure that the green Validation Passed message appears at the top. If the message doesn't appear, fix any validation problems and then select Review + create again.

  4. Select Create.

  5. Track the progress of the deployment on the Deployment is in progress page.

Depending on network conditions and other activity in your selected region, the deployment might take up to 40 minutes to complete.

Verify the functionality of the deployment

The steps in this section show you how to verify that the deployment completed successfully.

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 corner of any portal page, select the hamburger menu and then 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 navigation pane, in the Settings section, select Deployments. You 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.

    Screenshot of Azure portal showing IBM WebSphere Liberty and Open Liberty on Azure Red Hat OpenShift deployments with the oldest deployment highlighted.

  5. In the navigation pane, select Outputs. This list shows the output values from the deployment, which includes some useful information.

  6. Open your terminal and paste the value from the cmdToGetKubeadminCredentials field. You see the admin account and credential for logging in to the OpenShift cluster console portal. The following content is an example of an admin account.

    az aro list-credentials --resource-group abc1228rg --name clusterf9e8b9
{
  "kubeadminPassword": "xxxxx-xxxxx-xxxxx-xxxxx",
  "kubeadminUsername": "kubeadmin"
}

  7. Paste the value from the clusterConsoleUrl field into an Internet-connected web browser, and then press Enter. Fill in the admin user name and password and sign in.

  8. Verify that the appropriate Kubernetes operator for Liberty is installed. In the navigation pane, select Operators, then Installed Operators, as shown in the following screenshot:

    Screenshot of Red Hat OpenShift cluster console portal showing Installed Operators page.

    Take note if you installed the WebSphere Liberty operator or the Open Liberty operator. The operator variant matches what you selected at deployment time. If you selected IBM Supported, you have the WebSphere Liberty operator. Otherwise you have the Open Liberty operator. This information is important to know in later steps.

  9. Download and install the OpenShift CLI oc by following steps in tutorial Install the OpenShift CLI, then return to this documentation.

  10. Switch to Outputs pane, copy the value from the cmdToLoginWithKubeadmin field, and then paste it in your terminal. Run the command to sign in to the OpenShift cluster's API server. You should see output similar to the following example in the console:

    Login successful.

You have access to 71 projects, the list has been suppressed. You can list all projects with 'oc projects'

Using project "default".

Create an Azure SQL Database

The following steps guide you through creating an Azure SQL Database single database for use with your app:

  1. Create a single database in Azure SQL Database by following the steps in Quickstart: Create an Azure SQL Database single database, carefully noting the differences described in the following note. Return to this article after creating and configuring the database server.

    Note

    At the Basics step, write down the values for Resource group, Database name, <server-name>.database.windows.net, Server admin login, and Password. The database Resource group is referred to as <db-resource-group> later in this article.

    At the Networking step, set Connectivity method to Public endpoint, Allow Azure services and resources to access this server to Yes, and Add current client IP address to Yes.

    Screenshot of the Azure portal that shows the Networking tab of the Create SQL Database page with the Connectivity method and Firewall rules settings highlighted.

  2. Create an environment variable in your shell for the resource group name for the database.

    export DB_RESOURCE_GROUP_NAME=<db-resource-group>

Now that you created the database and ARO cluster, you can prepare the ARO to host your WebSphere Liberty application.

Configure and deploy the sample application

Follow the steps in this section to deploy the sample application on the Liberty runtime. These steps use Maven.

Check out the application

Clone the sample code for this guide by using the following commands. 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 20240223
cd 3-integration/connect-db/mssql

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 3-integration/connect-db/mssql/. Here's the file structure of the application:

mssql
├─ src/main/
│  ├─ aro/
│  │  ├─ db-secret.yaml
│  │  ├─ openlibertyapplication.yaml
│  │  ├─ webspherelibertyapplication.yaml
│  ├─ docker/
│  │  ├─ Dockerfile
│  │  ├─ Dockerfile-ol
│  ├─ liberty/config/
│  │  ├─ server.xml
│  ├─ java/
│  ├─ resources/
│  ├─ webapp/
├─ 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, there are three deployment files. db-secret.xml is used to create Kubernetes Secrets with DB connection credentials. The file webspherelibertyapplication.yaml is used in this quickstart to deploy the WebSphere Liberty Application. Use the file openlibertyapplication.yaml to deploy the Open Liberty Application if you deployed Open Liberty Operator in section Deploy IBM WebSphere Liberty or Open Liberty on Azure Red Hat OpenShift.

In the docker directory, there are two files to create the application image with either Open Liberty or WebSphere Liberty. These files are Dockerfile and Dockerfile-ol, respectively. You use the file Dockerfile to build the application image with WebSphere Liberty in this quickstart. Similarly, use the file Dockerfile-ol to build the application image with Open Liberty if you deployed Open Liberty Operator in section Deploy IBM WebSphere Liberty or Open Liberty on Azure Red Hat OpenShift.

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

Build the project

Now that you gathered the necessary properties, you can build the application by using the following commands. The POM file for the project reads many variables from the environment. As part of the Maven build, these variables are used to populate values in the YAML files located in src/main/aro. You can do something similar for your application outside Maven if you prefer.

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

# The following variables are used for deployment file generation into target.
export DB_SERVER_NAME=<server-name>.database.windows.net
export DB_NAME=<database-name>
export DB_USER=<server-admin-login>@<server-name>
export DB_PASSWORD=<server-admin-password>

mvn clean install

(Optional) Test your project locally

You can now run and test the project locally before deploying to Azure by using the following steps. For convenience, we use the liberty-maven-plugin. To learn more about the liberty-maven-plugin, see Building a web application with Maven. For your application, you can do something similar using any other mechanism, such as your local IDE. You can also consider using the liberty:devc option intended for development with containers. You can read more about liberty:devc in the Liberty docs.

  1. Start the application by using liberty:run, as shown in the following example. liberty:run also uses the environment variables defined in the previous section.

    cd ${BASE_DIR}/3-integration/connect-db/mssql
mvn liberty:run

  2. Verify that 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 http://localhost:9080/ or https://localhost:9443/ in your browser and verify the application is accessible and all functions are working.

  3. Press Ctrl+C to stop.

Next, use the following steps to containerize your project using Docker and run it as a container locally before deploying to Azure:

  1. Run the docker build command to build the image.

    cd ${BASE_DIR}/3-integration/connect-db/mssql/target
docker buildx build --platform linux/amd64 -t javaee-cafe:v1 --pull --file=Dockerfile .

  2. Run the image using the following command. Note we're using the environment variables defined previously.

    docker run -it --rm -p 9080:9080 -p 9443:9443 \
    -e DB_SERVER_NAME=${DB_SERVER_NAME} \
    -e DB_NAME=${DB_NAME} \
    -e DB_USER=${DB_USER} \
    -e DB_PASSWORD=${DB_PASSWORD} \
    javaee-cafe:v1

  3. Once the container starts, go to http://localhost:9080/ or https://localhost:9443/ in your browser to access the application.

  4. Press Ctrl+C to stop.

Build image and push to the image stream

When you're satisfied with the state of the application, you build the image remotely on the cluster by using the following steps.

  1. Use the following commands to identity the source directory and the Dockerfile:

    cd ${BASE_DIR}/3-integration/connect-db/mssql/target

# If you are deploying the application with WebSphere Liberty Operator, the existing Dockerfile is ready for you

# If you are deploying the application with Open Liberty Operator, uncomment and execute the following two commands to rename Dockerfile-ol to Dockerfile
# mv Dockerfile Dockerfile.backup
# mv Dockerfile-ol Dockerfile

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

    oc create imagestream javaee-cafe

  3. 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-config --binary --strategy docker --to javaee-cafe:v1

  4. 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-config --from-dir . --follow

Deploy and test the application

Use the following steps to deploy and test the application:

  1. Use the following command to apply the DB secret:

    cd ${BASE_DIR}/3-integration/connect-db/mssql/target
oc apply -f db-secret.yaml

    You should see the output secret/db-secret-mssql created.

  2. Use the following command to apply the deployment file:

    oc apply -f webspherelibertyapplication.yaml

  3. Wait until all pods are started and running successfully by using the following command:

    oc get pods -l app.kubernetes.io/name=javaee-cafe --watch

    You should see output similar to the following example to indicate that all the pods are running:

    NAME                          READY   STATUS    RESTARTS   AGE
javaee-cafe-67cdc95bc-2j2gr   1/1     Running   0          29s
javaee-cafe-67cdc95bc-fgtt8   1/1     Running   0          29s
javaee-cafe-67cdc95bc-h47qm   1/1     Running   0          29s

  4. Use the following steps to verify the results:

    1. Use the following command to get the host of the Route resource deployed with the application:

      echo "route host: https://$(oc get route javaee-cafe --template='{{ .spec.host }}')"

    2. Copy the value of route host from the output, then open it in your browser to test the application. If the web page doesn't render correctly, that's because the app is still starting in the background. Wait for a few minutes and then try again.

    3. Add and delete a few coffees to verify the functionality of the app and the database connection.

      Screenshot of the running app.

Clean up resources

To avoid Azure charges, you should clean up unnecessary resources. When the cluster is no longer needed, use the az group delete command to remove the resource group, ARO cluster, Azure SQL Database, and all related resources.

az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait
az group delete --name $DB_RESOURCE_GROUP_NAME --yes --no-wait

Next steps

Learn more about deploying IBM WebSphere family on Azure by following these links:

What are solutions to run the IBM WebSphere family of products on Azure?