These days it’s nearly impossible to come across an architecture roadmap that doesn’t mention microservices, containers, or cloud. Companies understand the value in deploying these smaller, portable applications in orchestration frameworks that natively provide essential services, either on private cloud or public cloud environments.

This article will demonstrate how you to can deploy Java Open API microservices. We will package an OpenAPI v3 microservice on to a WebSphere Liberty Docker container. We will then deploy the Docker container into various flavours of the open source Kubernetes orchestration framework.

Ready? Let’s go!

WebSphere Liberty in a container

The first thing we need is to package an application and corresponding configuration into a WebSphere Liberty container. By far the most used type of container is a Docker container, which is supported by a vibrant community. It allows developers to package the entire stack of their application (including the operating system, language runtimes, and libraries, configurations, etc). This helps to ensure that the same software is being run in all stages of the application: Dev, QA, production, etc. You can find out more about the basics of Docker containers on the Docker website.

For this article, we’ll use a sample OpenAPI v3 application that we have made available as open source. This application contains a basic set of RESTful endpoints that have been augmented with new OpenAPI v3 annotations, producing a very nice OpenAPI user interface as output.

After installing Docker, simply download the packaged application and its server.xml configuration file. Then run this simple Dockerfile:

FROM websphere-liberty:kernel
COPY server.xml  /config/
COPY airlines.war /config/apps/ 
RUN installUtility install --acceptLicense defaultServer

Good job! You now have a Docker image that encapsulates an OpenAPI v3 application running in WebSphere Liberty! You can create a free account on Docker Hub and push that container image into it.

If you want to do a quick run of this container before proceeding, in a terminal run docker run --name openapi -d -p 80:9080 myrepo/websphere-liberty. Point your browser to http://localhost/api/explorer/ to see the new OpenAPI v3 UI! Stop the container by running docker stop openapi.

Helm charts

As we hinted at the beginning of this article, Kubernetes is an open-source container orchestration framework that helps you manage container deployments. It is run by a very large community of developers and supported by all major cloud companies (IBM being one of the main supporters). There are some cool interactive tutorials to get you more familiar with the framework.

In Kubernetes there are different ways to deploy containers. One of the most common, and easiest, is to utilize a Helm chart that has a set of pre-configured values that can be overridden for customized deployments.

IBM has open sourced a vast amount of Helm charts available on this repository.

For this article we will focus on the WebSphere Liberty Helm chart, which helps you deploy your microservice Java application by making it easy to configure things such auto-scaling, transaction logs, and ingress exposure.

We will be working with this chart for the rest of this article so you need two command line tools: helm client and kubectl client.

The kubectl (short for “kube control”) client allows you to interact with a remote Kubernetes cluster while the helm client allows you to install Helm charts into that cluster underneath the covers using kubectl.

Environment 1: Minikube

Most developers working with Kubernetes will have Minikube installed in their laptops. It is a light (but pretty complete) version of Kubernetes, meant to give developers a local platform to work with.

After installing minikube, simply run minikube start to configure your kubectl client. Now you have a direct connection to the local VM running Minikube.

To use the WebSphere Liberty Helm chart we first must initiate the server side of Helm, which is called Tiller. Do so by running helm init and you should see a message such as “Tiller (the helm server side component) has been installed into your Kubernetes Cluster”.

The next step is to add IBM’s Helm chart repository: helm repo add ibm-charts

Now you are all set to deploy WebSphere Liberty containers using this chart! There are many default values that can be overridden. For this example we will override the container being deployed as well as the autoscaling default values:

helm install --name openapi --set image.repository=myrepo/websphere-liberty --set resources.constraints.enabled=true --set autoscaling.enabled=true --set autoscaling.minReplicas=2 ibm-charts/ibm-websphere-liberty

You just deployed an OpenAPI v3 containerized WebSphere Liberty application with an autoscaling policy that will keep a minimum of two pods alive at all times and scale those up to 10 pods depending on their CPU utilization. Very cool!

Run kubectl get services to get a list of the currently deployed service. For example:

NAME                       CLUSTER-IP   EXTERNAL-IP   PORT(S)          AGE
kubernetes                    443/TCP          6h
openapi-ibm-websphere-li          9080:31619/TCP   3h

In the example above, the service we just deployed is called openapi-ibm-websphere-li. To see this application in your browser, run minikube service openapi-ibm-websphere-li --url to get the application’s base address. Append /api/explorer to it and you should see the awesome OpenAPI UI…running in a Kubernetes cluster on your laptop!

For more information about Minikube, see the Minikube official docs.

Environment 2: IBM Cloud Private

Now that your containerized WebSphere Liberty application is working in your Minikube environment, you are ready to deploy into a fully matured and secure on-premises Kubernetes environment. You can view Minikube as a development environment where you run your microservice in isolation, and IBM Cloud Private as your production-grade Kubernetes environment where all the microservices from your enterprise come together—providing and consuming services.

