Enabling IBM Instana monitoring
Enable IBM Instana to get proactive monitoring of cluster-based metrics and operators in IBM Cloud Pak® for Integration.
For more information about how Instana Observability works, see Automatic discovery and monitoring.
Follow these steps, in the order given:
Installing the Instana back end (on premises, only)
See Troubleshooting if you experience problems integrating Instana with Cloud Pak for Integration.
On-premises deployment vs. SaaS deployment
Instana is available as an on-premises solution, or as a SaaS solution. If installing:
On premises, install both the Instana back end and the Instana agent operator.
As SaaS, install only the Instana agent operator. Skip the first section, "Installing the Instana back end" and begin with Installing the Instana agent operator.
Note that the limited entitlement to Instana monitoring that is included with new purchases of Cloud Pak for Integration 2022.4 only applies to on-premises deployments. See Licensing for more information.
Installing the Instana back end
This is required for installing on-premises only. If you are installing Instana as a SaaS solution, skip this section.
Follow the steps in Installing and configuring a self-hosted Instana backend on Kubernetes or Red Hat OpenShift (on-premises) (in the Kubernetes documentation).
When completed, continue with the next section, Installing the Instana agent operator.
Installing the Instana agent operator
Before installing the Instana agent operator, you must first create a namespace and enable privileged security context for that namespace.
Create a namespace called instana-agent
You need to set up a namespace (project) for the Instana agent and configure its service account permissions.
instana-agent
; if not, the creation process for the Instana agent fails.Using the OpenShift web console:
Log into the OpenShift web console with administrator credentials.
In the navigation menu, click Home > Projects.
Click Create Project, enter the name for your new project (
instana-agent
), and click Create.
Using the CLI:
Run this command to create the namespace:
oc new-project instana-agent
Enable privileged security context for the instana-agent
namespace:
The instana-agent
service account is created by the operator.
Run the following command in the CLI to ensure that the instana-agent
service account is in the privileged security context:
oc adm policy add-scc-to-user privileged -z instana-agent
Installing the Instana agent operator
After you create the namespace and privileged security context, you can proceed with installing the operator for the Instana agent.
Follow the procedure in Installing the operators by using the Red Hat OpenShift console. In step 4, select the IBM Instana Agent operator.
Creating an instance of the Instana agent
The Instana agent must be deployed to monitor the cluster. Perform the following steps, in the order given, to deploy the agent.
Creating an opaque secret
The opaque secret contains the agent key (and also the download key, if your Instana installation is on premises).
For on premises installations, both keys are located in your settings.hcl
file. The keys are stored in the opaque secret so that the credentials are hidden in the Instana agent custom resource.
Using the CLI
Create a YAML file. For example, you could create a file called
instana-secret.yaml
with the following example configuration:apiVersion: v1 kind: Secret metadata: name: instana-agent-key namespace: instana-agent type: Opaque stringData: key: <agent_key> downloadKey: <download_key_on_premises>
Update these values:
data.key
- the agent key.- (On premises only)
data.downloadKey
- the download key. Set this value only if you are installing Instana on premises.Tip: UsingstringData
in the YAML ofkind: Secret
automatically base 64-encodes your data. If you use another method to create your secret, or want to specify the encoded secret data directly in your YAML file, you can base 64-encodedata.key
anddata.downloadKey
by using a tool of your choice. In this scenario, use thedata
object instead of thestringData
object in the YAML. For more information, see "Understanding secrets" in Providing sensitive data to pods (in the OpenShift docs).
Apply the YAML file to the cluster:
oc apply -f instana-secret.yaml
To verify that the secret has been created run:
oc get secret instana-agent-key -n instana-agent
Creating an instance of the Instana agent
Using the OpenShift web console
In the navigation menu, click Operators > Installed Operators.
Change Project to the
instana-agent
namespace. Click the drop-down arrow and select the name from the list.In the list on the Installed Operators panel, find and click Instana Agent Operator.
Click the Instana Agent tab.
Click Create InstanaAgent. The Create InstanaAgent panel opens.
Click YAML view to configure the instance.
Update these values:
spec.agent.endpointPort
- Endpoint port of your Instana instance.endpointHost
- Endpoint of your Instana instance.spec.agent.keysSecret
- Name of the secret you created in Create an opaque secret, for example,instana-agent-key
.spec.zone.name
- Zone name you want to associate with the nodes of your cluster. This name is used to customize the zone grouping that is displayed on the infrastructure map. It also sets the default name of the cluster.spec.cluster.name
- Identifier you want to assign to your cluster in Instana. You can use any name, but it needs to be consistent with the name you assign to this cluster in other Instana configurations.
Click Create. You are redirected to the Instana Agent tab. The instance is added to the list of instances.
To verify that the agent is being created, click the name of the instance created in the list. At the end of the page in the Conditions section, the Type should be
Pending
. When the agent is ready, this value changes toReady
.
Using the CLI
Create an
InstanaAgent
YAML file. For example, create a file that is calledinstana-agent.yaml
with the following example configuration:apiVersion: instana.io/v1 kind: InstanaAgent metadata: name: instana-agent namespace: instana-agent spec: agent: env: {} configuration_yaml: | endpointHost: <instana_endpoint> endpointPort: '<instana_endpoint_port>' keysSecret: <name_of_secret_storing_api_keys> cluster: name: <cluster_name> zone: name: <zone_name>
For example:
apiVersion: instana.io/v1 kind: InstanaAgent metadata: name: instana-agent namespace: instana-agent spec: agent: env: {} configuration_yaml: | com.instana.plugin.opentelemetry: enabled: true endpointHost: 'https://my_instana_url' endpointPort: '443' keysSecret: instana-agent-keys
Update the following values:
agent.configuration_yaml
- You can leave this field empty, or use it to configure your Instana agent. For more information, see Installing the host agent on kubernetes (in the Instana documentation).spec.agent.endpointPort
- Endpoint port of your Instana instance.endpointHost
- Endpoint of your Instana instance.spec.agent.keysSecret
- Name of the secret you created in Create an opaque secret, for example,instana-agent-key
.spec.zone.name
- Zone name you want to associate with the nodes of your cluster. This name is used to customize the zone grouping that is displayed on the infrastructure map. It also sets the default name of the cluster.spec.cluster.name
- Identifier you want to assign to your cluster in Instana. You can use any name, but it needs to be consistent with the name you assign to this cluster in other Instana configurations.
Apply the YAML file to the cluster:
oc apply -f instana-agent.yaml
To verify that the agent is being created run:
oc get agent -n instana-agent
When the agent is ready, this status changes to
Ready
.You can further customize the Instana agent to include additional back ends, and also modify proxy, TLS and update strategy settings. For more information, see Installing the host agent on Kubernetes (in the Instana documentation).
Configuring the Instana agent for capabilities
In Cloud Pak for Integration, Instana monitoring is currently supported for the following capabilities:
Integration tracing (IBM App Connect Enterprise)
Event streams (IBM Event Streams)
Messaging (IBM MQ)
Gateway (IBM DataPower)
Depending on your deployment, you may need to further configure the agent you created in the previous section. Configure the agent by using the CLI or the OpenShift web console.
Using the OpenShift web console
Add the configuration from the sensor guides in the agent.configuration_yaml
section of the InstanaAgent
custom resource.
In the navigation menu, click Operators > Installed Operators.
For Project, select the
instana-agent
namespace.Click the Instana Agent operator.
Click the Instana Agent tab.
Click your instance of
instana-agent
.Click YAML and edit the YAML. This is an example for a local DataPower instance:
spec: agent: configuration_yaml: | com.instana.plugin.ibmdatapower: enabled: true poll_rate: 60 instances: local: port: '5554' # DataPower instance REST management interface port (required) username: 'admin' # User account to connect to DataPower (required) password: 'admin' # User password to connect to DataPower (required)
Using the CLI
Add the configuration from the sensor guides to the agent.configuration_yaml
section of the InstanaAgent
custom resource that is located in the instana-agent namespace:
oc edit agent instana-agent -n instana-agent
This is an example for a local DataPower instance:
spec:
agent:
configuration_yaml: |
com.instana.plugin.ibmdatapower:
enabled: true
poll_rate: 60
instances:
local:
port: '5554' # DataPower instance REST management interface port (required)
username: 'admin' # User account to connect to DataPower (required)
password: 'admin' # User password to connect to DataPower (required)
Integration tracing and Event Streams
Instana automatically discovers IBM App Connect Enterprise and IBM Event Streams instances. However, if you make updates to the security configuration, you need to enable the Instana agent sensor. For more information, see the applicable task in the Instana documentation:
Monitoring Kafka (IBM Event Streams)
Messaging and gateway
Instana does not automatically discover IBM MQ and IBM DataPower instances, so you need to configure the Instana agent sensor. For more information, see the applicable task in the Instana documentation:
- Monitoring IBM MQImportant: 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 MQQueueManager
custom resource.If you need to configure an authenticated MQ queue manager to work with Instana, see Configuring authenticated IBM Instana monitoring with MQ TLS (in the MQ documentation).
Confirming the connection of the capabilities is successful
If you configured the Instana agent in the previous step, confirm that the connection to Instana for MQ and DataPower is successful.
Access Instana.
Click the Infrastructure icon.
Click the Entity Explorer tab.
Click or search for the configured capability.
Confirm that the capability appears:
For IBM MQ, the IBM MQ Queue Manager appears after the name of the underlying queue manager.
For IBM DataPower, the IBM DataPower appliances appear after the name of the DataPower host or IP address.
If the capability does not appear, refer to the Instana capability guides, or contact Instana support.
Enabling Instana monitoring links in the Platform UI
The Platform UI can link directly to Instana entities to provide easy access to monitoring data. The Platform UI must be configured with access to Instana to lookup entities.
If you do not have a deployed instance of the Platform UI, create one by following the instruction in Deploying the Platform UI.
Creating the API token and secret
Instana requires an API token to generate monitoring links in the Platform UI. To create the token:
Access Instana.
Click the Settings icon.
Click the Team Settings tab, then click API Tokens.
Click Add API Token to create a new API token.
You do not need to select any permissions.
Copy the token and use it to create a key-value secret with a key name of
apiToken
and a value of the Instana API token string.To create the secret by using the CLI, run:
oc create secret generic <secret_name> \ --from-literal=apiToken=<api_token_value>
For example:
oc create secret generic observabilitysecret \ --from-literal=apiToken=545454aabbab
This creates a secret named
observabilitysecret
.For more information, see Managing Secrets using kubectl (in the Kubernetes documentation).
Configuring the Platform UI custom resource
To enable Instana monitoring in the Platform UI, you must add the Observability section to the Platform UI custom resource. This can be done by using the OpenShift web console or the CLI.
Using the OpenShift web console
Log into the OpenShift web console with your OpenShift cluster admin credentials.
In the navigation panel, click Operators > Installed Operators.
For Project, select the namespace of the Platform UI.
In the list on the Installed Operators panel, find and click IBM Cloud Pak for Integration.
Click the Platform UI tab.
In the list, click the name of the deployed instance.
Click YAML.
Modify the
PlatformNavigator
custom resource by adding the following to thespec
section. For example:observability: authentication: secretName: <secret-name> apiToken: <api-token-key-name> caCertificate: <ca-certificate-key> url: <base-url> clusterName: <cluster-name>
Update these values:
secretName - Name of the secret that contains the API token.
apiToken - Key name within the secret that contains the API token. Default is
apiToken
.caCertificate - Key name within the secret that contains the CA certificate for your Instana solution. Set this value only if installing Instana on premises.
clusterName - Name of the cluster given in the Instana agent.
url - Base URL of the tenant unit, for example,
https://test-example.instana.io
. This is the same URL that is used to access the Instana user interface.
Using the CLI:
Log in to the OpenShift CLI.
Change the
project
to the namespace of the Platform UI:oc project <namespace>
Edit the resource by running this command, replacing with the name of your instance:
oc edit pn <instance_name>
Modify the
PlatformNavigator
custom resource by adding the followingobservability
section to thespec
section. For example:spec: observability: authentication: secretName: <secret-name> apiToken: <api-token-key-name> caCertificate: <ca-certificate-key> url: <base-url> clusterName: <cluster-name>
Update these values:
secretName - Name of the secret that contains the API token.
apiToken - The key name within the secret that contains the API token. Default is
apiToken
.caCertificate - Key name within the secret that contains the CA certificate for your Instana solution. Set this value only if installing Instana on premises.
clusterName - This is the name of the cluster given in the Instana agent.
url - This is the base URL of the tenant unit, for example,
https://test-example.instana.io
. This is the same URL that is used to access the Instana user interface.
Accessing Instana monitoring in the Platform UI
To access Instana monitoring:
Log in to the Platform UI.
Click Integration Instances to get a list of available instances.
Hover over the overflow menu for the instance you want and click Monitoring .
Troubleshooting
Find solutions for issues that may arise when using Instana monitoring.
Clicking Instana Monitoring in UI returns "Entity not found"
Cause: To diagnose the issue, confirm there's a connection between the capability instance and the Instana agent.
Sign in to the Instana user interface.
Click Infrastructure > Entity Explore > Search/Find Capability > view capability instance. If you are unable to find the instance of the capability, there is a issue with the connection between the Instana agent (sensor) and the capability.
Identify the nodes that the capability is running on, then find the
instana-agent
pods running on the same node. This allows you to get the sensor-related logs for the capability.
Solution: Review the Instana configuration for the instance and refer to the applicable configuration guide for the capability being monitored.
Multiple issues when you install two different cert-managers
For information about diagnosing and solving this issue, see Problem when you install two different cert-managers.