Sidecar Pattern in Microservices

Picture a motorcycle with a sidecar attached. The motorcycle does the main job, driving, while the sidecar adds extra capabilities, such as carrying a passenger or luggage, without changing the motorcycle itself. The Sidecar pattern in microservices works exactly like this.

This guide explains how sidecars work, why they are useful, and how to run them in Kubernetes, with Docker Compose and in a service mesh. It also covers the Ambassador and Adapter variations, sidecar-less alternatives, and best practices, with configuration and Java examples.

1. What Is the Sidecar Pattern?

The Sidecar pattern attaches a helper component, the sidecar, to a main application, the microservice, to extend or enhance it without changing the application’s code.

In technical terms, the sidecar is a separate process or container that runs right next to the main application: in the same Kubernetes pod, or on the same virtual machine. The two share the same life cycle: they are created, scaled and removed together. If the service scales to five instances, there are five sidecars as well.

 +-------------------------- Pod / host ---------------------------+
 |                                                                  |
 |   [ Main service ]  <--- localhost --->  [ Sidecar ]             |
 |    business logic                        logging, metrics,       |
 |    (the motorcycle)                      security, proxying      |
 |                                          (the sidecar)           |
 +------------------------------------------------------------------+

2. Why Do We Need the Sidecar Pattern?

Every microservice needs the same supporting features: logging, metrics, security, configuration, retries. The Sidecar pattern moves these non-business responsibilities into a helper, so the service stays simple and focused:

3. How a Sidecar Works with Its Service

Because the main container and the sidecar run together in one unit, they share resources that make cooperation easy:

Communication over localhost is very fast and needs no service discovery: the sidecar is always at the same address.

4. A Practical Example: Metrics, Discovery and Logs

Consider a service that must report metrics, register with service discovery and send its logs to a central store.

4.1 Without a sidecar

The microservice code contains client logic for the metrics system, the discovery system and the log store. Every service, in every language, needs its own version of this code. It bloats the service and makes upgrades painful.

4.2 With a sidecar

The main service contains only business logic. A separate sidecar container handles the infrastructure work, and they talk through localhost or a shared volume.

5. A Sidecar in Kubernetes

In Kubernetes, a sidecar is simply a second container in the same pod. Here, a log shipper reads the order service’s log files from a shared emptyDir volume:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: order-service
  template:
    metadata:
      labels:
        app: order-service
    spec:
      containers:
        # 1. The main application
        - name: order-service
          image: shop/order-service:2.1
          ports:
            - containerPort: 8080
          env:
            - name: LOGGING_FILE_NAME          # Spring Boot: logging.file.name
              value: /var/log/app/order-service.log
          volumeMounts:
            - name: app-logs
              mountPath: /var/log/app
          resources:
            requests: { cpu: "500m", memory: "512Mi" }

        # 2. The sidecar: ships the log files to the central log store
        - name: log-shipper
          image: fluent/fluent-bit:3.1
          volumeMounts:
            - name: app-logs
              mountPath: /var/log/app
              readOnly: true
          resources:
            requests: { cpu: "50m", memory: "64Mi" }
            limits: { cpu: "100m", memory: "128Mi" }

      volumes:
        - name: app-logs
          emptyDir: {}          # shared folder that lives as long as the pod

