改了 ConfigMap 却不生效：K8s 配置热加载的三种姿势、延迟窗口与一次 4 小时排查

结论先行：kubectl edit configmap 之后 Pod 里读到的还是旧值，这不是 bug，而是 K8s 的设计——配置「更新」和「Pod 感知到更新」之间隔着两层机制，且它们的生效条件完全不同。这篇文章把 ConfigMap/Secret 生效的三条路径讲清楚，给一份我能直接抄的「热加载」落地方案，以及一个反直觉的点：环境变量注入的 ConfigMap 永远不会自动更新，只有 volume 挂载的文件才有（带延迟的）自动同步。

一、现象与背景：一次改了配置、4 小时没人敢重启的排查

先交代规模。一个 30 节点（8C16G，Kubernetes 1.29.3，containerd 1.7.13）的集群，跑着一个 40 副本的 Java 服务，其中一批关键开关（限流阈值、下游超时）放在 ConfigMap 里，通过环境变量 envFrom 注入。

上周一次线上限流阈值调整：我们把 ConfigMap 里的 rate.limit 从 800 改成 1500，kubectl apply 成功、kubectl get cm 立刻看到新值 1500。但服务行为一点没变，压测打上去还是按 800 限流，直接误伤了真实流量。

排查花了约 4 小时，期间最大的坑是：所有人都盯着「为什么 ConfigMap 没更新」，反复 get cm、describe pod，结果 ConfigMap 一直是 1500，Pod 一直 Running——没有任何报错。因为问题根本不在「更新失败」，而在「Pod 压根不会自动感知」。

最终定位：这个服务是用 envFrom.configMapRef 注入配置的，而这种注入方式的值在容器启动那一刻就被固化成环境变量了，之后 ConfigMap 怎么改，容器里的环境变量都不会变。要让它生效，唯一的办法是重启 Pod（让容器重新读一遍环境变量）。

二、原理：ConfigMap 生效的三条路径，规则各不相同

把「ConfigMap 怎么进容器」拆开，K8s 实际上给了三条路径，它们的自动更新行为完全不同，这是所有混乱的根源：

路径 A：环境变量注入（env / envFrom）——永不自动更新。 容器启动时，kubelet 把 ConfigMap 的值展开成环境变量传进容器。进程一旦启动，环境变量就写死在进程环境里了。ConfigMap 后续怎么改，已经运行的容器都感知不到。这是 K8s 文档明确写死的：「Changes to ConfigMaps are not propagated to the environment variables of existing Pods。」

路径 B：volume 挂载成文件（volumes + configMap）——会延迟自动更新。 这是唯一「改了就生效」的姿势。kubelet 通过 watch API 监听 ConfigMap 变更，变更后更新挂载进容器的文件。但有两个关键细节：

1. 有同步延迟，不是实时的。kubelet 的同步周期由 --sync-frequency（默认 1min）驱动，实际生效通常在变更后 1~60 秒之间，不保证上限，且和节点负载、watch 队列有关。
2. 容器里看到的文件路径是 kubelet 维护的代理文件（symlink），不是直接挂到容器镜像里的。你 kubectl exec 进去 cat 到的，是 kubelet 已经同步过来的版本——这让你误以为「它已经生效了」，但如果你的应用只在启动时读一次文件、之后不再读，那它用的还是旧值。

路径 C：Secret 挂载——和路径 B 一样，且延迟更大。 Secret 的同步周期默认和 ConfigMap 一致，但历史版本里 Secret 的 --sync-frequency 有时被单独配置得更长，且 Secret 的变更通知链路更长，实际观察到延迟能到 60~120 秒。更坑的是：Secret 通过 env 注入时（路径 A 的规则）同样永不自动更新，只有 volume 挂载才走路径 B。

一句话总结：「是不是 volume 挂载」决定能不能自动更新，「应用是不是持续读文件」决定更新后你拿不拿得到，「kubelet 同步延迟」决定多久能拿到。

三、具体做法：让配置「改了就用」的可复现方案

核心原则：配置走 volume 文件挂载 + 应用侧做文件监听热加载 + 监控里加一个「配置版本」探针。别用 envFrom 承载「会变的开关」。

1) 部署侧：把会变的配置从 env 挪到 volume

