Multi container Pods Design Patterns

This guide describes the common multi-container Pod design patterns used in Kubernetes and when to apply each. These patterns help you structure containers that must run together in the same Pod—whether they are peers, one-off initializers, or long-running helpers (sidecars). There are three primary patterns:

Co-located containers (multiple concurrent containers in the containers array)
Init containers (initContainers)
Sidecar containers (helper containers used alongside the main application)

Each pattern addresses different requirements for startup ordering, lifecycle, and responsibilities. Why this matters: properly choosing a pattern helps you manage startup ordering, capture startup logs, coordinate shared volumes, and enforce initialization steps before your main workload runs.

Pattern summary

Pattern	What it is	Typical use cases	Startup/ordering guarantee
Co-located containers	Multiple containers listed in the Pod `containers` array that run for the Pod lifetime	Independent peers, multiple processes that should run concurrently	No ordering guarantee; containers start concurrently from Kubernetes’ perspective
Init containers	Containers in `initContainers` that run sequentially and exit when complete	One-time initialization tasks, schema migrations, waiting for external services	Strong ordering: runs sequentially; main `containers` start only after all init containers exit successfully
Sidecar containers	A regular container used as a helper to the main app (e.g., log shippers, proxies, metrics exporters)	Log collection, proxies, service mesh proxies, local caches	No built-in startup order among regular `containers`; use init containers, readiness probes, or app-level waits for ordering

For more conceptual detail, see the Kubernetes Pod overview: Kubernetes Pods

Co-located containers

The co-located container pattern is the simplest: multiple containers are listed in the Pod’s containers array and run concurrently for the Pod lifetime. Kubernetes treats these containers as peers and does not guarantee a specific startup order between them. Example Pod with two co-located containers:

apiVersion: v1
kind: Pod
metadata:
  name: simple-webapp
  labels:
    app: simple-webapp
spec:
  containers:
    - name: web-app
      image: web-app:latest
      ports:
        - containerPort: 8080
    - name: main-app
      image: main-app:latest

When to use

Use this pattern when containers are independent or can start in any order.
Avoid this pattern when one container must be initialized and ready before another starts.

Init containers

Init containers are defined in the Pod initContainers array and run one at a time in the order specified. Each init container must complete successfully before the Pod proceeds to start the regular containers. They are intended for initialization tasks and are not long-running services. Key characteristics:

Init containers run to completion and then exit.
They run sequentially in the order listed.
Main application containers start only after all init containers succeed.

Example Pod using init containers:

apiVersion: v1
kind: Pod
metadata:
  name: simple-webapp
  labels:
    app: simple-webapp
spec:
  initContainers:
    - name: db-checker
      image: busybox:1.35
      command: ["sh", "-c", "/scripts/wait-for-db-to-start.sh"]
    - name: api-checker
      image: busybox:1.35
      command: ["sh", "-c", "/scripts/wait-for-another-api.sh"]
  containers:
    - name: web-app
      image: web-app:latest
      ports:
        - containerPort: 8080

When to use

Tasks such as migrations, one-time configuration, or waiting for external services before the main app runs.
Not suitable for long-running supporting processes — use a sidecar for that.

Init containers are not long-running — they run to completion and exit. If you need a helper process to stay active for the Pod lifetime (for example, a log shipper or proxy), use a sidecar container instead.

Sidecar containers

A sidecar is a helper container that runs alongside the main application container inside the same Pod. Common sidecar responsibilities include log collection, request proxying, metrics exporting, or syncing files. Technically, a sidecar is just another container in the containers array, but it’s designed to augment the main application. Important correctness about ordering:

Kubernetes does not guarantee startup order for regular containers within the same Pod.
If the main application must not start until the sidecar is ready, use one of these options:
- An initContainer to perform prerequisite work (note: init containers exit and cannot be long-running sidecars).
- A readiness probe on the sidecar and make the main application wait (for example, by checking the sidecar’s health endpoint).
- Application-level waiting logic (retry/wait loop, IPC, or coordination scripts).
- Shared volumes for coordination (e.g., a lock file or a ready marker).

Sidecars typically run for the full Pod lifecycle and enable tasks like log shipping, local caching, or proxying. Example Pod with a Filebeat-like sidecar and a readiness probe on the web app:

apiVersion: v1
kind: Pod
metadata:
  name: simple-webapp
  labels:
    app: simple-webapp
spec:
  containers:
    - name: web-app
      image: web-app:latest
      ports:
        - containerPort: 8080
      readinessProbe:
        httpGet:
          path: /health
          port: 8080
        initialDelaySeconds: 5
        periodSeconds: 10

    - name: filebeat-sidecar
      image: filebeat:latest
      args: ["-e"]
      # filebeat runs alongside the app and ships logs
  restartPolicy: Always

Use readiness and liveness probes and/or explicit startup coordination if the sidecar must be available before the main application begins serving.

An illustrated diagram titled "Design Patterns" showing three container patterns—Co-located Containers, Regular Init Containers, and Sidecar Containers—each represented by colored circles with gear icons and connecting lines. The panels use different sizes and placements of the circles to show the relationships between containers.

So those are the three common patterns. Below is a practical sidecar use case for log collection.

Realistic sidecar example: log collection (Filebeat + Elasticsearch + Kibana)

A very common sidecar scenario is running a log shipper next to your application container. For example, run Filebeat as a sidecar to collect application logs and forward them to Elasticsearch for indexing and Kibana for visualization. Because the sidecar runs in the same Pod, it can capture startup and termination logs the moment the main container writes them. High-level architecture:

A simple architecture diagram showing a Pod running an APP with a Sidecar Filebeat sending logs to Elasticsearch, which then feeds into Kibana. Kibana is shown as the interface for a user to view the data.

Best practices for log-sidecars

Ensure the sidecar can read the same log files or shared volume as the app (share a volume mount).
Consider log rotation and retention to avoid disk pressure.
If capturing startup logs is critical, make the main app wait until the sidecar signals readiness, or use a tiny init container to write a configuration that the sidecar needs before the main app starts.
Use structured logs (JSON) when possible for easier indexing in Elasticsearch.

Kubernetes does not provide a built-in guarantee for the startup order of regular containers in the containers array. Use initContainers, readiness probes, or application-level waiting logic when strict ordering is required between sidecar and main containers.

Quick references

Kubernetes Pods and multi-container patterns: https://kubernetes.io/docs/concepts/workloads/pods/
Init containers: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
Probes (liveness, readiness, startup): https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
Filebeat: https://www.elastic.co/beats/filebeat
Elasticsearch: https://www.elastic.co/elasticsearch
Kibana: https://www.elastic.co/kibana

Use these patterns to match your operational requirements—choose init containers for ordered initialization, co-located containers for independent peers, and sidecars for long-running helper processes that augment your main application.

Introduction

Core Concepts

Configuration