k8s-image-swapper私有镜像拉取全解imagePullSecrets机制深度解析【免费下载链接】k8s-image-swapperMirror images into your own registry and swap image references automatically.项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-image-swapperk8s-image-swapper是一个 Kubernetes 变更准入 Webhook它会把你集群里的镜像自动镜像mirror到私有镜像仓库如 AWS ECR、GCP Artifact Registry并把 Pod 中的镜像地址自动替换为新位置。拉取私有镜像仓库中的镜像时它依赖 Kubernetes 原生的imagePullSecrets 机制来获取认证凭据。本文带你完整理解这套私有镜像认证机制是如何工作的。一、为什么私有镜像仓库是难点k8s-image-swapper 的核心工作流是拦截Pod 创建请求先经过它的 Mutating Webhook见 image_swapper.go复制把源镜像如nginx用 skopeo 拷贝到你的私有仓库替换把容器镜像地址改写为你的仓库域名/nginx。其中第 2 步有个前提如果源镜像本身存放在私有镜像仓库里比如公司内部的 registry、需要登录的 Docker Hub 仓库skopeo 必须持有对应的账号密码才能把镜像拉出来。这正是 imagePullSecrets 机制要解决的问题。二、imagePullSecrets 认证机制3 条凭据获取路径私有镜像凭据的读取全部由 KubernetesImagePullSecretsProvider 完成它对每条路径都有对应实现路径凭据来源是否自动获取① Pod 级 imagePullSecretspod.spec.imagePullSecrets✅ 是② ServiceAccount 级 imagePullSecretsserviceAccount.imagePullSecrets✅ 是③ ECR 源仓库自动认证目标仓库的同一套 AWS 凭据✅ 是需配置路径①和②Provider 会先读取 Pod 自身的imagePullSecrets再通过 API 客户端获取 Pod 引用的 ServiceAccount把其中挂载的 imagePullSecrets合并进来——也就是说即使你的 Pod 本身没有配置只要 ServiceAccount 挂了私有仓库凭据一样能用。路径③对于 AWS ECR 这类私有仓库还支持在配置中声明源 ECR 列表k8s-image-swapper 会用操作目标仓库的同一套 AWS 凭据如 IAM Role 或 IAM 密钥自动生成认证信息无需手工创建 Secret。配置方式见 configuration.md 的 Source - AWS / Private registries 章节整体安装步骤参考 getting-started.md。三、凭据如何合并一次看懂 secret 聚合流程这是机制中最精巧的部分代码在 pkg/secrets/kubernetes.go 中逐个获取 Secret按名字从 Pod 所在命名空间拉取 Secret且同一个 Secret 只取一次去重类型过滤只接受kubernetes.io/dockerconfigjson类型的 Secret其他类型直接跳过容错设计获取失败或缺失只会打一条警告日志不会阻断整个 Webhook 流程——这与它的 failure policy 为Ignore的容错哲学一致见 faq.mdJSON 合并所有 Secret 的auths内容通过jsonpatch.MergePatch合并成一个统一的 docker config 文档落盘为认证文件合并结果写入一个临时文件AuthFile()用完即删避免凭据残留。最终这个临时文件会作为--src-authfile参数传给 skopeo目标仓库侧则用独立的凭据ECR 自动轮换的认证令牌见 ecr.go通过--dest-creds传入——源、目标两套认证互不干扰。skopeo 的调用逻辑在 ecr.go 的 CopyImage 方法 中。四、什么时候才真正去拉取私有镜像k8s-image-swapper 有延迟拷贝delayed copy策略Webhook 只负责改镜像地址真正的 skopeo 拷贝任务被提交到异步工作池只有当目标仓库中确实还没有该镜像时才会执行拉取ImageCopyPolicyDelayed为默认策略。这意味着 imagePullSecrets 中的凭据并非每次请求都会用到只在源镜像首次被镜像的那一刻真正生效。这也是为什么凭据读取逻辑放在拷贝任务 image_copier.go 的 taskCopyImage 中而不是 Webhook 主流程里。五、上手检查清单如果你正准备接入私有镜像仓库可以按这份清单自查私有仓库的dockerconfigjsonSecret 已创建在Pod 所在的命名空间Secret 已挂到 Pod 的imagePullSecrets或挂到 Pod 使用的 ServiceAccount 上Secret 中的auths域名与源镜像仓库域名完全一致若源是 ECR确认 AWS 凭据具备源仓库的拉取权限或改用配置中的 ECR 源列表自动认证目标仓库权限正常目标侧认证与 imagePullSecrets 无关是独立的总结k8s-image-swapper 对私有镜像仓库的支持非常务实复用 Kubernetes 原生的 imagePullSecrets 体系Pod 级 ServiceAccount 级双重来源通过 JSON 合并聚合成单一认证文件交给 skopeo并叠加 ECR 源仓库的自动凭据兜底。整条链路容错性强、凭据不落盘配合延迟拷贝策略让私有镜像的镜像化过程对运维几乎透明。如果你想继续深入了解配置项如ImageCopyPolicy、JMESPath 过滤器可以直接阅读 configuration.md。【免费下载链接】k8s-image-swapperMirror images into your own registry and swap image references automatically.项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-image-swapper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考