Mulesoft Flex Gateway policy

The MuleSoft Flex Gateway policy enables Traceable data collection by capturing API request and response payloads as they flow through Flex Gateway. This Rust-based custom policy intercepts incoming requests and outgoing responses, queues them, and asynchronously transfers the data to the Traceable Platform Agent (TPA). The transfer occurs at regular intervals or when the queue size exceeds a configured limit, ensuring efficient and reliable delivery without affecting the inline request–response flow.

What you will learn in this topic

The prerequisites required for installing the MuleSoft Flex Gateway policy.
How to download, configure, and publish the Flex Gateway policy.
How to attach the policy at the global (automated policy) or individual API level.
How to configure reporting, TLS, and data capture options.

Before you begin

Ensure the following prerequisites are met before installing the policy:

Rust: Minimum version 1.74.0.
Flex Gateway runtime: Supported on versions 1.6.1 and later.
Node.js: Minimum version 16.
MuleSoft tools:
- Install Anypoint CLI and the PDK plugin (see MuleSoft Documentation).
- Install Cargo (see Cargo Book).
Conditional step for Cargo setup (required if Cargo is freshly installed or has not been connected with Anypoint before):
To enable Cargo to authenticate with the Anypoint registry, follow this sequence:
1. Configure the Git credential helper. This step ensures Git can automatically provide the token when accessing the Anypoint registry:
```
git config --global credential."https://anypoint.mulesoft.com/git/68ef9520-24e9-4cf2-b2f5-620025690913/19f9d123-5775-44d7-a67f-49328cfa00b0".username <your-username>
git config --global --replace-all credential."https://anypoint.mulesoft.com/git/68ef9520-24e9-4cf2-b2f5-620025690913/19f9d123-5775-44d7-a67f-49328cfa00b0".helper ""
git config --global --add credential."https://anypoint.mulesoft.com/git/68ef9520-24e9-4cf2-b2f5-620025690913/19f9d123-5775-44d7-a67f-49328cfa00b0".helper '!f() { test "$1" = get && echo "password=$(anypoint-cli-v4 pdk get-token)"; }; f'
```
2. Install the Anypoint Cargo plugin. This command makes the Cargo client aware of the Anypoint registry:
```
cd traceable-flex-gateway-policy
cargo install cargo-anypoint@1.2.0 --registry anypoint --config .cargo/config.toml
```
3. Log in to Cargo with the Anypoint registry. This validates your authentication and allows further package operations:
```
cargo login --registry anypoint $(anypoint-cli-v4 pdk get-token)
```
Note
Depending on your shell or Git version, the syntax for the credential helper function may behave differently. The provided example has been tested and validated, but if you encounter issues during cargo login, review your shell’s handling of functions and $ escaping. Consult your platform’s Git documentation for adjustments.
System requirements: Install the build-essential package on Linux. This meta-package provides the fundamental compiler and build tools (for example, gcc, g++, make, and common headers) required to compile native dependencies used by the Rust-based policy and its crates. Without these tools, builds can fail with missing headers or toolchain errors.
```
sudo apt update
sudo apt install build-essential
```

Configuration steps

In this section, you will install and publish the Flex Gateway policy, and then attach it either as an automated policy (applied across all APIs in an environment) or to a specific API. Finally, you will configure the required reporting and data capture values to ensure that request and response data is sent to the Traceable Platform Agent (TPA).

Step 1 — Set up the policy

Start by preparing and publishing the policy so it becomes available for use in Anypoint Exchange.

Download the Flex Gateway policy package from the download site.
Set the organization ID in your environment:
```
export ANYPOINT_ORG=<replace-org-id>
```

Unzip the downloaded package and run the install script:

cd traceable-flex-gateway-policy
./flex-gateway-policy-install.sh

This action publishes the policy to Anypoint Exchange as an asset, making it available for use.

Step 2 — Attach the policy

Once the policy is published, you can attach it. Depending on whether you want the policy applied globally or to a single API, there are two approaches.

Option A — Attach as an automated policy

This option applies the policy across all APIs in a given environment.

Step 1 — Log in to Anypoint Platform and go to API Manager.
Step 2 — From the left menu, select Automated Policies.
Step 3 — Click Add automated policy and choose the uploaded Traceable Flex Gateway policy.

Step 4 — Select the uploaded Traceable Flex Gateway policy.

Step 5 — Configure default values. One of the following must be set, depending on the TA-TLS-ENABLED flag:

If TA-TLS-ENABLED is enabled, configure TA-REPORTING-SERVICE.
If TA-TLS-ENABLED is disabled, configure TA-REPORTING-ENDPOINT using http://<REPLACE_TPA_IP>:5442/ext_cap/v1/req_res_list_cap.

Configuring TLS for automated policy

