kube-image-keeper (kuik)

kuik (pronounced /kwɪk/, like "quick") is the shortname of kube-image-keeper.

✅ Its primary objective is to maximize the availability of Pod images strictly within the Kubernetes cluster it runs on.

✅ Its secondary goal is to ensure bulletproof reliability by keeping the manipulation of Kubernetes primitives to an absolute minimum.

Under the hood

It relies on three core mechanisms:

• Image routing: rewrites Pod image paths on the fly during their creation to redirect them to a functional registry.
• Image copy: mirror images used by the local cluster across registries, building a virtual, highly available registry.
• Image monitoring: continuously tracks the availability of Pod images used within the local cluster across various registries.

Note : image routing is performed at Pod creation by a lightweight MutatingWebhook that automatically rewrites the image path whenever the source registry becomes unavailable.

Developed by Enix, kube-image-keeper is a battle-tested solution currently running in production across multiple Kubernetes clusters.

Table of contents

Documentation, concepts and use cases are available here: kuik.enix.io

• Get started
• Releases & Roadmap
• Known limitations to date
• Why Version 2?

🚀 Get started

We rely on cert-manager Custom Resources to manage the kuik mutating webhook certificate, so you need to install it first.

VERSION=2.2.3
helm upgrade --install --create-namespace --namespace kuik-system kube-image-keeper oci://quay.io/enix/charts/kube-image-keeper:$VERSION

Custom Resource Definitions (CRDs) are used to configure the behavior of kuik such as its routing and mirroring features. Those are described in the CRD reference.

To setup an ImageSetMirror (or a ClusterImageSetMirror), you will first need to configure a registry where kuik will copy matched images. Then generate a token with permission to pull, push and delete (if cleanup enabled) in this registry and create the secret to use in your ImageSetMirror with:

kubectl create secret docker-registry my-registry-secret --docker-server=my-registry.company.com --docker-username=my-username --docker-password=my-token

If you let kuik cleanup expired images in your registry, you still have to configure garbage collection on your own as kuik only delete images reference.

📅 Releases & Roadmap

Kuik v2 has reached General Availability and is Production Ready as of v2.2.2 🚀

Already available

• v2.0 We announced the launch of version 2.0 (General Availability) at the Cloud Native Days France 2026 convention
• v2.1 Priorities for routing and replication are now a thing
  • v2.1.1 Fix concurrent access to a single registry (in particular regarding the garbage collect mechanism) by multiple Kuik instances on multiple clusters
• v2.2 Complete implementation of the Image monitoring feature with associated metrics

Planned features

• v2.3 Better filtering
• v2.4 Complete OCI support of tags, architectures and digests
• v2.5 Improve stability & efficiancy

🚧 Known limitations to date

• The mutating webhook do not support the Pod Update call
• Digest tags are not supported, ex: @sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805
• Per-platform mirroring status is not tracked in the (Cluster)ImageSetMirror status. As a result: (1) Kuik cannot report which architectures are actually mirrored for a given image — a mirror is marked successful as long as at least one configured platform is available, and missing platforms are only logged as a warning; and (2) changing mirroring.platforms after images have been mirrored does not re-mirror or clean up already-copied manifests (added or removed platforms only apply to subsequent mirror operations)

Why Version 2?

Even if we are proud of what we achieved with the v1 of kube-image-keeper, it was too often painful to work with: it was hard to deploy, overly complex, and the image caching feature — while ambitious — introduced often too much issues. We missed our original goal: to make kube-image-keeper an easy, no-brainer install for any cluster which would help ops in their day to day work and provide confidence.

We learned a lot from this experience and with v2, we're starting fresh! Our focus is on simplicity and ease of use with the same set of features and even more! kuik should be effortless to install and to use — you shouldn't have to think twice before adding it to your cluster. Our goal: you will forget it's even there and don't even notice when a registry goes down or an image becomes unavailable.