Using an umbrella helm chart to deploy the composite IBM Stock Trader sample

Let’s dive in to how to deploy and run our Cloud Native sample application.

First, let’s take a look at all of the pieces of this composite application. This diagram has evolved over time, as we have added additional pieces to demonstrate various cloud native technologies.

In the past, people deployed each microservice individually, using the manifests/deploy.yaml in each of the repositories under https://github.com/IBMStockTrader, and manually defining a whole bunch of secrets needed to connect to each prerequisite. While that manual per-microservice approach is still possible, and might be desirable when developing and debugging one of the microservices, it is not the best story for those just wishing to use this as if it were an “off the shelf” application, as it is far too complicated, especially around defining the configuration needed by each microservice. To dramatically simplify this, we are now ready to debut our new helm chart for this composite application. Unlike other helm charts you might have seen generated for a specific microservice, this “umbrella” helm chart will deploy all of the microservices at once, grouped as a helm release, and will take care of configuring everything, like connections to prerequisite middleware.

That may look scary at first. The good news is, most of what’s there is optional, only needed for certain bells and whistles within the app. The only mandatory pieces are Trader, Portfolio, StockQuote, DB2, and the connection to API Connect. Just those pieces will be enough to create portfolios, buy stock for them, and see the portfolio details. So those are the things that you MUST configure when using the helm chart; everything else is optional and can be skipped, unless you want specialized functionality. All of the defaults for each of those microservices will generally be sufficient, so the only real thing you need to focus on is configuring the connection to DB2.

You have choices for DB2:

1. Deploy DB2 into your Kubernetes cluster

2. Use an on-premises DB2

3. Use DB2-as-a-Service in the public cloud

Generally we do #1, though we have tested all three approaches and everything has worked fine each way. The good news is, neither the source code, nor anything else in the Docker container, changes depending on your choice. All that changes is what fields are placed in the corresponding config map or secret. And each of those fields are asked for in the helm chart. Here’s a teaser of that section of the helm chart (which, to be clear, doesn’t install such prerequisites — it just helps you configure a connection to them):

Let’s walk through actually deploying that helm chart now. We’ll use IBM Cloud Private (ICP) as our example for this blog. But the approach would be very similar for other Kubernetes distributions that support Helm (in some cases, you may need to deploy Tiller, like if on OpenShift, to use Helm there). Login to the ICP console, and choose Manage->Helm Repositories:

Note that I am hosting my own helm repository inside my GitHub repository, to simplify things. If you prefer, you can clone the GitHub repo and then cd into it and do your own “helm package stocktrader” to build the .tgz file yourself and then use “cloudctl catalog load-chart” against that tgz. But here, we’ll just use the helm repo directly instead, as that’s easier.

In the first field of the dialog, enter whatever name you like for this new helm repository, such as “cloud-native-sample”. In the second field, enter the following URL:

https://raw.githubusercontent.com/IBMStockTrader/stocktrader-helm/master/repo

Then click the blue “Sync Repositories” button, and give it a few minutes to process.

