发布显示「成功」但 3 台节点的 Pod 仍跑着旧二进制：imagePullPolicy=IfNotPresent 撞上可变 tag 的幽灵镜像复盘

结论先行

K8s 里有一类事故，kubectl rollout status 一路绿灯、kubectl get pods 全 Running、监控指标也正常，但同一份 Deployment 在不同节点上跑的根本不是同一个二进制。根因几乎都是 imagePullPolicy: IfNotPresent 叠加了可变 tag（latest、build-137 被复用、或 CI 把新包盖到旧 tag）——节点本地已有同 tag 镜像，kubelet 就不再拉取，直接复用旧层。发布「成功」了，成功的定义只是「Pod 起来了」，不是「跑的是新代码」。

一、现象：同一次发布，13 台节点里 3 台是旧版本

上周我们对一个 46 节点（Kubernetes 1.29.3 + containerd 1.7.13，私有 Harbor）的订单服务做了一次常规发布。CI 流水线把新镜像推到 tag order-svc:release-20240517，kubectl rollout restart 后 rollout status 显示 successfully rolled out，耗时 41 秒，13 个副本全部 Ready。

但 20 分钟后客服反馈「只有部分用户的新功能入口没出现」。我们逐节点核对了容器里二进制的 git commit：

# 在 13 台节点上分别 exec 进去
kubectl exec -it <pod> -- /app/order-svc version

结果：10 台节点打印 commit a3f9c21（新），3 台节点打印 7be10d4（旧）。同一个 tag release-20240517，三台节点跑的是三天前的包。监控上看，这 3 个 Pod 的 CPU、QPS、错误率都完全正常——因为它们只是「旧代码跑得好好的」，新接口字段没暴露，业务侧只表现为「功能缺失」而非「报错」。这就是它难查的地方：没有任何一条监控在报警。

二、根因：IfNotPresent 的判定粒度是「节点本地有没有这个 tag」，不是「这个 tag 的内容变没变」

imagePullPolicy 三个取值的实际行为：

• Always：每次创建 Pod 都向 registry 请求 manifest，比对后决定是否拉取；
• IfNotPresent：先查本节点本地（containerd 的 image store）是否已存在同 name:tag 的镜像，存在就直接用，不向 registry 发起 manifest 校验；
• Never：绝不用远端，本地没有直接 ErrImageNeverPull。

关键点在 IfNotPresent 的判定单位是字符串 tag，不是内容 digest。我们的事故链条：

1. 三天前一次发布，CI 把旧包推到了 release-20240517（当时 tag 命名规则是「日期」，撞车了）；
2. 其中 3 台节点在那次发布时拉过这个 tag，本地 image store 里已缓存了 7be10d4 对应的层；
3. 本次发布复用了同一个 tag 字符串 release-20240517，CI 把新包 a3f9c21 盖到了这个 tag 上（digest 变了，但 tag 没变）；
4. rollout restart 让 13 个 Pod 重建，调度到那 3 台节点的 Pod 命中本地缓存 → IfNotPresent 判定「本地已有」→ 直接启动旧二进制；其余 10 台节点本地没有这个 tag，走 Always 语义拉到了新包。

注意：imagePullPolicy: IfNotPresent 对非 latest 的具体 tag 其实默认也是 IfNotPresent（只有 :latest 或无 tag 才是默认 Always）。所以「我明明用了具体 tag，应该每次都拉」这个直觉是错的。

三、定位与验证（可复现）

1) 比对每个 Pod 实际镜像的 digest，而不是看 tag：

# 每个 Pod 真实拉到的 digest（来自 containerd，而非 spec 里的 tag）
kubectl get pods -n order -o json \
 | jq -r '.items[] | select(.spec.containers[0].name=="order-svc") |
    .metadata.name + "  " + (.status.containerStatuses[] | select(.name=="order-svc").imageID)'

输出里如果同一个 image（tag）对应两个不同 imageID（sha256 digest），就是实锤——同一个 tag 在集群里指向了不同内容。

2) 确认本地缓存命中：

# 在那 3 台「旧版本」节点上
crictl images | grep order-svc        # 看本地是否存在该 tag
crictl inspecti order-svc:release-20240517 | jq '.image.repoDigests'  # 对比 digest

3) 查 kubelet 是否发起过拉取（IfNotPresent 命中缓存时这条日志根本不会出现）：

journalctl -u kubelet | grep -i "pulling image order-svc:release-20240517"

四、修复与防复发

临时止血（让那 3 台节点强制拉新包）：

# 方案 A：清掉本地缓存再 restart（最稳）
crictl rmi order-svc:release-20240517
kubectl rollout restart deployment/order-svc -n order

根治（三选一，我们组合用了 A + C）：

• A. 可变 tag 一律 Always：对任何「会被复用/覆盖」的 tag 显式写 imagePullPolicy: Always。代价是每次创建 Pod 多一次 manifest 请求（我们实测 46 节点规模下，单次 rollout 额外增加约 1.2s，可忽略）。
• B. 改 tag 规则，让「内容变 → tag 必变」：CI 改用 release-20240517-a3f9c21（tag 里带 commit 短 hash），或干脆用 @sha256:<digest> 固定。这样即使 IfNotPresent 命中缓存，命中的也是「正确的内容」。
• C. 用 digest 发布：CI 推送后回写 pod.spec.containers[].image 为 registry/...@sha256:...，imagePullPolicy: Always + digest 是「内容寻址」，从根上消灭「tag 撞车」。

五、踩过的坑（反直觉处）

1. rollout status 的「成功」不含「版本正确」——它只确认 Pod 达到 Ready，不校验二进制内容。发布后一定要有一道「版本指纹核对」（比如 /version 接口或镜像 digest 比对）门禁。
2. 「用了具体 tag 就会每次拉」是错的。只有 latest/无 tag 默认 Always，具体 tag 默认 IfNotPresent。
3. Always 也不是万能的：它只保证「向 registry 要 manifest 并比对」，如果 Harbor 那边 tag 指向的 digest 本身就是旧的（仓库缓存/同步延迟），Always 也会拉到旧包。所以内容寻址（digest 发布）才是终局。
4. 监控盲区：这类事故 CPU/内存/错误率全绿，靠现有 SLO 监控 100% 发现不了。必须在发布流水线里加一步「N 个副本的版本指纹一致性校验」，不一致直接 fail。

六、结论与可复用清单

• [ ] 发布前确认 tag 命名规则：内容变则 tag 必变，杜绝 tag 复用/覆盖；
• [ ] 对可变 tag 显式 imagePullPolicy: Always，对关键服务直接上 @sha256 digest 发布；
• [ ] CI 流水线加门禁：rollout 后抓取所有副本的 imageID（digest），集合去重后必须 = 1，否则发布判失败；
• [ ] 排障口诀：「同 tag 不同 digest = 本地缓存命中旧包」，先 crictl images 看本地、再 journalctl 看 kubelet 有没有 pulling；
• [ ] 发布「成功」的定义里，加上「版本指纹一致」这一项，而不是只看 Ready。

一句话记住：IfNotPresent 比的是 tag 字符串，你比的是二进制内容，两者错位的那一刻，幽灵镜像就诞生了。