kaniko - Build Images In Kubernetes

kaniko is a tool to build container images from a Dockerfile, inside a container or Kubernetes cluster.

[!IMPORTANT] This is a supported replacement of the original GoogleContainerTools/kaniko repository, which was archived in June of 2025. Further details in History and Status.

History and Status

kaniko was originally created by Priya Wadhwa (@priyawadhwa), Dan Lorenc (dlorenc), and others at Google and published at GoogleContainerTools/kaniko. The project was archived in June 2025 and forked by Chainguard, including Priya and Dan, to chainguard-dev/kaniko to continue upkeep with security patches and maintenance of the project.

No major feature work is planned.

Releases

kaniko releases are only created as tags on the source repository.

Release notes and source code archives are available on the releases section.

Binary release artifacts such as container images are not published. The old container images as gcr.io/kaniko-project/executor and gcr.io/kaniko-project/warmer are unmaintained and no longer updated. Users must build these artifacts themselves or use the Chainguard container images as customer:

• kaniko
• kaniko-warmer
• kaniko-fips
• kaniko-warmer-fips

Other available images:

• kaniko-build organization

Community

Some community members can be found on #kaniko on Kubernetes Slack but there is no active monitoring, regular availability, or access to older discussions.

kaniko doesn't depend on a Docker daemon and executes each command within a Dockerfile completely in userspace. This enables building container images in environments that can't easily or securely run a Docker daemon, such as a standard Kubernetes cluster.

kaniko is meant to be run as an image. We do not recommend running the kaniko executor binary in another image, as it might not work as you expect - see Known Issues.

Table of Contents generated with DocToc

• kaniko - Build Images In Kubernetes
• History and Status
• Community
• Releases
• How does kaniko work?
• Known Issues
• Demo
• Tutorial
• Using kaniko
  • kaniko Build Contexts
  • Using Azure Blob Storage
  • Using Private Git Repository
  • Using Standard Input
  • Running kaniko
  • Running kaniko in a Kubernetes cluster
    • Kubernetes secret
  • Running kaniko in gVisor
  • Running kaniko in Google Cloud Build
  • Running kaniko in Docker
  • Caching
  • Caching Layers
  • Caching Base Images
  • Pushing to Different Registries
  • Pushing to Docker Hub
  • Pushing to Google GCR
  • Pushing to GCR using Workload Identity
  • Pushing to Amazon ECR
  • Pushing to Azure Container Registry
  • Pushing to JFrog Container Registry or to JFrog Artifactory
  • Additional Flags
  • Flag --build-arg
  • Flag --cache
  • Flag --cache-dir
  • Flag --cache-repo
  • Flag --cache-copy-layers
  • Flag --cache-run-layers
  • Flag --cache-ttl duration
  • Flag --cleanup
  • Flag --compressed-caching
  • Flag --context-sub-path
  • Flag --custom-platform
  • Flag --digest-file
  • Flag --dockerfile
  • Flag --force
  • Flag --git
  • Flag --image-name-with-digest-file
  • Flag --image-name-tag-with-digest-file
  • Flag --insecure
  • Flag --insecure-pull
  • Flag --insecure-registry
  • Flag --label
  • Flag --log-format
  • Flag --log-timestamp
  • Flag --no-push
  • Flag --no-push-cache
  • Flag --oci-layout-path
  • Flag --push-retry
  • Flag --registry-certificate
  • Flag --registry-client-cert
  • Flag --registry-map
  • Flag --registry-mirror
  • Flag --skip-default-registry-fallback
  • Flag --reproducible
  • Flag --single-snapshot
  • Flag --skip-push-permission-check
  • Flag --skip-tls-verify
  • Flag --skip-tls-verify-pull
  • Flag --skip-tls-verify-registry
  • Flag --skip-unused-stages
  • Flag --snapshot-mode
  • Flag --tar-path
  • Flag --target
  • Flag --use-new-run
  • Flag --verbosity
  • Flag --ignore-var-run
  • Flag --ignore-path
  • Flag --image-fs-extract-retry
  • Flag --image-download-retry
  • Debug Image
• Security
  • Verifying Signed Kaniko Images
• Kaniko Builds - Profiling
• Creating Multi-arch Container Manifests Using Kaniko and Manifest-tool
  • General Workflow
  • Limitations and Pitfalls
  • Example CI Pipeline (GitLab)
  • Building the Separate Container Images
  • Merging the Container Manifests
  • On the Note of Adding Versioned Tags
• Comparison with Other Tools
• Community
• Limitations
  • mtime and snapshotting
• References

How does kaniko work?

The kaniko executor image is responsible for building an image from a Dockerfile and pushing it to a registry. Within the executor image, we extract the filesystem of the base image (the FROM image in the Dockerfile). We then execute the commands in the Dockerfile, snapshotting the filesystem in userspace after each one. After each command, we append a layer of changed files to the base image (if there are any) and update image metadata.

Known Issues

• kaniko does not support building Windows containers.
• Running kaniko in any Docker image other than the official kaniko image is not supported due to implementation details.
• This includes copying the kaniko executables from the official image into another image (e.g. a Jenkins CI agent).
• In particular, it cannot use chroot or bind-mount because its container must not require privilege, so it unpacks directly into its own container root and may overwrite anything already there.
• kaniko does not support the v1 Registry API (Registry v1 API Deprecation)

Demo

Tutorial

For a detailed example of kaniko with local storage, please refer to a getting started tutorial.

Please see References for more docs & video tutorials

Using kaniko

To use kaniko to build and push an image for you, you will need:

1. A build context, aka something to build
2. A running instance of kaniko

kaniko Build Contexts

kaniko's build context is very similar to the build context you would send your Docker daemon for an image build; it represents a directory containing a Dockerfile which kaniko will use to build your image. For example, a COPY command in your Dockerfile should refer to a file in the build context.

You will need to store your build context in a place that kaniko can access. Right now, kaniko supports these storage solutions:

• GCS Bucket
• S3 Bucket
• Azure Blob Storage
• Local Directory
• Local Tar
• Standard Input
• Git Repository

Note about Local Directory: this option refers to a directory within the kaniko container. If you wish to use this option, you will need to mount in your build context into the container as a directory.

Note about Local Tar: this option refers to a tar gz file within the kaniko container. If you wish to use this option, you will need to mount in your build context into the container as a file.

Note about Standard Input: the only Standard Input allowed by kaniko is in .tar.gz format.

If using a GCS or S3 bucket, you will first need to create a compressed tar of your build context and upload it to your bucket. Once running, kaniko will then download and unpack the compressed tar of the build context before starting the image build.

To create a compressed tar, you can run:

tar -C <path to build context> -zcvf context.tar.gz .

Then, copy over the compressed tar into your bucket. For example, we can copy over the compressed tar to a GCS bucket with gsutil:

gsutil cp context.tar.gz gs://<bucket name>

When running kaniko, use the --context flag with the appropriate prefix to specify the location of your build context:

If you don't specify a prefix, kaniko will assume a local directory. For example, to use a GCS bucket called kaniko-bucket, you would pass in --context=gs://kaniko-bucket/path/to/context.tar.gz.

Using Azure Blob Storage

If you are using Azure Blob Storage for context file, you will need to pass Azure Storage Account Access Key as an environment variable named AZURE_STORAGE_ACCESS_KEY through Kubernetes Secrets

Using Private Git Repository

You can use Personal Access Tokens for Build Co