BKCI-Builder-Mutator-面向蓝盾构建的K8s-Pod动态资源修改方案

一、项目背景

1.1 问题

蓝盾 (BK-CI) 在代码层面硬编码了构建 Pod 的资源 request(如 memory=1Gi),但实际构建任务使用约 4Gi 内存。当节点资源不足时,Kubernetes 根据 request 值判断 Pod 资源占用,导致过度调度,最终触发 OOM 或节点驱逐。

核心矛盾:无法修改蓝盾源码,但必须在 Pod 创建时修正资源配置。

1.2 解决方案:BKCI Builder Mutator

通过 Kubernetes Mutating Admission Webhook,在 Pod 创建时自动修正资源配置:

二、架构设计

2.1 整体架构

graph TD
    A[K8s API Server] -->|Pod CREATE| B[MutatingWebhookConfiguration
namespaceSelector 限定范围] B -->|AdmissionReview| C[bkci-builder-mutator
2 replicas, HA] C --> D[HTTPS Server
TLS via Helm genCA/genSignedCert] C --> E[Admission Handler → Rule Engine] E --> E1["1. 从 informer cache 加载 BKCIBuilderMutationRule"] E1 --> E2["2. 逐条匹配
(namespace + PipelineRef via MySQL Resolver)"] E2 --> E3["3. 生成 JSON Patch(资源 + annotations)"] E3 --> E4["4. 返回 AdmissionResponse"] C --> F[CRD Informer
watch BKCIBuilderMutationRule] C --> G[MySQL Resolver
查询 BK-CI 构建表, TTL 缓存 + stale fallback] C --> H[Metrics & Health
/metrics, /healthz, /readyz]

2.2 请求处理流程

  1. K8s API Server 收到 Pod CREATE 请求
  2. 通过 namespaceSelector(bkcimutator.io/enabled: "true")筛选目标 namespace
  3. 发送 AdmissionReview 到 webhook 的 /mutate 端点
  4. Webhook 解码 Pod
  5. 加载所有 BKCIBuilderMutationRule
  6. 逐条执行:
    • namespace 检查 — Pod 所在 namespace 是否在规则的 namespaces 列表中
    • PipelineRef 匹配 — 从 Pod 的 generateName 提取 buildID → MySQL 查询 T_DISPATCH_PIPELINE_BUILD → 获取 (projectID, pipelineID) → 前缀匹配
    • 生成 patch — 资源覆盖(第一个容器)+ annotations 合并
  7. 追加审计注解(bkcimutator.io/mutated、bkcimutator.io/rules)
  8. 返回合并后的 JSON Patch

2.3 MySQL Resolver 设计

Resolver 将 BK-CI 的构建身份信息注入到 K8s admission 链路中,是实现 PipelineRef 匹配的核心组件。

