6.1 workqueue:去重、重试与退避
第 3 章讲过 informer 用 DeltaFIFO 把事件变成「待处理队列」。但控制器真正干活前还有一个队列:workqueue。本节拆解它的四个核心语义——去重、延迟、退避、放弃——以及它们为什么是控制器正确性的地基。
事件不是命令,是「需要看一眼」的信号
控制器收到 informer 的事件时,直接反应是「对 key 执行 reconcile」。但直接执行有三个问题:
- 同一 key 可能瞬间来多次事件(一次滚动更新产生几十个变更)。每次都 reconcile 是浪费。
- reconcile 可能失败(暂时性故障、依赖未就绪)。失败必须能重试。
- reconcile 可能很慢。事件涌入的速度远超处理速度,需要排队缓冲。
workqueue 的答案是:把事件翻译成「key 的入队」,reconcile 从队列取 key 执行。事件与执行之间隔着一个队列,三个问题都在队列上解决:
| 问题 | workqueue 的解法 |
|---|---|
| 重复事件 | 去重:同 key 未处理完前忽略再次入队 |
| 暂时性失败 | 重试:失败后按退避重新入队 |
| 速度不匹配 | 缓冲:队列吸收事件洪峰 |
这也是第 5 章「控制器不处理事件、只把 key 入队」的具体实现。
去重:同一 key 只入队一次
workqueue 的 Add 是这个语义的核心:
func (q *Queue) Add(key string) {
q.mu.Lock()
defer q.mu.Unlock()
if q.pending[key] {
return // 已排队且未处理完,忽略
}
q.pending[key] = true
q.queue = append(q.queue, key)
q.cond.Signal()
}
要点:pending 集合记录「队列中或正在处理的 key」。只要 key 还没 Done,再次 Add 就被忽略。
去重的工程意义:控制器正在处理 nginx(花了 2 秒),期间它又变了 3 次(3 个事件)。如果全部入队,控制器会连跑 4 次 reconcile;去重后只跑 1 次,且这次 reconcile 从最新现实出发——处理旧事件的重复劳动被省掉了。这与 3.2 节 DeltaFIFO 的去重合并是同一哲学,只是层次不同:DeltaFIFO 合并「缓存同步的增量」,workqueue 合并「reconcile 的触发信号」。
延迟入队:给现实时间消化
有些失败不能立刻重试,要等一会儿。workqueue 的 AddAfter 提供延迟入队:
func (q *Queue) AddAfter(key string, deadline time.Time) {
q.mu.Lock()
defer q.mu.Unlock()
if q.pending[key] {
return
}
q.delayed[key] = deadline
}
delayed 是一个 key → 到期时刻的映射。Get 时先把已到期的延迟项搬运进主队列:
for k, t := range q.delayed {
if !t.After(now) {
delete(q.delayed, k)
q.pending[k] = true
q.queue = append(q.queue, k)
}
}
延迟入队解决什么问题?第 3.3 节的缓存滞后:控制器写了一个对象,想让缓存有时间反映结果,再处理它的下一阶段。或者:依赖资源还没创建好,等它出现再试。「等一会儿再处理」是异步控制器的标准动作,不是投机取巧。
重试与退避:失败不是放弃
reconcile 失败的 key 通过 AddRateLimited 重新入队。它的语义是「按退避延迟,且累计重试次数」:
func (q *Queue) AddRateLimited(key string, retries int) {
q.mu.Lock()
if retries < 0 {
retries = q.attempts[key]
}
q.attempts[key] = retries + 1
q.mu.Unlock()
delay := ExponentialBackoff(q.attempts[key])
q.AddAfter(key, q.now().Add(delay))
}
退避时长由 ExponentialBackoff 计算:
func ExponentialBackoff(attempt int) time.Duration {
base := 10 * time.Millisecond
if attempt <= 1 {
return base
}
for i := 1; i < attempt; i++ {
base *= 2
if base >= 1000*time.Second {
base = 1000 * time.Second
break
}
}
return base
}
退避序列:10ms → 20ms → 40ms → 80ms → … → 封顶 1000s。指数增长 + 封顶,是分布式重试的标准形态。
退避的分布式意义(第 3.3 节 relist 退避、第 5.2 节节拍,同源):失败越频繁越要放慢,避免「重试风暴」把自己和 apiserver 都压垮。第 12 章 APF 限流讨论的也是同一个「系统内自我节流」原则。
放弃阈值:什么时候不再重试
重试不是无限的。NumRequeues 返回 key 的累计重试次数,控制器据此做放弃判定:
if q.NumRequeues(key) >= maxRetries {
// 放弃:记错误、清理资源、不再重试
q.Forget(key)
return
}
Forget 清零重试计数(成功处理或最终放弃时调用)。
两个语义要点:
- 重试计数是 per-key 的:不同 key 各自累计,一个失败 10 次不影响另一个新 key 的首次尝试。
- 放弃是控制器的选择:workqueue 只计数,不替控制器决定「多少次算太多」。真实控制器对不同类型的失败给不同的上限——暂时性失败(409、网络)可以多试,永久性失败(校验不过、资源不存在)尽早放弃。
workqueue 与 DeltaFIFO 的分工
两个队列常被混淆,职责完全不同:
| DeltaFIFO(informer 内) | workqueue(控制器内) | |
|---|---|---|
| 输入 | Reflector 的 list-watch 增量 | informer 的事件回调 |
| 内容 | 对象增量(含对象数据) | 只有 key(namespace/name) |
| 语义 | 缓存同步的增量合并 | reconcile 的触发信号 |
| 重试 | 不重试(relist 兜底) | 退避重试 + 放弃阈值 |
数据流:Reflector → DeltaFIFO → worker → 更新 Indexer + 把 key 放入 workqueue → reconcile 读 Indexer。两个队列一个管「缓存怎么同步」,一个管「reconcile 怎么调度」,配合完成「事件驱动 + 幂等重试」的完整链路。
三个常见误解
- 「workqueue 是消息队列」——错误。它是内存中的去重工作队列,没有持久化、没有订阅/发布,只服务单个控制器进程。
- 「失败就无限重试」——错误。退避封顶 + 放弃阈值,控制器会终止不可收敛的 key。
- 「每个事件必然触发一次 reconcile」——错误。去重让同一 key 在未处理完前的多次事件合并为一次处理。
本节 lab
本节验证 workqueue 的去重、延迟与退避核心语义:
cd private/labs/k8s-ctrl-lab
go test ./workqueue -run 'TestDedup|TestAddAfter|TestExponentialBackoff|TestAddRateLimited|TestRequeueLimit' -v
TestDedup:同一 key 连续 Add 三次,队列中只有一条;Done 后才可再次入队——「去重直到处理完」。TestAddAfter:延迟项在 deadline 前不出队,到期后进入主队列。TestExponentialBackoff:退避序列单调递增、封顶 1000s——重试的自我节流。TestAddRateLimited:失败重试按退避延迟重新入队,重试计数递增。TestRequeueLimit:控制器用 NumRequeues 判断放弃——「重试有上限」的验证。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。