To understand init containers we first need a handful of simple words: container, pod, kubelet, volume and init.

So what exactly is an init container?

An init container is a special container inside a pod that runs before any of the pod’s app containers. It runs to completion, which means it does its job and then exits. If the pod has several init containers, they run strictly one after another, in the order they are written. The app containers start only after the last init container has finished successfully.

Think of it as a checklist that must be fully ticked before the doors open. Each item is a small container. If any item fails, the checklist stops, the item is tried again, and the doors stay closed until everything passes.

The four golden rules

Almost everything about init containers follows from four simple rules. Keep these in mind and the rest of the guide will feel natural.

A short history

Google released Kubernetes as open source in 2014. Very early on, users noticed that many applications need some preparation before they can start: waiting for a database, fetching a settings file, fixing folder permissions. People squeezed these tasks into complicated start-up scripts inside the main container, which made images bloated and fragile. Init containers arrived as an early experimental feature and became a stable, officially supported part of Kubernetes in version 1.6, in 2017. They have been a standard tool ever since.

Ordinary containers all start at the same time, with no promise about order. That is fine for many programs and painful for others.

Everything starts together

In a pod, all the ordinary containers are launched at about the same moment. Kubernetes does not wait for one to become ready before starting the next. This is simple and fast, but it creates several real-world headaches.

The old workaround and why it hurts

Before init containers were common, teams wrote long start-up scripts that ran inside the application container. The script would wait for the database, download files, fix permissions, and only then start the program. This works, but it has serious downsides.

The image must contain every tool the script needs, so it grows. The script runs with the same permissions as the application, so any power needed for preparation, such as changing file ownership, stays available to the application forever. Errors in the script are mixed with errors in the application, which makes logs confusing. And nobody can see from outside whether the pod is “preparing” or “running”, since it is all one container.

flowchart TB
  subgraph WITHOUT["Without init containers: everything starts at once"]
    direction LR
    A1["Pod starts"] --> A2["App container starts immediately"]
    A2 --> A3["Database or file not ready yet"]
    A3 --> A4["App crashes and restarts repeatedly"]
  end
  subgraph WITH["With init containers: preparation comes first"]
    direction LR
    B1["Pod starts"] --> B2["Init container prepares and waits"]
    B2 --> B3["Preparation succeeds"]
    B3 --> B4["App container starts into a ready world"]
  end
    

Init containers look like ordinary containers, but a few important differences define how they behave. Learn these and everything else will fit.

How init containers differ from ordinary containers

What they share and what they keep separate

All containers in a pod share the same network address and can share volumes. Each container, however, has its own image and therefore its own file system. This is the key design idea. An init container can use a completely different image from the app, packed with exactly the tools it needs. It communicates its results to the app through a shared volume, a folder both can see.

Reading the pod status

Because init containers run first, the pod’s status column tells a story as they progress. You will meet these words often.

Init containers are not a separate machine or a separate service. They are part of the pod, managed by the same parts of Kubernetes that manage every other container. Let us meet the players.

flowchart TB
  API["API Server holds the pod definition"] --> SCH["Scheduler picks a node using the pod's effective resource needs"]
  SCH --> KUB["Kubelet on the chosen node"]
  KUB --> SBX["Pod sandbox: network address and shared settings"]
  KUB --> IC1["Init container 1"]
  IC1 --> IC2["Init container 2"]
  IC2 --> APP["App containers"]
  VOL["Shared volume"] --- IC1
  VOL --- IC2
  VOL --- APP
  KUB -->|"status and events"| API
    

Piece by piece

The pod definition is where you write the init containers. It has one list for init containers and another for the ordinary app containers. The order of the init list is the order of execution. Names must be unique across both lists, so an init container cannot share a name with an app container.

The API server stores the definition and is the notice board through which everything else learns about it. When the kubelet reports progress, such as “init container one finished”, the API server records it in the pod’s status, which is what you see with your status commands.

The scheduler decides which computer will host the pod. It must know how much processor and memory the pod needs. For a pod with init containers, this is worked out in a special way that we explain in the next chapter, so a hungry init container can affect where the pod lands.

