> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/traceable/agent-docs/istio.md).

# Traceable Istio Agent

This section provides documentation for the Traceable Istio agent, which integrates with Istio service mesh deployments to deliver API observability and inline protection.

## Quick Links

* [Deployment Architectures](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/README.md)
  * [Direct TPA vs TME](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/direct-tpa-vs-tme.md)
  * [Load Balancer and TLS](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/lb-and-tls.md)
  * [ext\_proc Operating Modes](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/ext-proc-modes.md)
  * [v1 vs v2 and Migration](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/v1-vs-v2.md)
  * [Latency and Timeouts](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/latency-and-timeouts.md)
  * [SSE and WebSocket](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/sse-and-websocket.md)
  * [Custom Blocking Responses](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/custom-blocking.md)
  * [Ingress, Egress, and Selectors](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/ingress-egress-and-selectors.md)
* [v1](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v1/README.md)
  * [Configuration](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v1/Configuration.md)
  * [Installation Steps](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v1/InstallationSteps.md)
  * [Troubleshooting](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v1/Troubleshooting.md)
* [v2](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v2/README.md)
  * [Configuration](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v2/Configuration.md)
  * [Installation Steps](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v2/InstallationSteps.md)
  * [Troubleshooting](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/v2/Troubleshooting.md)
* [Images](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/images/README.md)

Istio is an open-source service mesh that integrates with existing distributed applications. It also serves as a platform with APIs that enable integration with logging and telemetry systems. Traceable provides an agent that integrates with Istio to monitor your system and detect anomalies and attacks. Traceable can also block attacks on your system based on the configurations that you make on the platform. For more information on blocking, see [Policies](https://docs.traceable.ai/docs/protection-policies). The following is a high-level deployment diagram for Traceable's Istio solution.

The agent is available in two versions: v1 and v2, each with different architectures and use cases.

## Version Comparison: v1 vs v2

### Architectural Differences

| Feature                | v1                                                                     | v2                                                                                      |
| ---------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Envoy Filter Type**  | Uses`ext_authz` for request capture and `ext_cap` for response capture | Uses`ext_proc` for both request and response capture                                    |
| **Span Generation**    | Creates 2 spans for each API call (one for request, one for response)  | Creates a single span containing both request and response details                      |
| **Payload Processing** | Better handling of very large payloads                                 | No strict restriction of payload limitation, but better with smaller payloads (\~ 10MB) |
| **Observability Mode** | Not available                                                          | Available ("Send and Go" mode or "Fire and Forget" mode)                                |

### Technical Implementation

#### v1 Architecture

* **Request Path**: Uses Envoy's `ext_authz` filter to intercept and analyze incoming requests
* **Response Path**: Uses a separate `response capture server of ext_cap` filter to capture response data
* **Data Flow**: Two separate data paths result in two spans per transaction

#### v2 Architecture

* **Unified Processing**: Uses Envoy's `ext_proc` filter for both request and response processing
* **Data Flow**: Single processing pipeline results in one span per transaction
* **Observability Mode**: Can be configured in "Send and Go" mode for minimal latency impact

## Recommendations

### When to Use v1

* When you need to process very large payloads (>10MB)
* In environments where you need backward compatibility with older Istio versions (1.10.0+)

### When to Use v2

* For most new deployments (recommended default)
* Deploy TPA in the **same cluster or VPC** as the gateway and connect **`ext_proc`** **directly to TPA** on port **5442**; use TME only when TPA is too far for acceptable latency — see [Deployment Architectures](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/direct-tpa-vs-tme.md)
* When blocking is not required, you can use observability mode (`extProc.observabilityMode: true`) — see [ext\_proc Operating Modes](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/istio/deployment-architectures/ext-proc-modes.md)
* For typical payload sizes up to \~10MB; for very large payloads (>10MB), evaluate v1 or test thoroughly in your environment.
* With newer Istio versions (1.13.0+)

## Version Selection

When installing the Traceable Istio agent using Helm:

* v1 charts use version format `1.x.x`
* v2 charts use version format `2.x.x`

If you don't specify a version when installing with Helm, the latest version (likely v2) will be installed by default. Since istio v1 charts is always released alongside TPA (Traceable Platform agent) latest istio v1 chart will be the latest TPA release version.

```bash
# To install v1
helm install traceableai-istio traceableai/traceableai-istio --namespace istio-system --version 1.57.1

# To install v2
helm install traceableai-istio traceableai/traceableai-istio --namespace istio-system
```