如何快速部署k8s-image-swapper：Helm一行命令实现ECR镜像自动镜像（新手保姆级教程）
【免费下载链接】k8s-image-swapperMirror images into your own registry and swap image references automatically.项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-image-swapper
k8s-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.go，ECR 仓库的具体实现见 pkg/registry/ecr.go。
部署前准备：5 分钟完成权限与凭证配置
以 AWS ECR 为目标仓库为例，只需三步：
- 选定命名空间：如
kube-system或operations，并确认它已存在 - 创建 IAM 用户（如
k8s-image-swapper）并授予创建 ECR 仓库、上传镜像的权限，完整 IAM 策略可参考官方部署文档 docs/getting-started.md - 把密钥存入 K8s Secret：
kubectl create secret generic k8s-image-swapper-aws \ --from-literal=aws_access_key_id=<你的AccessKeyID> \ --from-literal=aws_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.accountId=123456789012 \ --set config.target.aws.region=ap-southeast-2 \ --set awsSecretName=k8s-image-swapper-aws| 参数 | 说明 |
|---|---|
config.target.aws.accountId | 目标 ECR 所属的 AWS 账号 ID |
config.target.aws.region | 目标 ECR 所在区域，如ap-southeast-2 |
awsSecretName | 上一步创建的 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）
- 改了配置不生效？配置变更不会热加载，需要滚动重启 Pod
- Webhook 挂了怎么办？失败策略默认为
Ignore，集群会像没装它一样继续工作 - 目标仓库里没有这个镜像？行为由
imageCopyPolicy/imageSwapPolicy决定，详见 docs/configuration.md - sidecar 镜像没被替换？可开启
webhook.reinvocationPolicy: IfNeeded
更多问题见 docs/faq.md。
📚 项目文档与源码导航
| 内容 | 路径 |
|---|---|
| 部署指南（Helm / Terraform / IAM） | docs/getting-started.md |
| 完整配置选项 | docs/configuration.md |
| Webhook 核心逻辑 | 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），仅供参考
