Kaniko Image Builder

Building container images with Kaniko.

The Kaniko project has been archived as of early June 2025. While existing installations will continue to work, the project is no longer actively maintained. Consider using alternative image builders such as the Local, GCP, or AWS image builders for your containerization needs.

The Kaniko image builder is an image builder flavor provided by the ZenML kaniko integration that uses Kaniko to build container images.

When to use it

You should use the Kaniko image builder if:

• you're unable to install or use Docker on your client machine.

• you're familiar with/already using Kubernetes.

How to deploy it

In order to use the Kaniko image builder, you need a deployed Kubernetes cluster.

How to use it

To use the Kaniko image builder, we need:

• The ZenML kaniko integration installed. If you haven't done so, run

  zenml integration install kaniko

• kubectl installed.

• A remote container registry as part of your stack.

• By default, the Kaniko image builder transfers the build context using the Kubernetes API. If you instead want to transfer the build context by storing it in the artifact store, you need to register it with the store_context_in_artifact_store attribute set to True. In this case, you also need a remote artifact store as part of your stack.

• Optionally, you can change the timeout (in seconds) until the Kaniko pod is running in the orchestrator using the pod_running_timeout attribute.

We can then register the image builder and use it in our active stack:

zenml image-builder register <NAME> \
    --flavor=kaniko \
    --kubernetes_context=<KUBERNETES_CONTEXT>
    [ --pod_running_timeout=<POD_RUNNING_TIMEOUT_IN_SECONDS> ]

# Register and activate a stack with the new image builder
zenml stack register <STACK_NAME> -i <NAME> ... --set

For more information and a full list of configurable attributes of the Kaniko image builder, check out the SDK Docs .

Authentication for the container registry and artifact store

The Kaniko image builder will create a Kubernetes pod that is running the build. This build pod needs to be able to pull from/push to certain container registries, and depending on the stack component configuration also needs to be able to read from the artifact store:

• The pod needs to be authenticated to push to the container registry in your active stack.

• In case the parent image you use in your DockerSettings is stored in a private registry, the pod needs to be authenticated to pull from this registry.

• If you configured your image builder to store the build context in the artifact store, the pod needs to be authenticated to read files from the artifact store storage.

ZenML is not yet able to handle setting all of the credentials of the various combinations of container registries and artifact stores on the Kaniko build pod, which is you're required to set this up yourself for now. The following section outlines how to handle it in the most straightforward (and probably also most common) scenario, when the Kubernetes cluster you're using for the Kaniko build is hosted on the same cloud provider as your container registry (and potentially the artifact store). For all other cases, check out the official Kaniko repository for more information.

AWS

• Add permissions to push to ECR by attaching the EC2InstanceProfileForImageBuilderECRContainerBuilds policy to your EKS node IAM role.

• Configure the image builder to set some required environment variables on the Kaniko build pod:

# register a new image builder with the environment variables
zenml image-builder register <NAME> \
    --flavor=kaniko \
    --kubernetes_context=<KUBERNETES_CONTEXT> \
    --env='[{"name": "AWS_SDK_LOAD_CONFIG", "value": "true"}, {"name": "AWS_EC2_METADATA_DISABLED", "value": "true"}]'

# or update an existing one
zenml image-builder update <NAME> \
    --env='[{"name": "AWS_SDK_LOAD_CONFIG", "value": "true"}, {"name": "AWS_EC2_METADATA_DISABLED", "value": "true"}]'

Check out the Kaniko docs for more information.

GCP

Azure

Passing additional parameters to the Kaniko build

You can pass additional parameters to the Kaniko build by setting the executor_args attribute of the image builder.

zenml image-builder register <NAME> \
    --flavor=kaniko \
    --kubernetes_context=<KUBERNETES_CONTEXT> \
    --executor_args='["--label", "key=value"]' # Adds a label to the final image

List of some possible additional flags:

• --cache: Set to false to disable caching. Defaults to true.

• --cache-dir: Set the directory where to store cached layers. Defaults to /cache.

• --cache-repo: Set the repository where to store cached layers.

• --cache-ttl: Set the cache expiration time. Defaults to 24h.

• --cleanup: Set to false to disable cleanup of the working directory. Defaults to true.

• --compressed-caching: Set to false to disable compressed caching. Defaults to true.

For a full list of possible flags, check out the Kaniko additional flags