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 请求处理流程

  1. K8s API Server 收到 Pod CREATE 请求
  2. 通过 namespaceSelector(podmutator.io/enabled: "true")筛选目标 namespace
  3. 发送 AdmissionReview 到 webhook 的 /mutate 端点
  4. Webhook 解码 Pod,检查 escape hatch label
  5. 加载所有 PodMutationRule,按 priority 升序排列
  6. 逐条执行:匹配 → 排除 → 变更 → 收集 patch
  7. 追加审计注解,返回合并后的 JSON Patch
  8. 异步通知 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