Helm Charts: Deploying webMethods Components in Kubernetes


We bring you exciting news from the forefront of innovation. We have recently released a comprehensive set of Helm charts for deploying webMethods components, including the API Gateway, Developer Portal, MyWebMethods Server, Universal Messaging, and Microservices Runtime, in a Kubernetes environment on GitHub (GitHub - SoftwareAG/webmethods-helm-charts: This repository contains a collection of Helm charts for various webMethods components.). Join us on this voyage of seamless deployment as we explore the power of Helm charts with clear and concise instructions.

Getting Helm-Ready

Before we embark on this journey, let’s ensure we have all the necessary tools at our disposal. Begin by installing Helm on your system. If you haven’t done so already, visit the Helm website (https://helm.sh) for installation instructions. Remember, Helm will serve as our trusted compass throughout this adventure!

Helm in 60 seconds

Helm is a package manager for Kubernetes that simplifies the deployment and management of containerized applications. It uses “charts” to package Kubernetes resources and configurations, allowing for easy installation, upgrades, and customization.

Helm repositories store charts and the Helm CLI helps users interact with and manage releases of these charts in Kubernetes clusters.

The workflow for using Helm is as follows:

  • Create or obtain a Helm chart (like the webMethods helm chart library) that describes your application (1).
  • Customize the chart’s configuration by creating a values file or specifying values on the command line.
  • Use the Helm CLI to install the chart, specifying the values and release name (2).
  • Helm generates Kubernetes manifests based on the chart and values, deploys them to your cluster, and tracks the release (3,4).

You can use Helm to upgrade, roll back, or uninstall releases as needed.

Installing Helm

Helm is available for Linux, macOS, and Windows. You can install Helm using a package manager or download the binary and install it manually. Install Helm on a Linux System via the following command:

curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash

For Windows and macOS, visit the Helm website for installation instructions at Helm | Installing Helm.

Deploying webMethods with Helm

With our newly acquired webMethods Helm charts, deploying webMethods components becomes a breeze. Utilizing the Helm command, we can effortlessly deploy any webMethods component within our Kubernetes cluster. Let’s set sail by running the following commands in your terminal:

Adding the webMethods Helm repository

helm repo add webmethods https://open-source.softwareag.com/webmethods-helm-charts/charts

Listing the available webMethods Helm charts

You can view the available charts via:

helm search repo webmethods

Which should result in the following output:

NAME                            CHART VERSION   APP VERSION     DESCRIPTION                                       
webmethods/mywebmethodsserver   1.0.0           10.15           My webMethods Server (MWS) Helm Chart for Kuber...
webmethods/apigateway           1.0.0           10.15           API Gateway Helm Chart for Kubernetes             
webmethods/common               1.0.0           1.0.0           A Library Helm Chart for grouping common logic ...
webmethods/developerportal      1.0.0           10.15           webMethods Developer Portal Helm Chart for Kube...
webmethods/microservicesruntime 1.0.0           10.15           Microservices Runtime (MSR) Helm Chart for Kube...
webmethods/universalmessaging   1.0.0           10.15           Universal Messaging (UM) Helm Chart for Kubernetes

Install webMethods components

To install any of the webMethods components use the following command:

helm install <my-release> webmethods/<component-name>

Replace <component-name> with the specific webMethods component you wish to deploy, such as apigateway, developerportal, mywebmethods, universalmessaging, or microservicesruntime. And replace <my-release> with the name of your release.

Sit back and observe as Helm charts expertly handle the provisioning and orchestration of your chosen webMethods component.

Upgrading with Helm

In the ever-evolving realm of technology, it is vital to keep your webMethods components up to date. Helm charts simplify the process of upgrading your components to the latest versions. To upgrade a webMethods component, execute the following command:

helm upgrade <my-release> webmethods/<component-name>

By utilizing the upgrade command, you can ensure that your webMethods components remain current, benefitting from the latest features and improvements.

Please note, if you are using StatefulSets, you must use the helm upgrade --force command to force the upgrade - in this case, the upgrade will be performed one pod at a time. In some cases depending on your scenario, you may need to delete the StatefulSet and re-create it.

In CI/CD pipelines you may want to use the helm upgrade --install command to install the chart if it does not exist, or upgrade it if it does exist.

Configuring Helm Charts

Helm charts offer an array of configuration options to tailor your deployments according to your specific requirements. Customization is made simple by overriding default settings or specifying custom values. For instance, to modify the number of replicas in your webMethods component deployment, use the --set flag:

helm upgrade <my-release> webmethods/<component-name> --set replicaCount=3

With this capability, you can adapt the scale and behavior of your webMethods components to suit your needs effectively.

Rollback and Recovery

While sailing these technological waters, we may encounter rough patches and unforeseen challenges. Fear not, for Helm charts provide a rollback mechanism, allowing us to revert to previous versions and restore stability to our deployments. In the event of a failed upgrade, execute the following command to initiate a rollback:

helm rollback <my-release> 1

This powerful command allows us to navigate away from troubled waters and regain a solid foundation for our webMethods components (in this case back to revision 1).

A word of caution, however, the rollback command will only work if the chart has not changed between the current and previous versions. If the chart has changed, you will need to use the --force flag to force the rollback (in our webMethods chart library we will ensure that versions are not altered and new versions are released in case of changes - however, if you fork or copy the charts you will need to consider versioning also).

Also in some cases, a rollback may not be possible, for example, if you have dependent backing services such as databases that have been updated and are no longer compatible with the previous version of the webMethods component. In this case, you will need to restore the database to a previous backup (or attach Helm Chart Hooks (see Chart Hooks), that perform specific rollback jobs to support you with this), keep this in mind when handling with stateful components.

Uninstalling with Helm

If you wish to remove a webMethods component from your Kubernetes cluster, you can use the uninstall command:

helm uninstall <my-release>

This command will remove all Kubernetes resources associated with the release, including pods, services, and persistent volumes. Helm does this by deleting all resources associated with the release, except for Secrets, ConfigMaps, and PersistentVolumeClaims. These resources are not deleted by default because they may contain valuable data that you may wish to preserve. If you wish to delete these resources, you can use the --purge flag:

webMethods Helm Chart Library

The webMethods Helm Chart Library is a collection of Helm charts for deploying webMethods components in a Kubernetes environment. Chart sources, documentation, and examples are available on the Software AG Github repository at: GitHub - SoftwareAG/webmethods-helm-charts: This repository contains a collection of Helm charts for various webMethods components.

Our helm charts have been designed to offer a consistent and intuitive experience for deploying webMethods components in Kubernetes. The charts are based on our official Software AG container images from https://containers.softwareag.com or if required, provide information on how to build your custom webMethods images) for each component and are configured to use Kubernetes resources such as StatefulSets, Deployments, Services, ConfigMaps, Ingresses, Secrets, etc. The charts also support the use of persistent volumes for storing data if required.

If you need to extend certain components, the charts provide a mechanism for adding also additional Kubernetes resources to the deployment like additional ConfigMaps, Secrets, or Services, Jobs, initContainers, lifecycle hooks, etc.

Example Deployment of Microservice Runtime

Let’s take a look at an example deployment of the Microservices Runtime component. Begin by adding the webMethods Helm repository:

helm repo add webmethods https://open-source.softwareag.com/webmethods-helm-charts/charts

To pull images from the Software AG Containers Registry (sagcr.azurecr.io → https://containers.softwareag.com), create an “Image Pull Secret” with your registry credentials. Should you prefer to use your private registry, replace the details accordingly to ensure secure image retrieval.

kubectl create secret docker-registry regcred --docker-server=sagcr.azurecr.io --docker-username=<your-name> --docker-password=<your-pwd> --docker-email=<your-email>

Before you can install the Microservices Runtime you will need to install a valid license for the Microservices Runtime component:

kubectl create configmap microservicesruntime-license-key --from-file=licensekey=<your path and filename to Microservices Runtime license file>

Next, install the Microservices Runtime component:

helm install my-msr webmethods/microservicesruntime

This command will deploy the Microservices Runtime component in your Kubernetes cluster under the default namespace (you can use a separate namespace by providing -n <namspace> if required). You can verify the deployment by running the following command:

kubectl get pods

You should see the following output:

NAME                                 READY   STATUS    RESTARTS   AGE
my-msr-microservicesruntime-57c7bcb8f4-gv24c   0/1     ContainerCreating   0          3m11s

You can also list the Helm releases in your cluster by running the following command:

helm list

which should produce the following output:

NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                           APP VERSION
my-msr  my-msr          1               2023-09-21 15:57:29.79356 +0200 CEST    deployed        microservicesruntime-1.1.0      10.15      

Congratulations! You have successfully deployed the Microservices Runtime component in your Kubernetes cluster. Now, let’s take a look at the various configuration options available for this component.

Configuration Options

The Microservices Runtime Helm chart offers a variety of configuration options to customize your deployment. You can override default settings or specify custom values to tailor your deployment according to your specific requirements. For instance, to modify the number of replicas and the default ingress in your deployment, use the --set flag:

helm upgrade my-msr webmethods/microservicesruntime \
  --set replicaCount=3 \
  --set "ingress.hosts[0].host=my-msr.mydomain.com"   \
  --set "ingress.hosts[0].paths[0].path=/"            \
  --set "ingress.hosts[0].paths[0].pathType=Prefix"   \
  --set "ingress.hosts[0].paths[0].port=5555"

With this capability, you can adapt the scale and behavior of your Microservices Runtime deployment to suit your needs effectively as well as deploy automatically ingress rules to access your microservices runtime through the URL my-msq.mydomain.com.

For more complex settings it is recommended to provide your own values.file and use the --values flag to specify the file:

helm upgrade my-msr webmethods/microservicesruntime --values my-values.yaml

Example values.yaml

The following example values.yaml file shows how to configure the Microservices Runtime component:

# values.yaml
  repository: "store/softwareag/webmethods-microservicesruntime"
  tag: ""

Using a Custom Container Image

In reality, you will most likely want to use your own custom images for your Microservice Runtime image, as we have basically just deployed an empty Microservices Runtime with no solutions in it.

To do this, you will need to build your own images and push them to a container registry. You can then use these images as your base image in the Helm chart. There are two ways to do this:

Extending from the Software AG base image

FROM store/softwareag/webmethods-microservicesruntime:

# copy your solutions to the image
COPY --chown=1724:1724 ./solutions /opt/softwareag/IntegrationServer/packages

Build and push the image to your container registry:

docker build -t <image-name>:<image-tag> .
docker push <image-name>:<image-tag>

Where the image tag uses your private container registry, for example:

docker build -t myregistry.io/myrepo/my-msr:

To use the new image simply specify the image name and tag in the values.yaml file:

  repository: "myregistry.io/myrepo/my-msr"
  tag: ""

Building a custom image via the SAG Installer

To build a custom image via the SAG Installer, you will need to download the Software AG Installer for Linux and execute the following command:

./SoftwareAGInstaller202103.001_Linux_x86_64.bin create image -i <image-name> -l <license-key> 

This will create a custom image with the name and the license key in your local Docker registry.

Once you have tagged the image and pushed it to your container registry, you can use it as your base image in the Dockerfile:

FROM <image-name>:<image-tag>

# copy your solutions to the image
COPY --chown=1724:1724 ./solutions /opt/softwareag/IntegrationServer/packages

In upcoming releases, the webMethods Package Manager (wpm) will streamline containerization by eliminating the need to create base images manually. Instead, users will be able to leverage the official base images directly from the containers.softwareag.com registry. The process will be simplified to adding necessary Adapters and Solutions atop the base image within a Dockerfile, facilitating a more efficient and straightforward integration.

More Examples

Please check the Microservices Runtime Helm Chart Readme for a complete list of configuration options.

Additional examples for configuring the Microservice Runtime component for specific scenarios such as Process Engine, Client-side Queuing (CSQ), Service Auditing and others can be found in the Microservices Runtime Helm Chart Examples


Congratulations once again, intrepid sailors of the webMethods seas! Equipped with the latest Helm charts for webMethods components, you can confidently deploy and manage these powerful tools within your Kubernetes environment. But remember, Helm charts are just one part of a larger ecosystem.

If you need expert guidance or assistance with your journey into modern cloud infrastructures, such as Kubernetes and OpenShift, our Professional Services teams are ready to assist you. With their extensive experience and expertise, they can provide invaluable support in optimizing your infrastructure and ensuring a seamless integration of webMethods components. Please also check our service offerings from here: Digital Transformation: Software AG Professional Services

Set sail with confidence, knowing that expert help is just a reach away. Embrace the power of webMethods in Kubernetes seas with Helm charts as you navigate the ever-changing tides of technology.

Fair winds and expert guidance on your magnificent voyage!


Note, the Software AG Github Helm Charts provided are samples from field experiences from the Software AG Professional Services team, without any warranty or official support. Feel free to fork and adopt the github helm repository to your needs or use them as library charts directly as described in this article. We are happy to take pull requests and improvements from the community.



This is really good stuff. Everyone was looking forward to something like this.

Thank you @Marc_Friedhoff1 for this fantastic writeup :clap:

Brilliant, I will be stealing from this for my upcoming article on how to deploy an edge runtime into kubernetes.

Wow, As a beginner this such a great resource to come across. Thank You. :sparkles:

This is an excellent resource, it will definitely make my life easier for the upgrade. Though I have some questions.

Can we change the repository url of MSR to IS and use integration server instead of MSR?
If not what else do we need to change?

Is there a recommended/predefined way to deploy packages from a git repo?

Thanks in advance!

For deployments in CaaS environments it’s better to use the MSR, which has a smaller size, requires far less resources to run, and has key capabilities to deal with containerization: properties based configuration, health endpoint, exposition of prometheus metrics, to name a few.
So the MSR is not a subset of the IS, it’s a superset of the IS.
The big difference is, the MSR comes with virtually no package by default, whereas the IS comes with many packages, most of which you never use.

If you’re using the MSR then the ABE and deployer are not longer needed. You create images that contains the integration runtime and your packages, and the CaaS creates pods using these images.
To configure your integration runtime container and plug it to its environment (for instance to its database), you then inject properties files and environment variables into the container when it’s created. That’s the approach these Helm charts follow.

1 Like

I would use MSR if I could. We don’t have a license for it. I have just replaced the MSR container repo with IS container repo. It downloads the container and starts it up without any error, but the container is shutting down claiming I don’t have a license for MSR, which is correct but irrelevant. It looks like the IS container that I download from containers.softwareag.com also uses MSR components. It doesn’t want me to inject properties file claiming its part of MSR product. Its still weird though, if I run the container in my local it works, if I use helm charts to deploy it, it shuts down.

HI @engin_arlak. The helm charts expect at least a valid license, and the K8S deployment will also leverage readiness and liveness probes defined in the Helm Charts, which are not exposed in standard Integration Server AFAIK. You might want to check your deployments / pods events in order to find out why the container is shut down. Liveness and Readiness probes could be configured through custom values files if required. As Stephane mentioned already, I would not recommend using pure Integration Server without Microservices License - even if there might be a way to get this technically running - externalizing all configuration properties is essential for container environments and this is not available without the Microservices License add-on.

Isn’t Integration Server container hosted on container.softwareag.com pure Integration Server? I think I am misunderstood. I am using Integration Server container, which is prepared and shipped by softwareAG, using the helm chart above. I have pushed the IntegrationServer license as recommended in the read me file and I verified that license file is reachable within the container. So far I am using the helm charts only to deploy the integration server container automatically but its shutting down claiming I don’t have MSR license, which is true but irrelevant. I attached the related logs below.

jvm 1    | !ENTRY com.softwareag.platform.hook.mirrors 1 0 2024-02-13 21:00:42.763
jvm 1    | !MESSAGE Overriding ClassLoader of com.softwareag.osgi.is.proxy_10.15.0.0008-0674 with tracker (service.pid=com.softwareag.osgi.is.classloader)
jvm 1    | ESAPI: WARNING: System property [org.owasp.esapi.opsteam] is not set
jvm 1    | ESAPI: WARNING: System property [org.owasp.esapi.devteam] is not set
jvm 1    | ESAPI: Attempting to load ESAPI.properties via file I/O.
jvm 1    | ESAPI: Attempting to load ESAPI.properties as resource file via file I/O.
jvm 1    | ESAPI: Not found in 'org.owasp.esapi.resources' directory or file not readable: /opt/softwareag/IntegrationServer/instances/default/ESAPI.properties
jvm 1    | ESAPI: Not found in SystemResource Directory/resourceDirectory: .esapi/ESAPI.properties
jvm 1    | ESAPI: Not found in 'user.home' (/opt/softwareag) directory: /opt/softwareag/esapi/ESAPI.properties
jvm 1    | ESAPI: Loading ESAPI.properties via file I/O failed. Exception was: java.io.FileNotFoundException
jvm 1    | ESAPI: Attempting to load ESAPI.properties via the classpath.
jvm 1    | ESAPI: SUCCESSFULLY LOADED ESAPI.properties via the CLASSPATH from '/ (root)' using current thread context class loader!
jvm 1    | ESAPI: SecurityConfiguration for Validator.ConfigurationFile.MultiValued not found in ESAPI.properties. Using default: false
jvm 1    | ESAPI: Attempting to load validation.properties via file I/O.
jvm 1    | ESAPI: Attempting to load validation.properties as resource file via file I/O.
jvm 1    | ESAPI: Not found in 'org.owasp.esapi.resources' directory or file not readable: /opt/softwareag/IntegrationServer/instances/default/validation.properties
jvm 1    | ESAPI: Not found in SystemResource Directory/resourceDirectory: .esapi/validation.properties
jvm 1    | ESAPI: Not found in 'user.home' (/opt/softwareag) directory: /opt/softwareag/esapi/validation.properties
jvm 1    | ESAPI: Loading validation.properties via file I/O failed.
jvm 1    | ESAPI: Attempting to load validation.properties via the classpath.
jvm 1    | ESAPI: SUCCESSFULLY LOADED validation.properties via the CLASSPATH from '/ (root)' using current thread context class loader!
jvm 1    | [ProxyLogManager] readConfiguration(java.io.BufferedInputStream@117b9641) -> com.webmethods.sc.logging.jul.HandlerLogManager@1b94faf2
jvm 1    | INFO: Getting audit  config from it's default location.
jvm 1    | WARNING: Audit configuration neither exists, nor could be found on the classpath. Auditing will not work.
jvm 1    | INFO: Using dummy audit implementation.
jvm 1    | 2024-02-13 21:00:48 GMT [ISS.0028.0107I] Successfully copied source license file /opt/softwareag/IntegrationServer/licenseKey.xml to destination /opt/softwareag/IntegrationServer/instances/default/config/licenseKey.xml.
jvm 1    | 2024-02-13 21:00:49 GMT [ISS.0028.9999I] Validating License file for Microservices
jvm 1    | 2024-02-13 21:00:49 GMT [ISS.0028.0103I] License file /opt/softwareag/IntegrationServer/instances/default/config/licenseKey.xml is not enabled for the Microservices functionality.
jvm 1    | 2024-02-13 21:00:49 GMT [ISS.0028.9999C] The license provided is invalid or cannot be read. Remove application.properties file or provide a valid MSR license.
jvm 1    | 2024-02-13 21:00:49 GMT [ISS.0028.9999C] com.softwareag.is.dynamicvariables.DynamicVariablesCriticalException: The license provided is invalid or cannot be read. Remove application.properties file or provide a valid MSR license.
jvm 1    | 	at com.softwareag.is.dynamicvariables.DynamicVariablesManager.processDynamicVariables(DynamicVariablesManager.java:351)
jvm 1    | 	at com.wm.app.b2b.server.Server.run(Server.java:469)
jvm 1    | 
jvm 1    | [ProxyLogManager] reset() -> com.webmethods.sc.logging.jul.HandlerLogManager@1b94faf2
jvm 1    | [Tue Feb 13 21:00:50 GMT 2024] [INFO] Bootstrap: Stopping...
jvm 1    | [ProxyLogManager] setDelegate: com.webmethods.sc.logging.jul.HandlerLogManager@1b94faf2 -> com.softwareag.platform.jul.proxy.DefaultLogManager@22a637e7
jvm 1    | [Tue Feb 13 21:00:51 GMT 2024] [INFO] Bootstrap: Stopped
wrapper  | <-- Wrapper Stopped
Integration Server trapped shutdown signal.

HI @engin_arlak there are 3 different flavours for Integration Server:

  1. a pure Integration Server (no MSR functionality)
  2. a MSR
  3. an Integration Server with MSR functionality

The 3rd option is what you will need if you really want a full-blown Integration Server instead of an MSR - the Microservice functionality is purely enabled by a flag in the license file. I haven’t tried this yet but you might want to skip providing your own non-Microservice License with the IS by using:

--set microservicesruntime.licenseKeyProvided=false

Hope this helps…

This seems like fixed the immediate shut down problem.
What is the proper way of providing the license file and the configuration set to IS container then? Should I create a seperate repo for config files and set the CI/CD pipeline to update those files? Is there any way I can use values.yaml files?

Please check the documentation here: webmethods-helm-charts/microservicesruntime/helm at main · SoftwareAG/webmethods-helm-charts · GitHub. For license file you can chose either via --set-file parameter or providing a config map that has the license file in it. Your values files should in any case be separated for your solutions in a different repository. The license file is usually shared among multiple instances of the MSR / IS - so you might want to put this in some central repository and have the license file deployed as a config map before your IS / MSR solution is deployed.

Again please check also the examples folder on the Github repo - you will hopefully find more answers to your questions.

I didn’t check examples throughly, I will check them.

Adding the parameter --set microservicesruntime.licenseKeyProvided=false to helm install command seems like solved the immediate shutdown problem. I was passing license as config map but now that I added this parameter I don’t think it will get the license file from config map, right? I am a little bit confused though. Does this command just disable microservices runtime features or it just doesn’t pass the license file altogether? It is not complaining about license in past hour. What does --set microservicesruntime.licenseKeyProvided=false parameter do exactly?

I already created a base config repo in our of repository and mirrored the main branch from softwareAG github repo and doing all of the configuration in the values.yaml file. The question here was, if I could still use values.yaml file for Integration server eventhough we don’t have microservices license. I don’t want to push towards the wrong direction. I want to keep all our configuration files in one place and automate building the environment process completely.

The command below doesn’t create the config map properly. UM server expects a license file as licence.xml but the command creates the config map as licencekey. This is misleading, I checked the license path and have seen that the license file exists there, checked the file using cat command, nothing was wrong with it. I didn’t realize it had a wrong name and created a support ticket. After editing the config map to licence.xml the issue is resolved.

kubectl create configmap universalmessaging-licence-key --from-file=licence.xml=<filepath>

I also couldn’t add the defaults in the link below to values.yaml. It returns the error below

Error: INSTALLATION FAILED: failed to parse webmethods-base-configuration-repo/dish-values/is-default-values.yaml: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal string into Go value of type map[string]interface {}

Is there a sample yaml file that has everything that I can refer to?

Dear @engin_arlak I would ask you to please report issues or questions regarding the helm charts directly on Github - I have answered both of your questions directly there.

1 Like