Vault Agent Sidecar默认不自动注入Secret，因为它仅是代理，需显式配置Kubernetes Auth角色、Vault策略、正确模板及exit_on_read_error=false等参数，且依赖Pod能网络连通Vault、通过ServiceAccount完成身份认证并获授权读取对应secret路径。
Vault Agent Sidecar 为什么默认不自动注入 Secret？
因为 Vault Agent 本身不主动拉取或写入密钥，它只是个代理——需要你明确配置 template + exit_on_read_error = false + auto_auth，且 Pod 必须能访问 Vault（网络连通、策略授权、Token 或 Kubernetes Auth 配置正确）。常见现象是容器启动后 /vault/secrets/ 目录为空，或者日志里反复出现 error="no token found" 或 "permission denied" on path "secret/data/myapp"。
关键点在于：Vault Agent 不是“开箱即用”的密钥分发器，它依赖两个前提——身份认证成功、策略允许读取对应路径。Kubernetes Auth 方法最常用，但容易漏掉 ServiceAccount 绑定 auth/kubernetes/role/xxx 角色，或没给该角色配 policy。
如何正确配置 Vault Agent 的 Kubernetes Auth 和模板渲染？
必须在 Vault 中提前注册 Kubernetes 认证后端，并绑定 Role；同时在 Pod 的 agent-inject 注解中指定角色名和模板。Agent 容器启动时会用 Pod 的 serviceAccountToken 向 Vault 换 Token，再用该 Token 去读 secret/data/myapp。
- 确保 Vault 已启用
kubernetesauth：vault auth enable kubernetes - 配置 Kubernetes 认证后端指向 Kube API（注意
token_reviewer_jwt和kubernetes_ca_cert必须准确） - 创建 Role 并绑定 Policy：
vault write auth/kubernetes/role/myapp bound_service_account_names=myapp-sa bound_service_account_namespaces=default policies=myapp-policy - Pod 中通过注解触发注入：
vault.hashicorp.com/agent-inject-status设为update，vault.hashicorp.com/agent-inject-secret-mysecret.txt设为secret/data/myapp - 模板必须显式声明输出路径与权限：
vault.hashicorp.com/agent-inject-template-mysecret.txt的值需是 base64 编码的 Go template，例如{{ with secret "secret/data/myapp" }}{{ .Data.data.password }}{{ end }}
为什么 /vault/secrets/mysecret.txt 总是 0 字节或延迟更新？
这是模板未生效或 Vault Agent 没完成首次读取的典型表现。根本原因通常是模板语法错误、Secret 路径返回结构不符（比如用了 secret/myapp 但实际是 secret/data/myapp），或 Agent 没拿到有效 Token 导致静默失败。
调试建议：
- 进 Agent 容器执行：
curl -H "X-Vault-Token: $(cat /home/vault/.vault-token)" http://vault:8200/v1/secret/data/myapp，确认能返回 JSON 且.data.data.password存在 - 检查 Agent 日志是否含
template: mysecret.txt:1:9: executing "mysecret.txt" at: error calling secret: permission denied - 模板中避免硬编码字段名，改用
{{ .Data.data | toJSON }}先看原始结构 - 若用
vault kv get -format=json secret/myapp测试成功，但 Agent 失败，大概率是 KV 版本不一致：Agent 默认调 v2 接口，而secret/myapp是 v1 路径，应统一为secret/data/myapp（v2）或显式设kv_version = "1"在 template 配置中
Sidecar 容器启动顺序和应用读取时机怎么协调？
默认情况下，主容器可能比 Vault Agent 更早启动，导致应用一上来就读不到密钥文件。不能依赖 initContainer 等待 Agent（它本身是长期运行的），而要用 readinessProbe 或启动脚本轮询。
- 推荐在主容器中加启动检查：
while [ ! -s /vault/secrets/mysecret.txt ]; do sleep 2; done - 或用
readinessProbe.exec.command检查文件存在且非空：sh -c 'test -s /vault/secrets/mysecret.txt' - 不要设
livenessProbe对密钥文件做健康检查——密钥不会动态变更，且 Agent 重启会导致文件短暂消失，引发误杀 - 若应用是 Java/Spring Boot，可配合
spring.cloud.vault.generic.enabled=false关闭内置 Vault client，纯走文件挂载，避免双通道冲突
Vault Agent Sidecar 看似自动化，实则每一步都卡在认证链和路径精度上。最常被忽略的是 KV v1/v2 的路径差异、ServiceAccount Token 自动挂载是否被 PodSecurityPolicy 拦截、以及模板中对 .Data.data 层级的假设是否成立——这些细节不验证，就永远停在“文件为空”。
