mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
137 lines
7.0 KiB
Markdown
137 lines
7.0 KiB
Markdown
# ADR-0131：Barman Plugin cert-manager 证书 Authority
|
||
|
||
- 状态：Proposed（cert-manager v1.20.3 与 Kubernetes 1.32.8 兼容选择、
|
||
official release manifest SHA-256、三个实际运行 image 的 OCI index 与
|
||
amd64/arm64 digest、Barman 双向 TLS 身份/轮换窗口、cross-lock 和 mutation
|
||
gate 已完成；真实 API readiness 与轮换演练仍是 Release Gate）
|
||
- 日期：2026-08-03
|
||
- 关联 RFC：QL-RFC-0001 D-127、D-128、D-129
|
||
- 关联 ADR：ADR-0127、ADR-0129、ADR-0130
|
||
|
||
## 背景
|
||
|
||
Barman Cloud CNPG-I plugin 与 CloudNativePG operator 之间使用 TLS。官方 v0.13.0
|
||
release manifest 创建 namespaced SelfSigned Issuer、client Certificate 和 server
|
||
Certificate，并要求 cert-manager API 在安装 plugin 前 ready。上游也允许部署方
|
||
自管证书，但部署方必须自行证明完整证书链、双向身份和轮换。
|
||
|
||
QL3 当前 live Kubernetes 基线为 1.32.8。不能直接使用 `releases/latest`：最新版
|
||
可能提高最低 Kubernetes 版本，也不能在 release manifest 中继续保留 tag-only
|
||
image 后声称供应链锁定。
|
||
|
||
## 决策
|
||
|
||
### 1. Barman 默认证书 authority 为 cert-manager v1.20.3
|
||
|
||
选择 cert-manager `1.20.3`，因为官方支持矩阵覆盖 Kubernetes `1.32`–`1.35`，
|
||
与 QL3 `1.32.8` Kind 基线相交；更新的 `1.21.0` 从 Kubernetes `1.33` 起，不作为
|
||
当前默认值。`1.20.3` 还包含 Challenge/Order 聚合 RBAC 的高危安全修复。
|
||
|
||
该依赖只属于启用 Barman 的 Cluster 基础设施：
|
||
|
||
- cert-manager 安装在 `cert-manager` namespace；
|
||
- Barman plugin 和它的 Issuer/Certificate 安装在 CloudNativePG operator 所在的
|
||
`cnpg-system` namespace；
|
||
- edge、standalone、worker 和 QL3 npm/package 闭包不得导入 cert-manager client、
|
||
CRD 或 installer；
|
||
- cluster-control 应用 Pod 无安装、签发、renew 或读取 plugin 私钥的权限。
|
||
|
||
### 2. 供应链锁与 live readiness 分离
|
||
|
||
`operators/cert-manager/selection-lock.json` 当前强制：
|
||
|
||
- `version: 1.20.3`；
|
||
- reviewed Kubernetes `1.32.8`；
|
||
- official release asset SHA-256
|
||
`7ee74ba06845213e96d8ceaff3d20dd51e682765c1418eddda4e8780ba082261`；
|
||
- release manifest 实际引用的 controller、cainjector、webhook 三个 image 均锁定
|
||
OCI index 及 `linux/amd64`、`linux/arm64` 子 manifest；
|
||
- static manifest 没有 startup API check 或 solver workload，禁止为满足数量要求
|
||
虚构第四个 image；
|
||
- `status: supply-chain-verified`、`releaseReady: false`；
|
||
- 只保留 `live-cert-manager-api-and-plugin-mtls-rotation-evidence` blocker。
|
||
|
||
源码 tag 内的 `manifest.yaml` 不是 Release 资产：v1.20.3 仍必须从固定 Release URL
|
||
下载并先核对上述 SHA-256，再按 selection lock 将三个 tag-only 引用改写为对应
|
||
OCI index digest。锁目录保持仅含 JSON，不复制约 1 MiB 的上游 installer。
|
||
|
||
该静态 lock 不会因为仓库中出现一份历史报告而改写为 `releaseReady: true`。每次正式
|
||
镜像发布必须由 `cluster-dr-release-evidence` 在 commit-scoped 私有 runner mount 中
|
||
重新审计一份 24 小时内、source revision 精确匹配的 live report；该报告必须同时证明
|
||
client/server 轮换后 WAL、backup、latest restore 与 PITR 继续成功。`publish` Job 对此
|
||
证据采用硬 `needs`，因此没有 live 报告时保持不可发布，而不是让 operator 版本锁冒充
|
||
运行证据。
|
||
|
||
### 3. Barman 双向 TLS 身份固定
|
||
|
||
在 `cnpg-system` 中只允许以下资源合同：
|
||
|
||
- `Issuer/selfsigned-issuer`，`cert-manager.io/v1`、namespaced、SelfSigned；
|
||
- client Certificate `barman-cloud-client`：
|
||
`commonName=barman-cloud-client`、`usage=client auth`、
|
||
Secret `barman-cloud-client-tls`；
|
||
- server Certificate `barman-cloud-server`：
|
||
`commonName=barman-cloud`、DNS SAN `barman-cloud`、
|
||
`usage=server auth`、Secret `barman-cloud-server-tls`；
|
||
- 两者 `duration=2160h`、`renewBefore=360h`。
|
||
|
||
Secret 内容不得进入 Git、审计输出或应用 Pod。证书名称、用途、SAN、namespace 或
|
||
轮换窗口漂移必须失败关闭。SelfSigned 只用于 namespace 内 plugin transport，
|
||
不能复用为 PostgreSQL、Ingress、Worker 或用户 workload 的通用 CA。
|
||
|
||
### 4. 安装和轮换顺序固定
|
||
|
||
安装顺序：
|
||
|
||
1. 核验 cert-manager release asset 与全部平台 image digest；
|
||
2. 以 cluster-admin 安装锁定清单；
|
||
3. 等待 CRD established、webhook/cainjector/controller ready，并通过 API
|
||
readiness；不能只看 Deployment 副本数；
|
||
4. 核验 Barman release asset，使用 digest-pinned controller/sidecar 引用安装；
|
||
5. 等待两个 Certificate Ready，复验证书 Secret type、key 集合、subject/SAN、
|
||
usage、serial、NotBefore/NotAfter 与不相同的私钥；
|
||
6. 等待 Barman Deployment ready，再允许任何 Cluster 增加 plugin/WAL archiver。
|
||
|
||
轮换演练必须在有连续 WAL 和可恢复 base backup 的测试集群上执行：
|
||
|
||
1. 记录 client/server 旧 serial、Secret resourceVersion 和 NotAfter；
|
||
2. 触发受审 renew，不删除 Issuer、Secret 或跳过证书验证；
|
||
3. 等待两个 Certificate 再次 Ready，并证明 serial/resourceVersion 推进；
|
||
4. 证明 CloudNativePG operator 与 Barman manager 重连、每个 PostgreSQL sidecar
|
||
使用新证书且无旧证书长期连接；
|
||
5. 轮换窗口内继续归档 WAL，完成一份新 base backup，并用轮换后的证书恢复；
|
||
6. 保存非密钥事件、condition、serial/fingerprint 和中断时间报告。
|
||
|
||
仅 Certificate Ready、Secret 更新或 plugin Pod 重启不能单独证明轮换成功。
|
||
|
||
## 替代方案
|
||
|
||
- **直接使用 `releases/latest`**：拒绝。版本、Kubernetes 兼容性和镜像都会漂移。
|
||
- **当前选择 cert-manager 1.21.0**：拒绝。其官方最低 Kubernetes 为 1.33，高于
|
||
QL3 1.32.8 live 基线。
|
||
- **每个部署默认自管证书 Secret**：拒绝作为默认值。它会把链验证、双向身份、
|
||
renew、原子 Secret 发布和 sidecar/operator 重载证明复制给每个部署。成熟平台
|
||
可在独立 ADR/overlay 中采用外部 CA，但必须满足同等证据。
|
||
- **复用 PostgreSQL operator CA 或应用 CA**：拒绝。会合并数据库、plugin 和应用
|
||
transport 的信任域。
|
||
- **由 cluster-control Pod 生成证书**：拒绝。常驻应用不能获得 cluster-wide
|
||
签发或 Secret 写 authority。
|
||
|
||
## 影响
|
||
|
||
- 启用 Barman 的 Cluster 增加 cert-manager controller、webhook 和 cainjector
|
||
常驻成本；这不进入路由器/standalone/worker 产物。
|
||
- Kubernetes 1.32 基线存在时，cert-manager 不能独立升级到 1.21；若升级
|
||
Kubernetes，需重新评审两者的原子升级顺序。
|
||
- 供应链锁已完成；真实 API readiness 与轮换证据完成前，本 ADR 和 Barman
|
||
Release Gate 保持 Proposed。
|
||
|
||
## 验证
|
||
|
||
- `pnpm audit:cert-manager-selection:ql3`
|
||
- `node --test test/back/ql3CertManagerSelectionAudit.test.cjs`
|
||
- `pnpm audit:barman-cloud-supply-chain:ql3`
|
||
- `node --test test/back/ql3CloudNativePgDrEvidenceAudit.test.cjs`
|
||
- official Release manifest/OCI digest 复核
|
||
- cert-manager API readiness、Barman mTLS 安装与 renew/backup/restore live evidence
|