--- title: Transparent Proxy / Sidecar Mode shortTitle: Transparent Proxy description: Run MockServer as a Kubernetes sidecar with transparent proxy interception for service mesh integration. layout: page pageOrder: 3 section: 'Chaos Testing' subsection: true sitemap: priority: 0.7 changefreq: 'monthly' lastmod: 2026-06-01T08:00:00+00:00 keywords: sidecar proxy, transparent proxy, kubernetes sidecar, iptables redirect, mockserver sidecar, conntrack ---

MockServer can run as a Kubernetes sidecar with transparent HTTP proxy interception. This enables service mesh integration patterns where MockServer intercepts traffic destined for external services without any application code changes.

## Transparent Proxy Mode

When `transparentProxyEnabled` is set to `true`, MockServer treats all incoming HTTP connections as proxy requests. Instead of requiring clients to send explicit HTTP CONNECT requests or configure proxy settings, it uses the `Host` header from each request to determine the forwarding target.

This works with Linux `iptables` REDIRECT rules that redirect outbound traffic to MockServer's port, making the interception completely transparent to the application.

### How it works

1. An init container sets up iptables rules to redirect outbound HTTP/HTTPS traffic to MockServer's port
2. MockServer resolves the original destination:
   - On Linux: reads the original destination from the kernel conntrack table (`/proc/net/nf_conntrack`), which records the pre-REDIRECT destination. This works even when the Host header is missing or incorrect.
   - Fallback: if conntrack is unavailable (non-Linux, module not loaded, or entry flushed), MockServer falls back to reading the `Host` header.
3. If an expectation matches, MockServer returns the mock response
4. Otherwise, MockServer forwards the request to the original target

### Configuration

Property | Default | Description
--- | --- | ---
`transparentProxyEnabled` | `false` | Enable transparent proxy mode

Environment variable: `MOCKSERVER_TRANSPARENT_PROXY_ENABLED`

### iptables init container example

Add an init container to your Pod spec to redirect outbound traffic to MockServer:

    initContainers:
      - name: iptables-init
        image: alpine:3.19
        securityContext:
          capabilities:
            add: ["NET_ADMIN"]
        command:
          - sh
          - -c
          - |
            # RETURN first -- exclude MockServer's own egress (UID 65534) to prevent redirect loop.
            # The UID must match app.runAsUser (default 65534 in the Helm chart).
            iptables -t nat -I OUTPUT -m owner --uid-owner 65534 -j RETURN
            # Then REDIRECT HTTP and HTTPS to MockServer
            iptables -t nat -A OUTPUT -p tcp --dport 80 -j REDIRECT --to-port 1080
            iptables -t nat -A OUTPUT -p tcp --dport 443 -j REDIRECT --to-port 1080

## Helm Chart

The MockServer Helm chart includes sidecar configuration values:

    sidecar:
      enabled: false
      transparentProxy: false
      iptables:
        enabled: false
        excludeUid: 65534   # must match app.runAsUser to prevent redirect loop

When `sidecar.transparentProxy` is `true`, the chart sets `MOCKSERVER_TRANSPARENT_PROXY_ENABLED=true` in the deployment.

When `sidecar.iptables.enabled` is `true`, the chart renders an init container that adds a UID-based RETURN rule (to exclude MockServer's own egress) before any REDIRECT rules, preventing an infinite redirect loop. The `excludeUid` must match `app.runAsUser` (both default to 65534).

## Original Destination Resolution (SO_ORIGINAL_DST)

On Linux with the `nf_conntrack` kernel module loaded, MockServer reads the original destination of intercepted connections from `/proc/net/nf_conntrack`. This provides accurate target resolution even when the Host header is absent or incorrect.

Requirements:

- Linux only -- on other OSes, MockServer gracefully falls back to Host-header resolution
- nf_conntrack module -- must be loaded and `/proc/net/nf_conntrack` must be readable
- iptables REDIRECT -- the rule must use `-j REDIRECT`
- NET_ADMIN capability -- required for the iptables init container

If conntrack is unavailable, MockServer automatically falls back to Host-header-based resolution with no configuration change needed.

## Limitations

- Conntrack lookup is O(n) with a cap -- the `/proc/net/nf_conntrack` file is parsed per connection, capped at 200,000 lines. If the conntrack table exceeds this limit, MockServer falls back to Host-header resolution. For high-throughput production use, consider a dedicated transparent proxy.
- Linux only for conntrack -- original-destination resolution via conntrack requires Linux. On other OSes, the transparent proxy falls back to Host-header resolution.
- iptables not automatic -- an init container or external mechanism must configure traffic redirection.