Traffic modes

The top-level mode chooses two things: where traffic is captured and who serves the caller’s response.

.outprobe.yaml

mode: divert

At a glance

Mode	Capture point	Callers caught	Response served by	feed
divert	Caller-side VirtualService	Meshed	Local app when rule matches	Supported
mirror	Caller-side VirtualService mirror	Meshed	Real target, always	Ignored
inbound-divert	Target-side EnvoyFilter route	Meshed + non-mesh	Local app when sidecar rule matches	Ignored
inbound-mirror	Target-side EnvoyFilter mirror	Meshed + non-mesh	Real target, always	Ignored

Start with divert when all relevant callers are in the mesh and you need your local response returned. Use a mirror mode when observation is enough. Reach for an inbound mode only when caller-side routing misses sidecar-less callers.

divert default

A caller’s Istio sidecar routes candidate traffic through the relay. The relay tunnels a matching request to your laptop and returns your local app’s response. Unmatched traffic is transparently proxied to the real Service with x-outprobe-bypass: 1 to avoid looping through the VirtualService.

meshed caller → caller sidecar → VirtualService → relay
                                               ├─ match → laptop → local response
                                               └─ no match → real target

Use it when:

• your relevant callers have Istio sidecars;
• you need to change the response seen by the caller;
• you want a feed: path/header pre-filter to reduce inline traffic.

The relay is inline for the diverted subset. A relay outage affects that subset until routing is removed.

mirror observe only

The caller-side VirtualService sends the original request to the target and an asynchronous copy to the relay. A matching copy reaches your laptop, but Istio discards the local response.

meshed caller → caller sidecar ─────────────→ real target → real response
                              └─ mirror copy → relay → laptop (response discarded)

Use it when:

• breakpoints, tracing, or log inspection are enough;
• the caller must never depend on the relay;
• all relevant callers are meshed.

feed: is ignored in v1 and all caller-side traffic is mirrored. If ingress is configured in mirror mode, every ingress route must use cloneFrom so outprobe can preserve the real backend and add a Gateway API RequestMirror filter.

inbound-divert all callers

A target-side EnvoyFilter inserts one selective inbound route into the target’s own Istio sidecar. Only a request matching the active JWT/header rule is routed to the relay; everything else falls through to the pod’s existing catch-all route.

any caller → target Service → target sidecar
                              ├─ active rule matches → relay → laptop → local response
                              └─ no match → target app → real response

Use it when a relevant caller has no sidecar and you need your local response returned.

The CLI preflights that the Service has a pod selector and running targets have istio-proxy. It hard-errors for sidecar-less or ambient-only targets. After apply, it attempts to verify the inserted route through the live proxy config.

Low-level and version-coupled

EnvoyFilter patches Istio/Envoy internals that can change between versions. outprobe makes failures loud with preflight and verification, but this mode is more cluster-coupled than caller-side divert.

JWT selection in this mode uses a small, unverified Lua payload decode in the target sidecar. Malformed or non-matching tokens fail safe to the real app. Unusual JSON escaping or formatting can cause the sidecar selector to miss a claim that the relay itself would decode.

inbound-mirror all callers · observe

The target’s sidecar mirrors a copy of every inbound request to the relay while the target app serves the original.

any caller → target Service → target sidecar → target app → real response
                              └─ mirror copy → relay → laptop (response discarded)

Use it when sidecar-less callers must be observed and serving a local response is unnecessary.

This mode has no selective target-side pre-filter: every inbound body is copied to the relay, which can be expensive for a busy service. Prefer mirror whenever every caller is already meshed.

Choosing a mode

Need	Recommended mode
Return a local response; callers are meshed	divert
Observe only; callers are meshed	mirror
Return a local response; some callers are not meshed	inbound-divert
Observe non-mesh callers	inbound-mirror
Lowest caller impact	mirror
Path/header pre-filter before relay	divert with feed

Read Scope & caveats before using an inbound mode on a busy or security-sensitive service.