Pod-Resource-Mutator-轻量级K8s-Pod动态资源修改方案
一、项目背景
1.1 问题
在实际的 Kubernetes 集群运维中,经常遇到这样的场景:某些第三方平台或遗留系统在创建 Pod 时硬编码了不合理的资源 request/limit。
典型例子:CI/CD 平台的构建 Pod 固定 request memory=1Gi,但实际构建任务需要 4Gi 内存;数据处理平台按默认模板创建 Job Pod,request 远低于实际用量。这些不合理的 request 会导致 Kubernetes 调度器过度调度(scheduler 认为节点还有资源),最终触发 OOM 或节点级驱逐。
核心矛盾:不掌控上游系统的代码或配置,但需要在 Pod 落地时修正资源配置。
1.2 方案选型
| 方案 | 优点 | 不足 |
|---|---|---|
| Kyverno | CRD 策略模型成熟、match/exclude 结构完善 | 太重,引入整个策略引擎 |
| OPA/Gatekeeper | 模板与参数分离 | Rego 学习曲线陡峭 |
| LimitRanger | K8s 原生默认值 | 仅 namespace 粒度,无 label/annotation 匹配 |
| VPA Admission Controller | 容器级 resource patch 的参考实现 | 仅处理 resource,不够通用 |
| 自研 Mutating Webhook | 轻量、专注、可控 | 需要自行开发 |
最终选择自研,做一个 CRD 驱动的轻量级专用 Webhook,借鉴 Kyverno 的匹配模型,但只关注 Pod mutation,不做策略引擎。
二、架构设计
2.1 整体架构
graph TD
A[K8s API Server] -->|Pod CREATE| B[MutatingWebhookConfiguration
namespaceSelector 限定范围]
B -->|AdmissionReview| C[pod-resource-mutator
2 replicas, HA]
C --> D[HTTPS Server
TLS via Helm genCA/genSignedCert]
C --> E[Admission Handler → Rule Engine]
E --> E1["1. 从 informer cache 加载 PodMutationRule"]
E1 --> E2["2. 按 priority 排序,逐条匹配"]
E2 --> E3["3. 合并 JSON Patch"]
E3 --> E4["4. 返回 AdmissionResponse"]
C --> F[CRD Informer
watch PodMutationRule]
C --> G[Rule Status Updater
异步批量更新 matchCount]
C --> H[Metrics & Health
/metrics, /healthz, /readyz]2.2 请求处理流程
- K8s API Server 收到 Pod CREATE 请求
- 通过
namespaceSelector(podmutator.io/enabled: "true")筛选目标 namespace - 发送 AdmissionReview 到 webhook 的
/mutate端点 - Webhook 解码 Pod,检查 escape hatch label
- 加载所有 PodMutationRule,按 priority 升序排列
- 逐条执行:匹配 → 排除 → 变更 → 收集 patch
- 追加审计注解,返回合并后的 JSON Patch
- 异步通知 StatusUpdater 更新规则 matchCount
2.3 项目结构
pod-resource-mutator/
├── api/v1alpha1/ # CRD 类型定义
│ ├── types.go # PodMutationRule 完整类型
│ ├── groupversion_info.go # GVK 注册
│ └── zz_generated.deepcopy.go
├── internal/
│ ├── engine/ # 核心引擎
│ │ ├── matcher.go # 规则匹配
│ │ ├── mutator.go # Patch 生成
│ │ ├── engine.go # 编排(排序→匹配→变更→审计)
│ │ ├── template.go # 模板变量渲染
│ │ └── rulegetter.go # informer cache 适配器
│ ├── webhook/
│ │ └── handler.go # AdmissionReview 处理
│ ├── controller/
│ │ └── rule_status_updater.go # 异步批量状态更新
│ ├── audit/
│ │ └── audit.go # 结构化审计日志
│ └── metrics/
│ └── metrics.go # Prometheus 指标
├── cmd/main.go # 入口
├── chart/ # Helm chart(部署 webhook 本身)
├── instances/ # PodMutationRule CRD 实例(ArgoCD 同步)
├── Dockerfile
├── Makefile
└── go.mod
三、CRD 设计:PodMutationRule
3.1 完整示例
以下是一个典型场景:某 CI/CD 平台创建的构建 Pod 硬编码了 memory=1Gi,但实际需要 4Gi,同时希望将这类 Pod 调度到专用节点。
apiVersion: podmutator.io/v1alpha1
kind: PodMutationRule
metadata:
name: ci-builder-resource-fix
spec:
description: "将 CI 构建 Pod 的资源从默认值提升到实际所需"
match:
namespaces: ["ci-system"]
labelSelector:
matchLabels:
app.kubernetes.io/managed-by: "ci-platform"
matchExpressions:
- key: ci.example.com/builder-type
operator: In
values: ["docker", "kubernetes"]
annotations:
- key: "ci.example.com/pipeline-id"
operator: Exists
namePattern: "^build-.*$"
containers:
namePattern: "^builder$"
imagePattern: ".*ci-builder.*"
exclude:
labelSelector:
matchLabels:
podmutator.io/skip: "true"
priority: 10
mode: Enforce
mutations:
containers:
resources:
requests:
memory: "4Gi"
cpu: "1"
limits:
memory: "8Gi"
cpu: "4"
strategy: Replace
env:
- name: JAVA_TOOL_OPTIONS
value: "-XX:MaxRAMPercentage=75.0"
action: Upsert
pod:
annotations:
podmutator.io/mutated: "true"
podmutator.io/rule: "{{ .Rule.Name }}"
tolerations:
- key: "dedicated"
operator: "Equal"
value: "ci-builder"
effect: "NoSchedule"
action: Append
nodeSelector:
node-role.kubernetes.io/ci-builder: "true"
priorityClassName: "high-priority"
3.2 匹配规则
所有字段之间是 AND 关系,字段内多个值是 OR 关系:
| 字段 | 说明 |
|---|---|
namespaces | Pod 所在 namespace 必须在列表中 |
labelSelector | 标准 K8s LabelSelector(matchLabels + matchExpressions) |
annotations | 支持 Exists / DoesNotExist / Equals / Regex 四种操作符 |
namePattern | Pod 名称正则匹配 |
containers.namePattern | 容器名称正则(同时用于筛选变更目标容器) |
containers.imagePattern | 容器镜像正则 |
exclude 与 match 结构相同,匹配 exclude 的 Pod 即使满足 match 也会被跳过。
3.3 Resource 合并策略
| 策略 | 行为 | 场景 |
|---|---|---|
Replace | 无条件覆盖 | 上游硬编码值必须修正 |
Max | 取较大值 | 确保至少 4Gi,不降低已有 8Gi |
Min | 取较小值 | 限制资源上限 |
IfNotPresent | 仅在未设置时填入 | 设置默认值 |
3.4 模板变量
在 env.value 和 pod.annotations 中可以使用 Go 模板语法:
| 变量 | 说明 |
|---|---|
{{ .Pod.Name }} | Pod 名称 |
{{ .Pod.Namespace }} | Pod 所在 namespace |
{{ .Pod.Labels.xxx }} | Pod label 值 |
{{ .Pod.Annotations.xxx }} | Pod annotation 值 |
{{ .Rule.Name }} | 当前规则名称 |
不含 {{ 的字符串不会触发模板解析,零开销。
四、安全机制
| 机制 | 说明 |
|---|---|
| Escape Hatch | Pod 加 label podmutator.io/skip: "true" 跳过所有规则 |
| failurePolicy: Ignore | Webhook 挂了不阻塞 Pod 创建 |
| namespaceSelector | 仅拦截 podmutator.io/enabled: "true" 的 namespace |
| timeoutSeconds: 5 | 快速超时,避免影响 Pod 创建延迟 |
| DryRun 模式 | 规则级别,计算 patch 但不应用,只记日志和更新 status |
| 审计注解 | 被修改的 Pod 自动加 podmutator.io/mutated 和 podmutator.io/rules |
| Priority 排序 | 多规则按 priority 升序执行,低数字优先 |
五、可观测性
5.1 Prometheus 指标
| 指标 | 类型 | 标签 | 说明 |
|---|---|---|---|
podmutator_requests_total | Counter | namespace, rule, mode | 处理的 admission 请求总数 |
podmutator_request_duration_seconds | Histogram | namespace | 请求处理延迟 |
podmutator_rules_matched_total | Counter | rule, namespace | 各规则匹配次数 |
podmutator_patches_applied_total | Counter | rule, namespace | 各规则实际应用 patch 次数 |
5.2 结构化审计日志
使用 controller-runtime 内置的 zap logger,分三级输出:
| 级别 | 内容 |
|---|---|
| V(0) / Info | 变更已应用:Pod 名、namespace、匹配规则列表、patch 数量 |
| V(1) | 无操作决策:没有规则匹配、跳过原因 |
| V(2) | 逐条 patch 详情(op/path/value)、逐规则匹配结果 |
5.3 Rule Status
CRD status 子资源自动更新:
status:
matchCount: 1234 # 累计匹配 Pod 数
lastMatchTime: "..." # 最近匹配时间
通过异步批量更新器实现,每 10 秒 flush 一次到 API Server,避免频繁写入。
六、技术选型
| 组件 | 选择 | 理由 |
|---|---|---|
| 语言 | Go 1.22+ | K8s 生态原生 |
| 框架 | controller-runtime | CRD 脚手架、informer、webhook server 内置 |
| JSON Patch | gomodules.xyz/jsonpatch/v2 | controller-runtime 原生使用 |
| 日志 | zap(controller-runtime 内置) | 结构化、高性能 |
| 指标 | prometheus/client_golang | K8s 生态标准 |
| 证书 | Helm 内置 genCA/genSignedCert | 零依赖,install 时自动生成自签名证书 |
| 部署 | Helm chart | 标准 K8s 部署方式 |
| 镜像 | alpine | 轻量运行时 |
七、部署方式
7.1 Helm 部署
# 部署 webhook
helm upgrade --install pod-resource-mutator chart/ \
--namespace podmutator-system \
--create-namespace
# 启用目标 namespace
kubectl label namespace ci-system podmutator.io/enabled=true
# 应用规则
kubectl apply -f instances/ci-builder-resource-fix.yaml
7.2 ArgoCD 集成
instances/ 目录可直接作为 ArgoCD Application 的 source,实现规则的 GitOps 管理:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: podmutator-rules
spec:
source:
repoURL: <repo-url>
path: instances
destination:
server: https://kubernetes.default.svc
7.3 关键 values 配置
replicaCount: 2 # HA 部署
webhook:
failurePolicy: Ignore # webhook 故障不阻塞
timeoutSeconds: 5
namespaceSelector:
matchLabels:
podmutator.io/enabled: "true"
tls:
regenerate: false # upgrade 时复用已有证书,设为 true 强制重新生成
八、验证
# 检查规则状态
kubectl get podmutationrules
# NAME MODE PRIORITY MATCHES AGE
# ci-builder-resource-fix Enforce 10 0 5s
# 创建测试 Pod 后,检查资源
kubectl get pod <new-pod> -n ci-system -o jsonpath='{.spec.containers[0].resources}'
# {"limits":{"cpu":"4","memory":"8Gi"},"requests":{"cpu":"1","memory":"4Gi"}}
# 检查审计注解
kubectl get pod <new-pod> -n ci-system -o jsonpath='{.metadata.annotations.podmutator\.io/mutated}'
# true
# 检查规则匹配计数
kubectl get podmutationrule ci-builder-resource-fix -o jsonpath='{.status.matchCount}'
# 1
九、测试覆盖
项目包含 46 个单元测试,覆盖:
| 测试文件 | 用例数 | 覆盖范围 |
|---|---|---|
matcher_test.go | 12 | namespace/label/annotation/name/container 匹配 + exclude |
mutator_test.go | 17 | 4 种 resource 策略、env、annotation、toleration、nodeSelector、container 过滤 |
engine_test.go | 8 | skip label、priority 排序、DryRun、审计注解 |
template_test.go | 9 | 模板渲染、缺失字段、语法错误 |
go test ./... -v
# PASS - 46/46 tests