80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
# 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 示例
|
||
|
||
```yaml
|
||
apiVersion: database.ddupan.top/v1alpha1
|
||
kind: PostgreSQLTenant
|
||
metadata:
|
||
name: netbox
|
||
namespace: netbox
|
||
spec:
|
||
instanceRef: shared
|
||
database: netbox
|
||
loginRole: netbox
|
||
extensions: [pg_trgm]
|
||
credential:
|
||
secretName: netbox-postgresql
|
||
deletionPolicy: Retain
|
||
```
|
||
|
||
上例描述获批后的目标 API；`config/samples` 当前仍随旧 API 骨架保留，将在实现 API
|
||
合同的同一改动中重新生成。系统架构见
|
||
[`docs/architecture.md`](docs/architecture.md)。API、部署、安全、迁移和运维合同见
|
||
[`docs/api-reference.md`](docs/api-reference.md)、
|
||
[`docs/deployment.md`](docs/deployment.md)、[`docs/security.md`](docs/security.md)、
|
||
[`docs/migration.md`](docs/migration.md) 和 [`docs/operations.md`](docs/operations.md)。
|
||
|
||
系统已批准的规范性行为、验收标准和设计决策见
|
||
[`docs/specification.md`](docs/specification.md)。
|
||
|
||
分支、提交、PR 和 CI 约定见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
|
||
Docker/devcontainer、PostgreSQL、OpenBao、envtest 与 Kind 的启动顺序见
|
||
[`docs/development.md`](docs/development.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 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`。
|