kube-image-keeper (kuik)

kuik (pronounced /kwɪk/, like "quick") is the shortname of kube-image-keeper, a container image routing, mirroring and replication system for Kubernetes developed by Enix. It helps make applications more highly available by ensuring reliable access to container images.

🚀 Status: General Availability

Note

kuik v2 is a complete rewrite of the project with a focus on simplicity and ease of use.

Caution

Not recommended for production use yet. Kuik v2 is currently being battle tested on several clusters.

✨ What's New in v2

Mostly a redesigned architecture

• Minimal default features: core functionality enabled by default, others opt-in
• Image routing: kuik can rewrite Pod images on-the-fly to point to an operational registry
• Image replication: kuik can manage copy between registries to create a virtual highly available registry
• Image monitoring: kuik can monitor image availability across various registries (planned for v2.2)
• Redesigned CRDs for better clarity and extensibility

🧪 Roadmap

Planned features for future minor versions (subject to change):

• 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
• v2.3 Improve stability of critical components (such as the mutating webhook) by deploying them individually

🚧 Known limitations to date

• Digest tags are not supported, ex: @sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805
• Mirrored images are considered replicated even if the image was later deleted (to be fixed in v2.1.1)
• The mutating webhook do not support the Pod Update call
• With replication enabled from registry A to registry B, launching a Pod with image on B will be rerouted (rewritten) to image on A
• Competition between Kuik's cluster wide custom ressources and namespaced ressources might lead to weird scenarios (to be partially fixed in v2.1.1)

📦 Installation

kubectl create namespace kuik-system
VERSION=2.0.0
helm upgrade --install --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 docs/crds.md document.

🤷 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.