docs: 同步 Database 资源与申请分离设计
关联 Ayatori 本地提交 6db8a495fb9f8981d336c9e6288253628ab478b6；两仓库均未推送。
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Ayatori 控制面边界
|
||||
last_reviewed: 2026-09-20
|
||||
last_reviewed: 2026-09-24
|
||||
---
|
||||
|
||||
# Ayatori 控制面边界
|
||||
@@ -39,6 +39,14 @@ Compute 方向已被记录但延后实施：选择性复用 `core/v1 Node` 与 L
|
||||
可以是普通 Linux 节点上的 libvirt/QEMU；Proxmox 用于 brownfield adopt 和过渡。OpenSandbox/Kata
|
||||
microVM 属于 Run/Sandbox 的隔离实现，不因此成为 VirtualMachine 资源。
|
||||
|
||||
Database 资源模型于 2026-09-24 明确采用官方 PV/PVC 的资源/申请分离模式：Instance 提供
|
||||
管理入口，独立 Database 表示实际资源，Tenant 表示用户申请。Retain 保留资源对象，支持
|
||||
人工导入和明确授权后的重新绑定；不维护 PostgreSQL ownership registry，不为创建结果不确定
|
||||
提供自动认领保证。详见 [DBaaS 设计](../services/postgresql-tenant-operator.md#当前资源模型2026-09-24-已确认)。
|
||||
|
||||
新增 Kubernetes 资源生命周期前须核对官方设计方式，记录采用与偏离的语义；参考模式不意味着
|
||||
部署对应上游组件，也不意味着复制全部字段与抽象。
|
||||
|
||||
详细设计以 Ayatori 仓库的
|
||||
[ADR-0001](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/decisions/0001-kubernetes-api-machinery.md)
|
||||
、[ADR-0006](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/decisions/0006-demand-driven-resource-scope.md)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 架构约束索引
|
||||
|
||||
审阅日期：2026-09-20。以下是现有仓库明确记录的约束摘要；Ayatori 条目来自其独立项目的
|
||||
审阅日期：2026-09-24。以下是现有仓库明确记录的约束摘要；Ayatori 条目来自其独立项目的
|
||||
已接受设计，其余来源路径相对于 homelab-infra。修改时必须读原文和对应代码，新出现的差异
|
||||
先向维护者确认；[首轮状态对齐](../verification.md)已完成。
|
||||
|
||||
@@ -10,6 +10,7 @@
|
||||
| Kubernetes 内置资源不绑定上游实现组件 | 可由 Ayatori Agent/controller 实现和消费 Node、Lease 等 API；使用 Node 不推导必须部署 kubelet、Pod 或 kube-scheduler | [Ayatori 控制面边界](ayatori-control-plane.md) |
|
||||
| Ayatori 只为已验证的管理缺口新增北向资源 | 当前优先 Database、LoadBalancer、Bucket/Object Storage；VM 价值已确认但南向较重；Run 是内部切片，KaaS 按需，FaaS/PaaS 默认不做 | [Ayatori 控制面边界](ayatori-control-plane.md) |
|
||||
| Ayatori Compute 复用 Node/Lease API，但不引入 Kubernetes workload plane | Compute Agent 实现 Node 状态；libvirt 是长期候选主路径，PVE 是 brownfield 过渡；Kata microVM 属于 Sandbox backend | [Ayatori 控制面边界](ayatori-control-plane.md) |
|
||||
| Database 采用独立资源与用户申请分离 | Instance → Database → Tenant；Retain 保留资源并人工回收，显式导入，不维护 PG registry；替代旧所有权持久化合同 | [DBaaS 设计修订](../services/postgresql-tenant-operator.md#当前资源模型2026-09-24-已确认) |
|
||||
| Samba AD、OCI、Proxmox 优先 IaC，以代码为准 | Ansible/Terraform 声明及任务优先于旧 README；声明不等于已验证部署 | 维护者于 2026-09-16 明确、各服务使用指南 |
|
||||
| 服务独立部署，Terraform root/state 按服务隔离 | 避免认证和变更影响范围绑在一起 | `AGENTS.md`、`CLAUDE.md` |
|
||||
| OpenBao 恢复不能依赖 k3s 或读取自己内部的恢复凭据 | 先恢复信任根，再恢复消费者 | `infrastructure/openbao/README.md`、`CLAUDE.md` |
|
||||
|
||||
+1
-1
@@ -75,7 +75,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
|
||||
|
||||
- [e5renew、research-auto](external-consumers.md)：GitHub 上的外部消费者，不属于 homelab 基础设施；仅保留归属入口。
|
||||
- [Gitea Dynamic Runner](gitea-dynamic-runner.md)：正在积极开发的动态 Pod/VM runner，原名 gitea-microvm-runner；具体启用范围、调度和队列约定以项目文档为准。
|
||||
- [PostgreSQL Tenant Operator](postgresql-tenant-operator.md)：计划中的 DBaaS 中间层，管理共享实例中的数据库与账号；README 记录为 API 骨架阶段，不代表服务已上线。
|
||||
- [PostgreSQL Tenant Operator](postgresql-tenant-operator.md)：计划中的 DBaaS 中间层，管理共享实例中的数据库与账号；现转入 Ayatori Database，采用独立 Database 资源与 Tenant 申请；设计修订不代表服务上线。
|
||||
- [workload-sts](../architecture/workload-sts-history.md)：已归档的早期机器身份方案；停止开发、不部署 PoC，由 SPIFFE/SPIRE 替代。
|
||||
- Backstage：规划中的服务目录与文档入口；本轮未发现独立部署目录。
|
||||
- Keycloak、Casdoor：`archive/` 下有明确退役记录，替代入口为 Authelia。
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title: PostgreSQL Tenant Operator（计划中的 DBaaS）
|
||||
lifecycle: planned
|
||||
evidence: documented
|
||||
last_reviewed: 2026-09-20
|
||||
last_reviewed: 2026-09-24
|
||||
last_verified: null
|
||||
sources:
|
||||
- https://git.ddupan.top/panxiao81/postgresql-tenant-operator
|
||||
@@ -54,9 +54,9 @@ adapter 和 controller 的纵向切片进入 Ayatori；暂停中的两个未提
|
||||
合并不承担旧运行链路、旧 CRD/status 或数据的兼容责任：直接读取 OpenBao 管理凭据的旧路径可以
|
||||
删除，未投入使用且落后于规范的 CRD/samples/实现结构不保留兼容层。
|
||||
|
||||
源项目已批准的系统规格、API 语义、Instance/Tenant 领域模型、状态机、ownership registry、
|
||||
凭据交付、Retain/Delete、恢复和测试设计整体直接复用为 Ayatori DBaaS 合同。大胆重构针对旧运行
|
||||
实现和项目装配，不表示可以静默改变这些已批准行为；合同变化仍须先修订规格并单独评审。
|
||||
2026-09-20 的迁移决定原要求整体沿用源设计。2026-09-24，维护者明确批准下述资源/申请
|
||||
分离修订，替代 registry、自动所有权恢复与原 Retain 合同；管理凭据、TLS、OpenBao/ESO 和
|
||||
其他适用安全边界继续保留。这是显式设计修订，不是已完成运行验证。
|
||||
|
||||
原 `database.ddupan.top/v1alpha1` API group 也不保留。Ayatori 中的目标 API 使用
|
||||
`database.ayatori.ddupan.top/v1alpha1`，并纳入统一的 `api/database/v1alpha1` 与 Database 模块
|
||||
@@ -66,11 +66,34 @@ adapter 和 controller 的纵向切片进入 Ayatori；暂停中的两个未提
|
||||
[#3 的 ADR-0008](https://git.ddupan.top/panxiao81/ayatori/src/commit/33fb3ec9725dca8a10f2ad4bcd71cf83413932ee/docs/decisions/0008-merge-postgresql-tenant-operator.md)；
|
||||
该决定已于 2026-09-21 合并 main，链接固定到合并版本；设计合并不表示 Database 实现已完成。
|
||||
|
||||
## 当前资源模型（2026-09-24 已确认）
|
||||
|
||||
参考 [Kubernetes 官方 PV/PVC](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) 的
|
||||
资源/申请分离：Instance 是资源来源与管理入口；独立 Database 类似 PV；Tenant 是类似 PVC
|
||||
的用户申请。Instance 一对多 Database，每个 Database 同时最多绑定一个 Tenant。
|
||||
|
||||
Database 自带 instanceRef，手工登记不依赖 Tenant；动态申请由 Tenant 选择 Instance，
|
||||
引用已有 Database 时从资源获取 Instance，不重复声明另一份来源。
|
||||
|
||||
Retain 在申请删除后保留 Database 对象和外部数据，进入 Released，等待管理员处理数据、
|
||||
旧访问权限和凭据后显式授权重新绑定。已有数据库可由管理员显式登记导入，初始验证不改密、
|
||||
不改 owner；发现未知同名资源仍报 Conflict。回收策略位于资源侧，Database 不随 Tenant GC。
|
||||
|
||||
撤销 PostgreSQL ownership registry 和任意 status 丢失自动重建所有权的要求。CR 记录持久
|
||||
身份、绑定和进度；普通失败幂等重试，无法确认外部创建结果时报告足够人工诊断的冲突。
|
||||
不引入 CSI 协议、存储调度或通用 Claim。资源 scope、绑定字段和凭据重新交付协议仍需细化。
|
||||
|
||||
本轮依据为维护者设计讨论和 Ayatori 本地提交
|
||||
`6db8a495fb9f8981d336c9e6288253628ab478b6` 中的
|
||||
`docs/decisions/0009-database-resource-and-claim.md` 与 `docs/database/specification.md`。
|
||||
该提交尚未推送；旧 registry 实现尚未撤除，新三资源链路尚未完成。
|
||||
远端来源链接待发布后补齐，见 [同步记录](../verification.md#ayatori-database-设计修订同步)。
|
||||
|
||||
## 计划中的使用方式
|
||||
|
||||
1. 平台管理员通过 `PostgreSQLInstance` 注册已有 PostgreSQL 实例及管理连接。
|
||||
2. 下游以 namespaced `PostgreSQLTenant` 声明所需 database、login owner 和扩展。
|
||||
3. controller 校验所有权与冲突，幂等创建凭据、role、database 和授权等资源。
|
||||
2. 下游以 namespaced `PostgreSQLTenant` 申请数据库，或显式引用管理员登记的 Database。
|
||||
3. controller 建立独立 Database 记录与排他绑定，供应或验证资源；未知同名及不确定创建报冲突。
|
||||
4. 应用凭据以 OpenBao KV 为事实来源，由 ESO 投射为 Kubernetes Secret。
|
||||
非 Kubernetes 消费者使用提供的 OpenBao API URL，并通过自身授权获取凭据。
|
||||
5. ESO 投射成功且应用凭据实际登录成功后，Tenant 才能进入 Ready。
|
||||
@@ -82,7 +105,8 @@ GitOps、Terraform、kubectl 和未来 Backstage 计划共用这套 Kubernetes A
|
||||
|
||||
- operator 管理实例内的租户资源，不运行 PostgreSQL/OpenBao，也不管理 VM、存储、备份或 OpenBao PKI。
|
||||
- 应用密码写入 OpenBao，不进入 CR、Event 或日志；ESO 负责向 Kubernetes 消费者投射。
|
||||
- 默认删除策略为 `Retain`，删除声明不会默认删除业务数据；显式 `Delete` 需重新校验所有权。
|
||||
- Database 默认 Retain；删除 Tenant 保留资源对象与数据，Released 不自动重新分配。
|
||||
- 资源侧 Delete 需明确授权、finalizer 与实际管理范围检查，导入不隐含删除或改密授权。
|
||||
- 遇到未知 database/role 等资源报告 Conflict，不能自动接管、覆盖或删除；现有数据库迁移需遵循迁移合同。
|
||||
- namespace 是 Kubernetes 身份与 RBAC 边界；database/role 名称在一个 PostgreSQL Instance 内仍全局唯一。
|
||||
|
||||
|
||||
@@ -63,3 +63,14 @@ SPIFFE/SPIRE 按维护者指定，以 [#34](https://git.ddupan.top/panxiao81/hom
|
||||
- Backstage 为计划中的统一入口，不作为已部署服务记录。
|
||||
|
||||
后续出现新的状态问题时，先向维护者对齐，再按授权范围更新对应服务文档。
|
||||
|
||||
## Ayatori Database 设计修订同步
|
||||
|
||||
2026-09-24，维护者批准 Instance → Database → Tenant 资源/申请分离，替代原 PostgreSQL
|
||||
registry 与自动所有权恢复合同。源仓库设计和 wiki 已在本地同步；Ayatori 设计已提交为
|
||||
`6db8a495fb9f8981d336c9e6288253628ab478b6`，本记录随 wiki 设计同步提交，双方尚未推送。
|
||||
新资源 API 与旧实现撤换未完成，不属于部署或现场验证。
|
||||
|
||||
源设计：`/tmp/ayatori-database-domain/docs/decisions/0009-database-resource-and-claim.md`；
|
||||
wiki 权威摘要：[DBaaS 设计](services/postgresql-tenant-operator.md#当前资源模型2026-09-24-已确认)。
|
||||
后续推送/合并后补正式来源链接；旧仓库固定基线及受保护工作树不修改。
|
||||
|
||||
Reference in New Issue
Block a user