The kubelet is the star of the show. It runs on the chosen computer, creates the pod’s shared environment, starts each init container in turn, watches for its exit, and then starts the next step. It is also the one that decides what to do when an init container fails.

The pod sandbox is the shared environment that exists before any of your containers. It holds the pod’s network address and shared settings. Because it is created first, even the very first init container already has a network address and can reach other services, which is essential for the “wait for a neighbour” pattern.

The container runtime is the software that actually creates and runs containers on request from the kubelet. It pulls images, starts processes, and reports exit codes back.

Shared volumes are the bridge between preparation and application. The most common kind is a temporary folder that is created empty when the pod starts and deleted when the pod ends. An init container fills it. The app reads it.

Here is what the kubelet does, step by step, from the moment a pod arrives on its computer.

flowchart TD
  A["Kubelet picks the next init container in written order"] --> B["Pull the image if needed and start it"]
  B --> C{"Did it exit with code zero?"}
  C -->|"Yes"| D{"Are more init containers waiting?"}
  D -->|"Yes"| A
  D -->|"No"| E["Start all app containers"]
  C -->|"No"| F{"Does the pod restart rule allow a retry?"}
  F -->|"Yes"| G["Wait with a growing delay then restart the same init container"]
  G --> B
  F -->|"No"| H["Pod is marked as failed"]
    

How the scheduler counts resources

Because init containers run one at a time, and each finishes before the next begins, they never use resources at the same moment. The app containers, on the other hand, all run together. Kubernetes therefore computes the pod’s effective need in a clever way: for each resource, it takes the larger of two numbers. The first number is the biggest request of any single init container. The second is the total of all the app containers’ requests added together.

Here is a worked example. The first init container asks for half a processor core and 256 megabytes of memory. The second asks for a fifth of a core and one gigabyte. The app containers together ask for four tenths of a core and 512 megabytes. For processor, the biggest init request is half a core, and the app total is four tenths, so the pod counts as needing half a core. For memory, the biggest init request is one gigabyte, and the app total is 512 megabytes, so the pod counts as needing one gigabyte.

The lesson is important. A heavy init container, for example one that unpacks a big archive, can make the whole pod look expensive to the scheduler for its entire life, even though that heavy work lasts only seconds. Keep init containers modest, or you may find pods refusing to fit onto computers where they would otherwise be welcome.

What retries really mean

When an init container fails, Kubernetes does not create a new pod. It restarts the same init container inside the same pod. Between attempts the delay grows: roughly ten seconds, then twenty, forty, and so on, up to a maximum of five minutes. This keeps a broken step from hammering the computer, but it also means a pod with a persistently failing init container may sit in the status Init:CrashLoopBackOff, retrying every few minutes for as long as nobody fixes the cause.

Notice that there is no built-in time limit for an init container. If it waits forever for a database that never appears, the pod waits forever too. The only outer limit is the pod-wide deadline, an optional setting that ends the pod after a set number of seconds no matter what. Good init containers therefore carry their own sensible time limits and give up with a clear message.

Now let us follow one pod through its whole life, watching what the init containers do and how their results reach the application.

sequenceDiagram
  participant U as User
  participant A as API Server
  participant K as Kubelet
  participant I1 as Init container 1
  participant I2 as Init container 2
  participant P as App containers
  U->>A: Create the pod
  A->>K: Pod is assigned to this node
  K->>K: Create the sandbox and attach volumes
  K->>I1: Start init container 1
  I1-->>K: Exit with code zero
  K->>I2: Start init container 2
  I2-->>K: Exit with code zero
  K->>P: Start the app containers
  K->>A: Report Initialized then Ready
    

The stages of life

How data moves from init container to application

The usual pattern is a shared temporary folder. The pod definition declares a volume, and mounts it into both the init container and the app container, possibly at different folder paths. The init container writes its result there, such as a downloaded settings file or a generated certificate. When it exits, the folder and its contents remain. The app then starts and simply reads the files as though they had always been there.

