Enabling IBM Instana monitoring

This task 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.

1. Create a namespace (project) for the Instana agent with the name instana-agent.

   Important: If the namespace is not named instana-agent, the creation process for the Instana agent fails.

   Create the namespace by using the OpenShift web console

   1. Log in to the OpenShift web console with administrator credentials.

   2. In the navigation menu, click Home > Projects.

   3. Click Create Project, enter the name for your new project (instana-agent), and click Create.

   Create the namespce by using the CLI

   Run this command to create the namespace:

   oc new-project instana-agent

2. Run the following command to enable privileged security context for the instana-agent namespace. This step is required because the instana-agent service account is created by the operator.

   oc adm policy add-scc-to-user privileged -z instana-agent

3. Install the Instana agent operator by following the procedure in Installing the operators by using the Red Hat OpenShift console. In step 4, select the IBM Instana Agent operator.

The Instana agent must be deployed to monitor the cluster.

Create 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.

1. 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: Using stringData in the YAML of kind: 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-encode data.key and data.downloadKey by using a tool of your choice. In this scenario, use the data object instead of the stringData object in the YAML. For more information, see "Understanding secrets" in Providing sensitive data to pods (in the OpenShift docs).

1. Use the CLI to apply the YAML file to the cluster:

   oc apply -f instana-secret.yaml

2. To verify that the secret was created, run:

   oc get secret instana-agent-key -n instana-agent

Create an instance of the Instana agent by using the OpenShift web console

1. In the navigation menu, click Operators > Installed Operators.

2. Change Project to the instana-agent namespace. Click the drop-down arrow and select the name from the list.

3. In the list on the Installed Operators panel, find and click Instana Agent Operator.

4. Click the Instana Agent tab.

5. Click Create InstanaAgent. The Create InstanaAgent panel opens.

6. Click YAML view to configure the instance.

7. Update these values:

• spec.agent.endpointPort - Endpoint port of your Instana instance.

• endpointHost - Endpoint of your Instana instance.

• spec.agent.keysSecret - Name of the opaque secret that you created earlier, 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.

1. Click Create. You are redirected to the Instana Agent tab. The instance is added to the list of instances.

2. 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 to Ready.

Create an instance of the Instana agent by using the CLI

1. Create an InstanaAgent YAML file. For example, create a file that is called instana-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 opaque secret that you created earlier, 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.

2. Apply the YAML file to the cluster:

   oc apply -f instana-agent.yaml

3. 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.

4. 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).

In Cloud Pak for Integration, Instana monitoring is supported for the following instance types:

• Integration runtime

• Kafka cluster

• Queue manager

• Enterprise gateway

Depending on your deployment, you might 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.

1. In the navigation menu, click Operators > Installed Operators.

2. For Project, select the instana-agent namespace.

3. Click the Instana Agent operator.

4. Click the Instana Agent tab.

5. Click your instance of instana-agent.

6. 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 IBM App Connect Enterprise (ACE)

• Monitoring Kafka (IBM Event Streams)

Queue manager and Enterprise gateway

Instana does not automatically discover Queue manager and Enterprise gateway instances, so you need to configure the Instana agent sensor. For more information, see the applicable task in the Instana documentation:

• Monitoring IBM DataPower

• Monitoring IBM MQ

  Important: 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 to configure an authenticated Queue manager to work with Instana, see Configuring authenticated IBM Instana monitoring with MQ TLS (in the MQ documentation).

If you configured the Instana agent in the previous step, confirm that the connection to Instana for MQ and DataPower is successful.

1. Access Instana.

2. Click the Infrastructure icon.

3. Click the Entity Explorer tab.

4. Click or search for the configured instance.

5. Confirm that the instance is available:

• For IBM MQ, the IBM MQ Queue Manager is listed after the name of the underlying queue manager.

• For IBM DataPower, the IBM DataPower appliances are listed after the name of the DataPower host or IP address.

• If you can't find the instance, refer to the Instana guides, or contact Instana support.

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.

1. Create an API token for Instana to use to generate monitoring links in the Platform UI:

   1. In Instana, click the Settings icon.

   2. Click the Team Settings tab, then click API Tokens.

   3. Click Add API Token to create a new API token. You do not need to select any permissions.

      

2. Copy the token, then 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 the following command:

   oc create secret generic <secret_name> \
     --from-literal=apiToken=<api_token_value>

   For example:

   oc create secret generic observabilitysecret \
     --from-literal=apiToken=545454aabbab

   This command creates a secret that is named observabilitysecret.

   For more information, see Managing Secrets using kubectl (in the Kubernetes documentation).

3. Open the Platform UI custom resource for editing:

   • To open the resource from the Platform UI, log in with your admin credentials. Find the Platform UI instance in the list of instaces, click the overflow menu (three-dot icon) for that instance, then click Edit. Click the YAML tab.

   • To open the resource with the CLI, log in to the OpenShift CLI with your credentials. Change the project to the namespace of the Platform UI:

     oc project <namespace>

     Edit the resource by running the following command, replacing <instance_name> with the name of your instance:

     oc edit pn <instance_name>

4. Modify the instance by adding the following YAML code to the spec section:

   observability:
     authentication:
       secretName: <secret-name>
       apiToken: <api-token-key-name>
       caCertificate: <ca-certificate-key>
     url: <base-url> 
     clusterName: <cluster-name>

   Replace the placeholders with the following values:

   • secretName: the name of the secret that contains the API token.

   • apiToken: the key name within the secret that contains the API token. The default value is apiToken.

   • caCertificate: the key name within the secret that contains the CA certificate for your Instana solution. Set this value only when Instana is installed as an on-premises solution.

   • clusterName: the name of the cluster that is given in the Instana agent.

   • url: the base URL of the tenant unit. For example: https://test-example.instana.io. This value is the same URL that you use to access the Instana user interface.

5. To access Instana monitoring in the Platform UI, log in, click the overflow menu (three-dot icon) for the instance that you want, then click Monitoring.