While that is processing, we need to create a namespace for the sample, and need to give it an image policy that says it is allowed to pull images from the IBMStockTrader org in DockerHub. Create the namespace (via Manage->Namespaces), then do the following to authorize it to pull the microservice Docker images from our location in DockerHub. Choose Manage->Resource Security, then click on Image Policies, then click the blue Create Image Policy button, and fill it in as shown. The key part is to make sure to enter “docker.io/ibmstocktrader/*” for the registry URL. Of course, if you built each microservice yourself and pushed them to some other Docker image registry, you’d enter the details for that here. But for most people, just using the pre-built images in DockerHub is faster and easier.

Now click on Catalog, and you’ll see a list of dozens/hundreds of applications. You can either scroll down many pages to find “stocktrader” (they are arranged alphabetically), or you can filter that down, by clicking on Repositories and only checking the repository that you just added (such as “cloud-native-sample”, or whatever you called it).

Then you will see the sole helm chart in that repository, which of course is the IBM Stock Trader.

Click on that, and you’ll see the chart’s readme (if it says “No README found”, you haven’t waited long enough since doing the Sync Repositories). You can take a look at that, then click on Configure when ready.

On the configuration page, enter a release name and choose a namespace. Then expand the “All Parameters” twisty. Note the “Global Settings” at the top, which are configuration settings that apply to all of the microservices. For example, you’d check the “Output pod logs in JSON format” if you want to produce logs in a style that can be viewed in Kibana (the so called “ELK stack” — ElasticSearch/Logstash/Kibana).

You’ll have to scroll down a lot to see all of the settings here. But as stated earlier, don’t panic! Most of those are only needed in special circumstances, and usually the defaults are sufficient. Anything that is optional is clearly marked as such, and will explain what additional functionality that enables. Let’s start with looking at the available UI clients.

The easiest client to use is the “Trader” client, which is an old-fashioned form-based user interface implemented via Java servlets. It’s not pretty, but it doesn’t require any additional configuration to get working. There’s also the fancier “Tradr” client, which is a much more modern, responsive web app, implemented via Node.js and Vue.js. Note that this fancier client requires configuration of OpenID Connect (OIDC), which often requires registering a redirect URL with the OIDC provider before things will work. My recommendation would be to see some quick success via Trader, then move up to Tradr once you have some experience with getting things working. See that intro article mentioned earlier for further discussion and screenshots of the UI choice.

As an example of optional microservices, scroll on down to the Messaging and Notification sections. The Messaging microservice depends on IBM MQ (and the messages are only sent to MQ when the loyalty level changes, which only happens if IBM ODM is configured). There are two flavors of the Notification microservice; one performs its notifications by posting to a Slack channel, and the other sends a tweet. Unless you are in a fancy Istio environment with cool routing rules, you should only choose one of those two flavors of the notification microservice (otherwise, which you get routed to each time is random / unpredictable).

Read the description for each remaining section to see what each optional thing does. Of course, you can initial deploy without the optional pieces to get some quick success, before you have to learn things like how to setup the more complicated things like Kafka or Mongo. Once you are done, click the blue Install button, and if all input was accepted and validated correctly, you should see a popup dialog saying the helm release is being installed (if there’s a problem, scroll all the way up to the top and you should see a red error message about whatever field has invalid input).

Click on that blue “View Helm Release” button to see what all got deployed by this helm chart. You will see Deployments, Pods, Services, Ingresses, a Config Map, and a Secret.

You’ll need to scroll down a bit to see it all. The cool thing is, this gives you a one-stop shop for seeing everything associated with this sample on a single page. At the very bottom will be the contents of the Notes.txt from inside the helm chart, which describes how to launch the client (what is shown depends on whether you chose Trader, Tradr, or both).

Let’s take a quick look at the config map that got generated. Click on the “{release name}-config” link within the helm release page (or choose Configuration->ConfigMaps) to see where all of those host names and ports and such actually got stored that you entered when you installed the helm chart. If you look closely, you’ll see I didn’t bother entering real values for the Kafka and Mongo sections, as I wasn’t looking to use the optional Trade History microservice this time. Note there’s also a secret named “{release name}-credentials” with all of the user ids and passwords and such that you entered, stored in an obfuscated form.

If you click on Manage->Workloads->Helm Releases, you will see all of the various helm releases that have been installed. Many of them are standard ICP infrastructure. But you’ll also see each copy of Stock Trader that you chose to deploy.

Note that while you can have multiple copies of Stock Trader deployed via this helm chart, due to the way that Ingress works, you won’t be able to use the Ingress URL to access each (Ingress really only works for Stock Trader if you only have a single copy of it deployed to your Kubernetes cluster; having multiple copies causes collisions). In that case, you’ll have to drop back to using a Node Port. To do that, click on Network Access->Services, then click on the entry for the Trader service.

Then just click on the “https” link (32378 in the image above — the port number will be different each time you deploy). This will likely present a warning dialog, due to the use of a self-signed SSL certificate by default. Just choose “visit this website” to get past that.

This will take you to the root context of that pod, which will show the “Welcome to Liberty” page (this doesn’t happen when using the Ingress URL, but does with the Node Port). You’ll need to click on the address bar in the browser and add “/trader” to the end of the address.

Once you do that, you’ll see the Login page for Stock Trader. Assuming you haven’t modified the server.xml for Trader (like to uncomment the stanzas for LDAP or OIDC), it will just use a Basic Registry, which has a hardcoded list of ids/pwds, such as the “stock”/”trader” id/pwd combination.

Assuming you have DB2 configured properly, you should now see a list of portfolios (of course, if you haven’t created any portfolios within this database, the list will be empty and you’ll have to choose “Create a new Portfolio” to create one or more). If anything went wrong, you’ll see guidance about logs to check in the Trader or Portfolio pods for troubleshooting.

Congratulations, you have successfully deployed the IBM Stock Trader sample! Stay tuned for further blog entries (like on turning this umbrella Helm chart into an Operator…), and feel free to drop us some feedback. Thanks!

Originally published at https://www.ibm.com on July 18, 2019.