If you have enabled TA-TLS-ENABLED, additional TLS setup is required before the policy can communicate with the Traceable Platform Agent over HTTPS. Follow these steps:

Locate the service definition file — The downloaded policy package includes a file at service/service.yaml.
Edit the service.yaml file:
- Set a name under metadata.name. This will later be used in the policy configuration.
- Set the namespace under metadata.namespace.
- Set the address under spec.address to the TPA endpoint over HTTPS (port 5443).
Example:
```
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: traceable-https-egress-service
  namespace: default
spec:
  address: https://<REPLACE_TPA_IP>:5443
```

Define the policy binding: The service name and namespace must match between the Service and the PolicyBinding. If you change them from the defaults, ensure Service.metadata.name = PolicyBinding.spec.targetRef.name and Service.metadata.namespace = PolicyBinding.spec.targetRef.namespace.

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: traceable-https-egress-service-binding
spec:
  targetRef:
    kind: Service
    name: traceable-https-egress-service
    namespace: default
  policyRef:
    name: tls-outbound
  config:
    skipValidation: true
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert CA certificate here
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert private key here
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate here
        # -----END CERTIFICATE-----

For mutual TLS (mTLS): set skipValidation: false and include the CA, certificate, and key fields.
For one-way TLS: remove the trustedCA, certificate.crt, and certificate.key fields.

Deploy the service.yaml: Depending on your Flex Gateway deployment mode, copy this file into the Flex Gateway configuration directory. For Ubuntu:
```
cd traceable-flex-gateway-policy 
sudo cp service/service.yaml /usr/local/share/mulesoft/flex-gateway/conf.d/
```
Upload and attach the policy: Once the service file is configured and deployed, upload the policy to Exchange and attach it to APIs. On the configuration screen, ensure TA-TLS-ENABLED is checked.
Configure TA-REPORTING-SERVICE in the policy:
- name: must match the metadata.name in service.yaml.
- namespace: must match the metadata.namespace in service.yaml.
- endpoint: https://<REPLACE_TPA_IP>:5443/ext_cap/v1/req_res_list_cap.
Ensure that the spec.address defined in service.yaml matches the host specified in the endpoint.

Step 6 — Apply the policy and verify that it applies to all APIs in the environment.

Option B — Attach to a specific API

This option applies the policy only to the API you select.

Log in to Anypoint Platform and go to API Manager.
Select the API to which you want to attach the Traceable policy.
Open the Policies section and select the Flex Gateway policy.
Select the Traceable Flex Gateway policy.
Configure the required values (for example, set TA-REPORTING-ENDPOINT to point to your TPA IP).
Apply the policy and verify that it shows as attached.

Step 3 — Configure policy values

After attaching the policy, configure its runtime parameters. These values control what traffic is captured and how the captured data is sent to the TPA. The following table describes each option:

Configuration	Description
`TA-REPORTING-ENDPOINT`	HTTP endpoint for sending data to TPA (non-TLS). Example: `http://<tpa-host>:5442/ext_cap/v1/req_res_list_cap`.
`TA-REPORTING-SERVICE`	TLS-enabled service reference (name, namespace, endpoint). Example endpoint: `https://<tpa-host>:5443/ext_cap/v1/req_res_list_cap`.
`TA-SERVICE-NAME`	Service name for Flex applications.
`TA-DATA-CAPTURE-ALLOWED-CONTENT-TYPES`	Comma-separated list of allowed content types (for example, `json,graphql,x-www-form-urlencoded`).
`TA-DATA-CAPTURE-BODY-MAX-SIZE-BYTES`	Maximum body size to capture.
`TA-TPA-REQUEST-TIMEOUT`	Timeout for calls to TPA (default: `10000` ms).
`TA-DATA-CAPTURE-HTTP-BODY-REQUEST`	`true` or `false` – capture HTTP request body.
`TA-DATA-CAPTURE-HTTP-BODY-RESPONSE`	`true` or `false` – capture HTTP response body.
`TA-DATA-CAPTURE-HTTP-HEADERS-REQUEST`	`true` or `false` – capture request headers.
`TA-DATA-CAPTURE-HTTP-HEADERS-RESPONSE`	`true` or `false` – capture response headers.
`TA-BATCH-INTERVAL`	Interval between consecutive TPA calls (default: `10000` ms).
`TA-MAX-BATCH-SIZE`	Maximum batch size per call (default: `50`).

TLS quick reference (applies to automated policy and per-API attach)

If your deployment requires secure communication with the Traceable Platform Agent, follow these rules regardless of how the policy is attached:

Always use TA-REPORTING-SERVICE with a valid service definition (name, namespace, endpoint).

The endpoint must be specified as:

https://<tpa-host>:5443/ext_cap/v1/req_res_list_cap

Refer to MuleSoft Flex Gateway documentation for TLS configuration in local mode.