Archived content

Archive date: 2025-04-11

This content is no longer being updated or maintained. The content is provided “as is.” Given the rapid evolution of technology, some content, steps, or illustrations may have changed.

Customers are increasingly deploying applications in cloud native infrastructures to take advantage of agility, scalability, flexibility and innovation. Integrations technologies enable secure data exchanges across applications. Traditional integration approaches cannot cope with the speed of innovation. Hence the integration approaches have evolved to agile integration and the integrations are becoming first class citizens in cloud native world. However this presents the same observability and resource management challenges for cloud native integrations as we face with the microservices.

IBM Cloud Pak for Integration is industry’s most complete hybrid integration platform that includes traditional and cloud native integration capabilities ranging from API lifecycle management, application integration, messaging, events to high speed file transfer. One can pick and choose to deploy specific integration capabilities on the Cloud Pak for Integration platform.

When customers deploy IBM App Connect Enterprise (ACE) integrations on Cloud Pak for Integration, those integrations essentially get deployed as Kubernetes pods, which are referred as micro-integrations. As opposed to traditional deployments, where hundreds of integrations are deployed on integration nodes and are managed traditionally, now a very small set of integrations are deployed in an integration server running inside a pod. Similarly, IBM MQ queue managers are also deployed inside Kubernetes pods. So when customers move to Cloud Pak for Integration, they have to deal with these hundreds of integration pods, which present the typical challenges as with other microservices. Some of these challenges include how to auto-detect and auto-instrument the integration components, such as ACE integration servers or MQ queue managers, for monitoring, how to auto-trace the transactions, how to do automatic root cause analysis, how to ensure that the Kubernetes pods are always supplied the resources to match the demand.

IBM Instana Observability (Instana) is a fully automated enterprise observability solution, which ingests observability metrics, traces every request, and profiles every process automatically. Instana breaks through the complexity of your application environment to show how everything fits together in context. Instana helps you visualize how your application components work together and helps you with debugging errors in your application. Learn more about Instana in the documentation.

IBM Turbonomic (Turbonomic) is an application resource management (ARM) software that helps you assure application performance, improve efficiency, and ensure compliance by dynamically resourcing applications across hybrid and multicloud environments. Learn more about Turbonomic in the documentation.

Turbonomic understands the default Kubernetes objects like Deployments and StatefulSets. To makes necessary resource changes for pods, it updates the corresponding Deployment or StatefuleSet. However, in the case of integration capabilities, like ACE and MQ, in Cloud Pak for Integration, the Deployments and StatefulSets are managed by the respective Kubernetes Operator’s custom resources. For Turbonomic to handle these custom resources, we need to create appropriate operator resource mappings, which ensures persistent changes of integration component resources when actions are executed against them from within Turbonomic.

This tutorial shows you how Instana and Turbonomic come together to bring end-to-end observability and automatic resource management of Cloud Pak for Integration components like App Connect and MQ running on Red Hat OpenShift. This tutorial is also relevant to operator-based deployments of ACE and MQ on different flavors of Kubernetes including Azure Kubernetes Service (AKS), Elastic Kubernetes Service (EKS), Google Kubernetes Engine (GKE), or self-managed Kubernetes.

Prerequisites

This tutorial assumes that you have these skills:

Basic administration skills for IBM Cloud Pak for Integration
Basic Red Hat OpenShift administration skills
Basic skills in Instana and Turbonomic

This tutorial uses the Instana AutoTrace Webhook to trace ACE & MQ. In Cloud Pak for Integration v2022.4, native support for tracing ACE, MQ, Event Streams, and DataPower has been built using OpenTracing standards; therefore, this tutorial might be updated in the future to replace Instana AutoTrace Webhook with the native tracing implementation.

Also, to complete this tutorial, you must have installed these products:

This tutorial has been built using Instana and Turbonomic on-prem deployments; however, it is applicable to Instana SaaS and Turbonomic SaaS instances as well.

Steps

Step 1: Install the Instana Agent on the OpenShift cluster

You need to deploy Instana agent on the OpenShift cluster where Cloud Pak for Integration has been deployed. The agent gets deployed as a DaemonSet, which means one agent pod runs on each worker node of the cluster.

On the OpenShift web console, use the Operator Lifecycle Manager (OLM) to install the Instana Agent operator.

