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.
The kubelet starts prepare before the web application. The emptyDir exists and is mounted at /work for setup.
- Kubelet to prepare: runningrun first
- prepare: running to emptyDir pagewrite index.html
Read the complete visual sequence
- Start the initializer
The kubelet starts prepare before the web application. The emptyDir exists and is mounted at /work for setup.
- Completion opens the gate
prepare exits 0 after writing the file. Successful completion permits the next initialization step and then app startup.
- 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
- Initializer waits for web
A setup command waits for localhost:80 before exiting, but nginx is an ordinary app container that has not started.
- The dependency is circular
The app waits for successful init completion. The initializer waits for the app, so neither condition can advance.
- 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.
observer is listed under initContainers with restartPolicy Always. After it starts, initialization can proceed rather than waiting for it to exit.
- Kubelet lifecycle to observer: startedrestartable init
- Kubelet lifecycle to web: startingcontinue startup
Read the complete visual sequence
- 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.
- 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.
- 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
- 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.
- Running does not imply useful content
Containers may run while HTTP requests fail to retrieve the intended file. Check ownership, mode, and mount paths.
- 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