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.

📖 Full documentation: kuik.enix.io

• Introduction
• When to use Kube Image Keeper
• 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: only core functionality enabled by default, others opt-in.
• Image routing: Kuik can rewrite Pod images on-the-fly to redirect them to an operational registry.
• Image copy: Kuik manages image transfers between registries in order to create a virtual, highly-available registry.
• Image monitoring: Kuik tracks image availability across various registries.
• Redesigned CRDs: for better clarity and improved extensibility.

KuiK utilizes a mutating webhook to rewrite Pod container images when the primary ("original") source is not available. By leveraging ImageSetMirror or ReplicatedImageSet Custom Resources, Kuik generates a list of alternative image locations (including the original one). It then validates their availability to determine whether to stick with the original image or rewrite the manifest to a healthy alternative.

While both Custom Resources generate alternatives, their behavior differs slightly:

• ReplicatedImageSet: Focuses on checking availability across existing mirrors.
• ImageSetMirror: Also handles the automated copy of the original image to the specified mirror registry.

• You face an image pull rate limit
• Your upstream registry is no longer available

 Implementation guide

• 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

 Implementation guide

• 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

 Implementation guide

• 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)

 Implementation guide

• 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

 Implementation 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 Better filtering
• v2.4 Complete OCI support of tags, architectures and digests
• v2.5 Improve stability & efficiancy

• 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)

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:$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.

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.