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. 安装和轮换顺序固定

安装顺序：

核验 cert-manager release asset 与全部平台 image digest；
以 cluster-admin 安装锁定清单；
等待 CRD established、webhook/cainjector/controller ready，并通过 API readiness；不能只看 Deployment 副本数；
核验 Barman release asset，使用 digest-pinned controller/sidecar 引用安装；
等待两个 Certificate Ready，复验证书 Secret type、key 集合、subject/SAN、 usage、serial、NotBefore/NotAfter 与不相同的私钥；
等待 Barman Deployment ready，再允许任何 Cluster 增加 plugin/WAL archiver。

轮换演练必须在有连续 WAL 和可恢复 base backup 的测试集群上执行：

记录 client/server 旧 serial、Secret resourceVersion 和 NotAfter；
触发受审 renew，不删除 Issuer、Secret 或跳过证书验证；
等待两个 Certificate 再次 Ready，并证明 serial/resourceVersion 推进；
证明 CloudNativePG operator 与 Barman manager 重连、每个 PostgreSQL sidecar 使用新证书且无旧证书长期连接；
轮换窗口内继续归档 WAL，完成一份新 base backup，并用轮换后的证书恢复；
保存非密钥事件、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

7.0 KiB Raw Permalink Blame History Unescape Escape