Log in to the OpenShift cluster as cluster-admin. Create the instana-agent project, and then set the policy permissions to ensure the instana-agent service account is in the privileged security context.
```
 oc new-project instana-agent
 oc adm policy add-scc-to-user privileged -z instana-agent -n instana-agent
```
In the left navigation panel, open Operators, and select Operator Hub. Then, search for the Instana Agent Operator.
Select the operator. Then, click Install.
Click Install to complete the operator installation. The operator is installed in all namespaces.
Create an instance of the Instana Agent. Go to the instana-agent namespace and select Instana Agent Operator. Then, click the Instana Agent tab.
Click Create InstanaAgent.
In the YAML file, update the endpointHost, endpointPort, and agent key with values that you get from your Instana administrator. Also, specify the name for your cluster that will be displayed in Instana. We will update other agent configurations later.
Click Create. After the InstanaAgent has been installed, you should see instana-agent pods running by using this command: oc get daemonset -n instana-agent.

After few minutes, you should see the OpenShift cluster in the Instana dashboard.

Screen capture of Instana dashboard

Next, we’ll configure this OpenShift cluster for Turbonomic.

Step 2: Deploy KubeTurbo on the OpenShift Cluster

To manage a Kubernetes or OpenShift cluster, Turbonomic needs to deploy a KubeTurbo pod on the target cluster. Follow the detailed instructions in this GitHub repo to deploy KubeTurbo.

Before proceeding with the deployment of KubeTurbo, get the following information from your Turbonomic administrator:

Turbo_Server_URL: This is the topology-processor URL from the Turbonomic instance.
A Turbonomic user name with SITE ADMIN or ADMIN Role and the password.
Create a namespace, for example turbo, to deploy KubeTurbo using this command: oc new-project turbo.
Go to the Operator Hub in the OpenShift console and search for the Kubeturbo Operator.
Select the operator and install it in the namespace you created above.
Verify that the KubeTurbo operator has been installed successfully using this command: oc get po -n turbo.
Create the KubeTurbo instance. Go to the KubeTurbo operator in the namespace where it has been installed.
Click Create Kubeturbo and specify the Turbonomic server credentials. Follow these detailed instructions in the Kubeturbo docs in GitHub for the configuration options for Kubeturbo.

After successful deployment of the Kubeturbo, you should see the kubeturbo pod up and running, using this command: oc get deploy -n turbo.

Screen capture of command output showing the KubeTurbo operator running

After few minutes, you should start seeing the OpenShift cluster in Turbonomic dashboard.

Screen capture of Turbonomic dashboard

Step 3: Deploy Instana AutoTrace Webhook

The Instana AutoTrace WebHook is a Kubernetes and OpenShift-compatible admission controller mutating webhook that automatically configures the Instana tracing on Node.js, .NET Core, Ruby, and Python applications that run across the entire Kubernetes or OpenShift cluster and on IBM MQ and ACE that run in IBM Cloud Pak for Integration.

Replace in the following command with a valid Instana agent key or download key, and run it with administrator privileges for your OpenShift cluster:

helm install --create-namespace --namespace instana-autotrace-webhook instana-autotrace-webhook \
  --repo https://agents.instana.io/helm instana-autotrace-webhook \
  --set webhook.imagePullCredentials.password=<download_key> \
  --set openshift.enabled=true \
  --set autotrace.ibmmq.enabled=true \
  --set autotrace.ace.enabled=true

Ensure the instana-autotrace-webhook in the instana-autotrace-webhook namespace is running as expected by running this command: kubectl get pods -n instana-autotrace-webhook.

The Instana AutoTrace WebHook will take effect on new Kubernetes resources. That is, you might need to delete your Pods, ReplicaSets, StatefulStes, Deployments, and DeploymentConfigs and create them anew for the Instana AutoTrace WebHook to begin tracing.

Verify the auto-instrumentation of your ACE and MQ pods for Instana: kubectl get pod <pod-name> -n <namespace> -o=jsonpath=‘{.metadata.labels.instana-autotrace-applied}’

Follow this documentation for detailed instructions on setting up an Instana AutoTrace WebHook.

Step 4: Configure MQ monitoring

Instana does not automatically discover IBM MQ instances. Follow this documentation to configure queue manager monitoring. When the queue manager is referenced in the Instana agent, you need to provide the name of the underlying queue manager. You can find this in the spec.queueManager.name section of the IBM MQ QueueManager custom resource. If you need steps for configuring an authenticated MQ queue manager to work with Instana, see the MQ documentation.

Let’s now add the queue manager connection details in the Instana agent.

In this example, we do not have security enabled on the queue manager, so we need to only provide the name of the queue manager and the server-connection channel. Edit the instana-agent from the OpenShift console or using the CLI: oc get agent -n instana-agent.

Run the command oc edit agent instana-agent -n instana-agent.

Screen capture of command output for configuring the instana-agent

As shown in the screen capture, enter the connection details for queue managers to monitor. To connect to queue managers where security is enabled, follow this documentation.

