Mastering Kubernetes Init Containers: Lifecycle, Best Practices, and Debugging

Lifecycle

API server calls kubelet to issue a Pod creation command.

The container environment is initialized.

The Pod enters its creation phase.

A pause container is automatically generated to share network and storage.

Init containers (Init C) run to perform initialization tasks.

After all Init C finish, the main container starts, executing its START command and a STOP command on termination.

Readiness probes run to determine when the container is ready to accept traffic.

Liveness probes run to check if the container is still healthy; failures trigger restart actions.

Init Container Example

They can contain useful utilities, but for security reasons they should not be placed in the application container image.

They can run custom scripts or tools (e.g., sed, awk, python, dig) without bloating the application image.

They separate the build and deployment responsibilities, avoiding a single monolithic image.

Init containers run in a separate Linux namespace, allowing them to access Secrets that the application container cannot.

They must complete before the application container starts, providing a simple blocking mechanism until prerequisites are met.

Testing Init Containers

## Edit Pod manifest
vim initc.yaml
...
apiVersion: v1
kind: Pod
metadata:
  name: myapp-pod
  labels:
    app: myapp
    version: v1
spec:
  containers:
  - name: myapp-container
    image: busybox:v1
    command: ['sh','-c','echo The app is running! && sleep 3600']
    imagePullPolicy: IfNotPresent
  initContainers:
  - name: init-myapp
    image: busybox:v1
    command: ['sh','-c','until cat /root/myapp; do echo "/root/myapp no such file or directory!"; sleep 2; done']
    imagePullPolicy: IfNotPresent
  - name: init-mydb
    image: busybox:v1
    command: ['sh','-c','until cat /root/mydb; do echo "/root/mydb no such file or directory!"; sleep 2; done']
    imagePullPolicy: IfNotPresent
...
## Create Pod
kubectl create -f initc.yaml
pod/myapp-pod created
## Check status (init not completed)
kubectl get pod
NAME        READY   STATUS     RESTARTS   AGE
myapp-pod   0/1     Init:0/2   0          3m26s
## Describe Pod
kubectl describe pod myapp-pod
## View init container logs (failure)
kubectl log myapp-pod -c init-myapp
cat: /root/myapp: No such file or directory!
## Create required file to satisfy init container
kubectl exec -it myapp-pod -c init-myapp -- touch /root/myapp
kubectl get pod
NAME        READY   STATUS     RESTARTS   AGE
myapp-pod   0/1     Init:1/2   0          5m19s
## Satisfy second init container
kubectl exec -it myapp-pod -c init-mydb -- touch /root/mydb
kubectl get pod
NAME        READY   STATUS   RESTARTS   AGE
myapp-pod   1/1     Running  0          7m50s
## Init containers disappear after successful execution

Init Container Special Notes

If the Pod restarts, all Init C are re‑executed.

During Pod startup, Init C run after the pause container (network and volume) is created; each must finish before the next starts.

Failure of an Init C triggers a restart according to the Pod's restartPolicy; with restartPolicy: Always, the Init C failure follows the same policy.

The Pod does not become Ready until all Init C succeed; it remains in Pending/Initializing state otherwise.

Only the image field of an Init C can be changed; modifying other spec fields has no effect and changing the image forces a Pod restart.