ghcr.io/enix/kube-image-keeper:1.7.0-alpine

kube-image-keeper (kuik)

kuik（发音为/kwɪk/，类似“quick”）是kube-image-keeper的简称。

✅ 其主要目标是严格在其运行的Kubernetes集群内最大限度地提高Pod镜像的可用性。

✅ 其次要目标是通过将对Kubernetes原语的操作降至最低，确保万无一失的可靠性。

核心机制

它依赖于三个核心机制：

• 镜像路由：在Pod创建过程中动态重写镜像路径，将其重定向到可用的registry。
• 镜像复制：跨registry镜像本地集群使用的镜像，构建一个虚拟的高可用registry。
• 镜像监控：持续跟踪本地集群内使用的Pod镜像在多个registry中的可用性。

[!NOTE] 镜像路由由轻量级MutatingWebhook在Pod创建时执行，当源registry不可用时，该Webhook会自动重写镜像路径。

kube-image-keeper由Enix开发，是经过实战检验的解决方案，目前已在多个Kubernetes集群的生产环境中运行。

目录

文档、概念和用例可在此处获取：kuik.enix.io

• 快速开始
• 发布与路线图
• 当前已知限制
• 为什么是版本2？

🚀 快速开始

我们依赖cert-manager Custom Resources来管理kuik的mutating webhook证书，因此您需要https://cert-manager.io/docs/installation/%E3%80%82

VERSION=2.2.3
helm upgrade --install --create-namespace --namespace kuik-system kube-image-keeper oci://quay.io/enix/charts/kube-image-keeper:$VERSION

自定义资源定义（CRD）用于配置kuik的行为，例如其路由和镜像功能。这些在CRD参考中有详细描述。

要设置ImageSetMirror（或ClusterImageSetMirror），您首先需要配置一个registry，kuik将在其中复制匹配的镜像。然后生成一个具有拉取、推送和删除（如果启用清理）权限的令牌，并使用以下命令创建在ImageSetMirror中使用的密钥：

kubectl create secret docker-registry my-registry-secret --docker-server=my-registry.company.com --docker-username=my-username --docker-password=my-token

如果您让kuik清理registry中的过期镜像，您仍需自行配置垃圾回收，因为kuik仅删除镜像引用。

📅 发布与路线图

Kuik v2已达到正式发布（General Availability）状态，自v2.2.2版本起已具备生产环境就绪性 🚀

已发布功能

• https://github.com/enix/kube-image-keeper/releases/tag/v2.1.0 我们在2026年法国云原生日大会（Cloud Native Days France 2026）上宣布了2.0版本（正式发布）的推出
• https://github.com/enix/kube-image-keeper/releases/tag/v2.1.0 路由和复制的优先级现已支持
• https://github.com/enix/kube-image-keeper/releases/tag/v2.1.1 修复了多集群上的多个Kuik实例对单个registry的并发访问问题（特别是垃圾回收机制相关）
• https://github.com/enix/kube-image-keeper/releases/tag/v2.2.0 完成了镜像监控功能的实现，并提供了相关指标

计划功能

• https://github.com/enix/kube-image-keeper/milestone/1
• https://github.com/enix/kube-image-keeper/milestone/3
• https://github.com/enix/kube-image-keeper/milestone/2

🚧 当前已知限制

• mutating webhook不支持Pod的Update调用
• 不支持摘要标签，例如：@sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805
• （Cluster）ImageSetMirror状态中未跟踪每个平台的镜像状态。因此：（1）Kuik无法报告给定镜像实际镜像了哪些架构——只要至少一个配置的平台可用，镜像就会被标记为成功，缺失的平台仅记录为警告；（2）在镜像已被复制后更改mirroring.platforms不会重新镜像或清理已复制的清单（添加或删除的平台仅适用于后续的镜像操作）

为什么是版本2？

尽管我们为kube-image-keeper v1版本所取得的成就感到自豪，但使用它常常令人头疼：部署困难、过于复杂，而镜像缓存功能虽然雄心勃勃，却经常引发太多问题。我们偏离了最初的目标：使kube-image-keeper成为任何集群都能轻松、无需思考即可安装的工具，帮助运维人员日常工作并提供信心。

我们从这次经验中学到了很多，而在v2版本中，我们重新开始！我们的重点是简化和易用性，同时提供相同甚至更多的功能！kuik应该易于安装和使用——将其添加到集群中时，您无需三思。我们的目标：您甚至会忘记它的存在，当registry宕机或镜像不可用时也不会察觉。