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.

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

Concept : Container image alternatives

The most basic functionnality of Kuik is rewriting container image paths. Conceptually, you can differentiate the original image (path) and the rewritten image (path). Since there can be many rewritten images, both they and the original image are considered image (path) alternatives.

In other words, the original image is an alternative, just as a rewritten image is.

While configuring Custom Resources, you specify these alternative paths regardless of whether they are original or rewritten.

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
• 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 cluster wide resources (includeNamespace & excludeNamespace)
  • 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

• Mirrored images are considered replicated even if the image was later deleted fixed in v2.1.1
• Competition between Kuik's cluster wide custom resources and namespaced resources might lead to weird scenarios (to be partially 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
• Digest tags are not supported, ex: @sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805

📦 Installation

kubectl create namespace kuik-system
VERSION=2.2.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.