Appearance

Init containers and sidecars

Use ordered setup and persistent helpers without hiding their lifecycle costs.

What you will understand

  • Distinguish regular init containers from restartable sidecars
  • Explain explicit shared volume communication
  • Predict startup when initialization cannot complete

Builds on: The Pod lifecycle

Mental model: setup versus continued cooperation

A regular init container runs before ordinary app containers and must complete successfully before the next regular initialization step proceeds. Multiple regular init containers run in their specified sequence. They can perform setup using a different image from the main application, such as preparing a configuration file or checking a prerequisite. They are not permanent background workers. A regular init command that sleeps forever prevents the application from starting.

A sidecar is a helper that remains active alongside the main application. Kubernetes supports a restartable sidecar as an entry in initContainers with container-level restartPolicy: Always. It starts as part of initialization and keeps running, with independent restart supervision. An older pattern uses two ordinary app containers in containers; that can still be useful, but it does not express the same ordered sidecar lifecycle. Identify which pattern a manifest actually uses.

A sidecar is not a remote dependency made local by naming it a sidecar. It shares the Pod’s placement, network namespace, and lifecycle boundary. It consumes resources and can affect readiness and termination. If it needs independent scaling or release cadence, a separate workload may fit better. Shared placement is a coupling decision, not a default way to assemble every service.

Regular init containers are a completion gate

Run ordered setup before starting the app container.

Lifecycle viewStep 1 of 3
Start the initializerThe kubelet starts prepare before the web application. The emptyDir exists and is mounted at /work for setup.. Kubelet, active. prepare: running, active. emptyDir page, ready. web: not started, idleKubelet
KubeletIn focus
prepare: running
prepare: runningIn focus
emptyDir page
emptyDir pageReady
web: not started
web: not startedContext
KubeletIn focus
prepare: runningIn focus
emptyDir pageReady
web: not startedContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: initializer waits for its own app
Start the initializer

The kubelet starts prepare before the web application. The emptyDir exists and is mounted at /work for setup.

Read the complete visual sequence
  1. Start the initializer

    The kubelet starts prepare before the web application. The emptyDir exists and is mounted at /work for setup.

  2. Completion opens the gate

    prepare exits 0 after writing the file. Successful completion permits the next initialization step and then app startup.

  3. Serve the prepared file

    nginx mounts the same volume at its document root. Shared storage connects two different root filesystems.

Failure: initializer waits for its own app

Failure: initializer waits for its own app

  1. Initializer waits for web

    A setup command waits for localhost:80 before exiting, but nginx is an ordinary app container that has not started.

  2. The dependency is circular

    The app waits for successful init completion. The initializer waits for the app, so neither condition can advance.

  3. Remove the circular gate

    Prepare files independently or use an appropriate ongoing helper. Retry-safe initialization must be able to complete before ordinary app startup.

About this model

The Pod has one regular initializer; its default Pod restart policy retries failed initialization.

Walkthrough: create content before serving it

The following complete Pod uses a regular init container to write one file into an emptyDir. nginx then serves that shared file. A restartable sidecar watches the same file and writes only training content to its own stdout. Save it as collaboration-demo.yaml in your disposable lab namespace.

apiVersion: v1
kind: Pod
metadata:
  name: collaboration-demo
spec:
  initContainers:
    - name: prepare
      image: busybox:1.36.1
      command: ["sh", "-c", "printf 'prepared by init\n' > /work/index.html"]
      volumeMounts:
        - name: page
          mountPath: /work
    - name: observer
      image: busybox:1.36.1
      restartPolicy: Always # Restartable init sidecar: keep running.
      command: ["sh", "-c", "while true; do cat /work/index.html; sleep 10; done"]
      volumeMounts:
        - name: page
          mountPath: /work
          readOnly: true
  containers:
    - name: web
      image: nginx:1.27.5
      volumeMounts:
        - name: page
          mountPath: /usr/share/nginx/html
          readOnly: true
  volumes:
    - name: page
      emptyDir: {} # Pod lifetime, not persistent storage.

