ghcr.io/enix/kube-image-keeper:1.11.0-beta.2

kube-image-keeper (kuik)

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

[!NOTE] Kuik v2 已达到 正式发布（General Availability） 状态，自 v2.2.2 版本起已 生产就绪 🚀

📖 完整文档：kuik.enix.io

目录

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

简介

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

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

概念：容器镜像备选方案

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

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

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

何时使用 Kube Image Keeper

✅ 克服公共 registry 限制

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

 实施指南

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

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

 实施指南

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

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

 实施指南

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

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

 实施指南

✅ 使用本地 registry 提升性能

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

 实施指南

📘 文档

完整文档发布于 kuik.enix.io，源 Markdown 文件位于 website/src/content/docs/。

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

📅 发布版本与路线图

已发布版本

• https://github.com/enix/kube-image-keeper/releases/tag/v2.1.0 我们在 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

🚧 当前已知限制

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

📦 安装

我们依赖 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 的行为（如路由和镜像同步功能）。这些在 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 仅删除镜像引用。

为何推出版本 2？

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

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