postgresql-tenant-operator

面向 homelab 的 Kubernetes-native PostgreSQL 租户控制器。它不负责运行 PostgreSQL，而是把外部 PostgreSQL 实例中的 database、role、权限、扩展和 OpenBao 凭据生命周期暴露为 Kubernetes API。

项目目前处于 API 骨架阶段，尚未对 PostgreSQL 或 OpenBao 执行写操作。

目标

• 通过 PostgreSQLInstance 注册可管理的外部 PostgreSQL 实例。
• 通过 namespaced PostgreSQLTenant 声明 database、作为 owner 的 login role 和扩展。
• 生成的密码只写入 OpenBao，不写入 CR、Event 或日志。
• 通过 ExternalSecret 将七个原子连接字段投射到 Kubernetes Secret。
• 为非 Kubernetes 消费者输出不含认证信息的 OpenBao API URL。
• 使用 status.phase 展示进度，以 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
  loginRole: netbox
  extensions: [pg_trgm]
  credential:
    secretName: shared-netbox-database-credentials
  deletionPolicy: Retain

上例描述获批后的目标 API；config/samples 当前仍随旧 API 骨架保留，将在实现 API 合同的同一改动中重新生成。系统架构见 docs/architecture.md。API、部署、安全、迁移和运维合同见 docs/api-reference.md、 docs/deployment.md、docs/security.md、 docs/migration.md 和 docs/operations.md。

系统已批准的规范性行为、验收标准和设计决策见 docs/specification.md。

分支、提交、PR 和 CI 约定见 CONTRIBUTING.md。 Docker/devcontainer、PostgreSQL、OpenBao、envtest 与 Kind 的启动顺序见 docs/development.md。

本地开发

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

make manifests generate
make test
make build

安装 CRD 或在本机运行 controller：

make install
make run

默认 e2e 测试会创建和删除 Kind 集群，不要让它指向日常使用的集群。

路线

1. 按已批准规格完成 CRD 校验、默认值和状态约定。
2. 实现 PostgreSQL registry、OpenBao 和 ESO adapter 的测试替身及集成测试。
3. 实现凭据、login owner、database、grant、extension 和 Secret 投射的幂等收敛。
4. 实现并演练带 finalizer 的 Retain / Delete 删除流程和迁移 runbook。

代码和 Gitea Actions 工作流预期托管在 git.ddupan.top/panxiao81/postgresql-tenant-operator。