Sidecar Pattern Bringing Theory to Practice with an Example

A sidecar works because a second container is scheduled into the same Kubernetes Pod as your application, so both containers share one network namespace — they reach each other on localhost — and a set of iptables rules inside the Pod can silently redirect the app's inbound and outbound traffic through the sidecar, letting it add TLS, retries, and telemetry without the application knowing the sidecar exists.

That last clause is the whole point, and it is exactly what a naive example gets wrong. The previous version of this page said the sidecar and the app must live "within the same container" and then had the app make an explicit HTTP call to the sidecar. Both are wrong, and correcting them is how you actually understand the pattern.

The two things everyone gets wrong

1. Same Pod, not same container

A container is a single process tree with its own filesystem. If you jam two programs into one container you have thrown away independent images, independent restarts, independent resource limits, and independent CVE patching — every reason to split them in the first place. The correct unit is the Pod: two (or more) containers, each with its own image and lifecycle, that Kubernetes always schedules together on the same node and that share the Pod's network namespace and (optionally) volumes. "Deploy them in the same Pod" is right; "same container" is not.

2. The app should not call the sidecar — the sidecar intercepts the app

The old example had getData() do a blocking RestTemplate.getForEntity("http://localhost:8081/log", ...) on every request. That is the app reaching out to a helper. It contradicts the promise from the previous lesson that the sidecar "intercepts all incoming and outgoing traffic," and it defeats the pattern: the app now hard-codes the sidecar's port, blocks on it, and fails if it is down. Real traffic-interception sidecars (Envoy under Istio/Linkerd) require zero application changes.

Two legitimate flavors — know which one you mean

The previous lesson described the proxy flavor ("intercepts all traffic"), so the worked example below is a proxy. The helper flavor is real too — but even it does not put a synchronous call on the app's hot path.

The app you deploy is boring on purpose

Because interception happens below the app, the Java service is the original, unmodified version — no RestTemplate, no knowledge of a sidecar. That is the feature, not a shortcut:

@SpringBootApplication
@RestController
public class MainApplication {

    public static void main(String[] args) {
        SpringApplication.run(MainApplication.class, args);
    }

    @GetMapping("/api")
    public String getData() {
        return "Hello, Sidecar!";   // no sidecar call anywhere
    }
}

All the sidecar wiring lives in the Pod spec and in iptables, which the mesh's init-container installs automatically:

# The two containers share the Pod's network namespace.
apiVersion: v1
kind: Pod
metadata:
  name: orders
spec:
  containers:
    - name: app                     # your unmodified image
      image: orders:1.0
      ports: [{ containerPort: 8080 }]
    - name: istio-proxy             # the Envoy sidecar
      image: envoyproxy/envoy
      ports: [{ containerPort: 15006 }, { containerPort: 15001 }]

# What the init-container installs (simplified):
# redirect everything ARRIVING at the Pod into Envoy's inbound port
iptables -t nat -A PREROUTING  -p tcp -j REDIRECT --to-port 15006
# redirect everything the app SENDS OUT into Envoy's outbound port
iptables -t nat -A OUTPUT      -p tcp -j REDIRECT --to-port 15001

Why the naive version is wrong: the old code baked http://localhost:8081/log and a blocking call into getData(). That couples the app to the sidecar's port, adds a synchronous round-trip to every request, and makes /api fail when the logger is down — a helper that was supposed to be invisible now sits on your critical path. If you truly want a logging helper, have the app write to a file in a shared emptyDir volume and let a Fluent Bit sidecar tail it asynchronously; the request path never touches the sidecar.

Worked trace: one request through the proxy

Client Pod calls GET http://orders:8080/api. Watch where the app's port (8080) is quietly bent to Envoy's (15006).

Nowhere in steps 1–7 did the application call anything. Interception, not invocation, is the mechanism.

Pitfalls

• Startup/shutdown races. Before native sidecars (Kubernetes 1.29 initContainers with restartPolicy: Always, KEP-753), the app could start before Envoy was ready and its first outbound calls failed, or the app kept serving after Envoy died. If your app makes calls at boot (DB migration, config fetch), you must order the sidecar first.
• The Pod never fully exits. A batch/Job Pod finishes its work but the Envoy container runs forever, so the Job never reports Complete. Classic symptom of forgetting sidecar termination handling.
• Resource doubling. Every Pod now carries an Envoy (~50–150 MB RAM, a fraction of a core). At 2,000 Pods that is real money and real scheduling pressure — the tax is per-Pod, not per-service.
• Silent traffic that skips the mesh. UDP, or ports excluded from the iptables capture, bypass Envoy — so you think you have mTLS everywhere but a metrics port is plaintext.
• Debugging gets a new layer. A 503 might be the app, or Envoy's retry/circuit-breaker/outlier-detection. You now read two access logs per hop.

When to use it — and when not to

Reach for a sidecar (mesh) when: you have a polyglot fleet (Java, Go, Node) that all need the same cross-cutting behavior — mTLS, retries, uniform tracing, traffic-shifting for canaries — and a platform team wants to own that policy centrally without asking every app team to add a library and redeploy. The bigger and more heterogeneous the fleet, the more the sidecar pays off.

Do not reach for it for a single service or a monolith, for latency-critical hot paths where an extra proxy hop and its CPU are unacceptable, or for a small single-language team where a library is simply cheaper to run and reason about.

Trade-offs vs named alternatives

• vs in-process library (Resilience4j, gRPC interceptors, OpenTelemetry SDK): the library has zero extra hop and the lowest latency, and it is trivial to debug — but it is per-language, ships inside the app so a policy change means redeploying every service, and drifts across versions. The sidecar buys language-independence and central control at the cost of latency and per-Pod RAM/CPU.
• vs API gateway / edge proxy: a gateway centralizes concerns at the edge (one place to manage) but does nothing for east-west service-to-service traffic and is a shared choke point. Sidecars secure and observe every internal hop.
• vs eBPF / ambient mesh (Cilium, Istio ambient): moves L4 work into the kernel with no per-Pod proxy, cutting the resource tax — but L7 features are less mature/flexible than a full Envoy per Pod.

Choose the sidecar when you need uniform L7 policy across a large polyglot fleet you cannot or will not modify. Prefer an in-process library when you are single-language, latency-sensitive, and small enough that per-Pod proxies are pure overhead.

Takeaways

• Same Pod, separate containers — "same container" is the error to unlearn; the Pod is what makes localhost and shared volumes work.
• A proxy sidecar intercepts via iptables and the shared network namespace; the app is unmodified and never calls it. A synchronous app→sidecar call is not this pattern.
• Two valid flavors: transparent proxy (mesh) and async helper (log shipper via shared volume). Neither puts the sidecar on the app's synchronous hot path by design.
• The bill is real and per-Pod: +0.3–1.2 ms/hop and ~50–150 MB RAM each. Worth it for a large polyglot fleet; wasteful for one service — use a library there.

Re-authored and deepened for this guide. Sources: Kubernetes documentation (Pods, and native sidecar containers, KEP-753); Istio architecture and traffic-management docs (sidecar injection, iptables redirection to Envoy ports 15001/15006); Envoy proxy documentation; Bilgin Ibryam & Roland Huß, Kubernetes Patterns (Sidecar and Adapter/Ambassador patterns); Microsoft Azure Architecture Center, "Sidecar pattern." The original page's "same container" claim and its RestTemplate-to-sidecar example were corrected here.