What Are the Multi-Container Pod Patterns in Kubernetes?

Detailed Answer

Kubernetes Pods can contain multiple containers that share the same lifecycle, network namespace, and storage volumes. Multi-container Pods are designed for cases where two or more processes are tightly coupled and must run together on the same node.

The Three Classic Patterns

The Kubernetes community has identified three primary multi-container patterns, each solving a different class of problem.

Sidecar Pattern

The sidecar container extends or enhances the main container without modifying it. It runs alongside the primary container for the entire Pod lifetime.

Examples: log shippers, monitoring agents, service mesh proxies, certificate renewal agents.

apiVersion: v1
kind: Pod
metadata:
  name: sidecar-example
spec:
  containers:
    - name: web-server
      image: nginx:1.27
      volumeMounts:
        - name: shared-logs
          mountPath: /var/log/nginx
    - name: log-agent
      image: fluent/fluent-bit:3.2
      volumeMounts:
        - name: shared-logs
          mountPath: /var/log/nginx
          readOnly: true
  volumes:
    - name: shared-logs
      emptyDir: {}

The web server writes access logs to the shared volume; the log agent reads and forwards them.

Ambassador Pattern

The ambassador container proxies network connections from the main container to external services. The app container connects to localhost, and the ambassador handles service discovery, connection pooling, or protocol translation.

Examples: database connection poolers (PgBouncer), cloud SQL proxy, Redis cluster proxy.

apiVersion: v1
kind: Pod
metadata:
  name: ambassador-example
spec:
  containers:
    - name: app
      image: myapp/server:2.1
      env:
        - name: DB_HOST
          value: "localhost"
        - name: DB_PORT
          value: "5432"
      resources:
        requests:
          cpu: "250m"
          memory: "256Mi"
    - name: cloud-sql-proxy
      image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14
      args:
        - "--structured-logs"
        - "--port=5432"
        - "my-project:us-central1:my-db"
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
      securityContext:
        runAsNonRoot: true

The app connects to the database via localhost:5432. The Cloud SQL Proxy ambassador handles authentication and encrypted tunneling to the actual Cloud SQL instance.

Adapter Pattern

The adapter container transforms, normalizes, or reformats the output of the main container so it conforms to a standard interface expected by external systems.

Examples: Prometheus exporters that read application-specific metrics and expose them in Prometheus format, log format converters, protocol adapters.

apiVersion: v1
kind: Pod
metadata:
  name: adapter-example
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "9113"
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80
      volumeMounts:
        - name: nginx-status
          mountPath: /etc/nginx/conf.d
    - name: prometheus-exporter
      image: nginx/nginx-prometheus-exporter:1.4
      args:
        - "-nginx.scrape-uri=http://localhost/nginx_status"
      ports:
        - containerPort: 9113
      resources:
        requests:
          cpu: "50m"
          memory: "32Mi"
  volumes:
    - name: nginx-status
      configMap:
        name: nginx-status-config

The exporter adapter reads NGINX's proprietary status page and exposes it as Prometheus-compatible metrics on port 9113.

How Multi-Container Pods Share Resources

Shared Network Namespace

All containers in a Pod share the same IP address and port space. They communicate via localhost. This means two containers cannot both bind to the same port.

Shared Volumes

Containers can mount the same volumes to exchange files. The most common volume type for inter-container communication is emptyDir, which lives for the lifetime of the Pod.

Shared Process Namespace (Optional)

By setting shareProcessNamespace: true, containers can see each other's processes. This is useful for debugging or for helper containers that need to signal the main process.

spec:
  shareProcessNamespace: true
  containers:
    - name: app
      image: myapp/server:2.1
    - name: debugger
      image: busybox:1.37
      securityContext:
        capabilities:
          add: ["SYS_PTRACE"]

When Not to Use Multi-Container Pods

Multi-container Pods are not always the right choice. Avoid them when:

• Containers need to scale independently: A web server and a worker queue processor should be separate Deployments.
• Containers have very different resource profiles: A CPU-heavy container paired with a memory-heavy container wastes resources if you must scale together.
• Failure domains should be isolated: If a helper's crash should not affect the main app, run them in separate Pods.

Decision Framework

Ask these questions when deciding between single-Pod and multi-Pod architectures:

1. Must they share a network namespace? If yes, use a multi-container Pod.
2. Must they share files on disk? If yes, a multi-container Pod with shared volumes is simplest.
3. Must they scale as a unit? If yes, place them in the same Pod.
4. Can one outlive the other? If yes, use separate Pods managed by separate controllers.

Best Practices

1. Clearly define the role of each container -- name them descriptively (log-shipper, auth-proxy).
2. Set resource requests and limits on every container to avoid noisy-neighbor problems within the Pod.
3. Use native sidecars (Kubernetes 1.28+) when container startup ordering matters.
4. Log to stdout/stderr from all containers so kubectl logs -c <name> works consistently.
5. Keep the number of containers small -- more than 3-4 containers per Pod often signals a design problem.