docs: 记录 Compute 方向与 Database 模块合并
This commit is contained in:
@@ -32,6 +32,8 @@ Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kube
|
||||
- [ADR-0002：采用 k0s 与可选工作负载运行时](docs/decisions/0002-k0s-optional-workload-runtime.md)
|
||||
- [ADR-0003：直接连接 Dev API 的开发循环](docs/decisions/0003-dev-api-development-loop.md)
|
||||
- [ADR-0006：按实际管理缺口扩展资源 API](docs/decisions/0006-demand-driven-resource-scope.md)
|
||||
- [ADR-0007：复用 Node API 建立按需实现的 Compute 能力](docs/decisions/0007-compute-node-and-vm-boundary.md)
|
||||
- [ADR-0008：将 PostgreSQL Tenant Operator 合并为 Ayatori Database 模块](docs/decisions/0008-merge-postgresql-tenant-operator.md)
|
||||
|
||||
## 当前状态
|
||||
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
# ADR-0007：复用 Node API 建立按需实现的 Compute 能力
|
||||
|
||||
- 状态：Accepted
|
||||
- 日期：2026-09-20
|
||||
- 实施优先级：Deferred；当前优先 Database、LoadBalancer 与 Bucket
|
||||
|
||||
## 背景
|
||||
|
||||
Ayatori 长期可能需要管理现有 Proxmox VM、当前 libvirt VM，以及允许普通计算节点临时加入、
|
||||
排空和退出。Proxmox 的远程 API 不能覆盖全部所需操作；若 Ayatori 进一步实现节点 inventory、
|
||||
简单 placement、fencing 和安全 reschedule，Proxmox 的控制面价值会逐步被替代。
|
||||
|
||||
同一物理节点未来也可能运行 OpenSandbox/Kata 等执行后端。Kata 虽然以 microVM 隔离 Pod 或
|
||||
container，但其公开生命周期是 Sandbox/Run，不是具有磁盘、NIC、console、placement、迁移和
|
||||
长期身份的 VirtualMachine 产品。
|
||||
|
||||
## 决策
|
||||
|
||||
### 节点 API
|
||||
|
||||
Ayatori 选择性复用 `core/v1 Node` 与 `coordination.k8s.io/v1 Lease` 表达计算节点身份、能力、
|
||||
容量、健康、维护状态与心跳。它们只是 API contract：由 Ayatori Compute Agent 写入，并由
|
||||
Ayatori 自有 controller 消费。
|
||||
|
||||
这项选择不引入 kubelet、Pod、CRI、kube-scheduler 或 kube-controller-manager。Compute Agent
|
||||
不是对 kubelet 的模拟或兼容实现，而是 Node API 在 Ayatori Compute 领域中的正式 producer。
|
||||
每个 Node 必须带 Ayatori ownership label；Agent 只能更新自己的 Node/status 与 Lease。
|
||||
|
||||
初版 VirtualMachine 显式指定 Node。出现实际需求后，再由 Ayatori controller 基于 Node 的
|
||||
Ready、unschedulable、taints、labels、capacity 和已有 allocation 实现小规模 filter/score。
|
||||
具体资源分配不能依靠多个 controller 反复改写 `Node.status.allocatable`；需要并发预留时增加
|
||||
独立 Allocation 资源或等价的原子分配记录。
|
||||
|
||||
### VM 数据面
|
||||
|
||||
长期主路径可以是普通 Linux Compute Node 上的 libvirt/QEMU，由受限的 Compute Agent 执行
|
||||
版本化、强类型、幂等且可观察的 VM 操作。Agent 不提供任意远程 shell。
|
||||
|
||||
Proxmox 是 brownfield 迁移后端：初期用于 adopt 现有 VM，并继续提供当前已有的集群、存储、
|
||||
备份与 HA 能力。若 Ayatori Compute 已经可靠覆盖所需 placement、fencing、存储可移植性和恢复
|
||||
语义，可以逐步把 PVE 节点迁移为普通 Compute Node；不为维持虚假 backend 对等性承诺永久支持
|
||||
所有 Proxmox 特性。
|
||||
|
||||
### HA 边界
|
||||
|
||||
自动 reschedule 必须满足：旧节点已经可靠 fenced，且 Volume 明确报告可在目标节点使用。
|
||||
任一条件无法证明时，VM 进入 Blocked/ManualTask，不得冒险在第二个节点启动。首版允许完全
|
||||
人工 placement 与恢复；不以通用 Placement、透明 live migration、多租户 SDN 或 Nova 兼容为目标。
|
||||
|
||||
### Sandbox 边界
|
||||
|
||||
OpenSandbox/Kata microVM 归属于 Run/Sandbox backend 的隔离实现，不创建 VirtualMachine 资源。
|
||||
若未来 VM 与 Sandbox 共享物理节点，容量协调必须另行形成经过验证的设计；不能仅因两者底层
|
||||
都使用 KVM 就合并其北向生命周期。
|
||||
|
||||
## 结果
|
||||
|
||||
- 复用成熟 Node/Lease API，而不继承 Kubernetes workload plane。
|
||||
- Compute 能力可以按 homelab 所需规模实现，不必复制完整 Nova。
|
||||
- PVE 帮助现有资源平滑迁移，但不是长期架构必须保留的一层。
|
||||
- Compute 方向已记录，但不改变当前 Database、LoadBalancer、Bucket 的产品优先级。
|
||||
@@ -0,0 +1,65 @@
|
||||
# ADR-0008：将 PostgreSQL Tenant Operator 合并为 Ayatori Database 模块
|
||||
|
||||
- 状态：Accepted
|
||||
- 日期：2026-09-20
|
||||
|
||||
## 背景
|
||||
|
||||
独立仓库 `postgresql-tenant-operator` 已经为 homelab 共享 PostgreSQL 设计了
|
||||
`PostgreSQLInstance` 与 `PostgreSQLTenant` API，并包含批准的行为规格、领域值对象、状态机、
|
||||
PostgreSQL ownership registry、OpenBao/External Secrets 边界、迁移与恢复文档及测试。
|
||||
|
||||
Database 是 Ayatori 当前最优先的真实管理缺口之一。继续把该 controller 作为独立产品，会重复
|
||||
维护 manager、API machinery、发布、认证、可观测性和通用 controller 约定，也会使后续应用组合
|
||||
必须跨两个控制平面理解状态。
|
||||
|
||||
源仓库当前实现仍在按规格逐片完成，部分生成的 CRD/API 代码落后于批准规范；迁移不能把当前
|
||||
工作树或全部脚手架原样复制到 Ayatori。
|
||||
|
||||
## 决策
|
||||
|
||||
PostgreSQL Tenant Operator 合并为 Ayatori 的 Database 领域模块。保留已经批准且仍适用的外部
|
||||
行为，不重新发明 database、role、credential、ownership 和删除语义。
|
||||
|
||||
目标结构遵守 Ayatori 的模块化单体边界：
|
||||
|
||||
```text
|
||||
api/database/v1alpha1/
|
||||
internal/database/domain/
|
||||
internal/database/controller/
|
||||
internal/database/adapter/postgresql/
|
||||
internal/database/adapter/openbao/
|
||||
internal/database/adapter/externalsecrets/
|
||||
docs/database/
|
||||
```
|
||||
|
||||
最终目录可按 Kubebuilder 与现有模块约定微调，但 Database 不依赖 execution/Job 模块，也不把
|
||||
PostgreSQL、OpenBao 或 External Secrets 客户端放入共享万能 service/repository 层。
|
||||
|
||||
首轮迁移保留现有 `database.ddupan.top/v1alpha1` API group，避免仅为仓库归属制造无收益的 API
|
||||
重命名。迁移前逐项核对批准规格与当前 Go types；冲突时以批准规格为基线，并在 Ayatori 中记录
|
||||
任何有意改变。数据库尚未实际由该 operator 纳管，因此不需要执行已部署 CRD 的在线 conversion。
|
||||
|
||||
## 迁移方式
|
||||
|
||||
1. 等源仓库当前未提交的 Instance 工作形成可引用 commit；迁移期间不读取或复制脏工作树作为
|
||||
权威实现。
|
||||
2. 记录 source commit，并先迁移规范、领域模型和纯单元测试；保持行为与测试可追溯。
|
||||
3. 在 Ayatori multi-group 项目中用 Kubebuilder 注册 Database API，按批准规格迁移 types，重新
|
||||
生成 CRD、DeepCopy 与 RBAC；不直接复制旧生成文件或旧 `PROJECT`。
|
||||
4. 将依赖升级到 Ayatori 当前 Go、Kubernetes 与 controller-runtime 版本，并先迁移 PostgreSQL
|
||||
registry/adapter contract tests。
|
||||
5. 逐片迁移 Instance observe、Tenant provisioning、OpenBao、ExternalSecret、删除与恢复流程；
|
||||
每片必须包含对应单元、envtest 和真实 PostgreSQL/OpenBao 集成测试。
|
||||
6. Ayatori 中的 Database 模块达到原项目验收标准并完成迁移演练后，冻结旧仓库并将其 README
|
||||
指向 Ayatori；不同时运行两个 controller 管理同一组 CR。
|
||||
|
||||
不通过一次性 unrelated-history merge 或整仓复制保留表面上的 Git 历史。旧仓库和 source commit
|
||||
保留完整来源历史；Ayatori 迁移提交按可审阅行为切片记录 provenance。
|
||||
|
||||
## 结果
|
||||
|
||||
- Ayatori 获得第一个真实产品领域，而不是继续围绕实验性 Job 扩张。
|
||||
- 已批准的 DBaaS 设计与测试投资得到保留。
|
||||
- 单一 manager/release 不意味着领域耦合；Database 仍保持独立 package、adapter 和测试边界。
|
||||
- 在源仓库当前并行工作提交前，只进行文档与迁移准备，不移动其代码。
|
||||
+1
-1
@@ -34,7 +34,7 @@
|
||||
|
||||
- 建立稳定的 `VirtualMachine` 北向 API，并支持现有资源 adopt。
|
||||
- 南向按能力组合 Proxmox API、节点受限 Agent/CLI 与 `ManualTask`，不假设 Proxmox API 完整。
|
||||
- ComputeNode 加入、drain 和 `SafeToRemove`。
|
||||
- Node 加入、drain 和 `SafeToRemove`；Node API 由 Ayatori Compute Agent 实现，不依赖 kubelet。
|
||||
- StorageClass、StoragePool、Volume 与迁移计划。
|
||||
- 先支持人工磁盘迁移，再按实际收益自动化。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user