kube-image-keeper (kuik)

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

[!NOTE] Kuik v2 已达到 General Availability 状态，自 v2.2.2 版本起已 Production Ready 🚀

目录

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

简介

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

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

概念：容器镜像替代方案

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

虽然这两种自定义资源都能生成替代方案，但其行为略有不同：

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

何时使用 Kube Image Keeper

✅ 克服公共 registry 限制

• 面临镜像拉取速率限制
• 上游 registry 不再可用

 实施指南

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

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

 实施指南

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

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

 实施指南

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

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

 实施指南

✅ 使用本地 registry 提升性能

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

 实施指南

📘 文档

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

📅 发布与路线图

已发布版本

• https://github.com/enix/kube-image-keeper/releases/tag/v2.1.0 我们在 Cloud Native Days France 2026 大会 上宣布了版本 2.0（General Availability）的发布
• 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 不会重新同步或清理已复制的清单（添加或删除的平台仅适用于后续的镜像同步操作）

📦 安装

我们依赖 cert-manager 自定义资源 来管理 kuik mutating webhook 证书，因此你需要先安装它。

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

为什么是版本 2？

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

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