diff --git a/architecture/ayatori-control-plane.md b/architecture/ayatori-control-plane.md new file mode 100644 index 0000000..2970785 --- /dev/null +++ b/architecture/ayatori-control-plane.md @@ -0,0 +1,29 @@ +--- +title: Ayatori 控制面边界 +last_reviewed: 2026-09-20 +--- + +# Ayatori 控制面边界 + +Ayatori 是规划和早期实现中的 homelab 基础设施控制平面。它使用 kube-apiserver、etcd、CRD +和 Kubernetes API machinery 作为版本化 API 与状态协调平面，主要复用对象并发控制、 +list/watch、informer、RBAC、admission、审计和 API 版本机制，而不是复用 Kubernetes 的容器 +编排产品边界。 + +Ayatori controller-manager 负责领域资源的调度、生命周期、故障恢复、垃圾回收和后端收敛。 +这部分职责近似 Kubernetes 的 controller-manager，但面向 VM、LB、数据库、对象存储、任务、 +托管 Kubernetes 和人工操作等 Ayatori 领域。 + +Kubernetes workload 集群只是与 OpenSandbox、Proxmox 等并列的 backend/executor，可能位于 +远端，也可能在某个部署 profile 中不存在。除 Flux、Ayatori controllers 等管理组件的部署外， +领域 API 不得默认依赖同集群 Pod、Job、Service、NetworkPolicy、namespace 共置或 owner +reference；跨后端能力必须由领域 API 和 adapter 契约明确表达。 + +当前选择继续使用 kube-apiserver + CRD。generic-apiserver 或聚合 API Server 不会替代领域 +controller，只会让项目额外接管资源服务端、watch、RBAC、API 兼容和存储迁移责任。只有 CRD +或 kube-apiserver 的限制形成经过验证的阻碍时，才重新评估自建 API Server。 + +详细设计以 Ayatori 仓库的 +[ADR-0001](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/decisions/0001-kubernetes-api-machinery.md) +和[总体架构](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/architecture/overview.md)为准。 +本页记录跨 homelab 的稳定边界，不表示 Ayatori 已部署或达到生产可用状态。 diff --git a/architecture/constraints.md b/architecture/constraints.md index 72bf24f..34d775e 100644 --- a/architecture/constraints.md +++ b/architecture/constraints.md @@ -1,10 +1,12 @@ # 架构约束索引 -审阅日期：2026-09-16。以下是现有仓库明确记录的约束摘要，不是本轮新增的架构决策。 -来源路径相对于 homelab-infra；修改时必须读原文和对应代码，新出现的差异先向维护者确认；[首轮状态对齐](../verification.md)已完成。 +审阅日期：2026-09-20。以下是现有仓库明确记录的约束摘要；Ayatori 条目来自其独立项目的 +已接受设计，其余来源路径相对于 homelab-infra。修改时必须读原文和对应代码，新出现的差异 +先向维护者确认；[首轮状态对齐](../verification.md)已完成。 | 约束 | 原因与边界 | 来源 | |---|---|---| +| Ayatori 复用 Kubernetes API machinery，不复用其容器编排产品边界 | kube-apiserver/etcd 提供 API、watch、RBAC 与状态协调；领域调度、生命周期、恢复和 GC 属于 Ayatori controllers；Kubernetes workload 只是可替换 backend | [Ayatori 控制面边界](ayatori-control-plane.md) | | 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` | diff --git a/guides/task-index.md b/guides/task-index.md index 13e453d..deef7f2 100644 --- a/guides/task-index.md +++ b/guides/task-index.md @@ -1,6 +1,6 @@ --- title: 按任务查找文档 -last_reviewed: 2026-09-18 +last_reviewed: 2026-09-20 --- # 按任务查找文档 @@ -10,6 +10,7 @@ last_reviewed: 2026-09-18 | 要做什么 | 先读 | 需要时再读 | |---|---|---| +| 设计或实现 Ayatori 控制面能力 | [Ayatori 控制面边界](../architecture/ayatori-control-plane.md) | Ayatori 仓库 ADR、对应领域 API 与 adapter 文档 | | 发布新的 LAN Web 服务 | [发布新服务](publish-service.md) | [DNS](../services/lan-dns.md)、[Authelia](../services/authelia.md) | | 写 CI 或选择 Pod/VM runner | [Gitea / Actions](../services/gitea.md) | [Dynamic Runner](../services/gitea-dynamic-runner.md)、[SPIFFE](../services/spire.md) | | 为 CI 缓存 Ansible/Go 依赖 | [Nexus POC](../services/nexus.md) | [Dynamic Runner](../services/gitea-dynamic-runner.md)、[OpenBao](../services/openbao.md) |