The mount paths differ between containers but refer to the same volume. /work/index.html in the initializer becomes /usr/share/nginx/html/index.html in nginx. Root filesystems remain separate. The init image’s shell does not somehow become installed in the nginx image.

kubectl apply -f collaboration-demo.yaml
kubectl describe pod collaboration-demo
kubectl logs collaboration-demo -c prepare
kubectl logs collaboration-demo -c observer --tail=10
kubectl port-forward pod/collaboration-demo 8080:80

Request http://127.0.0.1:8080/ while the forward runs. Expect the prepared text if startup succeeds. The prepare container may emit no stdout because its command writes to a file. Its successful termination state, rather than a nonempty log, shows completion. Inspect status.initContainerStatuses to distinguish completed setup from the still-running observer sidecar.

A restartable helper keeps running

Use an init sidecar with restartPolicy Always and shared storage.

Lifecycle viewStep 1 of 3
Start the restartable sidecarobserver is listed under initContainers with restartPolicy Always. After it starts, initialization can proceed rather than waiting for it to exit.. observer: started, active. Kubelet lifecycle, active. web: starting, activeobserver: started
observer: startedIn focus
Kubelet lifecycle
Kubelet lifecycleIn focus
web: starting
web: startingIn focus
observer: startedIn focus
Kubelet lifecycleIn focus
web: startingIn focus
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: shared volume permissions
Start the restartable sidecar

observer is listed under initContainers with restartPolicy Always. After it starts, initialization can proceed rather than waiting for it to exit.

Read the complete visual sequence
  1. Start the restartable sidecar

    observer is listed under initContainers with restartPolicy Always. After it starts, initialization can proceed rather than waiting for it to exit.

  2. Run alongside the app

    The observer reads the shared page volume while nginx serves it. Both run in one Pod and share its resource and failure context.

  3. Supervise the helper independently

    If observer exits, kubelet can restart that sidecar without replacing the Pod or restarting nginx merely because the helper exited.

Failure: shared volume permissions

Failure: shared volume permissions

  1. Helper and app use different users

    The initializer creates a file with permissions the nginx process cannot read. The volume is shared, but permissions still apply.

  2. Running does not imply useful content

    Containers may run while HTTP requests fail to retrieve the intended file. Check ownership, mode, and mount paths.

  3. Align permissions deliberately

    Choose compatible ownership and minimum necessary access for the shared path. Do not solve every mount error by making all files world-writable.

About this model

The observer has no startup probe; production ordering may require an explicit health gate.

Practice: predict a blocked initializer

In a new disposable Pod, make the regular initializer exit 1. Under the basic Always Pod restart policy, the kubelet retries failed initialization, and the ordinary application waits. Inspect init status and kubectl logs ... -c prepare, not only the nginx log. If a regular initializer waits for the web process in that same Pod, it can create a circular dependency: the web process cannot start until initialization finishes.

Initialization should be safe to retry. A script that appends duplicate configuration or performs an irreversible database migration on every restart needs a stronger design. Keep setup idempotent, bound external waits, and make failures observable. For changes requiring coordination across many replicas, a Pod-local initializer is not a global deployment lock or a transactional migration controller.

Pitfalls

Starting a sidecar process does not necessarily mean it is ready to accept connections. Where startup ordering depends on actual readiness, use an appropriate startup probe and verify the sidecar lifecycle semantics. Merely placing a proxy first in YAML is not a health contract. A readiness probe on a sidecar can also contribute to Pod readiness, so test the effect of helper failure on traffic eligibility.

The shared emptyDir survives an individual container restart in this Pod, but replacement of the Pod creates a new emptyDir and reruns initialization. Keep durable business data outside this training volume. Also consider permissions: sharing a volume does not guarantee both images’ users can read or write the same files.

Check your understanding

A regular init container tails a file forever. Will the main web container start after it prints its first line?

No. A regular init container must finish successfully. Printing a line is not completion. If continued operation is intended, use a deliberately designed sidecar pattern; if setup is intended, make the command terminate after completing that setup. Then verify permissions, startup health, and retry behavior.

Practice ordered setup and the alternate failure branch in the module lab. Next, replace hard-coded settings with scoped ConfigMaps and Secrets.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.