Other channels exist too. An init container can write to a persistent volume, which survives the pod. It can also call a remote service to register the pod or to fetch a secret. What it cannot do is pass an environment variable to the app: environment variables are fixed when each container is created, and one container cannot change another’s.

When do init containers run again?

This is the most important lifecycle question, and the source of many surprises. There are three situations.

Most real-world init containers fall into a small set of patterns. Learn to recognise them and you can design a good one for almost any situation.

flowchart TD
  S["Init container starts"] --> P["Try to reach the database"]
  P --> Q{"Did it answer?"}
  Q -->|"Yes"| OK["Exit with code zero and let the app start"]
  Q -->|"No"| W{"Waited longer than the limit?"}
  W -->|"No"| Z["Sleep a few seconds"]
  Z --> P
  W -->|"Yes"| F["Print a clear message and exit with an error"]
    

Recent versions of Kubernetes stretched the idea of init containers to solve a different old problem: helper containers that must start before the app and keep running beside it.

What is a sidecar?

A sidecar is a helper container that runs alongside the main application for its whole life. Common examples are a log shipper that forwards logs, a proxy that handles secure connections, and a small agent that refreshes credentials. The name comes from the sidecar of a motorcycle: an extra seat attached to the main vehicle.

For years, sidecars were just ordinary containers in the same pod, with all the problems of ordinary containers: they start at the same time as the app, with no promise that the proxy is ready before the app makes its first call, and on shutdown they may stop in any order, so a log shipper could vanish before the app finished writing its final logs. Batch jobs had a special headache: a sidecar that never exits stopped the job from ever finishing.

The native sidecar idea

Kubernetes solved this by letting an init container carry a special setting that makes it restart-always. Such an init container starts in the normal init order, but, unlike a classic init container, it does not have to finish. Kubernetes considers it “started” once it is running, and the next init container, or the app containers, can proceed. It then keeps running for the whole life of the pod, and can even have health probes.

On shutdown, the order is reversed: app containers stop first, and sidecars stop afterwards, in reverse start order. The log shipper can therefore send the last logs, and a batch job can finish, because the sidecar is shut down once the main work is done. This feature became stable in recent Kubernetes releases, so check which version your cluster runs before relying on it.

Init containers run before your application, often with extra power, and often reach out to the network. That makes them useful, and also an attractive target.

The shared identity

All containers in a pod share the pod’s service account, which is the identity the pod uses when it talks to the cluster itself. An init container therefore has the same cluster permissions as the app. If an init container is compromised, everything that identity may do is at risk. Keep the pod’s identity narrow.

Who can add an init container?

Anyone who can edit a workload’s pod template can add an init container, and an init container is arbitrary code that runs first, before your application’s own defences. Treat permission to edit pod templates as a powerful permission. Many organisations use admission policies to require that init containers come only from approved registries and never request privileged mode.

Init containers are one of several ways to get work done around a pod. Choosing well avoids slow starts, fragile systems and surprising failures.

flowchart TD
  A["I have a task to do around my app"] --> B{"Must it finish before the app starts?"}
  B -->|"No"| C{"Must it run beside the app all the time?"}
  C -->|"Yes"| D["Ordinary container or native sidecar"]
  C -->|"No"| E["Separate job or scheduled task"]
  B -->|"Yes"| F{"Is it needed for every single pod start?"}
  F -->|"Yes"| G["Init container"]
  F -->|"No, only once per release"| H["Separate job that runs once per release"]
    

Reading the decision path

Start at the top with your task. The first question is about timing: must the task finish before the application begins? If not, it does not belong in an init container. Some tasks need to run beside the app for its whole life, which points to an ordinary container or a native sidecar. Others are separate concerns that can run on their own, such as a nightly report, and should be a separate job.

If the task must finish first, ask how often. A step needed by every pod, such as fetching this pod’s certificate, is a perfect init container. A step needed only once per release, such as changing the database layout, is better as a separate job that runs once per release, before the rollout, instead of being repeated by every pod that starts.

