> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi container Pods Design Patterns
> Guide to Kubernetes multi container Pod patterns including co located, init, and sidecar containers with use cases, startup ordering, and coordination best practices
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](https://kubernetes.io/docs/concepts/workloads/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:
```yaml theme={null}
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:
```yaml theme={null}
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:
```yaml theme={null}
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.
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:
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/](https://kubernetes.io/docs/concepts/workloads/pods/)
* Init containers: [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/](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
* Filebeat: [https://www.elastic.co/beats/filebeat](https://www.elastic.co/beats/filebeat)
* Elasticsearch: [https://www.elastic.co/elasticsearch](https://www.elastic.co/elasticsearch)
* Kibana: [https://www.elastic.co/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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.