《Kubernetes 分布式系统原理深入解析》6.1 workqueue:去重、重试与退避

控制器收到的事件不能直接当命令执行:它们只是『这个 key 需要看一眼』的信号,且同一个 key 可能瞬间来多次事件。workqueue 负责把事件信号转化成可重试、可去重、有限速的工作队列。本节拆解 workqueue 的四个核心语义:去重、延迟入队、指数退避重试与放弃阈值,并对照 client-go 的真实实现。lab 用 workqueue/workqueue.go 验证去重、退避序列与重试上限。

6.1 workqueue:去重、重试与退避

第 3 章讲过 informer 用 DeltaFIFO 把事件变成「待处理队列」。但控制器真正干活前还有一个队列:workqueue。本节拆解它的四个核心语义——去重、延迟、退避、放弃——以及它们为什么是控制器正确性的地基。

事件不是命令,是「需要看一眼」的信号

控制器收到 informer 的事件时,直接反应是「对 key 执行 reconcile」。但直接执行有三个问题:

  1. 同一 key 可能瞬间来多次事件(一次滚动更新产生几十个变更)。每次都 reconcile 是浪费。
  2. reconcile 可能失败(暂时性故障、依赖未就绪)。失败必须能重试。
  3. 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 清零重试计数(成功处理或最终放弃时调用)。

两个语义要点:

  1. 重试计数是 per-key 的:不同 key 各自累计,一个失败 10 次不影响另一个新 key 的首次尝试。
  2. 放弃是控制器的选择: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 判断放弃——「重试有上限」的验证。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图