Chapter 34 of 47 · Pod patterns

Init containers and sidecars

A Pod can hold more than your app. Init containers do setup work before your app starts, like a stage crew building the set before the show. Sidecars run next to your app the whole time, like a sound engineer who stays for the full concert. Both let you keep your app small and focused.

The picture

Init containers

You met one in chapter 14: a tiny container that waited for event-bus-srv before posts started. The rules are simple:

• They run before any normal container starts.
• They run one at a time, in the order you list them.
• Each must finish successfully (exit code 0) before the next one starts.
• They can use a different image from your app, with tools your app image does not need (a migration tool, curl, git).
• They can share files with the app through a volume such as emptyDir (chapter 30).

Click the parts of this Pod:

apiVersion: v1
kind: Pod
metadata:
  name: posts
spec:
  initContainers:
    - name: wait-for-bus
      image: busybox:1.36
      command: ["sh", "-c", "until nslookup event-bus-srv; do sleep 2; done"]
    - name: migrate
      image: micro-posts-migrate:1.0
      command: ["npm", "run", "migrate"]
  containers:
    - name: posts
      image: micro-posts:1.0
      volumeMounts:
        - name: shared
          mountPath: /app/data
  volumes:
    - name: shared
      emptyDir: {}

$ kubectl get pods
NAME    READY   STATUS     RESTARTS   AGE
posts   0/1     Init:0/2   0          5s     ← first init container running
posts   0/1     Init:1/2   0          12s    ← first done, second running
posts   1/1     Running    0          20s    ← both done, app started

$ kubectl logs posts -c migrate          # logs of one init container

Four classic init jobs

- name: wait-for-db
  image: busybox:1.36
  command: ["sh", "-c", "until nc -z db 5432; do echo waiting for db; sleep 2; done"]

- name: migrate
  image: micro-posts:1.0          # same image, different command
  command: ["node", "migrate.js"]

- name: download-model
  image: curlimages/curl:8.8.0
  command: ["curl", "-o", "/data/model.bin", "https://example.com/model.bin"]
  volumeMounts:
    - name: shared
      mountPath: /data

- name: fix-perms
  image: busybox:1.36
  command: ["sh", "-c", "chown -R 1000:1000 /data"]
  securityContext:
    runAsUser: 0                  # only this short step runs as root
  volumeMounts:
    - name: data
      mountPath: /data

When an init container fails

If an init container exits with an error, the Pod does not start. Kubernetes tries again, waiting longer each time, and the status tells you exactly where it is stuck:

Sidecars

A sidecar is a second container that keeps running next to your app and adds a feature, without changing your app's code. Like a sidecar on a motorbike: attached, travels along, separate seat.

Each helper can be written in any language, updated separately, and reused next to many apps. Adapters and ambassadors (chapter 35) are two special kinds of sidecar.

Native sidecars

The old way to add a sidecar was simply a second entry under containers. That has two annoying problems: Kubernetes does not know which one is "the app", so the sidecar may start after the app (logs from the first seconds are lost), and in a Job (chapter 36) the Pod never finishes because the sidecar never exits.

The fix, stable since Kubernetes 1.33: put the sidecar under initContainers with restartPolicy: Always.

spec:
  initContainers:
    - name: log-shipper
      image: fluent-bit:3.0
      restartPolicy: Always        # ← this makes it a sidecar, not a normal init step
      volumeMounts: [{ name: logs, mountPath: /logs }]
  containers:
    - name: posts
      image: micro-posts:1.0
      volumeMounts: [{ name: logs, mountPath: /var/log/app }]
  volumes:
    - name: logs
      emptyDir: {}

start:  log-shipper ✓ (running) → posts starts
stop:   posts stops first → log-shipper stops last
Job:    task finishes → sidecar is stopped → Job Complete ✓

start:  posts and log-shipper start in any order
stop:   both get SIGTERM at the same time
Job:    task finishes, sidecar keeps running → Job never completes ✗

Init, sidecar or postStart?

Recap

• Init containers run before the app, one at a time, and each must succeed.
• Use them for setup: waiting for dependencies, migrations, downloads, permissions.
• A failing init container blocks the Pod (Init:CrashLoopBackOff); read its logs with -c.
• Sidecars run next to the app and add features without touching its code.
• Native sidecars (initContainers + restartPolicy: Always) start first, stop last, and let Jobs finish.

Quick check