The case for putting resilience in the app

The wait-for-dependency init container is popular, but it has a limit. It checks the dependency only at start-up. If the database restarts tomorrow while the app is running, no init container will help. A well-built application handles missing dependencies itself, retrying connections with delays and reporting itself as not ready until they succeed. Where you can change the application, resilience inside the app is more robust. Init containers shine when you cannot change the app, or when the preparation is truly a separate concern.

Init containers versus readiness probes

People confuse these two. An init container runs first and blocks the app from starting. A readiness probe runs while the app is already running, and simply controls whether the pod receives traffic. If your worry is “do not send visitors until the app has warmed up”, that is a readiness probe. If your worry is “do not start the app until its files exist”, that is an init container.

Every init container adds time to every pod start. That price is small for one pod and large when hundreds of pods must start quickly.

Where the time goes

Total start-up delay is the sum of several parts. First comes pulling each init image, if it is not already on the machine. Then each init container starts and runs its work, one after another. Only afterwards do the app containers begin their own image pulls and starts. Because init containers run in sequence, three steps of ten seconds each add thirty seconds before the app even begins.

Resource reservations and scheduling

Recall from Chapter 5 that a pod’s effective request is the larger of the biggest init request and the total of the app requests. A heavy init container, for example one that unpacks a large archive, can therefore make the whole pod harder to place on a busy machine, even though that memory is needed only briefly. Give init containers realistic, modest requests, and if a step needs a large burst, ask whether it should be a separate job instead.

Scaling under sudden load

When traffic spikes and an autoscaler adds pods, each new pod must go through its init steps before it can help. If init takes a minute, the extra capacity arrives a minute late. For workloads that must scale fast, keep init lean, pre-pull images onto machines where possible, and keep slow preparation out of the start-up path.

Every design choice buys something and costs something. Here is an honest ledger for init containers.

The trade-offs in plain words

The core trade-off is start-up speed against clean design. Init containers make your system tidier, safer and more predictable, and in exchange each pod takes longer to become useful. For most applications, a few seconds of start-up are a fair price. For applications that scale rapidly, the price matters and deserves measurement.

A second trade-off is start-time checks against run-time resilience. Waiting for a dependency at start-up feels reassuring, but it tempts teams to skip building real resilience into the application. The safest systems use both: an init step for genuine preparation, and application-level retries for dependencies that come and go.

A third trade-off is one bigger container against several small ones. Putting many tasks into one init container reduces overhead but mixes tools and permissions. Splitting them gives clarity and least privilege at the cost of extra image pulls and start-up steps. Choose based on whether the tasks need different tools or different powers.

When a pod is stuck before its app even starts, you need to know where to look. This chapter is your troubleshooting map.

Reading the pod status

The status column of a pod listing is your first clue. It tells you which stage the pod is in, and the stage tells you where to look.

A calm troubleshooting routine

First, describe the pod. The events at the bottom read like a diary of what happened: image pulls, container starts, failures and back-offs. Second, read the logs of the specific init container by naming it, since a pod’s default logs show only app containers. Third, ask for the logs of the previous attempt, because a container that crashed and restarted has fresh logs that hide the failure. Fourth, check the exit code shown in the describe output: a code of one often means the script’s own error, while codes such as 137 hint at being killed for using too much memory.

Fifth, check the shared parts. Is the volume mounted where you think it is? Does the ownership allow writing? Is the network path to the dependency open, and does the name resolve? Sixth, compare the init container’s requests and limits with what it needs, because a step killed for memory looks like a mysterious crash.

A worked troubleshooting example

Imagine a pod that shows Init:1/2 for ten minutes. The number tells you that the first init container finished, and the second one is the suspect. You describe the pod and see, in the events, that the second init container has started once and has not restarted, so it is running rather than crashing. That already narrows the cause: it is waiting for something. You read that container’s logs and find repeated lines saying it is waiting for a service named “payments-db” to answer. You check the cluster and discover that the service is called “payments-database”. A single spelling difference kept the pod waiting. Fixing the name in the pod definition and rolling it out solves the problem.

