flemzord/mutating-registry-webhook

# Mutating Registry Webhook 一个 Kubernetes 准入控制器 Webhook，可自动重写容器镜像引用，以使用镜像缓存（例如 AWS ECR Pull Through Cache）。 ## 描述 此 webhook 会拦截 Kubernetes 集群中的 Pod 创建和更新请求，并根据可配置的规则自动重写容器镜像引用。这在以下情况下特别有用： - 使用 AWS ECR Pull Through Cache 来减少对外部镜像仓库的依赖 - 实施企业内部的镜像代理/缓存 - 将来自 Docker Hub、GCR、Quay.io 或其他镜像仓库的镜像重定向到您的内部镜像仓库 - 基于命名空间或 Pod 标签应用不同的规则 ## 功能 - 🔄 基于正则表达式模式的自动镜像 URL 重写 - 🎯 基于命名空间和标签的精准匹配 - ⚡ 借助内存规则缓存实现高性能 - 🔒 默认安全，集成 cert-manager - 📊 支持 Prometheus 指标 - 🎛️ 提供 Helm chart 以便轻松部署 - 🧪 全面的测试覆盖率 ## 入门指南 ### 前置条件 - go 版本 v1.24.0+ - docker 版本 17.03+ - kubectl 版本 v1.11.3+ - 可访问 Kubernetes v1.11.3+ 集群 - 集群中已安装 cert-manager v1.0+ ### 快速开始 1. **安装 cert-manager**（如果尚未安装）： ``` kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml ``` 2. **安装 webhook**： ``` kubectl apply -f https://github.com/flemzord/mutating-registry-webhook/releases/download/v0.4.0/install.yaml ``` 3. **创建一个 RegistryRewriteRule**： ``` apiVersion: dev.flemzord.fr/v1alpha1 kind: RegistryRewriteRule metadata: name: docker-hub-to-ecr spec: rules: # Redirect Docker Hub images to ECR pull-through cache - match: '^docker\.io/(.*)' replace: '123456789012.dkr.ecr.us-east-1.amazonaws.com/dockerhub/$1' # Handle images without explicit registry (defaults to docker.io) - match: '^([^/]+/[^/]+)$' replace: '123456789012.dkr.ecr.us-east-1.amazonaws.com/dockerhub/$1' ``` ### 在集群上部署 **构建你的镜像并将其推送到由 `IMG` 指定的位置：** ``` make docker-build docker-push IMG=/mutating-registry-webhook:tag ``` **注意：** 此镜像应发布到你指定的个人镜像仓库中。 并且要求工作环境具有拉取该镜像的权限。 如果上述命令不起作用，请确保你对该镜像仓库拥有适当的权限。 **将 CRD 安装到集群中：** ``` make install ``` **使用由 `IMG` 指定的镜像将 Manager 部署到集群中：** ``` make deploy IMG=/mutating-registry-webhook:tag ``` **创建你的解决方案实例** 你可以应用 config/sample 中的示例： ``` kubectl apply -k config/samples/ ``` ### 卸载 **从集群中删除实例 (CR)：** ``` kubectl delete -k config/samples/ ``` **从集群中删除 API (CRD)：** ``` make uninstall ``` **从集群中卸载控制器：** ``` make undeploy ``` ## 项目分发 以下是向用户发布和提供此解决方案的选项。 ### 通过提供包含所有 YAML 文件的捆绑包 1. 为已在镜像仓库中构建并发布的镜像构建安装程序： ``` make build-installer IMG=/mutating-registry-webhook:tag ``` **注意：** 上面提到的 makefile 目标会在 dist 目录中生成一个 'install.yaml' 文件。此文件包含使用 Kustomize 构建的所有资源， 这些资源是无需其依赖项即可安装此项目所必需的。 2. 使用安装程序 用户只需运行 'kubectl apply -f ' 即可安装 该项目，例如： ``` kubectl apply -f https://raw.githubusercontent.com//mutating-registry-webhook//dist/install.yaml ``` ### 通过提供 Helm Chart 1. 使用可选的 helm 插件构建 chart ``` kubebuilder edit --plugins=helm/v2-alpha ``` 2. 查看在 'dist/chart' 下生成的 chart，用户 可以从那里获取此解决方案。 **注意：** 如果你更改了项目，则需要 使用上面的相同命令更新 Helm Chart 以同步最新的更改。此外， 如果你创建了 webhook，则需要使用上述带有 '--force' 标志的命令，并手动确保在之后重新手动应用先前添加到 'dist/chart/values.yaml' 或 'dist/chart/templates/manager/manager.yaml' 的任何自定义配置。 ## 示例 ### 基础 Docker Hub 到 ECR ``` apiVersion: dev.flemzord.fr/v1alpha1 kind: RegistryRewriteRule metadata: name: dockerhub-cache spec: rules: - match: '^docker\.io/(.*)' replace: '${ECR_REGISTRY}/dockerhub/$1' - match: '^([^/]+/[^/]+)$' # nginx:latest becomes docker.io/nginx:latest replace: '${ECR_REGISTRY}/dockerhub/$1' ``` ### 多镜像仓库 ``` apiVersion: dev.flemzord.fr/v1alpha1 kind: RegistryRewriteRule metadata: name: multi-registry-cache spec: rules: # Docker Hub - match: '^docker\.io/(.*)' replace: '${ECR_REGISTRY}/dockerhub/$1' # Google Container Registry - match: '^gcr\.io/([^/]+)/(.+)' replace: '${ECR_REGISTRY}/gcr/$1/$2' # Quay.io - match: '^quay\.io/(.*)' replace: '${ECR_REGISTRY}/quay/$1' # GitHub Container Registry - match: '^ghcr\.io/(.*)' replace: '${ECR_REGISTRY}/ghcr/$1' ``` ### 特定命名空间的规则 ``` apiVersion: dev.flemzord.fr/v1alpha1 kind: RegistryRewriteRule metadata: name: production-only spec: rules: - match: '^docker\.io/(.*)' replace: '${PROD_REGISTRY}/$1' conditions: namespaces: ["production", "staging"] ``` ### 基于标签的规则 ``` apiVersion: dev.flemzord.fr/v1alpha1 kind: RegistryRewriteRule metadata: name: team-specific spec: rules: - match: '^docker\.io/(.*)' replace: '${TEAM_REGISTRY}/$1' conditions: labels: team: "platform" cache: "enabled" ``` ## 架构 该 webhook 包含： 1. **CRD (RegistryRewriteRule)**：使用正则表达式模式定义重写规则 2. **Mutating Webhook**：拦截 Pod 创建/更新并应用规则 3. **Rules Controller**：监视规则更改并更新缓存 4. **内存缓存**：提供 O(1) 的规则查找性能 ## 故障排除 ### 检查 webhook 是否正在运行： ``` kubectl get pods -n mutating-registry-webhook-system ``` ### 查看 webhook 日志： ``` kubectl logs -n mutating-registry-webhook-system deployment/mutating-registry-webhook-controller-manager ``` ### 使用示例 pod 进行测试： ``` kubectl run test --image=nginx:latest --dry-run=server -o yaml ``` ### 对特定 pod 禁用变更： 将注解 `rewrite-disabled: "true"` 添加到你的 pod 中： ``` metadata: annotations: rewrite-disabled: "true" ``` ## 性能 - 规则编译：在启动/规则更改时为 O(n) - 镜像变更：使用缓存规则时为 O(1) - 基准测试：每次镜像变更约 0.7μs - 内存使用：约 50MB 基础内存 + 规则占用 ## 贡献 我们欢迎您的贡献！详情请参阅我们的[贡献指南](CONTRIBUTING.md)。 **注意：** 运行 `make help` 以获取有关所有潜在 `make` 目标的更多信息 可以通过 [Kubebuilder 文档](https://book.kubebuilder.io/introduction.html)找到更多信息 ## 许可证 Copyright 2025 flemzord. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at ``` http://www.apache.org/licenses/LICENSE-2.0 ``` Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

标签：AWS, cert-manager, Docker Hub, DPI, ECR, EVTX分析, GCR, Go, Helm, k8s, Mutating Admission Webhook, Namespace, Pull-through Cache, Quay.io, Ruby工具, Webhook, Web截图, 企业镜像仓库, 力导向图, 子域名突变, 容器安全, 容器镜像, 提示注入, 日志审计, 标签选择器, 正则表达式重写, 流量拦截, 自定义请求头, 请求拦截, 资源调度, 运维工具, 镜像代理, 镜像缓存, 镜像重构, 集群管理