kaniko executor: Build Images Without a Daemon
kaniko /kaniko/executor builds an image from a Dockerfile entirely in userspace and pushes it, with no Docker daemon and no privileged container.
kaniko builds Dockerfiles where you cannot run dockerd: unprivileged Kubernetes pods and locked-down CI. It executes each instruction and snapshots the filesystem itself.
What it does
The kaniko executor reads a Dockerfile from --context, executes its instructions in the running container, snapshots the resulting layers, and pushes the image to --destination. It needs no daemon and no --privileged, so it fits restricted runners.
Common usage
# build and push (inside the gcr.io/kaniko-project/executor image)
/kaniko/executor \
--context "${CI_PROJECT_DIR}" \
--dockerfile "${CI_PROJECT_DIR}/Dockerfile" \
--destination ghcr.io/acme/app:1.4.0
# build without pushing, save a tarball
/kaniko/executor \
--context dir://. --dockerfile Dockerfile \
--no-push --tarPath image.tar --destination app:localOptions
| Flag | What it does |
|---|---|
| --context <path|url> | Build context: a dir, git URL, or bucket |
| --dockerfile <path> | Path to the Dockerfile within the context |
| --destination <ref> | Image reference(s) to push (repeatable) |
| --no-push | Build but do not push |
| --tarPath <file> | Write the built image to a tarball |
| --cache=true | Enable layer caching in a cache repo |
| --cache-repo <ref> | Registry repo to store cached layers |
In CI
kaniko is the go-to for building Dockerfiles inside unprivileged Kubernetes-based runners. Provide registry auth through a mounted config.json at /kaniko/.docker/config.json; enable --cache=true --cache-repo so layers persist between pipeline runs.
Common errors in CI
"error checking push permissions ... UNAUTHORIZED: authentication required" means the mounted docker config is missing or wrong for the destination registry. "error resolving dockerfile path" means --dockerfile/--context do not line up. "kaniko should only be run inside of a container" appears when you run the binary on a host; run it in the kaniko image. Out-of-memory on large builds is common; give the pod more memory.