IBM API Connect Analytics Policy

  • Published on Dec 27, 2024
  • 5 minute(s) read

The IBM API Connect Analytics Policy enables integration with the IBM API Connect Analytics subsystem to offload and process API activity data. By configuring this policy, users can enhance observability and analyze data in the Traceable SaaS platform, enabling better decision-making and security insights.

Before you begin

Ensure the following requirements are met before proceeding:

  1. Access Requirements:

    • IBM API Connect Administrator privileges.

  2. Networking:

    • IBM API Connect → TPA: Open a connection to the TPA host on port 5443.

    • TPA → Traceable SaaS: Open a connection to https://api.apac.traceable.ai on port 443.

  3. Configuration:

    • Configure the IBM API Connect activity log policy to capture payloads. For more details, see the IBM documentation.

    • Ensure sufficient storage provisioning to handle the additional logs generated by this configuration in alignment with your internal data retention policies.

  4. Make sure that the Traceable Platform agent (TPA) is installed. For more information, see the Installation section.

  5. Required Information:

    • TPA VM IP/Hostname.

    • Access to the TPA certificate for Base64 conversion.

  6. Download the policy from Traceable’s download site.

Installation

The installation process consists of two steps:

  1. Setting up TLS communication with TPA

  2. Deploying the offloading policy

Step 1 — Setting up TLS communication with TPA

  1. Convert the TPA certificate to Base64 format. Use a Base64 conversion tool or command (e.g., base64 in Linux) to encode the certificate: 

    base64 /path/to/tpa_certificate.crt > tpa_certificate_base64.txt

  2. Create a secret.yaml file with the following structure: 

    apiVersion: v1
kind: Secret
metadata:
  # Update the name to your preferred secret name
  name: offload-certificates
data:
  cacert.crt: "<Base64 Converted Secret>"

  3. Apply the secret in the namespace where the analytics cluster is installed: 

    kubectl apply -f secret.yaml -n <namespace>

Step 2 — Deploy the offloading policy

Follow these steps to deploy the offloading policy. You can complete the steps using either the Red Hat GUI or CLI. The following steps use the CLI to deploy the policy.

  1. Download the current analyticscluster configuration for the IBM API Connect Analytics subsystem. This file contains the existing settings for the analytics subsystem.

    oc get analyticscluster -n <namespace> -o yaml > analyticscluster.yaml

  2. Modify the configuration:

    1. Open the downloaded analyticscluster.yaml file in a text editor.

    2. Look for the spec.analytics section:

      • If the external.offload subsection does not exist, create it.

  3. Add the following configuration to enable offloading: 

    spec:
  analytics:
    external:
      offload:
        enabled: true
        filter: >-
          if "apicapievent" in [tags] {
            ruby {
              code => " require 'base64';
              request_method = event.get('[request_method]');
              source_port = 0;
              path = event.get('[uri_path]');
              scheme = event.get('[request_protocol]');
              source_address = event.get('[client_ip]');
              host = event.get('[host]');
              request_headers = event.get('[request_http_headers]');
              request_headers_hash = {};
              request_headers.each do |header|
                header.transform_keys!(&:downcase);
                request_headers_hash.merge!(header);
              end;
              request_body = event.get('[request_body]');
              encoded_request_body = Base64.strict_encode64(request_body);
              response_body = event.get('[response_body]');
              encoded_response_body = Base64.strict_encode64(response_body);
              status_code = event.get('[status_code]').split(' ')[0];
              response_headers = event.get('[response_http_headers]');
              response_headers_hash = {};
              response_headers.each do |header|
                header.transform_keys!(&:downcase);
                response_headers_hash.merge!(header);
              end;
              message = {
                'request' => {
                  'method' => request_method,
                  'source_port' => source_port,
                  'path' => path,
                  'scheme' => scheme,
                  'source_address' => source_address,
                  'host' => host,
                  'headers' => request_headers_hash,
                  'body' => encoded_request_body,
                },
                'response' => {
                  'status_code' => status_code,
                  'body' => encoded_response_body,
                  'headers' => response_headers_hash
                }
              };
              event.set('[@metadata][newevent]',message.to_json)"
            }
          }
        output: |
          http {
            url => "<REPLACE TPA IP HERE>:5443/ext_cap/v1/req_res_cap"
            http_method => "post"
            codec => "json"
            ssl_certificate_authorities => "/etc/velox/external_certs/offload/cacert.crt"
            content_type => "application/json"
            id => "offload_http"
            format => "message"
            message => "%{[@metadata][newevent]}"
          }
        secretName: offload-certificates

  4. Replace placeholders such as <REPLACE TPA IP HERE> with the actual TPA IP.

  5. Apply the updated configuration:

    1. Upload the updated configuration to the IBM API Connect Analytics subsystem: 

      oc edit analyticscluster -n <namespace>

    2. Copy the modified spec.analytics.external.offload section from your local file and paste it into the appropriate section in the editor.

    3. Save and exit the editor.

Deploying the changes

To enable the offloading policy:

  1. Apply the Configuration: After saving the changes in the analyticscluster configuration, Kubernetes will automatically apply the updates.

  2. Verify the Deployment: Check the status of the analytics cluster. Ensure the cluster status is healthy, and no errors are reported.

    kubectl get analyticscluster -n <namespace>

  3. Restart Pods (if Necessary): If the changes do not take effect immediately, restart the relevant pods: 

    kubectl rollout restart deployment <analytics-cluster-deployment-name> -n <namespace>

  4. Verify in Traceable SaaS: Log in to the Traceable SaaS platform and navigate to Analytics → Spans. Confirm that new spans are being reported.

Verification

To confirm the deployment:

  1. Log in to the Traceable SaaS platform.

  2. Navigate to Analytics → Spans.

  3. Verify that new spans are being reported.

Uninstall

To remove the offloading policy:

  1. Edit the analyticscluster configuration: 

    kubectl edit analyticscluster -n <namespace>

  2. Remove the offloading policy sections added earlier.

  3. Apply the changes by saving and exiting the editor.

  4. Verify the uninstallation:

    • Ensure the cluster status is healthy using the following: 

      kubectl get analyticscluster -n <namespace>