graph TD
    A["Pod generateName: build1788228447005-yrhnwqco-"] --> B["extractBuildID()"]
    B --> C["buildID: 1788228447005"]
    C --> D{cache hit?
TTL 5m} D -->|hit| E["return cached
(project, pipeline)"] D -->|miss| F["MySQL query:
SELECT project_id, pipeline_id
FROM T_DISPATCH_PIPELINE_BUILD
WHERE build_id = ?"] F -->|success| G["update cache
return result"] F -->|fail| H{stale cache?} H -->|yes| I["return stale"] H -->|no| J["return empty
fail-open"]

关键设计决策:

设计 说明
TTL 缓存 默认 5 分钟,避免重复查询同一 buildID
Stale fallback MySQL 不可用时,30 分钟内的过期缓存仍可使用
Fail-open 查询失败且无缓存时,返回不匹配,Pod 正常创建不受影响
连接池 maxOpen=5, maxIdle=2, connMaxLifetime=5m
可选部署 BKCI_MYSQL_HOST 未设置时跳过 MySQL,仅 namespace 匹配生效

2.4 项目结构

bkci-builder-mutator/
├── api/v1alpha1/               # CRD 类型定义
│   ├── types.go                # BKCIBuilderMutationRule 类型
│   ├── groupversion_info.go    # GVK 注册 (bkcimutator.io/v1alpha1)
│   └── zz_generated.deepcopy.go
├── internal/
│   ├── engine/                 # 核心引擎
│   │   ├── matcher.go          # namespace + PipelineRef 匹配
│   │   ├── mutator.go          # 资源 + annotations patch 生成
│   │   ├── engine.go           # 编排(匹配→变更→审计)
│   │   ├── template.go         # 模板变量渲染
│   │   └── rulegetter.go       # informer cache 适配器
│   ├── bkci/
│   │   ├── resolver.go         # MySQL 流水线解析器
│   │   └── resolver_test.go
│   ├── webhook/
│   │   └── handler.go          # AdmissionReview 处理
│   ├── audit/
│   │   └── audit.go            # 结构化审计日志
│   └── metrics/
│       └── metrics.go          # Prometheus 指标
├── cmd/main.go                 # 入口
├── chart/                      # Helm chart
├── instances/                  # CRD 实例(ArgoCD 同步)
├── Dockerfile
├── Makefile
└── go.mod

三、CRD 设计:BKCIBuilderMutationRule

3.1 完整示例

apiVersion: bkcimutator.io/v1alpha1
kind: BKCIBuilderMutationRule
metadata:
  name: gops-pipeline-memory-fix
spec:
  description: "将 gops 项目指定流水线的构建 Pod memory request 从 1Gi 提升到 4Gi"

  match:
    namespaces: ["blueking"]
    pipelineRef:
      projectID: "gops"
      pipelineID: "p-abcdef"       # 精确匹配

  mode: Enforce

  mutations:
    resources:
      requests:
        memory: "4Gi"
        cpu: "1"
      limits:
        memory: "8Gi"
        cpu: "4"
      strategy: Replace
    annotations:
      bkcimutator.io/mutated: "true"
      bkcimutator.io/rule: "gops-pipeline-memory-fix"

3.2 匹配规则

所有字段之间是 AND 关系:

字段 说明
namespaces Pod 所在 namespace 必须在列表中(OR 语义)
pipelineRef.projectID 精确匹配 BK-CI 项目 ID
pipelineRef.pipelineID 精确匹配 BK-CI 流水线 ID

3.3 Resource 合并策略

策略 行为 场景
Replace 无条件覆盖 蓝盾硬编码 1G 必须改 4G
Max 取较大值 确保至少 4Gi,不降低已有 8Gi

3.4 模板变量

在 annotations 值中可以使用 Go 模板语法:

变量 说明
{{ .Pod.Name }} Pod 名称
{{ .Pod.Namespace }} Pod 所在 namespace
{{ .Pod.Labels.xxx }} Pod label 值
{{ .Pod.Annotations.xxx }} Pod annotation 值
{{ .Rule.Name }} 当前规则名称

四、安全机制

机制 说明
failurePolicy: Ignore Webhook 挂了不阻塞 Pod 创建
namespaceSelector 仅拦截 bkcimutator.io/enabled: "true" 的 namespace
timeoutSeconds: 5 快速超时,避免影响 Pod 创建延迟
DryRun 模式 规则级别,计算 patch 但不应用,只记日志
审计注解 被修改的 Pod 自动加 bkcimutator.io/mutated 和 bkcimutator.io/rules
Resolver fail-open MySQL 查询失败时跳过规则,不阻塞 Pod 创建
Resolver 可选 BKCI_MYSQL_HOST 未设置时正常启动,PipelineRef 规则不生效

五、可观测性

5.1 Prometheus 指标

指标 类型 标签 说明
bkcimutator_requests_total Counter namespace, rule, mode 处理的 admission 请求总数
bkcimutator_request_duration_seconds Histogram namespace 请求处理延迟
bkcimutator_rules_matched_total Counter rule, namespace 各规则匹配次数
bkcimutator_patches_applied_total Counter rule, namespace 各规则实际应用 patch 次数

5.2 结构化审计日志

使用 controller-runtime 内置的 zap logger,分三级输出:

级别 内容
V(0) / Info 变更已应用:Pod 名、namespace、匹配规则列表、patch 数量
V(1) 无操作决策:没有规则匹配、使用 stale 缓存、跳过原因
V(2) 逐条 patch 详情(op/path/value)、逐规则匹配结果

六、技术选型

组件 选择 理由
语言 Go 1.22+ K8s 生态原生
框架 controller-runtime CRD 脚手架、informer、webhook server 内置
JSON Patch gomodules.xyz/jsonpatch/v2 controller-runtime 原生使用
MySQL 驱动 go-sql-driver/mysql Go 生态标准 MySQL 驱动
日志 zap(controller-runtime 内置) 结构化、高性能
指标 prometheus/client_golang K8s 生态标准
证书 Helm 内置 genCA/genSignedCert 零依赖,install 时自动生成自签名证书
部署 Helm chart 标准 K8s 部署方式

七、部署方式

7.1 Helm 部署

# 部署 webhook
helm upgrade --install bkci-builder-mutator chart/ \
  --namespace bkcimutator-system \
  --create-namespace \
  --set bkci.mysql.host=mysql.bkci.svc \
  --set bkci.mysql.password=xxx \
  --set bkci.mysql.database=devops_ci_dispatch

# 启用目标 namespace
kubectl label namespace blueking bkcimutator.io/enabled=true

# 应用规则
kubectl apply -f instances/gops-pipeline-memory-fix.yaml

7.2 无 MySQL 部署(仅 namespace 匹配)

适用于不需要 PipelineRef 功能的场景,或测试环境:

helm upgrade --install bkci-builder-mutator chart/ \
  --namespace bkcimutator-system \
  --create-namespace \
  --set bkci.mysql.host=""

7.3 关键 values 配置

replicaCount: 2                    # HA 部署
webhook:
  failurePolicy: Ignore            # webhook 故障不阻塞
  timeoutSeconds: 5
  namespaceSelector:
    matchLabels:
      bkcimutator.io/enabled: "true"
bkci:
  mysql:
    host: "mysql.bkci.svc"        # 留空则跳过 MySQL
    port: "3306"
    user: "root"
    password: ""
    database: "devops_ci_dispatch"
  cache:
    ttl: "5m"                      # 缓存 TTL
    staleLimit: "30m"              # stale fallback 上限
tls:
  regenerate: false                # upgrade 时复用已有证书

八、验证

# 检查规则
kubectl get bkcibuildermutationrules
# NAME                        MODE      AGE
# gops-pipeline-memory-fix    Enforce   5s

# 蓝盾构建触发后,检查新 Pod 资源
kubectl get pod <new-pod> -n blueking -o jsonpath='{.spec.containers[0].resources}'
# {"requests":{"cpu":"1","memory":"4Gi"},"limits":{"cpu":"4","memory":"8Gi"}}

# 检查审计注解
kubectl get pod <new-pod> -n blueking -o jsonpath='{.metadata.annotations.bkcimutator\.io/mutated}'
# true

九、测试覆盖

项目包含 27 个单元测试:

测试文件 用例数 覆盖范围
engine_test.go 6 无规则、命中、DryRun、审计注解、resolver 集成
matcher_test.go 7 namespace 匹配、PipelineRef 匹配/不匹配、nil resolver、空结果
mutator_test.go 7 Replace/Max 策略、nil map 处理、annotations、JSON Pointer 转义、仅首容器
template_test.go 9 模板渲染、缺失字段、语法错误
resolver_test.go 8 buildID 提取(正常/异常/边界)
go test ./... -v
# PASS - 27/27 tests