Fluent Bit is configured, through its own configuration file, to read /var/log/app/*.log and send the entries to the log store. Scaling the deployment to 10 replicas automatically creates 10 log shippers, one per pod.

6. Native Sidecar Containers in Kubernetes

Ordinary sidecar containers start and stop at the same time as the main container, which can cause problems: the app may start before its proxy is ready, or the log shipper may stop before the last logs are sent. Recent Kubernetes versions offer native sidecar containers to fix this. A native sidecar is an init container with restartPolicy: Always:

spec:
  initContainers:
    - name: log-shipper
      image: fluent/fluent-bit:3.1
      restartPolicy: Always       # turns this init container into a native sidecar
      volumeMounts:
        - name: app-logs
          mountPath: /var/log/app
          readOnly: true
  containers:
    - name: order-service
      image: shop/order-service:2.1
      volumeMounts:
        - name: app-logs
          mountPath: /var/log/app

7. What Changes in the Java Application

A sidecar removes code from your service, but the service must still cooperate with it. For a Spring Boot service, that usually means a few small settings:

spring:
  application:
    name: order-service

# Write logs where the log-shipper sidecar can read them
logging:
  file:
    name: ${LOGGING_FILE_NAME:/var/log/app/order-service.log}

# Expose health and metrics for sidecars and the platform
management:
  endpoints:
    web:
      exposure:
        include: health,prometheus
  endpoint:
    health:
      probes:
        enabled: true

For metrics, add micrometer-registry-prometheus, and Spring Boot publishes everything at /actuator/prometheus, ready for a monitoring agent or sidecar to collect. The business code does not change at all.

8. The Ambassador: A Sidecar for Outgoing Calls

The Ambassador pattern is a special kind of sidecar that acts as a local proxy for a service’s outgoing calls. The application calls the ambassador on localhost, and the ambassador handles the hard parts of talking to a remote system: TLS, authentication, retries, timeouts, circuit breaking and monitoring.

Example: the order service calls an external payment provider. Instead of building all that logic into the service, it calls an ambassador sidecar, such as an Envoy proxy configured for the provider:

package com.example.order.payment;

import java.math.BigDecimal;

import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;

@Component
public class PaymentProviderClient {

    private final RestClient restClient;

    public PaymentProviderClient(RestClient.Builder builder) {
        // The ambassador sidecar listens on localhost:9000.
        // It adds TLS, the API key, retries and timeouts before
        // forwarding the call to https://api.payments.example
        this.restClient = builder.baseUrl("http://localhost:9000").build();
    }

    public ChargeResponse charge(String orderId, BigDecimal amount) {
        return restClient.post()
                .uri("/v1/charges")
                .header("Idempotency-Key", orderId)
                .body(new ChargeRequest(orderId, amount))
                .retrieve()
                .body(ChargeResponse.class);
    }

    public record ChargeRequest(String orderId, BigDecimal amount) {
    }

    public record ChargeResponse(String chargeId, String status) {
    }
}

The Java code stays simple and contains no secrets: the API key lives only in the ambassador’s configuration. Services in other languages can use the same ambassador image, and switching providers, or adding retries, changes only the sidecar.

9. Sidecars Without Kubernetes

Sidecars are most common in Kubernetes, but the idea works anywhere two processes can share a host. With Docker Compose, a container can join another container’s network, so both share the same localhost:

services:
  order-service:
    image: shop/order-service:2.1
    ports:
      - "8080:8080"
    volumes:
      - app-logs:/var/log/app

  log-shipper:
    image: fluent/fluent-bit:3.1
    network_mode: "service:order-service"   # share order-service's localhost
    volumes:
      - app-logs:/var/log/app:ro
    depends_on:
      - order-service

volumes:
  app-logs:

On virtual machines, the same pattern appears as a helper process or agent installed next to the application, for example a monitoring agent or a local proxy managed by systemd.

10. Sidecars in a Service Mesh

The most famous use of sidecars is the service mesh. Tools such as Istio and Linkerd add a small proxy sidecar, such as Envoy or the Linkerd proxy, to every pod. All network traffic in and out of the service passes through that proxy, which adds:

• Mutual TLS: encrypted, authenticated traffic between services.
• Retries, timeouts and circuit breaking, configured centrally.
• Load balancing and traffic splitting, such as canary releases.
• Metrics and traces for every call, without code changes.

With Istio, you do not even add the sidecar yourself. Label a namespace, and Istio injects the proxy into every new pod:

# Every pod created in the "shop" namespace now gets an Envoy sidecar
kubectl label namespace shop istio-injection=enabled

# Restart the deployment so its pods are recreated with the sidecar
kubectl rollout restart deployment/order-service -n shop

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: payment-service
spec:
  hosts:
    - payment-service
  http:
    - route:
        - destination:
            host: payment-service
      timeout: 5s
      retries:
        attempts: 3
        perTryTimeout: 2s
        retryOn: 5xx,connect-failure

The order service keeps calling http://payment-service as before; the sidecars add timeouts and retries. Be careful not to retry in both the mesh and your Java code, or the attempts multiply. See the Retry pattern.

11. Common Use Cases

12. Sidecar vs Ambassador, Adapter and Shared Libraries

Libraries and sidecars are not enemies. A Java team may use Resilience4j and Micrometer inside the service, and a mesh sidecar for encryption and traffic control. Choose based on how many languages you use and how much you want to keep out of application code.

13. Sidecar-less Alternatives

Sidecars cost CPU and memory in every pod. With hundreds of pods, that adds up. Newer approaches reduce this:

• Node-level agents (DaemonSets): one log or metrics collector per machine instead of one per pod.
• Istio ambient mode: a shared, per-node proxy handles encryption and basic traffic, with optional per-service proxies only where advanced features are needed.
• eBPF-based networking, such as Cilium: some mesh features run inside the operating system kernel instead of a proxy.
• Proxyless gRPC: gRPC clients receive mesh configuration directly, with no proxy in between.

Sidecars remain the most flexible and widely supported option, but it is worth checking these alternatives for large clusters.

14. Key Benefits

• Decoupling and separation of concerns: the main service focuses purely on business logic, so it is simpler, cleaner and easier to test.
• Reusability: the same sidecar works with many services in different languages; the infrastructure logic is written once.
• Polyglot support: a Python service and a .NET service use exactly the same sidecar for discovery or metrics, with no client libraries to maintain per language.
• Independent updates: upgrade the sidecar image, for example for a security fix, without touching application code.
• Isolation: the sidecar runs as a separate process, with its own resource limits, so a bug in it does not have to crash the main service, and vice versa.

15. Challenges and Considerations

16. Best Practices

1. Keep sidecars generic: no business logic, only reusable infrastructure features.
2. Set resource requests and limits for every sidecar, so they cannot starve the main container.
3. Use native sidecar containers where available, to get correct startup and shutdown order.
4. Standardize sidecar images and versions across services, and update them centrally.
5. Prefer automatic injection, as in a service mesh, over copying sidecar definitions into every deployment.
6. Avoid duplicate features: do not retry or encrypt both in the sidecar and in the application.
7. Monitor sidecars like any other component: health, resource use and errors.
8. Question each sidecar: if a node agent or a small library would do the job, it may be cheaper.

17. Common Mistakes to Avoid

18. Summary

The Sidecar pattern extends and enhances microservices without changing their code. A helper container runs next to each service, shares its network, storage and life cycle, and takes over cross-cutting concerns such as logging, metrics, configuration, security and traffic control. Variations such as the Ambassador, for outgoing calls, and the Adapter, for translating output, solve specific problems, and the service mesh applies the pattern to every service at once. Keep sidecars generic, give them resource limits, use native sidecar containers for correct start and stop order, and weigh them against node agents and libraries. Used well, sidecars let developers focus on business value while delegating complex operational concerns to reusable, standardized components. Continue with the API Gateway pattern to see how traffic enters the system before it reaches your services.

19. Frequently Asked Questions (FAQ)