docs: define Ayatori platform vision
This commit is contained in:
@@ -0,0 +1,60 @@
|
||||
# 总体架构
|
||||
|
||||
```text
|
||||
Git / CLI / Backstage
|
||||
│
|
||||
▼
|
||||
Kubernetes API + CRD
|
||||
│
|
||||
Ayatori controllers
|
||||
│
|
||||
┌──────┼──────────────┐
|
||||
│ │ │
|
||||
Machine Human Direct adapters
|
||||
runner runner │
|
||||
│ │ │
|
||||
Pod Runbook Proxmox / Envoy / BGP
|
||||
OpenSandbox PostgreSQL / SeaweedFS
|
||||
Terraform OpenBao / DNS / KaaS
|
||||
Ansible
|
||||
```
|
||||
|
||||
## 控制面
|
||||
|
||||
Dev 与 Prod 使用独立的 Kubernetes API、数据库、身份和 controller 实例。两者可以
|
||||
共享物理宿主，但不能只依赖 namespace 隔离 cluster-scoped API 与高权限凭据。
|
||||
|
||||
Proxmox 作为稀缺物理基础设施可以共享，通过 pool、tag、token 和明确的资源范围区分
|
||||
环境。其他后端尽量使用独立数据库、角色、地址池、DNS 空间与凭据。
|
||||
|
||||
## 数据面
|
||||
|
||||
Ayatori 不承载或重新实现数据面。控制面故障只应阻止创建与变更，不应停止已有 VM、
|
||||
负载均衡、数据库、对象存储或租户 Kubernetes 集群。
|
||||
|
||||
## 资源分层
|
||||
|
||||
平台提供正交产品能力，例如：
|
||||
|
||||
- `Job`、`Sandbox`、`ManualTask`
|
||||
- `VirtualMachine`
|
||||
- `LoadBalancer`
|
||||
- `Database`
|
||||
- `Bucket`
|
||||
- `DNSRecord`
|
||||
- `Credential`
|
||||
- `KubernetesCluster`
|
||||
|
||||
只有具备独立领域生命周期的能力才应成为高阶资源。应用本身通过 GitOps 组合上述资源，
|
||||
重复组合可通过模板或 Composition 表达，而不是扩展中央 Application API。
|
||||
|
||||
## 后端策略
|
||||
|
||||
优先级如下：
|
||||
|
||||
1. 直接调用成熟且可观察的后端 API。
|
||||
2. 通过固定版本的 Terraform module 或 Ansible playbook 执行。
|
||||
3. 仅在必要时使用 GitOps bridge。
|
||||
|
||||
Controller 无论采用哪种执行方式，都必须提供一致的 ownership、conditions、删除语义、
|
||||
错误分类和恢复行为。
|
||||
@@ -0,0 +1,39 @@
|
||||
# API 设计原则
|
||||
|
||||
## 合理抽象
|
||||
|
||||
API 应当比后端简单，但不能剥夺自用场景真正需要的控制力。
|
||||
|
||||
- 用户主动做出的资源决策进入产品 API。
|
||||
- 平台稳定的运维策略进入 Profile、Class 或 Policy。
|
||||
- 能够稳定推导的机械参数由 adapter 生成。
|
||||
- 罕见但合理的特殊需求使用受控 override。
|
||||
- 解析结果、外部 ID 和后端摘要通过只读 status 展示。
|
||||
|
||||
例如 VM 用户可以指定 CPU、内存、磁盘、存储、镜像和逻辑网络；QEMU machine type、
|
||||
cloud-init 设备、bridge/VLAN 映射和默认 placement 由平台维护。
|
||||
|
||||
## 不做虚假可移植性
|
||||
|
||||
允许 API 表达当前真实后端的有用能力，但不接受任意 `rawConfig` 透传。未来出现第二个
|
||||
真实实现时，根据已经观察到的共同语义抽象，而不是预先猜测最低公分母。
|
||||
|
||||
## 引用与依赖
|
||||
|
||||
- 使用 typed reference 表达资源依赖，不复制动态地址和外部 ID。
|
||||
- 被引用资源暂时不存在或未 Ready 时，controller 应等待而不是要求 apply 顺序。
|
||||
- 长期依赖通过 API 关系推导；Flux `dependsOn` 只用于确实需要的提交顺序。
|
||||
|
||||
## 生命周期基线
|
||||
|
||||
所有受管资源必须定义：
|
||||
|
||||
- `observedGeneration`
|
||||
- 结构化 `status.conditions`
|
||||
- ownership 与外部资源标识
|
||||
- finalizer 与删除策略
|
||||
- import/adopt/observe 行为
|
||||
- controller 重启后的恢复行为
|
||||
- 可重试错误与需要人工介入错误的区别
|
||||
|
||||
对数据库、bucket、持久磁盘等资源，默认删除行为必须保守并显式表达。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 环境与发布
|
||||
|
||||
Ayatori 从第一天维护 Dev 与 Prod 两套控制面，因为首个稳定产品能力会立即承载真实服务，
|
||||
同时后续能力仍需要破坏性集成测试。
|
||||
|
||||
```text
|
||||
source commit
|
||||
↓
|
||||
immutable artifact
|
||||
↓
|
||||
Dev deployment + integration tests
|
||||
↓
|
||||
promotion review
|
||||
↓
|
||||
Prod deployment of the same artifact
|
||||
```
|
||||
|
||||
不维护长期漂移的环境分支。Git 中分别声明 Dev 与 Prod 当前采用的不可变制品版本或 digest。
|
||||
|
||||
Dev 应连接真实后端，但使用独立身份、地址空间和资源范围。Dev 凭据在后端权限层面不应
|
||||
具备修改 Prod 资源的能力。
|
||||
|
||||
当前手工管理的基础设施视为 legacy 数据面，由 Prod 逐项 import/adopt 或替换；它不是
|
||||
第三套 Ayatori 控制面。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 执行模型
|
||||
|
||||
Ayatori 将执行者统一视为具有不同能力与延迟特性的 executor。
|
||||
|
||||
```text
|
||||
Action
|
||||
├── Machine executor
|
||||
│ ├── Kubernetes Pod
|
||||
│ ├── OpenSandbox
|
||||
│ ├── Terraform
|
||||
│ └── Ansible
|
||||
└── Human executor
|
||||
└── Versioned Runbook
|
||||
```
|
||||
|
||||
## Job 与 Sandbox
|
||||
|
||||
`Job` 表达一次有限时长、有退出结果的批处理。第一执行后端是 Kubernetes Pod，第二
|
||||
执行后端通过 OpenSandbox API 获得强隔离环境。调用者表达资源、隔离与 capability
|
||||
需求，由调度策略选择后端。
|
||||
|
||||
`Sandbox` 表达带 TTL 的交互环境，可提供 shell、文件、快照或临时 endpoint。它与
|
||||
`Job` 共享镜像、资源、网络、凭据和回收能力，但具有不同生命周期，不合并为带大量
|
||||
互斥字段的上帝资源。
|
||||
|
||||
## 人工执行
|
||||
|
||||
无法自动化的步骤使用 `ManualTask` 建模：
|
||||
|
||||
```text
|
||||
Pending → Claimed → InProgress → Reported → Verifying → Succeeded
|
||||
```
|
||||
|
||||
通知 controller watch 待处理任务，并发送到 Telegram、Email 或 UI。人依据绑定版本的
|
||||
Runbook 操作后提交 `TaskReport`；人只报告执行结果，不直接宣告系统状态成功。
|
||||
|
||||
验证 controller 必须 observe 后端并验证证据，验证成功后更新 status，上游 reconcile
|
||||
自然继续。人工步骤因此是高延迟异步处理，而不是控制面之外的黑洞。
|
||||
|
||||
## 自动化演进
|
||||
|
||||
人工任务未来可以替换为机器 Job，但上游工作流不应改变：
|
||||
|
||||
```text
|
||||
executor: Human → executor: Job
|
||||
```
|
||||
|
||||
平台优先做到任务可建模、可通知、可追踪、可验证和可恢复，再逐步降低人工参与。
|
||||
@@ -0,0 +1,25 @@
|
||||
# ADR-0001：采用 Kubernetes API 作为资源模型
|
||||
|
||||
- 状态：Accepted
|
||||
- 日期：2026-09-17
|
||||
|
||||
## 背景
|
||||
|
||||
homelab 的基础设施状态分散在多套工具和后端中。仅集中 IaC 文件不能提供持续观察、依赖
|
||||
关系、异步状态、漂移纠正和人工任务协调。
|
||||
|
||||
## 决策
|
||||
|
||||
Ayatori 使用 Kubernetes API machinery 与 CRD 表达平台资源、引用和状态，但不将平台
|
||||
限定为容器编排系统。Controller 可以运行于专用 management environment，并管理集群外
|
||||
的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。
|
||||
|
||||
GitOps 是长期期望状态的主要提交入口；API 是当前意图、关系和状态的在线控制面；真实后端
|
||||
仍是运行事实来源。Controller 负责三者之间持续收敛。
|
||||
|
||||
## 结果
|
||||
|
||||
- 获得统一声明式 API、watch、RBAC、admission、conditions 和 controller 生态。
|
||||
- 可以把机器与人工执行统一建模为异步控制循环。
|
||||
- 必须维护 CRD 版本、conversion、认证、备份和控制面升级。
|
||||
- 不在 API 中保存日志、指标、大对象或业务数据，只保存控制所需状态及引用。
|
||||
@@ -0,0 +1,64 @@
|
||||
# 路线图
|
||||
|
||||
路线图按能够立即产生价值的纵向切片推进，而不是先构建完整通用框架。
|
||||
|
||||
## 0. 平台基础
|
||||
|
||||
- 建立 Dev 与 Prod API/control plane。
|
||||
- 建立认证、RBAC、OpenBao 凭据和备份恢复。
|
||||
- 定义 API、conditions、ownership 和 executor 公共约定。
|
||||
- 建立不可变制品与 Dev 到 Prod promotion。
|
||||
|
||||
## 1. Job Service
|
||||
|
||||
- 实现最小 `Job` API。
|
||||
- Kubernetes Pod executor。
|
||||
- 统一日志、退出状态、超时、workspace、cache 与 artifact。
|
||||
- 接入 Gitea Actions 和平台内部 IaC 执行。
|
||||
|
||||
## 2. OpenSandbox Executor
|
||||
|
||||
- 通过 OpenSandbox lifecycle 与 execd API 创建、执行和清理 sandbox。
|
||||
- 支持强隔离任务、未知代码、嵌套容器和 AI agent。
|
||||
- 增加交互式 `Sandbox` API、TTL、endpoint 与 snapshot。
|
||||
|
||||
## 3. Human Executor
|
||||
|
||||
- `ManualTask`、`TaskReport` 和版本化 Runbook。
|
||||
- Telegram/Email 通知、领取、提醒和升级。
|
||||
- 后端验证与上游 reconcile 恢复。
|
||||
|
||||
## 4. LBaaS
|
||||
|
||||
- Envoy 配置/xDS adapter。
|
||||
- 健康检查与 GoBGP 路由宣告。
|
||||
- 固定 VIP、listener/backend 引用和故障恢复。
|
||||
|
||||
## 5. Compute 与节点生命周期
|
||||
|
||||
- Proxmox VM adapter 与现有资源 adopt。
|
||||
- ComputeNode 加入、drain 和 `SafeToRemove`。
|
||||
- StorageClass、StoragePool、Volume 与迁移计划。
|
||||
- 先支持人工磁盘迁移，再通过 Job executor 自动化。
|
||||
|
||||
## 6. 数据服务
|
||||
|
||||
- PostgreSQL database/role/credential。
|
||||
- SeaweedFS bucket/policy/credential。
|
||||
- DNS 与证书资源。
|
||||
|
||||
## 7. KaaS
|
||||
|
||||
- 采用成熟 hosted-control-plane 后端。
|
||||
- 组合控制面、worker、LB、DNS、网络和凭据。
|
||||
- 用户集群只暴露 worker node，控制面完全由平台托管。
|
||||
|
||||
## 首个业务里程碑
|
||||
|
||||
完成 Laptop Rebuild Readiness：
|
||||
|
||||
1. 临时节点加入。
|
||||
2. laptop 上的 workload 被重建、迁移或形成可执行人工任务。
|
||||
3. laptop 达到 `SafeToRemove=True`。
|
||||
4. laptop 重装并重新加入。
|
||||
5. 临时节点排空并安全退出。
|
||||
@@ -0,0 +1,38 @@
|
||||
# 产品愿景
|
||||
|
||||
## 问题
|
||||
|
||||
当前 homelab 的期望状态散落在 Kubernetes manifests、Terraform state、Ansible、
|
||||
Proxmox、libvirt、OpenBao、DNS、对象存储以及人工文档中。即使每一部分分别实现
|
||||
IaC，跨系统变更仍需要人工安排顺序、复制状态并确认结果，容易产生遗漏、错误和漂移。
|
||||
|
||||
文档不能成为运行状态的权威来源：它只能解释设计和操作背景，无法持续观察现实并纠偏。
|
||||
|
||||
## 目标
|
||||
|
||||
Ayatori 提供统一、声明式、可组合的基础设施 API：
|
||||
|
||||
1. Git 保存经过 review 的长期期望状态。
|
||||
2. Kubernetes API 保存当前意图、资源关系与状态摘要。
|
||||
3. Controller 将请求翻译给成熟后端，并持续 observe/reconcile。
|
||||
4. 机器和人通过统一任务协议执行动作。
|
||||
5. 后端保存实际运行状态，数据面在控制面不可用时继续工作。
|
||||
|
||||
平台成功的直接标准是：新增 workload 时，使用者只需考虑它需要哪些资源，而不再回忆
|
||||
需要依次修改哪些系统、文件和文档。
|
||||
|
||||
## 产品定位
|
||||
|
||||
Ayatori 是具有产品质量的内部平台，而非初期即面向公众的通用私有云。源码公开不等于
|
||||
承担未知部署环境、任意后端和第三方兼容性的成本。
|
||||
|
||||
平台允许对当前环境形成明确意见：Proxmox、OpenSandbox、Envoy、GoBGP、OpenBao、
|
||||
PostgreSQL、SeaweedFS、Samba AD DNS、Cloudflare 和 Flux 都可以是已知实现。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不替代 hypervisor、microVM runtime、数据库、对象存储或网络协议栈。
|
||||
- 不从第一天构建通用 provider/plugin ABI。
|
||||
- 不以隐藏全部后端信息或制造虚假多云可移植性为目标。
|
||||
- 不创建理解所有应用需求的中央 Application controller。
|
||||
- 不要求所有人工步骤立即自动化。
|
||||
Reference in New Issue
Block a user