spec:
  containers:
  - name: app
    env:
    # 只放「启动后不会变」的固定值（镜像、时区、服务名）
    - name: TZ
      value: Asia/Shanghai
    volumeMounts:
    - name: cfg
      mountPath: /etc/app/config
      readOnly: true
  volumes:
  - name: cfg
    configMap:
      name: app-config
      items:                 # 只挂需要的 key，别整包挂
      - key: rate.limit
        path: rate.limit
      - key: downstream.timeout
        path: downstream.timeout

2) 应用侧（Java）：监听文件变更，别只读一次

用 watch 或轮询都行，给一个最小可复现的轮询实现（Spring 里用 @Scheduled）：

@Scheduled(fixedDelay = 5000)   // 每 5s 主动重读一次文件，兜底 kubelet 同步延迟
public void reloadConfig() throws IOException {
    String newLimit = Files.readString(Path.of("/etc/app/config/rate.limit")).trim();
    long v = Long.parseLong(newLimit);
    if (v != currentRateLimit.get()) {
        currentRateLimit.set(v);
        log.info("rate.limit reloaded: {} -> {}", currentRateLimit.get(), v);
    }
}

这里 fixedDelay=5000 是故意设得比 kubelet 的 1~60s 同步窗口短，让「应用轮询周期」成为生效上限的主导项，而不是被动等 kubelet。

3) 观测侧：把「当前生效的配置版本」暴露成指标

这是排查 4 小时那次事故后我们补的最重要的一环——让「Pod 实际在用的配置」可被观测：

// 暴露 /metrics，Grafana 直接看板
gauge("app_rate_limit_active", currentRateLimit::get);
gauge("app_config_mtime_epoch", () -> Files.getLastModifiedTime(path).toMillis()/1000);

有了这两个指标，「ConfigMap 是 1500」和「Pod 实际在跑 800」之间的 gap，在 Grafana 上一眼就能看出来，不用再靠压测反推。

落地后我们观察到：改一次 rate.limit，从 kubectl apply 到 Grafana 上 app_rate_limit_active 指标翻到 1500，稳定在 5~10 秒（5s 轮询主导），彻底告别「改了不知道生没生效」的盲猜。

四、踩过的坑与反直觉之处

1. envFrom 注入的 ConfigMap 永不自动更新——这是最多人踩的坑。K8s 文档白纸黑字写了，但绝大多数人还是把「会变的开关」塞进 env，然后以为「改 ConfigMap 就生效了」。
2. volume 挂载会更新，但你的应用不一定能拿到。如果应用只在 main() 里 readFile 一次，之后再也不读，那文件更新了也白搭——「文件在变」≠「进程在用新值」，这俩是两件事。
3. kubectl exec 里 cat 到的是 kubelet 已同步的文件，不是容器镜像里的。这会让你误判「已经生效了」。判断应用是否真用了新值，要看应用侧的日志/指标，而不是 cat。
4. Secret 的同步延迟通常比 ConfigMap 长，且 Secret 走 env 注入时同样永不更新。把「会变的密钥」塞进 Secret 的 env 里，是热加载陷阱的加强版。
5. --sync-frequency 默认 1min 是个隐藏上限。高要求场景下可以调小（比如 30s），但调得太小会放大 watch 风暴，30~60s 是常见的折中。
6. 整包挂载（不写 items）会让无关的 key 变更也触发文件更新，放大不必要的 I/O 和监听噪音。只挂你真正需要的那几个 key。

五、结论与可复用清单

「改了 ConfigMap 不生效」90% 是注入方式选错了（用了 env）或应用没做热加载，而不是 K8s 出问题。可复用清单：

• [ ] 会变的配置走 volume 文件挂载，别走 env/envFrom——这是第一优先级；
• [ ] 应用侧做文件轮询/监听热加载，轮询周期（5~10s）设得比 kubelet 同步窗口短，让应用主导生效上限；
• [ ] 把「当前生效的配置值 + 文件 mtime」暴露成 Prometheus 指标，让「ConfigMap 值」和「Pod 实际在用的值」可被直接对比；
• [ ] 判断是否生效，看应用侧指标/日志，不要 kubectl exec cat（你看到的是 kubelet 已同步的文件，不代表进程在用）；
• [ ] items 只挂需要的 key，别整包挂；
• [ ] Secret 同理：env 注入永不更新，volume 挂载才有延迟同步，且延迟通常更长。

这套做法我们在 3 个服务上落地后，「改配置不生效」类的工单基本清零——不是因为 K8s 变聪明了，而是因为我们终于不再用 env 承载会变的开关，并且让 Pod 实际在用的配置值变成了可观测的指标。