如何快速部署k8s-image-swapperHelm一行命令实现ECR镜像自动镜像新手保姆级教程【免费下载链接】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 Mutating Webhook能把集群中所有第三方容器镜像自动镜像mirror到你自己的 ECR / GCP 镜像仓库并在 Pod 创建时无缝替换镜像引用。本文手把手带你用Helm 一行命令完成部署实现 ECR 镜像自动同步全程无需修改任何 Deployment YAML。 为什么需要镜像自动同步日常使用 Kubernetes 时Pod 往往直接拉取 docker.io、quay.io 等外部公共仓库的镜像。k8s-image-swapper 帮你集中解决以下痛点️抵御外部仓库故障quay.io 宕机、docker.io 限流时集群照常运行️防止镜像被篡改或删除镜像落到自己仓库后版本完全可控降低网络流量成本同一镜像只需从公网拉一次后续节点从自建仓库拉取适配离线air-gapped环境无需改动清单即可使用工作原理Webhook 如何自动替换镜像引用整个流程对使用者完全透明你提交 Pod / Deployment镜像仍是nginx这类原始地址Kubernetes API Server 将请求交给 k8s-image-swapper 这个 Mutating Webhook它在后台异步复制镜像到目标仓库仓库不存在会自动创建并把 Pod 里的镜像地址改写成新仓库地址节点最终从你自己的 ECR / GCP 仓库拉取镜像核心逻辑见 pkg/webhook/image_swapper.goECR 仓库的具体实现见 pkg/registry/ecr.go。部署前准备5 分钟完成权限与凭证配置以 AWS ECR 为目标仓库为例只需三步选定命名空间如kube-system或operations并确认它已存在创建 IAM 用户如k8s-image-swapper并授予创建 ECR 仓库、上传镜像的权限完整 IAM 策略可参考官方部署文档 docs/getting-started.md把密钥存入 K8s Secretkubectl create secret generic k8s-image-swapper-aws \ --from-literalaws_access_key_id你的AccessKeyID \ --from-literalaws_secret_access_key你的SecretKey 如果你使用 EKS也可以用 Service Account WebIdentity IAM Role 的方式免管密钥Helm 参数会相应换成 Service Account 注解。Helm 一行命令部署 k8s-image-swapper先添加 estahn 的 Helm Chart 仓库并执行helm repo update仓库地址见 docs/getting-started.md 的 Helm 章节然后用下面一行命令完成安装与配置helm install k8s-image-swapper estahn/k8s-image-swapper \ --set config.target.aws.accountId123456789012 \ --set config.target.aws.regionap-southeast-2 \ --set awsSecretNamek8s-image-swapper-aws参数说明config.target.aws.accountId目标 ECR 所属的 AWS 账号 IDconfig.target.aws.region目标 ECR 所在区域如ap-southeast-2awsSecretName上一步创建的 AWS 凭证 Secret 名称GCP 用户切换 Artifact Registry 只需改 target如果你使用 GCP把target.type改为gcp即可所有镜像会集中存放在一个Artifact Registry 仓库中target: type: gcp gcp: location: us-central1 projectId: gcp-project-123 repositoryId: main部署后验证确认镜像已成功同步查看 Pod 是否就绪kubectl get pods -n kube-system部署一个使用公共镜像如nginx的测试 Pod打开 ECR 控制台能看到自动创建的仓库——命名规则是源仓库作前缀例如nginx→docker.io/library/nginx如果目标仓库是 GCP Artifact Registry控制台中会看到如下镜像列表新手必改的 2 个配置项配置文件为.k8s-image-swapper.yaml建议先调整以下两项dryRun: true # 试运行只记录不真正复制/改写镜像验证行为 logLevel: debug # 调试日志方便排查dryRun验证无误后改为false正式生效完整选项如imageSwapPolicy、imageCopyPolicy、JMESPath 过滤规则等见 docs/configuration.md常见问题快速排查FAQ改了配置不生效配置变更不会热加载需要滚动重启 PodWebhook 挂了怎么办失败策略默认为Ignore集群会像没装它一样继续工作目标仓库里没有这个镜像行为由imageCopyPolicy/imageSwapPolicy决定详见 docs/configuration.mdsidecar 镜像没被替换可开启webhook.reinvocationPolicy: IfNeeded更多问题见 docs/faq.md。 项目文档与源码导航内容路径部署指南Helm / Terraform / IAMdocs/getting-started.md完整配置选项docs/configuration.mdWebhook 核心逻辑pkg/webhook/image_swapper.go从 K8s 读取拉取凭证pkg/secrets/kubernetes.go端到端测试test/e2e_test.go想浏览完整源码可以克隆仓库git clone https://gitcode.com/gh_mirrors/k8s/k8s-image-swapper按本文操作从安装到镜像自动同步 ECR 全程不到 10 分钟。部署完成后你的集群就拥有了抗仓库故障、抗限流的镜像保险柜 【免费下载链接】k8s-image-swapperMirror images into your own registry and swap image references automatically.项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-image-swapper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考