To install and learn more about IBM Cloud private, see the IBM Cloud Private official documentation.

Once installed, you’ll see this nice user interface:

At this point you could set up your kubectl client to point to the IBM Cloud Private cluster by clicking Configure client and then use the same helm instructions from section #1 (Minikube) to add and deploy the ibm-websphere-liberty Helm chart:

However, it is even easier than that! IBM Cloud Private has a Catalog section that is pre-loaded with IBM’s official Helm charts:

Click that Helm chart to see a rendered documentation table explaining the different values, and then click Configure to move to the configuration page where you can override the default values of the Helm chart. So, as you can see, it’s everything that you did in the command-line in Minikube but with a nice user interface.

Pick the same values as in section #1 for consistency, then click Install:

Release name: openapi 
image.repository: myrepo/websphere-liberty 
resources.constraints.enabled: true
autoscaling.enabled: true
autoscaling.minReplicas: 2

Under “Workloads -> Helm releases” you will find your “openapi” release. Scroll down the page for the details, such as the auto-scaling information:

Scroll down further to the deployment section and click its link. The deployment-details page opens and you can view your deployed container by clicking access liberty:

You’ll see the WebSphere welcome page show up. Append api/explorer to that URL and you’ll see the nice OpenAPI UI you saw in Minikube. This time, though, it is running in a robust enterprise-wide IBM Cloud Private cluster! Your colleagues can now connect their microservices with yours, tapping into your REST APIs to obtain valuable systems-of-record information.

Environment 3: IBM Cloud

IBM Cloud (previously known as Bluemix) offers a container service in the public (yet still very secured) space. It is also based entirely on Kubernetes, which enables a smooth transition of applications between IBM Cloud Private and IBM Cloud.

In your API journey, you may want to push new systems-of-interaction applications into IBM Cloud, which aggregate various back-end calls to APIs running inside IBM Cloud Private and exposes them as composed APIs to application developers. For enhanced API management and gateway capabilities, check out API Connect, which works in either IBM Cloud and IBM Cloud Private.

To get started, log in or create a free account in IBM Cloud and go into the Containers section of the dashboard. Click the Create a cluster button, and then follow the wizard to set up the region and other details of the deployment.

When your cluster is ready (times may vary), you will see a nice dashboard with its summary. Here’s a screenshot of our sample light cluster:

Click the left menu item called Access for the instructions on how to set up access to your cluster from command line. You’ll need two tools: kubectl (which you’ve already set up in this article) and bx, which allows you to connect to the IBM Cloud environment and interact with your Kubernetes cluster using the sub-command bx cs.

When you have your command line kubectl bridge set up, you might be wondering: Wouldn’t it be nice if I could use the same ibm-websphere-liberty Helm chart I used in the previous two scenarios?

The answer is: Yes, you can!

Just like in the Minikube scenario, set up your Helm bridge, add the official IBM Helm repository, and deploy a WebSphere Liberty application using its Helm chart:

helm init 
helm repo add ibm-charts
helm install --name openapi --set image.repository=myrepo/websphere-liberty --set resources.constraints.enabled=true --set autoscaling.enabled=true --set autoscaling.minReplicas=2 ibm-charts/ibm-websphere-liberty

Simple and consistent! Since we’re using the light, free cluster, only the NodePort service type is available. If you wish to set up Ingress or LoadBalancer services you need the subscription-based cluster.

To get the URL of the application you just deployed, you just need to find out two things:

  1. The public IP of your worker node by running bx cs workers <cluster_name>
  2. The NodePort that was assigned to your service:
    kubectl get services
    kubectl describe services <service-name>

Here’s a sample output:

Open a browser and navigate to <worker_IP>:<service_NodePort>/api/explorer and you will see the same OpenAPI application, running in the public IBM Cloud!

For more information on working with your deployed application, see the Bluemix docs.

Environment 3.1: Cloud Foundry

Although the current IBM Cloud version of Cloud Foundry is not using Kubernetes nor Docker containers, it’s worth noting that the exact same application and configuration can be pushed into that PaaS environment using a custom buildpack to enable the OpenAPI v3 functionality. Check out our running live example and the corresponding lab instructions on how to get there!


In this article, you successfully deployed WebSphere Liberty’s Helm chart into three Kubernetes environments: Minikube, IBM Cloud Private, and IBM Cloud. You saw the consistency of being able to deploy the exact same Docker image using the exact same Helm chart across all of them. This provides you with the certainty that you can move and integrate legacy applications within a hybrid cloud environment.

Updated 2018-06-14 to update link URLs and remove mention of the free cluster.

Join The Discussion

Your email address will not be published. Required fields are marked *