CSI 驱动开启自动轮换要配什么？光设 requiresRepublish 没用，还得加这个参数
CSI 驱动开启自动轮换必须同时满足两个条件：CSIDriver 对象设置 requiresRepublish=true，且运行参数包含–enable-secret-rotation=true。
核心前提：为什么光有 CSIDriver 不够？
仅设置 CSIDriver 的 requiresRepublish 字段只是声明了能力，若缺少启动参数–enable-secret-rotation=true，驱动无法主动从外部源拉取新密钥。
Secrets Store CSI Driver 从 v1.6.0 版本起引入了 RequiresRepublish 机制，支持外部机密源的周期性更新。[1] 但这仅仅是一个“能力声明”，就像给车装上了导航系统，并不代表车子会自动开动起来。如果你只在 CRD 里设置 CSIDriver.requiresRepublish=true，却忽略了启动参数，驱动依然不会主动去拉取最新的密钥。
这就引出了大家最关心的问题：CSI 驱动开启自动轮换要配什么？ 答案很明确：必须同时满足“声明支持”和“开启功能”两个条件。如果缺少 --enable-secret-rotation 这个启动开关，即便集群知道该驱动具备重发布能力，它也不会执行实际的轮询动作。[1]
要确保配置无误，你需要核查以下四个关键点：
- CRD 对象检查：确认
spec.podInfoOnMount.requiresRepublish字段已设为true。 - 容器参数注入：DaemonSet 或 Deployment 的启动参数中必须包含
--enable-secret-rotation=true。 - 轮询间隔设置：配置合理的轮询周期，避免因更新滞后导致业务短暂不可用。
- 版本兼容性：确保驱动镜像版本在 v1.6.0 以上，旧版本根本不支持此逻辑。[1]
这里有个常见的误区：控制器层面的 resourceVersion 变了，并不代表应用进程已经感知到了新值。如果是文件挂载，应用需要自行侦测文件变化并重载；如果是环境变量，Pod 必须重启才能拿到新数据。这一步没做对，后续所有的轮换配置都只是在空转。[1]
实战避坑指南：很多团队在配置时容易忽略轮询周期的默认行为，导致“假死”。例如，某金融团队在测试环境将轮询间隔设为 30 秒，但在生产环境直接沿用，结果因网络抖动导致驱动频繁尝试连接外部 Vault 服务，触发了外部系统的限流熔断，反而让密钥更新彻底卡死。因此，在正式部署前，务必根据外部机密源（如 HashiCorp Vault、AWS Secrets Manager）的速率限制策略，手动调整 --rotation-poll-interval 参数，将其设置为外部 API 允许的最大频率之下，而不是盲目使用默认值。[1]
如何配置才能真开启自动轮换？两步到位指南
真正启用自动轮换需将 CRD 定义与容器启动参数完整配置，缺一不可，否则驱动不会执行周期性轮询更新。
很多团队在排查问题时发现，改完 CSIDriver 资源后，日志里依然没有轮询记录。原因通常在于只完成了第一步，漏掉了第二步。要真正跑通自动轮换，你必须把 CRD 定义和容器参数这两块拼完整。[1]
Step 1：修改 CSIDriver 资源定义
首先检查集群中是否存在对应的 CSIDriver 资源。如果没有，新建一个；如果有，直接编辑。核心操作是将 spec.requiresRepublish 字段显式设置为 true。这一步是告诉 Kubernetes 控制器：“嘿，这个驱动支持动态更新 Pod 的挂载内容。”这是启用后续所有自动化逻辑的基础门槛。[1]
”`yaml apiVersion: storage.k8s.io/v1 kind: CSIDriver metadata: name: secrets-store.csi.k8s.io spec: requiresRepublish: true 注意，这个字段自 v1.6.0 版本起才生效。如果你的驱动镜像还是老版本，即便加了配置也完全无效。务必先确认版本号，否则后续步骤全是徒劳。[1]
Step 2：调整 DaemonSet 启动参数
光有 CRD 配置还不够，驱动进程本身必须被“唤醒”。你需要找到部署驱动组件的 DaemonSet（或 Deployment），在容器的 args 列表中添加 --enable-secret-rotation=true 参数。[1]
很多故障案例都源于漏加这个参数，或者因为拼写错误、多余空格导致参数未被识别。请务必仔细核对 YAML 中的启动命令，确保参数完整且格式正确。
”`yaml containers:
name: secrets-store-csi-driver image: k8s-secrets-store-csi-driver:v1.6.0 args:
–enable-secret-rotation=true
其他原有参数…
缺少这一行，驱动就不知道要去轮询外部源获取新值。哪怕 CSIDriver 对象配置得再完美，轮换逻辑也不会触发。[1]
验证检查清单
配置完这两步后，别急着上线业务，先按以下清单逐项核对，确保万无一失：
- [ ] CRD 状态：执行
kubectl get csidriver，确认REQUIRESREPUBLISH列为true。 - [ ] 版本合规：确认驱动镜像版本 >= v1.6.0。
- [ ] 参数注入：查看 DaemonSet 详情，确认
--enable-secret-rotation=true存在于启动参数中。 - [ ] 日志确认：观察驱动 Pod 日志，搜索 “rotation” 或 “republish” 相关关键词，确认轮询任务已启动且无报错。[1]
只有这四步全部通过，自动轮换才算真正就位。
轮换生效不等于服务无中断：不同消费方式的验证逻辑
Secret 资源版本变更不代表业务已获取新凭证，必须根据应用读取机密的具体方式执行差异化验收以确认轮换生效且无中断。
Secret 的 resourceVersion 变了，不代表你的业务已经拿到了新凭证。[1] 很多团队误以为驱动更新了挂载点就万事大吉，结果生产环境出现连接超时或鉴权失败。要确认轮换真正生效且无影响，必须根据应用读取机密的方式，执行不同的验收动作。
文件挂载 vs 环境变量：谁需要重启？
CSI 驱动更新的是容器内的文件内容或 Kubernetes Secret 对象，但应用进程是否感知，取决于它的读取机制。
对于文件挂载消费者，驱动会将新密钥写入 Pod 内的挂载目录。如果应用不支持热加载（Hot Reload），它只会继续读取旧文件直到下次启动。文档未证明所有应用具备自动侦测文件变化并重新加载配置的能力。[1] 你必须确认该进程能监听文件修改事件，并在检测到变更后主动重载协议或配置。
对于环境变量消费者，情况更严格。Kubernetes 的环境变量在 Pod 创建时注入，一旦运行中无法动态刷新。即使背后的 Secret 已更新，正在运行的 Pod 依然持有旧值。要让应用拿到新值，Pod 必须经历重启或滚动升级。[1]
| 消费方式 | 更新传播路径 | 是否需要重启/重载 | 常见风险点 |
|---|---|---|---|
| 文件挂载 | 驱动更新文件 -> 应用需主动检测 | 需支持热加载 | 应用无热加载能力导致读旧数据 |
| 环境变量 | 驱动更新 Secret -> 触发 Pod 重建 | 必须重启或滚动 | 滚动期间短暂不可用或读旧值 |
表格中的数据表明，环境变量模式天然依赖滚动策略来覆盖重启窗口，而文件模式则完全依赖应用自身的实现能力。[1]
行业视角补充：除了 K8s 原生的环境变量和文件挂载，部分云厂商的 PaaS 平台（如 AWS Fargate 或 Azure Container Apps）在处理 CSI 卷时的行为与标准 K8s 节点略有不同。例如在某些 Serverless 环境中，文件系统的 inode 更新可能不会立即触发应用层的文件系统通知，这要求开发者在代码层面引入更主动的“心跳检测”机制，或者强制配合应用的优雅退出逻辑，而不能单纯依赖操作系统的事件通知。[1]
如何判断轮换真正成功且无影响？
不要只看 K8s 层面的资源版本变化，那是“控制器层面”的状态。真正的验收标准在于业务监控。[1]
如果是文件挂载，你需要在业务日志或监控面板上确认：在驱动轮询更新后，应用确实发起了新的连接请求或配置重载操作，且没有报错。如果是环境变量，必须构建一套组合拳：确保滚动更新策略平滑、Readiness 探针准确判断实例健康、实例冗余足够高，并且业务监控覆盖了整个重启窗口。[1]
现有材料未提供应用级演练数据，这意味着“轮换无中断”不能靠猜。你必须通过实际的压力测试或灰度发布，观察在轮换发生时，业务指标（如错误率、延迟）是否波动。只有当监控显示业务连续稳定，才算轮换真正成功。[1]
本章验收清单
- [ ] 确认应用是否支持文件热加载，否则需安排重启计划
- [ ] 检查环境变量应用的滚动策略和就绪探针配置
- [ ] 验证 Secret
resourceVersion更新后，业务日志中出现新凭证记录 - [ ] 在业务监控中设置告警，覆盖轮换期间的潜在抖动
常见问题解答 (FAQ)
Q: 为什么我设置了 requiresRepublish 但日志里没有轮询记录？
A: 这通常是因为缺少了 --enable-secret-rotation=true 启动参数。requiresRepublish 只是声明能力，而启动参数才是触发执行的钥匙。两者缺一不可。
Q: 环境变量模式下，如何避免轮换时的服务中断？ A: 环境变量无法热更新，必须重启 Pod。建议配合滚动更新策略（RollingUpdate）和就绪探针（Readiness Probe）使用，确保在重启过程中流量被平滑转移，避免单点故障。
Q: 旧版本的 CSI 驱动（低于 v1.6.0）能否开启自动轮换？
A: 不能。RequiresRepublish 机制和相关的启动参数是从 v1.6.0 版本开始引入的。旧版本即使配置了相关参数也无法生效，建议升级驱动版本。