kube-image-keeper (kuik)

kuik（发音为 /kwɪk/，与 "quick" 相同）是 kube-image-keeper 的简称，是由 Enix 开发的 Kubernetes 容器镜像路由、镜像（缓存）和复制系统。它通过确保容器镜像的可靠访问，帮助提高应用程序的高可用性。

[!NOTE] Kuik v2 已达成正式发布（General Availability），自 v2.2.2 版本起已具备生产就绪能力 🚀

目录

• 简介
• 何时使用 Kube Image Keeper
• 📘 文档
• 📅 发布版本与路线图
• 🚧 已知限制
• 📦 安装
• 为什么是 Version 2？

Introduction

kuik v2 是对该项目的完全重写，重点关注简洁性和易用性：

• 最小化默认功能：默认仅启用核心功能，其他功能需手动开启。
• 镜像路由：Kuik 可实时重写 Pod 镜像，将其重定向到可用的 registry。
• 镜像复制：Kuik 管理 registry 之间的镜像传输，以创建虚拟的高可用 registry。
• 镜像监控：Kuik 跟踪不同 registry 中的镜像可用性。
• 重新设计的 CRD：提高清晰度和可扩展性。

概念：容器镜像备选方案

KuiK 利用变异 Webhook（mutating webhook） 在主（“原始”）镜像源不可用时重写 Pod 容器镜像。通过 ImageSetMirror 或 ReplicatedImageSet 自定义资源，Kuik 生成备选镜像位置列表（包括原始位置）。然后它会验证这些位置的可用性，以决定是使用原始镜像还是将清单重写为健康的备选镜像。

虽然这两种自定义资源都会生成备选方案，但它们的行为略有不同：

• ReplicatedImageSet：专注于检查现有镜像源的可用性。
• ImageSetMirror：还会处理将原始镜像自动复制到指定的镜像 registry。

When to use Kube Image Keeper

✅ 克服公共 registry 限制

• 遇到镜像拉取速率限制
• 上游 registry 不可用

 实施指南

✅ 在故障发生前检测缺失镜像

• 计划进行维护，需要在新工作节点上重新调度大量 Pod
• 计划升级 Kubernetes
• 集群中部署了大量遗留镜像

 实施指南

✅ 保护镜像免受垃圾回收影响

• 启用了激进的垃圾回收策略
• 拥有大量镜像（过时版本、历史版本、开发版本），但实际上只有一小部分在使用
• 希望仅将有用镜像的子集推送到生产 registry

 实施指南

✅ 自动将镜像路由到代理缓存 registry

• 已设置代理缓存 registry（如 Harbor 或 Gitlab 代理缓存），但不知道如何使用
• 不想检查所有工作负载部署（并更改其镜像路径）

 实施指南

✅ 通过本地 registry 提升性能

• 为生产 Kubernetes 集群使用开发 registry（如 gitlab、maven 等）
• registry 负载过高
• Kubernetes 拉取镜像速度太慢/耗时太长
• 源 registry 与 Kubernetes 集群在网络/地理/延迟方面距离过远

 实施指南

📘 Documentation

• 所有 Kuik 自定义资源 的详细说明
• 操作员配置文件 参考（路由、监控、指标）
• Kuik 管理镜像的多个备选方案并选择最合适的方案。您可能需要了解更多关于 优先级机制 的信息
• Kuik v1 到 v2 的迁移路径
• 已记录的 使用场景 集合
• 开发指南

📅 Releases & Roadmap

已发布版本

• https://github.com/enix/kube-image-keeper/releases/tag/v2.1.0 我们在 Cloud Native Days France 2026 大会 上宣布了 v2.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 完整实现 镜像监控 功能及相关指标

计划功能

• v2.3 多项用户体验改进
• 更完善的资源过滤（includeNamespace 和 excludeNamespace、includeLabels 和 excludeLabels 等）
• 可选的镜像监控功能，在需要时自动重新镜像
• v2.4 通过单独部署关键组件（如变异 Webhook）提高稳定性
• 减少内存占用

🚧 Known limitations to date

• 变异 Webhook 不支持 Pod 的 Update 调用
• 不支持摘要标签，例如：@sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805
• 镜像已镜像后修改 mirroring.platforms 不会重新镜像或清理已复制的清单（添加或移除平台仅适用于后续镜像操作）

📦 Installation

我们依赖 cert-manager 自定义资源 来管理 kuik 变异 Webhook 证书，因此您需要先安装 cert-manager。

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

自定义资源定义（CRD）用于配置 kuik 的行为，如路由和镜像功能。这些在 docs/crds.md 文档中有详细描述。

要设置 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 仅删除镜像引用。

Why Version 2?

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

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