postgresql-tenant-operator/README.md

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 示例

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，初始架构和安全边界见 docs/architecture.md。

分支、提交、PR 和 CI 约定见 CONTRIBUTING.md。

本地开发

需要 Go、Docker、kubectl 和一个可用于测试的 Kubernetes 集群。

make manifests generate
make test
make build

安装 CRD 或在本机运行 controller：

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。