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 创建时自动修正资源配置:
- 匹配方式:namespace + PipelineRef(通过 MySQL 解析 BK-CI 构建表)
- 变更范围:仅第一个容器资源 + annotations(蓝盾构建 Pod 的核心需求)
- 策略:Replace(无条件覆盖)/ Max(取较大值)
二、架构设计
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 请求处理流程
- K8s API Server 收到 Pod CREATE 请求
- 通过
namespaceSelector(bkcimutator.io/enabled: "true")筛选目标 namespace - 发送 AdmissionReview 到 webhook 的
/mutate端点 - Webhook 解码 Pod
- 加载所有 BKCIBuilderMutationRule
- 逐条执行:
- namespace 检查 — Pod 所在 namespace 是否在规则的 namespaces 列表中
- PipelineRef 匹配 — 从 Pod 的
generateName提取 buildID → MySQL 查询T_DISPATCH_PIPELINE_BUILD→ 获取 (projectID, pipelineID) → 前缀匹配 - 生成 patch — 资源覆盖(第一个容器)+ annotations 合并
- 追加审计注解(
bkcimutator.io/mutated、bkcimutator.io/rules) - 返回合并后的 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