初始化 PostgreSQL 租户控制器项目

README.md

@@ -0,0 +1,67 @@
+# postgresql-tenant-operator
+
+面向 homelab 的 Kubernetes-native PostgreSQL 租户控制器。它不负责运行
+PostgreSQL，而是把外部 PostgreSQL 实例中的 database、role、权限、扩展和
+OpenBao 凭据生命周期暴露为 Kubernetes API。
+
+项目目前处于 API 骨架阶段，尚未对 PostgreSQL 或 OpenBao 执行写操作。
+
+## 目标
+
+- 通过 `PostgreSQLInstance` 注册可管理的外部 PostgreSQL 实例。
+- 通过 namespaced `PostgreSQLTenant` 声明 database、owner、login 和扩展。
+- 生成的密码只写入 OpenBao，不写入 CR、Event 或日志。
+- 使用 `status.conditions` 暴露持续 reconcile 的结果。
+- 默认使用 `Retain` 删除策略，避免删除 CR 时意外删除数据。
+- 允许 GitOps、Terraform、`kubectl` 和未来的 Backstage 使用同一套 API。
+
+## API 示例
+
+```yaml
+apiVersion: database.ddupan.top/v1alpha1
+kind: PostgreSQLTenant
+metadata:
+  name: netbox
+  namespace: netbox
+spec:
+  instanceRef: shared
+  database: netbox
+  ownerRole: netbox_owner
+  loginRole: netbox
+  extensions: [pg_trgm]
+  credential:
+    openBaoPath: kv/k8s/netbox/database
+  deletionPolicy: Retain
+```
+
+更完整的资源见 [`config/samples`](config/samples)，初始架构和安全边界见
+[`docs/architecture.md`](docs/architecture.md)。
+
+## 本地开发
+
+需要 Go、Docker、`kubectl` 和一个可用于测试的 Kubernetes 集群。
+
+```sh
+make manifests generate
+make test
+make build
+```
+
+安装 CRD 或在本机运行 controller：
+
+```sh
+make install
+make run
+```
+
+默认 e2e 测试会创建和删除 Kind 集群，不要让它指向日常使用的集群。
+
+## 路线
+
+1. 完成 CRD 校验、默认值和状态约定。
+2. 抽象 PostgreSQL 与 OpenBao client，用 fake 实现测试 reconciliation。
+3. 实现 database、owner role、login role、grant 和 extension 的幂等收敛。
+4. 实现带 finalizer 的 `Retain` / `Delete` 删除流程。
+
+代码和 Gitea Actions 工作流预期托管在
+`git.ddupan.top/panxiao81/postgresql-tenant-operator`。