kube-image-keeper (kuik)

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 🚀

Table of contents

• Introduction
• When to use Kube Image Keeper
• Documentation
• Releases & Roadmap
• Known limitations to date
• Installation
• Why Version 2?

Introduction

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

Concept : Container image alternatives

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.

When to use Kube Image Keeper

✅ Overcome public registry limitations

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

 Implementation guide

✅ Detect missing images before outage

• 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

✅ Protect images from garbage collect

• 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

✅ Automatically route images to a proxy cache 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)

 Implementation guide

✅ Better performance with local registry

• 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

📘 Documentation

• 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

📅 Releases & Roadmap

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 Various quality of life improvements
• Better filtering for resources (includeNamespace & excludeNamespace, includeLabels & excludeLabels, …)
• Optional monitoring of mirrored images with re-mirroring when needed
• v2.4 Improve stability of critical components (such as the mutating webhook) by deploying them individually

🚧 Known limitations to date

• The mutating webhook do not support the Pod Update call
• Digest tags are not supported, ex: @sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805

📦 Installation

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

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.