初始化 PostgreSQL 租户控制器项目

2026-09-09 19:52:54 +00:00
commit 4ad94dc194
64 changed files with 4729 additions and 0 deletions
@@ -0,0 +1,59 @@
+# 初始架构
+
+## 职责边界
+
+Kubernetes API 保存期望状态和最近一次观察结果；PostgreSQL catalog 是 database、
+role 和权限的事实来源；OpenBao 是凭据的事实来源。controller 不把明文密码写入
+Kubernetes API、Event 或日志。
+
+```text
+Git / kubectl / Terraform / Backstage
+                  |
+                  v
+        Kubernetes API (CRD)
+                  |
+                  v
+   postgresql-tenant-operator
+          |               |
+          v               v
+  external PostgreSQL   OpenBao
+```
+
+## 资源模型
+
+### PostgreSQLInstance
+
+Cluster-scoped，由平台管理员创建。它描述服务器端点、管理凭据的 OpenBao 引用，
+以及租户可以申请的 extension 白名单。
+
+### PostgreSQLTenant
+
+Namespaced，描述一个应用租户，包括 database、无登录 owner role、应用 login
+role、extensions、凭据路径和删除策略。
+
+第一版规定一个 tenant 拥有一个 database 和一个 login role。跨租户 grant、多个
+login role 和定时轮换等需求出现后再扩展 API。
+
+## Reconcile 原则
+
+- 每轮从 PostgreSQL 和 OpenBao 读取实际状态，不把 `status` 当作事实来源。
+- 所有操作幂等；任意步骤失败后可以从下一轮继续。
+- 先验证 extension 白名单，再执行任何变更。
+- controller 生成密码，调用方只能得到 OpenBao 路径和状态。
+- `metadata.generation` 只表示 spec 变更，不承载凭据版本语义。
+
+## 删除
+
+默认 `deletionPolicy: Retain`。删除 CR 时保留 PostgreSQL database、roles 和
+OpenBao 数据。`Delete` 模式将在实现备份检查、活动连接处理和可测试的 finalizer
+状态机后加入实际销毁逻辑。
+
+## 暂不包含
+
+- PostgreSQL 实例、VM 或存储的创建。
+- Web UI 或独立 REST API；Kubernetes API 已提供 get、list、watch 和 RBAC。
+- PostgreSQL 高可用和备份编排。
+- 凭据轮换；controller 只负责首次生成长期凭据并写入 OpenBao。只有出现能够
+  重新加载凭据并妥善处理现有连接的实际消费者后，才重新评估轮换协议。
+- 自动将 OpenBao 数据投射为 Kubernetes Secret；这由 External Secrets Operator
+  负责。