Enabling IBM Instana monitoring

You need to set up a namespace (project) for the Instana agent and configure its service account permissions.

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.

Using the CLI:

Run this command to create the namespace:

oc new-project instana-agent

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

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.

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

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

2. Apply the YAML file to the cluster:

   oc apply -f instana-secret.yaml

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

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

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

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

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

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

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

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)

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)

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)

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

1. Instana requires an API token to generate monitoring links in the Platform UI. To create the token:

   1. Access Instana.

   2. Click the Settings icon.

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

   4. Click Add API Token to create a new API token.

      

      You do not need to select any permissions.

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

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 Platform UI or the CLI.

Using the Platform UI:

1. Log into the Platform UI with your admin credentials.

2. In the navigation panel, click Administration > Integration instances.

3. In the list of instances, find the instances of type Platform UI.

4. Click the overflow menu (three-dot icon), then click Edit.

5. Click the YAML tab.

6. Modify the instance by adding the following to the spec section:

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

   Note these values for the example:

   • 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 when Instana is installed 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:

1. Log in to the OpenShift CLI.

2. Change the project to the namespace of the Platform UI:

   oc project <namespace>

3. Edit the resource by running this command, replacing with the name of your instance:

   oc edit pn <instance_name>

4. Modify the PlatformNavigator custom resource by adding the following observability section to the spec 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.

To access Instana monitoring:

1. Log in to the Platform UI.

2. Click Integration Instances to get a list of available instances.

3. Hover over the overflow menu (three-dot icon) for the instance you want and click Monitoring .

Cause: To diagnose the issue, confirm there's a connection between the capability instance and the Instana agent.

1. Sign in to the Instana user interface.

2. Click Infrastructure > Entity Explore > Search/Find Capability > view capability instance. If you are unable to find the instance of the capability, there is an issue with the connection between the Instana agent (sensor) and the capability.

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

For more information about diagnosing and solving this issue, see Problem when you install two different cert-managers.