imicola的猫咖

一个 bug 剖析：429 洪泛与 Watch 事件风暴#

1
return ctrl.Result{RequeueAfter: 120 * time.Second}, nil

1
ctrl.NewControllerManagedBy(mgr).For(&MaintenancePlan{}).Complete(r)

sequenceDiagram
    participant R as Reconciler
    participant API as API Server
    participant W as Watch 模块
    participant Q as 工作队列

    R->>API: EvictPod（驱逐请求）
    API-->>R: 429 Too Many Requests（建议 120s 后重试）
    R->>API: Status.Update（reason: pdb-budget-exhausted）
    API--)W: 广播 Update 事件
    R->>Q: 返回 RequeueAfter: 120s（登记定时闹钟）
    W->>Q: 立刻塞入同一 Key（立即就绪！）
    Q->>R: 秒级派发下一轮 Reconcile
    R->>API: 再次 EvictPod（429 洪泛！）

1
NextActionAt = CurrentTime + Delay

1
// 先走全面的事实判断！
2
d := DecideDrain(plan, &f, now)
3

4
// 只有当业务决策明确要求「发起一次新驱逐动作 (ActionEvict)」时，冷却门才生效！
5
if d.Action == ActionEvict {
6
    next := plan.Status.EvictionProgress.NextActionAt
7
    if next != nil && now.Before(next.Time) {
8
        // 门只拦住「鲁莽的新动作」，绝不拦住「对已发生事实的汇报」
9
        return ctrl.Result{
10
            RequeueAfter: next.Time.Sub(now),
11
        }, nil
12
    }
13
    return r.evictOne(ctx, l, plan, d)
14
}

三个时间#

在整个疏散流程中，代码里出现了三个和时间相关的机制，它们各自回答不同的问题。流程如下：

三个时间概念如下：

• 单次调用超时：evictCallTimeout = 10s 与 context.WithTimeout
  • 表示这一次向 API Server 发送的 HTTP 请求最多等待多久必须返回
  • 超时后会释放本地底层 HTTP 连接与 Goroutine 资源
  • 超时返回只代表客户端放弃等待，不能反推服务端没有执行
• 整轮总截止：spec.drainTimeoutSeconds / status.evictionProgress.Deadline
  • 表示一整轮维护任务，从开始算起最多允许任务推进到什么时刻
  • 一旦 now.After(deadline)，决策层立刻将状态推入 Blocked/deadline-exceeded，停止一切驱逐动作
• 动作冷却时刻：status.evictionProgress.NextActionAt
  • 表示下一次最早允许向 API Server 尝试发出新驱逐调用的绝对时刻是几点几分
  • 阻止过密调用与 429 洪泛。属于动态推进的冷却门，被拒绝则向后推移，未达到该时刻只等待、不发包

从 Go 结构体到 etcd 持久化#

在真实的 k8s 体系中，一个字段要真正安全地落入 etcd 并且在重启后能被准确读出，必须经历下述环节：

flowchart LR
    Go["Go 结构体"] -->|"JSON Tag"| Ser["Scheme 序列化"]
    Ser -->|"HTTP POST"| Api["API Server<br/>Schema 校验与裁剪"]
    Api -->|"真正落盘"| Etcd[("etcd")]
    Etcd -->|"读取"| Cache["本地缓存 / etcd 读取"]
    Cache -->|"DeepCopy / 反序列化"| Restore["内存对象状态还原"]
    Restore -.->|"下一轮 Reconcile"| Go

这其中有几点需要注意：

• Go 字段与类型定义：必须使用指针类型 *metav1.Time。如果使用普通类型，零值会被序列化为一个无意义的时间戳；而指针类型的 nil 则可以表达「当前没有冷却约束 / 历史旧版本 CR 没有该字段」，从而实现向前兼容
• JSON Tag 契约：需要明确指定 json:"nextActionAt,omitempty"，以确保序列化时的字段大小写与 CRD 定义的完全一致
• CRD OpenAPI v3 Schema 声明：在 k8s/maintenance-crd.yaml 中必须明确加入 nextActionAt 的字段声明，如果遗漏则会被 API Server 静默丢弃
• 深拷贝与浅拷贝：在协调器比对状态变化的时候，不能简单使用 before := plan.Status。因为 Status 内部包含指针，浅拷贝会复制指针地址——后续修改了 NextActionAt 后，由于 before 中的指针指向同一个地址，它也会「跟着变成」新值
• 无变化不写（statusEqual）：在 writeDrainStatus 中，每次准备写 status 前都会比对 statusEqual(before, plan.Status)。只有当状态、原因或冷却时刻真正发生变化时才调用 API。这不仅是为了降低 API Server 的写入负载，更是为了防止无意义的 Update 再次激起前面分析过的 Watch 事件风暴

容器化#

说到底这还是一个集群项目，所以我们需要将整个模块构建成一个 container 才能部署进集群。

标准构建指令是：

1
docker build -f module/maintenance-controller/dockerfile.controller -t maintenance-controller:w45 module/maintenance-controller

其中 -f 指定的是构建规则文件的具体位置，最后的参数 module/maintenance-controller 是真正的构建上下文。在 Dockerfile 中写 COPY go.mod go.sum ./ 时，Docker 引擎是以这个上下文根目录为基准去寻找文件的，所以打构建命令的时候不能把上下文弄混了。

结语#

到这里，maintenance-controller 的项目笔记就整理完了。回头看，这个项目最有价值的部分不是「实现了一个排空节点的工具」，而是在实现过程中被迫去理解的那些 Kubernetes 的底层机制：Watch 与工作队列的交互语义、status 写回的副作用、PDB 裁决的非原子性、以及一个字段从 Go 结构体到 etcd 的完整生命周期。

如果你也在学习 Kubernetes controller 开发，欢迎看看 sentinel-go，也欢迎交流指正。