Notice the path of reasoning. The status gave the stage, the events gave the behaviour, the logs gave the cause, and a comparison with reality gave the fix. Nothing required guessing, and the application code was never involved. With practice, this routine takes only a few minutes, and it works for nearly every init problem you will meet.

Logging good init containers

Init containers are short-lived, and their logs are valuable evidence. Write clear, human-readable lines about what the step is checking, what it found, and why it is exiting. A line such as “waiting for the database, attempt 4 of 30” saves a stranger an hour of guessing. Never print secrets. Because logs of finished pods can disappear with the pod, send logs to a central logging system so you can investigate after the fact.

Monitoring at the fleet level

Track how many pods are in init states, how long pods spend initialising, and how often init containers restart. A sudden rise in time-to-start is an early warning that a dependency has become slow. Alerts on pods stuck in initialisation for longer than a sensible limit catch quiet failures that dashboards on running apps never see, since those pods never became apps at all.

Designing for failure

Assume every init step will fail sometimes, and design so that failure is safe and visible. Make steps idempotent so retries are harmless. Set time limits so a hopeless step ends with a clear error. Emit clear messages. Keep steps small, so a failure points to one precise cause. And decide in advance whether a failure should be retried forever, as with the default policy, or should mark the pod failed, as with a never-restart policy in a batch setting.

A pattern is a proven way of solving a repeated problem. An anti-pattern is a tempting approach that keeps causing pain. Knowing both saves months of learning the hard way.

Patterns worth adopting

Anti-patterns to avoid

This chapter gathers everything into checklists you can pin beside your desk.

Best practices

Common mistakes

These generic stories, based on common patterns rather than any specific company, show how init containers appear in everyday systems.

Three worked scenarios: thinking like a designer

Stories are useful, but the real skill is deciding what to do with a fresh problem. Here are three short scenarios, each with the reasoning a careful designer would follow.

A short mental checklist for new designs

Before adding any init container, pause and walk through a short list. State the job in one sentence. If you cannot, the container is doing too much. Decide what it needs to read and what it must write, and confirm the shared folder both sides will use. Decide what happens when it runs twice. Decide what happens when it runs for an hour, and set a limit. Decide which permissions it needs, and remove everything else. Decide what a stranger would see in its logs at three in the morning. Finally, estimate the time it adds to every pod start and ask whether that price is acceptable. Ten minutes on this checklist prevents most of the problems described in this article.

Quick answers to the questions beginners ask most often.

This post was written without live web research. Please verify version-sensitive details, such as native sidecar support, against the official documentation for your cluster version.

Let us close the loop, returning to our theatre crew from the start of this article.

Just as a stage crew sets the scene before the curtain rises and only then lets the actors begin, init containers prepare a pod before its application starts. They run in order, each one finishing before the next begins. They can carry different tools, hold different permissions and produce results in shared folders. They retry when they fail, and they rerun when a pod is recreated, which is why they must be safe to repeat.

You met the problem they solve, the ordering headache of starting an app before its world is ready. You saw their core concepts, their architecture, and how the kubelet drives them through a decision loop. You followed data through the lifecycle, met the usage patterns, compared them with native sidecars, and learned how to secure, size, monitor and troubleshoot them. You also saw where they do not belong.

Version drift and things to verify

Kubernetes changes steadily, and details around init containers have shifted over the years. Native sidecar support arrived much later than classic init containers, and the exact behaviour of features such as probes on sidecars, shutdown ordering and resource accounting has been refined across releases. Because this article was written without live web research, treat version-specific statements as a starting point. Before relying on a feature in production, read the official documentation for your cluster’s exact version, try the behaviour in a test namespace, and note the version in your team’s own documentation so that future upgrades prompt a re-check.

It also helps to know your managed platform. Cloud providers sometimes run older or newer versions than you expect, and some add their own admission rules that change what init containers may do, such as blocking privileged mode or requiring images from an approved registry. A five-minute check of your platform’s rules can save an afternoon of confusing errors.

A small glossary to keep nearby