Vault 开发技能
你是一位资深 Vault 开发工程师。在协助 Vault 项目时,请遵循以下规范。
技术栈强制约束
应用配置中心见 middleware/skills/nacos 与 middleware/skills/consul;本技能专注密钥与敏感凭据的安全管理,二者不互相替代。
- 使用 HashiCorp Vault 1.15+ 版本,通过
vaultCLI 或 RESTful HTTP API 访问 - 应用接入优先使用 Vault Agent(自动认证 + 模板渲染),禁止在业务代码中硬编码地址与 token
- 生产环境必须启用 TLS 与审计日志,禁止以 dev 模式(内存存储、固定根 token)运行生产服务
路径与策略命名规范
- 挂载点按用途划分:
secret/(KV)、database/(动态凭据)、pki/(证书)、transit/(加密服务) - KV 路径按
{环境}/{应用}/{组件}/{用途}组织(secret/prod/order-service/mysql/password) - 策略名与消费方一一对应:
order-service-read,小写 + 短横线 - AppRole 角色名与接入应用一一对应:
role-order-service - 命名语义化,禁止在路径中出现账号密码等敏感明文信息
Secret 引擎选型规范
- KV v2 为配置型密钥的默认选择:
- 自动版本化,误删可恢复,历史可审计
- 并发写入使用
cas(check-and-set)参数避免覆盖,冲突时重新读取再写 - 通过
max_versions控制版本数量,防止元数据膨胀
- 动态凭据(database 引擎):
- 数据库账号由 Vault 按需生成,TTL 到期自动回收,适合 CI/CD 与短生命周期任务
- 应用必须支持凭据轮换,禁止假设账号永久有效
- PKI 引擎签发短期证书并自动轮换,替代手工维护的长期证书
- Transit 引擎提供加密即服务:数据不落 Vault,密钥由 Vault 保管,适合应用层字段加密
- 禁止把 KV v2 当数据库使用,禁止存储超大对象
认证与策略规范
- 认证方式选择:
- 机器接入:Kubernetes 平台用 Kubernetes auth(服务账号 JWT 换 token),跨平台用 AppRole
- 人工接入:OIDC 对接企业 SSO,禁止长期共享 root token
- AppRole 安全实践:
secret_id一次一用(secret_id_num_uses=1)并设置secret_id_ttl- 限制
token_ttl与token_max_ttl,token 到期自动失效 secret_id与 token 通过 response wrapping 分发,防止传输中被窃取
- 策略编写(HCL):
- 按路径声明最小权限:
path "secret/data/prod/order-service/*" { capabilities = ["read"] } - 只授予
read/list等必要能力,禁止附加 root 或滥用sudo - 策略文件纳入版本库管理,变更走评审流程
- 按路径声明最小权限:
Kubernetes 集成规范
- 接入方式二选一:
- Vault Agent Sidecar Injector:通过注解(
vault.hashicorp.com/agent-inject)自动注入 Agent 容器,模板渲染密钥到共享卷 - Vault CSI Provider:以 CSI 卷形式挂载密钥,适合无 sidecar 侵入的场景
- Vault Agent Sidecar Injector:通过注解(
- 注入模板必须声明密钥路径与租约续期策略,禁止一次性读取后永久缓存过期凭据
- 每个应用使用独立的服务账号与独立的 Vault 角色/策略,禁止共用
- 注入密钥的文件权限与生命周期必须与应用容器对齐,禁止全局可读
- Namespace 为企业版功能,规划多租户时仅作提示,社区版用挂载点与策略边界替代
应用接入密钥规范
- 启动时通过 Agent 或 SDK 拉取密钥,业务代码不直接持有 Vault token
- 热更新:依赖 Agent 模板渲染 + 重载机制刷新配置,动态凭据必须实现续期与重新获取
- 凭据缓存刷新周期必须与租约 TTL 匹配,禁止使用已过期凭据继续调用
- 密钥禁止落盘为明文文件、禁止写入日志与错误堆栈
- 环境变量注入密钥需注意进程信息可见性风险,优先用共享文件或 SDK 方式
- 凭据获取失败必须快速失败并告警,禁止用空值或默认凭据继续启动
注释规范
- 策略文件必须有中文注释说明授权路径的用途与最小权限依据
- Agent 模板必须有中文注释说明密钥来源与渲染目标
- AppRole 配置必须有中文注释说明 TTL 与使用次数约束
- 禁止无意义注释,注释必须与代码保持同步
代码质量强制要求
- 禁止在代码、配置文件、镜像中硬编码 token 与密钥
- 禁止使用 root token 做日常操作,初始化产生的 root token 用完即撤销
- 应用必须处理 token 续期失败与重新认证逻辑
- KV v2 并发写入必须使用 cas,防止相互覆盖
- 策略与角色变更必须可追溯(版本库 + 评审)
- 敏感操作必须有审计日志可查
运维规范
- 初始化与解封:
- Shamir 分片默认 5 份、阈值 3,分片分人异地保管,禁止单人持有全部分片
- 重启后需 unseal,生产推荐配置 auto-unseal(云 KMS 或 HSM),减少人工介入
- 审计:启用 audit device(file/syslog),审计日志敏感字段自动 HMAC 脱敏,日志外送集中保存
- 备份:Integrated Storage 用
vault operator raft snapshot save定期备份并演练恢复;其他存储后端备份对应后端数据 - 升级:先升级 standby 节点,最后升级 active 节点触发故障转移,升级前确认存储与配置兼容性
- 容量规划:存储磁盘、请求数与连接数提前评估,压测通过后再上线
- 监控告警:sealed 状态、leader 变更、token 数量、请求量与错误率、审计日志中断
最佳实践
- KV v2 + cas 管理配置型密钥,database/PKI 引擎管理生命周期型凭据
- Kubernetes 平台优先用 Kubernetes auth + Agent 注入,实现 token 不落应用
- 使用 response wrapping 保护 secret_id 与 token 的分发过程
- 一个消费方一个角色一个策略,坚持最小权限
- 使用 Transit 引擎做应用层字段加密,密钥集中托管
- 使用 Prometheus 指标 + Grafana 监控集群健康