kuik (pronounced /kwΙͺk/, like "quick") is the shortname of kube-image-keeper, a container image routing, mirroring (caching) and replication system for Kubernetes developed by Enix. It helps make applications more highly available by ensuring reliable access to container images.
Note
Kuik v2 has reached General Availability and is Production Ready as of v2.2.2 π
- Introduction
- When to use Kube Image Keeper
- Documentation
- Releases & Roadmap
- Known limitations to date
- Installation
- Why Version 2?
kuik v2 is a complete rewrite of the project with a focus on simplicity and ease of use :
- 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 copy: kuik can manage copy between registries to create a virtual highly available registry
- Image monitoring: kuik can monitor image availability across various registries
- Redesigned CRDs for better clarity and extensibility
KuiK use a mutating webhook to rewrite pod containers images when their are not available. It use Custom Resources ImageSetMirror and ReplicatedImageSet to generate a list of alternatives image values (including original one) for a given container image and check their availability to know if we keep using original image or rewrite it to an available alternative.
ReplicatedImageSet and ImageSetMirror both generate alternatives images when checking image availability in mutating webhook, but ImageSetMirror also handle the copy of original image to the given mirror registry.
- You face an image pull rate limit
- Your upstream registry is no longer available
- You plan a maintenance which will reschedule a lot of pods on new workers
- You plan a Kubernetes upgrade
- You have a lot of legacy images deployed on your cluster
- You have an aggressive garbage collect
- You have plenty of images (outdated, prior versions, development version) but only a small fraction is being used in reality
- You would like to push only a subset of useful images to your production registry
- You already have setup a proxy cache registry (like Harbor or Gitlab proxy cache) but do not know how to use it
- You do not want to review all workloads deployments (and change their image path)
- You use a development registry (ex: gitlab, maven, ...) for production Kubernetes clusters.
- Your registry is overloaded.
- Image pull from Kubernetes are too slow / long.
- Your source registry is too far away (from a network / geographic / latency standpoint) from the Kubernetes cluster
- A detailed explanation of all Kuik Custom Resources
- A reference for the operator configuration file (routing, monitoring, metrics)
- Kuik manages multiple alternatives of an image and selects the best-suited one. You might want to learn more about the Priority mechanism
- A preliminary migration path from Kuik v1 to Kuik v2
- A collection of documented use cases
- A development guide
- 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 Various quality of life improvements
- Better filtering for resources (
includeNamespace&excludeNamespace,includeLabels&excludeLabels, β¦) - Optional monitoring of mirrored images with re-mirroring when needed
- Better filtering for resources (
- v2.4 Improve stability of critical components (such as the mutating webhook) by deploying them individually
- The mutating webhook do not support the Pod
Updatecall - Digest tags are not supported, ex:
@sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805
We rely on cert-manager Custom Resources to manage the kuik mutating webhook certificate, so you need to install it first.
VERSION=2.2.2
helm upgrade --install --create-namespace --namespace kuik-system kube-image-keeper oci://quay.io/enix/charts/kube-image-keeper:$VERSIONCustom 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.
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-tokenIf 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.
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.