docs: 完善 v1alpha1 设计与运维合同

2026-09-10 05:23:33 +00:00
parent 4823eeb767
commit a723372c6e
10 changed files with 732 additions and 91 deletions
@@ -0,0 +1,112 @@
+# 部署与配置
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | Review |
+| 环境 | homelab Kubernetes + 外部 PostgreSQL/OpenBao |
+| 最后更新 | 2026-09-10 |
+
+本文定义 v1alpha1 的运行依赖、启动顺序和部署级配置。当前 manifests 尚未实现这些
+配置，示例是后续实现合同，不可直接用于现有脚手架。
+
+## 依赖与顺序
+
+1. 准备 PostgreSQL VM、持久盘、备份和网络入口。
+2. 用 OpenBao PKI 签发 PostgreSQL server 证书，包含 Instance `host` 的 DNS SAN 与
+   `hostaddr` 的 IP SAN；配置 PostgreSQL 强制 TLS。
+3. 创建 PostgreSQL controller 管理 role 和管理 database 连接权限。
+4. 在 OpenBao KV v2 写入管理 role 凭据。
+5. 配置 OpenBao Kubernetes auth、controller policy 和面向 ESO 的读取 policy。
+6. 在 Kubernetes 安装 ESO，创建可读取租户路径的 `ClusterSecretStore`。
+7. 创建公开 CA bundle ConfigMap，并挂载到 controller 和需要直接验证数据库的应用。
+8. 部署 controller，再创建 Instance；等待 Ready 后才创建 Tenant。
+
+任何一步都不得把真实密码、Token、kubeconfig 或 CA 私钥提交进 Git。
+
+## Controller 配置合同
+
+具体 CLI flag/env 名称将在实现时按下表确定；语义和作用域已经固定：
+
+| 配置 | 必填/默认 | 说明 |
+| --- | --- | --- |
+| OpenBao internal API address | 必填 | controller 可访问的 HTTPS 地址 |
+| OpenBao consumer API address | 默认同 internal | 写入 Tenant status，必须能被预期外部消费者解析 |
+| OpenBao auth mount | 默认 `kubernetes` | Kubernetes auth mount 名称 |
+| OpenBao auth role | 必填 | controller ServiceAccount 对应 role |
+| OpenBao KV mount | 默认 `kv` | KV v2 mount；开发可显式用 `secret` |
+| OpenBao tenant base path | 必填 | controller 专属 mount-relative 前缀 |
+| ESO ClusterSecretStore name | 必填 | controller 创建的 ExternalSecret 固定引用 |
+| CA bundle path | 必填（TLS） | 只读 PEM trust bundle，不含私钥 |
+| reconcile timeout | 有安全默认 | 单轮外部操作的总期限 |
+
+Tenant 路径固定推导为 `<base-path>/<namespace>/<name>`。namespace/name 都已通过
+Kubernetes 名称校验，因此不再允许 CR 提供任意路径。KV v2 API URL 使用 consumer
+address 拼为 `<address>/v1/<mount>/data/<base-path>/<namespace>/<name>`。
+
+配置变化不得隐式迁移既有凭据。修改 KV mount/base path 或 consumer address 前必须
+停止 controller、评估现有 Tenant，并走明确迁移；实现应把 mount/base path 视为安装
+身份的一部分并在 registry 留存，以便检测错误配置。
+
+## PostgreSQL 管理 role
+
+生产部署禁止使用 superuser。管理 role 至少需要：
+
+- 连接管理 database、读取必要 catalog；
+- 创建/修改受管 login role；
+- 创建 database 并指定 owner；
+- 撤销 `PUBLIC` CONNECT、授予租户 role CONNECT；
+- 连接租户 database 并创建 allowlist extension；
+- 创建和维护 controller 专属 registry schema/table；
+- `Delete` 时禁止连接、终止目标 database session、删除已验证归属的 database/role。
+
+部分 PostgreSQL 操作天然要求较高权限，尤其终止其他 session 和安装某些 extension。
+应优先使用 PostgreSQL 预定义角色、受控 SECURITY DEFINER 管理函数或限定数据库的
+授权；任何不得不使用 superuser 的 extension 都必须按实例单独记录，不得扩大默认
+controller 权限。最终可执行 SQL grant 将随 PostgreSQL adapter 集成测试固化。
+
+## OpenBao 与 ESO
+
+controller policy 分成两个范围：
+
+- 只读 Instance 管理凭据路径；
+- 在固定 tenant base path 下 create/read/update/delete KV v2 data 和 metadata，Delete
+  必须能永久删除全部版本及 metadata。
+
+ESO 使用独立身份，只需读取 tenant base path；它不应读取 PostgreSQL 管理凭据。
+`ClusterSecretStore` 由平台管理员创建，controller 只引用，不创建或修改 Store。
+controller 创建的 ExternalSecret 与 Tenant 同 namespace，并设置 ownerReference；目标
+Secret 包含固定七键：`username`、`password`、`database`、`host`、`hostaddr`、`port`、
+`sslmode`。
+
+## Kubernetes RBAC
+
+- controller 可读/写 Instance、Tenant 的 status/finalizer 和 Event。
+- controller 可在 Tenant namespace 创建、读取、更新、删除 ExternalSecret，并只读检查
+  对应 Secret 是否完成投射。
+- namespace 用户可以管理本 namespace Tenant，但不能管理 Instance、Store、controller
+  配置或其他 namespace 的 ExternalSecret。
+- controller 无需读取目标 Secret 的 data；验证登录使用从 OpenBao 读取的应用凭据，
+  对 Secret 只检查存在性和 ESO 状态。
+
+## 升级与回滚
+
+v1alpha1 尚不承诺跨版本转换。升级前备份 CR、PostgreSQL registry 和 OpenBao metadata，
+先在隔离 Kind 环境运行 E2E。禁止在同一组 CR 上同时运行两个 controller 版本。若新版本
+在执行任何破坏性迁移前失败，可回滚镜像；涉及 API/storage 或 registry schema 迁移时，
+必须先写独立升级规格和回滚步骤。
+
+## 上线验证
+
+```text
+PostgreSQL TLS 与备份验证
+  -> OpenBao auth/policy 验证
+  -> ClusterSecretStore Ready
+  -> controller Ready/leader elected
+  -> Instance Ready
+  -> 测试 Tenant Ready
+  -> DNS host 与 IP hostaddr 分别登录
+  -> 删除测试 Tenant 并验证所选策略
+```
+
+生产 homelab 上线前还必须完成 [`security.md`](security.md) 的权限检查和
+[`operations.md`](operations.md) 的备份/逃生检查。