In couple of minutes, you should see the queue manager in the Instana console. Verify it by accessing the Services view.

Screen capture of Instana dashboard Services view

Or, accessing the Infrastructure view.

Screen capture of Instana dashboard Infrastructure view

In the Instana console, you can drill down to the queue manager and various MQ objects to see the required level of details. In this first screen shot, you see the Connections and Messages.

Screen capture of Instana dashboard showing metrics details for MQ queue manager

As you scroll down the window, you see Message Time and Calls.

Screen capture of the rest of the Instana dashboard showing metrics details for MQ queue manager

Step 5: Configure ACE Tracing in Instana

Instana automatically discovers ACE instances. However, in cases where you have configured additional security, follow this Instana documentation to enable the Instana agent sensor.

Now, you should be able to trace the messages flowing through ACE integrations and MQ in Instana.

You can analyze specific calls and see very fine-grained details.

Screen capture of Instana dashboard tracing the messages flowing through ACE and MQ

From an Infrastructure perspective, you can look at individual message flows and view various metrics at a very fine-grained level. In this first screen capture, you see Elapsed Time metrics.

Screen capture of Instana dashboard showing an individual message flow and metrics

As you scroll down the window, you see details of Input Messages.

Screen capture of the rest of the Instana dashboard showing an individual message flow and metrics

You can define your application using Instana’s application perspective. Instana will dynamically build the service dependency diagram for the application.

Screen capture of the service dependency diagram in Instana dashboard

Step 6: Define Operator Resource Mappings (ORM) for ACE and MQ

ACE integration servers and MQ queue managers on Cloud Pak for Integration or Kubernetes are custom resources, which are extensions of the Kubernetes API. In order for Turbonomic to understand ACE and MQ operators, we need to define operator resource mappings or ORMs.

First, create ORM Custom Resource Definition (CRD) to the OpenShift cluster:

kubectl apply -f https://raw.githubusercontent.com/turbonomic/orm/master/config/crd/bases/turbo_operator_resource_mapping_crd_v1.yaml

Now let’s create ORM custom resources for ACE and MQ in respective namespaces. For example, if you have deployed ACE integration servers and queue managers in the ace namespace, then create these resource mappings in the ace namespace. Here are sample ORM CR yaml files for ACE integration server and MQ queue manager.

ACE IntegrationServer ORM sample yaml:

Screen capture of ACE IntegrationServer ORM YAML file

This yaml file contains resource mappings for three IntegrationServers (processrecords, notify-server, and customer-info) deployed in ace namespace. You can add resource mappings for all your IntegrationServers deployed in this namespace.

Apply this yaml file using this command: oc apply -f ace_orm.yaml.

MQ ORM Sample yaml:

Screen capture of MQ ORM YAML file

If you have more than one queue manager in the namespace, you can add all of them in this single ORM instance. Apply this queue manager ORM using this command: oc apply -f mq_orm.yaml.

Verify that the ACE and MQ ORMs have been created successfully using this command: oc get orm -n ace.

Screen capture of command output for verifying ORMs were created

Rediscover the KubeTurbo target from the Turbonomic dashboard. There is no need to restart the corresponding Kubeturbo pod in OpenShift cluster.

Screen capture of Turbonomic dashboard and rediscovering the KubeTurbo target

Search the logs to verify that the OMR CRs have been successfully discovered by using a command like this: oc logs kubeturbo -n turbo | grep 'Operator managed Custom Resources'.

ORM CR will be successfully discovered when you see a log message from Kubeturbo like those shown in the following screen capture:

Screen capture of command output for searching for log messages about OMR CRs being discovered

This completes all the steps of configurations. Now Turbonomic can execute actions on ACE and MQ instances on Cloud Pak for Integration to manage the resources.

Screen capture of Turbonomic dashboard showing actions for managing resources

You can define automation policies in Turbonomic to execute these actions automatically. Most enterprises rely on a change management system to make any modifications in production. This blog explains how ServiceNow can be integrated with Turbonomic to automate action execution within the change management process.

Demonstration

Watch this demo video to see how Instana and Turbonomic come together to bring end-to-end observability and automatic resource management of Cloud Pak for Integration components like ACE and MQ running on Red Hat OpenShift.

Video will open in new tab or window.

Summary

In this tutorial you learned how to bring Instana and Turbonomic together to observe and manage your complex environments that include IBM App Connect Enterprise and IBM MQ running on Cloud Pak for Integration. You can extend this approach to observe and manage other Cloud Pak for Integration components, like IBM DataPower and IBM Event Streams.

Observe and manage IBM Cloud Pak for Integration environments

Observe and manage IBM Cloud Pak for Integration environments