docs: define Ayatori platform vision
This commit is contained in:
+16
@@ -0,0 +1,16 @@
|
|||||||
|
# Build output
|
||||||
|
/bin/
|
||||||
|
/dist/
|
||||||
|
/coverage/
|
||||||
|
|
||||||
|
# Local configuration and credentials
|
||||||
|
.env
|
||||||
|
.env.*
|
||||||
|
*.kubeconfig
|
||||||
|
*.key
|
||||||
|
*.pem
|
||||||
|
|
||||||
|
# Editor and OS files
|
||||||
|
.idea/
|
||||||
|
.vscode/
|
||||||
|
.DS_Store
|
||||||
@@ -0,0 +1,10 @@
|
|||||||
|
# Agent Notes
|
||||||
|
|
||||||
|
- 本仓库是 ddupan.top homelab 的内部基础设施控制平面，不以通用发行版为初期目标。
|
||||||
|
- 提交、文档和代码注释优先使用中文；公共 API 标识符和代码遵循对应语言惯例。
|
||||||
|
- 不要重新实现已有成熟后端的核心能力；新增实现前先确认能否通过稳定 API 进行薄适配。
|
||||||
|
- 不要引入统一包装所有能力的 Application CRD；应用应直接组合正交的平台资源。
|
||||||
|
- 所有 controller 必须考虑幂等、observe、finalizer、conditions、删除策略和恢复行为。
|
||||||
|
- Secret、token、kubeconfig 及具体生产凭据不得提交到仓库。
|
||||||
|
- `deploy/dev/` 与 `deploy/prod/` 使用相同制品；生产版本只通过 promotion 更新。
|
||||||
|
- 内部专用不构成降低测试、版本、恢复、安全和可审计要求的理由。
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
# Ayatori
|
||||||
|
|
||||||
|
> Infrastructure, woven by intent.
|
||||||
|
> 意図から、インフラを編む。
|
||||||
|
|
||||||
|
Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kubernetes API
|
||||||
|
作为统一资源模型，通过薄适配器组合成熟后端，并让机器执行器与人工操作共同推动
|
||||||
|
实际状态持续收敛到声明的期望状态。
|
||||||
|
|
||||||
|
本仓库公开源代码，但当前只面向一个确定的内部环境。它不是通用私有云发行版，暂不
|
||||||
|
承诺开箱即用、后端可替换性或面向第三方的兼容性。
|
||||||
|
|
||||||
|
## 核心原则
|
||||||
|
|
||||||
|
- 内部专用只缩小需求与兼容范围，不降低软件工程质量。
|
||||||
|
- 优先采用可以立即投入使用的成熟后端，不重新实现复杂的数据面。
|
||||||
|
- 平台统一入口、策略、组合、状态与生命周期；后端保留领域实现。
|
||||||
|
- 应用通过 GitOps 直接组合正交的平台原语，不引入 `ApplicationService` 上帝控制器。
|
||||||
|
- Pod、OpenSandbox、Terraform、Ansible 和人都可以成为 executor。
|
||||||
|
- 暂时不能自动化的操作必须被建模、追踪并验证，而不是遗落在文档和记忆中。
|
||||||
|
- 控制面中断不得破坏已运行的数据面。
|
||||||
|
|
||||||
|
## 文档
|
||||||
|
|
||||||
|
- [产品愿景](docs/vision.md)
|
||||||
|
- [总体架构](docs/architecture/overview.md)
|
||||||
|
- [API 设计原则](docs/concepts/api-design.md)
|
||||||
|
- [执行模型](docs/concepts/execution-model.md)
|
||||||
|
- [环境与发布](docs/concepts/environments.md)
|
||||||
|
- [路线图](docs/roadmap.md)
|
||||||
|
- [ADR-0001：采用 Kubernetes API 作为资源模型](docs/decisions/0001-kubernetes-api-machinery.md)
|
||||||
|
|
||||||
|
## 当前状态
|
||||||
|
|
||||||
|
Ayatori 处于设计与早期实现阶段。第一个纵向切片计划是统一 Job API 与 Kubernetes
|
||||||
|
Pod executor，随后接入 OpenSandbox executor。
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
@@ -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。
|
||||||
|
- 不要求所有人工步骤立即自动化。
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
Reference in New Issue
Block a user