mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
107 lines
6.7 KiB
Markdown
107 lines
6.7 KiB
Markdown
# ADR-0499：直接 Vault KV Worker Secret 外部托管
|
||
|
||
- 状态：Accepted
|
||
- 日期：2026-08-24
|
||
- 决策：D-404
|
||
- 关联：ADR-0058、ADR-0114、ADR-0233、ADR-0491、ADR-0494、ADR-0496、ADR-0497、ADR-0498
|
||
|
||
## 背景
|
||
|
||
ADR-0494 已证明 `mounted-files` provider 可以在 Kubernetes atomic projection 轮换后无重启读取新值，并且 Worker ingress 不需要 Secret API 权限。但该模式仍由 Kubernetes Secret 保存真实值，不能满足要求控制面只持有短期访问能力、密钥材料始终由外部托管系统保管的部署。
|
||
|
||
QingLong 3.0 需要一个可选的直接外部 custody adapter，同时保持小型 Edge/Standalone 默认闭包不变，也不能把 Vault token、Secret 值、Legacy Env 名称或 provider 路径写入 PostgreSQL、Pod environment、公开 evidence 或日志。
|
||
|
||
## 决策
|
||
|
||
### 1. Provider 边界
|
||
|
||
在既有 `@qinglong/cluster-control` Remote Execution 子域中增加 `vault-kv-v2` provider，不新建 workspace package。基础 Kubernetes 部署继续默认使用 `mounted-files`；只有显式选择 `QL3_WORKER_SECRET_PROVIDER=vault-kv-v2` 的 Cluster overlay 才加载该实现。Edge/Standalone 不导入 Cluster Control，因此其制品、常驻内存和依赖树不增加 Vault 客户端。
|
||
|
||
provider 只在 durable Worker delivery authority 已经通过 Run、Attempt、Lease、Session、execution digest 和精确 SecretRef 集合校验后执行。每个路径由 `SHA-256(canonical SecretRef)` 推导，不把 SecretRef 或环境变量名放入 URL。普通 Secret 与 opaque environment bundle 继续分别服从 16 KiB、96 KiB 和总交付上限。
|
||
|
||
### 2. 传输与身份
|
||
|
||
实现只接受无凭据、无 path/query/fragment 的 `https://` authority，使用显式投影 CA，并要求协商 TLS 1.3；不跟随 redirect，不使用系统 CA 回退。控制 Pod 只投影 CA 和短期 token，不投影真实 Secret 值，也不挂载 ServiceAccount token。
|
||
|
||
token 必须同时满足：
|
||
|
||
- orphan、non-renewable、service token；
|
||
- 只含一个精确配置的读取 policy；
|
||
- 剩余 TTL 大于 0 且不超过配置上限，部署默认上限为 900 秒；
|
||
- 每次 `verify` 或 `resolve` 都重新打开投影文件并调用 `auth/token/lookup-self`。
|
||
|
||
实现没有 cache、watcher、timer、renewal loop 或后台连接。token 轮换由外部部署 authority 原子替换投影文件；旧 token 的撤销与新 token 的签发不由 QingLong 接管。Vault 不可达、封存、CA 不可信、token 过宽/过期或材料缺失时交付失败关闭，不回退到 `mounted-files`。
|
||
|
||
### 3. KV v2 数据合同
|
||
|
||
每个值固定存放在：
|
||
|
||
```text
|
||
<mount>/data/<prefix>/<sha256(canonical SecretRef)>
|
||
```
|
||
|
||
KV payload 必须是 exact shape：
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": 1,
|
||
"secretRefDigest": "<same 64-hex digest>",
|
||
"encoding": "base64",
|
||
"value": "<canonical base64>"
|
||
}
|
||
```
|
||
|
||
KV metadata 必须表明 version 为正整数、未删除且未销毁。空 Secret 是合法的 canonical base64；超限、非 canonical 编码、digest 不一致、未知字段或异常 metadata 均失败关闭。成功 material 在调用方 `dispose()` 时清零；报告和错误只暴露有界分类，不包含 endpoint path、token、SecretRef 或 value。
|
||
|
||
### 4. Kubernetes 部署
|
||
|
||
`deploy/kubernetes/ql3-cluster/vault-kv-worker-secret` overlay 删除基础部署的 value Secret env/mount/volume，只增加私有 CA 与短期 token 投影。示例文件只含占位符，仓库不保存可用 credential。
|
||
|
||
Vault policy 固定为：
|
||
|
||
```hcl
|
||
path "worker-secrets/data/values/production/*" {
|
||
capabilities = ["read"]
|
||
}
|
||
|
||
path "auth/token/lookup-self" {
|
||
capabilities = ["read"]
|
||
}
|
||
```
|
||
|
||
外部 Vault 的 HA、unseal、KMS/HSM seal、审计设备、备份和灾备属于部署方独立门禁。本 ADR 证明 QingLong 的直接 custody 数据边界，不把单机 Vault file storage fixture 冒充生产 Vault HA。
|
||
|
||
## 被拒绝的替代方案
|
||
|
||
### 在 PostgreSQL 或 ConfigMap 保存密文
|
||
|
||
拒绝。即使值已加密，也会扩大数据库/配置平面的 custody、备份和读取权限，并把轮换与数据库生命周期绑定。
|
||
|
||
### 给控制 Pod Kubernetes Secret API 权限
|
||
|
||
拒绝。它扩大为 namespace 级读取能力，无法把访问限制到 durable delivery authority 中的精确引用。
|
||
|
||
### 引入 Vault SDK、Agent sidecar 或常驻续租器作为必选依赖
|
||
|
||
拒绝。直接 HTTPS adapter 已能满足有界请求；额外 SDK 或 sidecar 会扩大依赖、镜像、常驻内存和凭据生命周期。部署方可以负责 token projection，但不得通过该机制把真实值重新投影进 Pod。
|
||
|
||
## 验证
|
||
|
||
真实 arm64 live contract 使用 digest-pinned Vault 1.21.4、私有 TLS CA、3-share/2-threshold 初始化和短期 orphan token，完成两个普通 Secret 与一个 opaque environment bundle 的读取，并证明：
|
||
|
||
- value 轮换和 token 原子轮换均无需重启；
|
||
- 旧 token accessor 撤销后不再可用；
|
||
- 缺失 material、不可信 CA 和 sealed Vault 均失败关闭；
|
||
- unseal 后恢复，Vault 容器在同一持久存储上替换后值仍可读取；
|
||
- 私有 `0600` 报告不含 token、SecretRef、value、证书私钥或 Vault path。
|
||
|
||
该单机 fixture 以当前非 root UID/GID、read-only rootfs、`cap-drop=ALL`、不增加 capability、`no-new-privileges` 和 `memory-swappiness=0` 运行。为兼容 capability/lock 策略不同的原生 Linux hosted runner，fixture 显式 `disable_mlock=true`；这只作用于临时测试 authority，不替代生产 Vault 主机的 swap 禁用或 mlock、HA seal 与审计硬化门禁。
|
||
|
||
最终 capability-free 本地报告 SHA-256 为 `281fe542e1bf6078132216b9701a28e76f36dcbccc95367997d8457773a9c210`，离线 audit 为 `compatible=true`、`findings=[]`。共享 CI 在原生 x64/arm64 runner 上分别构建 provider、审计 overlay、拉取同一 digest-pinned Vault image 并重跑完整 live contract；远程运行结果作为提交后的独立证据。
|
||
|
||
本地完整验证中，Cluster Control 为 `279 total / 277 pass / 2 conditional skip / 0 fail`，backend 为 `1574 total / 1572 pass / 2 conditional skip / 0 fail`，18-package clean build/test 退出 0。package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Cluster dependency、122-module Edge import、service-manager bridge、Cluster deployment、Local image、Vault overlay 和 14 档 Local artifact 均 compatible。基础 Edge/Standalone 制品仍为 `2,669,390 / 2,669,468 bytes`、325 files、58 loaded modules，不包含 Cluster Control 或 Vault adapter。
|
||
|
||
## 影响与剩余门禁
|
||
|
||
D-404 关闭 ADR-0491 的直接外部 custody adapter 门。ADR-0491 转 Accepted 前只剩固定低性能物理 Edge 的真实空间、RSS/I/O、写放大、ENOSPC 与断电恢复证据；开发机、Docker、CI runner 和 Cluster Vault live gate 均不能替代该设备证据。
|