Kubernetes init containers: Use cases and working examples

Init containers are containers that run to completion before the main container in a pod starts. They run sequentially: the first init container runs and completes, then the second, and so on. The main container does not start until every init container has completed successfully.

Init containers have access to the same volumes, network, and environment as the main container, but their lifecycle is separate. None of the pod's liveness or readiness probes apply to init containers.

Use cases

• Fetching assets or configuration before the main container starts: An init container can download files, render templates, or pull configuration from an internal service and write the result to a shared volume. The main container starts with everything it needs already in place. In production this pattern is commonly used to fetch config from object storage or an internal configuration service rather than public URLs.
• Waiting for a dependency to be ready: An init container can poll a database, a messaging queue, or another service using nslookup or curl and only complete once the dependency is reachable. This prevents the main container from starting before its prerequisites exist, avoiding crashloopbackoff caused by a missing dependency.
• Modifying the filesystem before the main container starts: An init container can set file permissions, write configuration files to a shared volume, or clone a git repository that the main container then uses. This is useful when the main container image cannot be modified but needs certain files or permissions at startup.
• Reducing attack surface: Utilities needed only during setup, such as curl, wget, or database migration tools, can live in an init container rather than the main container image. The main container image stays lean and does not expose those tools at runtime.

Example 1: single init container with a shared volume

This pod uses an init container to fetch an HTML page from civo.com and write it to a shared volume. The nginx main container then serves that file.

1apiVersion: v1
2kind: Pod
3metadata:
4  name: init-demo1
5spec:
6  initContainers:
7  - name: install
8    image: busybox
9    command: ["wget", "-O", "/work-dir/index.html", "http://civo.com"]
10    volumeMounts:
11    - name: workdir
12      mountPath: /work-dir
13  containers:
14  - name: nginx
15    image: nginx
16    ports:
17    - containerPort: 80
18    volumeMounts:
19    - name: workdir
20      mountPath: /usr/share/nginx/html
21  volumes:
22  - name: workdir
23    emptyDir: {}

1kubectl apply -f init1.yaml
2kubectl get pods

Expected output while the init container is running:

1NAME         READY   STATUS     RESTARTS   AGE
2init-demo1   0/1     Init:0/1   0          5s

Expected output once the init container completes and nginx starts:

1NAME         READY   STATUS    RESTARTS   AGE
2init-demo1   1/1     Running   0          15s
3

Exec into the pod and verify nginx is serving the fetched HTML:

1kubectl exec -it init-demo1 -- sh

1curl localhost

The HTML from civo.com is returned. Exit the pod:

1exit

Describe the pod to see the init container lifecycle in the events:

1kubectl describe pod init-demo1

In the Events section you will see busybox pulled first, the init container started and completed, and then the nginx container started. The Init Containers section shows what command ran and its exit status.

Example 2: multiple init containers as a dependency gate

This pod has two init containers that check whether two services exist before the main container starts. The pod stays in a waiting state until both services are reachable.

1apiVersion: v1
2kind: Pod
3metadata:
4  name: init-demo2
5spec:
6  initContainers:
7  - name: wait-for-appservice
8    image: busybox
9    command: ["sh", "-c", "until nslookup appservice; do echo waiting for appservice; sleep 2; done"]
10  - name: wait-for-dbservice
11    image: busybox
12    command: ["sh", "-c", "until nslookup dbservice; do echo waiting for dbservice; sleep 2; done"]
13  containers:
14  - name: main
15    image: busybox
16    command: ["sh", "-c", "echo main container started && sleep 3600"]

Apply the pod before the services exist:

1kubectl apply -f init2.yaml
2kubectl get pods

Expected output — neither init container has completed:

1NAME         READY   STATUS     RESTARTS   AGE
2init-demo2   0/1     Init:0/2   0          10s

Describe the pod to see which init container is running:

1kubectl describe pod init-demo2

In the Init Containers section you will see wait-for-appservice in Running state and wait-for-dbservice in Waiting state. The pod status shows Init:0/2.

Now create the services the init containers are waiting for:

1kubectl apply -f init2svc.yaml

Watch the pod transition:

1kubectl get pods -w

Expected output as each init container completes:

1NAME         READY   STATUS     RESTARTS   AGE
2init-demo2   0/1     Init:0/2   0          30s
3init-demo2   0/1     Init:1/2   0          35s
4init-demo2   0/1     PodInitializing   0   40s
5init-demo2   1/1     Running    0          45s

Init:0/2 means no init containers have completed. Init:1/2 means the first has completed and the second is running. PodInitializing means both init containers have completed and the main container is starting.