From 7b841d7dbaaaf0a1d233ee491d5f2543cf067d96 Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Sun, 20 Sep 2026 19:02:06 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=20API=20machinery=20?= =?UTF-8?q?=E4=B8=8E=E9=A2=86=E5=9F=9F=E6=8E=A7=E5=88=B6=E5=BE=AA=E7=8E=AF?= =?UTF-8?q?=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 13 ++++++++ README.md | 2 +- docs/architecture/overview.md | 22 +++++++++++-- .../0001-kubernetes-api-machinery.md | 31 ++++++++++++++++--- 4 files changed, 61 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c40b995..5a49f7d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,19 @@ - 本仓库是 ddupan.top homelab 的内部基础设施控制平面，不以通用发行版为初期目标。 - 提交、文档和代码注释优先使用中文；公共 API 标识符和代码遵循对应语言惯例。 - 不要重新实现已有成熟后端的核心能力；新增实现前先确认能否通过稳定 API 进行薄适配。 +- Ayatori 复用 Kubernetes 的核心目标是 API machinery：对象存储与并发控制、list/watch、 + informer、RBAC、admission、版本化 API 和审计；不要据此推断 Ayatori 是 Kubernetes + workload 平台，也不要默认复用 Kubernetes 的调度与数据面语义。 +- kube-apiserver 是 Ayatori 的 API 与状态协调平面，不是领域调度器。资源的调度、生命周期、 + 故障恢复、垃圾回收和后端收敛由 Ayatori controllers 实现；新增能力前应明确其属于 API + machinery、Ayatori 领域控制循环还是外部 backend，避免把职责放错层。 +- Kubernetes、OpenSandbox、Proxmox 等均是 Ayatori 的可替换 backend/executor。除管理组件自身 + 的部署外，不得仅因 controller 运行在 Kubernetes 中，就把原生 Pod、Job、Service、 + NetworkPolicy、owner reference 或同 namespace 行为作为领域 API 的隐含语义；需要这些能力时 + 必须由 adapter 契约显式表达，并考虑后端位于其他集群或完全不是 Kubernetes 的情况。 +- 不要以减少自有 controller 数量为目的引入 generic-apiserver、聚合 API Server 或自行实现 + API Server。只有 CRD/kube-apiserver 在存储、API 语义或扩展能力上形成已验证的阻碍时，才评估 + 接管 watch、RBAC、版本兼容和存储迁移等复杂度；controller 工作本身不会因此消失。 - 在自行设计通用控制循环、资源生命周期、调度、回收或故障恢复机制前，先调查 Kubernetes 核心及成熟开源 controller/operator 的实现；优先复用经过验证的模式，并记录有意偏离的 理由。 diff --git a/README.md b/README.md index bc182df..759c7ea 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kube - [执行模型](docs/concepts/execution-model.md) - [环境与发布](docs/concepts/environments.md) - [路线图](docs/roadmap.md) -- [ADR-0001：采用 Kubernetes API 作为资源模型](docs/decisions/0001-kubernetes-api-machinery.md) +- [ADR-0001：采用 Kubernetes API machinery 作为状态协调平面](docs/decisions/0001-kubernetes-api-machinery.md) - [ADR-0002：采用 k0s 与可选工作负载运行时](docs/decisions/0002-k0s-optional-workload-runtime.md) - [ADR-0003：直接连接 Dev API 的开发循环](docs/decisions/0003-dev-api-development-loop.md) diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index fe9655e..723b03b 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -4,9 +4,11 @@ Git / CLI / Backstage │ ▼ - Kubernetes API + CRD + kube-apiserver + etcd + CRD + API / state coordination plane │ - Ayatori controllers + Ayatori controller-manager + scheduling / lifecycle / recovery / GC │ ┌──────┼──────────────┐ │ │ │ @@ -19,6 +21,15 @@ Terraform OpenBao / DNS / KaaS Ansible ``` +Ayatori 复用 Kubernetes 的 API machinery，而不是 Kubernetes 的容器编排产品边界。 +kube-apiserver 提供版本化对象、并发控制、list/watch、RBAC、admission 和审计；Ayatori +controller-manager 承担所有领域控制循环。Kubernetes workload 集群只是与 OpenSandbox、 +Proxmox 等并列的 executor/backend，不默认等于运行 controller 的 management environment。 + +因此，领域 API 不得依赖“资源最终一定变成同集群原生对象”的假设。原生 Pod、Job、Service、 +NetworkPolicy、namespace 共置与 owner reference 只有在 Kubernetes adapter 内才具有原生含义； +跨后端所需能力必须由领域模型显式定义。 + ## 控制面 Dev 与 Prod 使用独立的 Kubernetes API、数据库、身份和 controller 实例。两者可以 @@ -58,3 +69,10 @@ Ayatori 不承载或重新实现数据面。控制面故障只应阻止创建与 Controller 无论采用哪种执行方式，都必须提供一致的 ownership、conditions、删除语义、 错误分类和恢复行为。 + +## API Server 边界 + +首选 kube-apiserver + CRD，持续复用其成熟的 watch、RBAC、版本化存储和 API 生态。 +generic-apiserver 或聚合 API Server 不会减少领域 controller 的数量，只会把资源服务端、 +兼容性和存储迁移责任转移给 Ayatori。只有 CRD 的限制已经形成可复现、不可通过合理领域建模 +解决的阻碍时，才重新评估自建 API Server。 diff --git a/docs/decisions/0001-kubernetes-api-machinery.md b/docs/decisions/0001-kubernetes-api-machinery.md index 4091c69..44eff5f 100644 --- a/docs/decisions/0001-kubernetes-api-machinery.md +++ b/docs/decisions/0001-kubernetes-api-machinery.md @@ -1,4 +1,4 @@ -# ADR-0001：采用 Kubernetes API 作为资源模型 +# ADR-0001：采用 Kubernetes API machinery 作为状态协调平面 - 状态：Accepted - 日期：2026-09-17 @@ -10,16 +10,39 @@ homelab 的基础设施状态分散在多套工具和后端中。仅集中 IaC ## 决策 -Ayatori 使用 Kubernetes API machinery 与 CRD 表达平台资源、引用和状态，但不将平台 -限定为容器编排系统。Controller 可以运行于专用 management environment，并管理集群外 -的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。 +Ayatori 使用 kube-apiserver、etcd、Kubernetes API machinery 与 CRD 构成 API 和状态协调 +平面。主要复用的是以下难以可靠重建的能力： + +- 版本化对象 API、schema、defaulting、validation 与 admission； +- 带 `resourceVersion` 的乐观并发、list/watch 与断线恢复； +- informer/cache/workqueue 生态； +- authentication、RBAC、namespace、审计与 API discovery； +- spec/status、conditions、finalizer 等控制面约定。 + +这项选择不把 Ayatori 限定为容器编排系统，也不意味着原生 Kubernetes workload API 是领域 +模型。kube-apiserver 保存期望、引用和观察状态；Ayatori controller-manager 实现平台领域的 +调度、生命周期、故障恢复、垃圾回收和后端收敛。Controller 可以运行于专用 management +environment，并管理集群外的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。 + +Kubernetes workload 集群与 OpenSandbox、Proxmox 等一样，是通过 adapter 接入的 backend 或 +executor。它可以是远端集群，也可以完全不存在。除 Flux 和 Ayatori controllers 等管理组件的 +部署外，领域 API 不得隐含依赖 controller 所在集群的 Pod、Job、Service、NetworkPolicy、 +namespace 共置或 owner reference 语义；确有需要的能力必须由领域 API 和 adapter 契约显式表达。 GitOps 是长期期望状态的主要提交入口；API 是当前意图、关系和状态的在线控制面；真实后端 仍是运行事实来源。Controller 负责三者之间持续收敛。 +`generic-apiserver` 或 Kubernetes API aggregation 只会让 Ayatori 接管资源的服务端实现，并不会 +替代上述领域 controller。除非 CRD/kube-apiserver 的存储模型、API 语义或扩展边界形成经过验证的 +阻碍，Ayatori 不自行承担 watch、RBAC、API 兼容、存储版本迁移和高可用 API Server 的实现与运维。 + ## 结果 - 获得统一声明式 API、watch、RBAC、admission、conditions 和 controller 生态。 +- Ayatori controller-manager 实际承担类似 kube-controller-manager 的领域控制循环职责，必须把 + reconcile、状态迁移、恢复与后端契约作为产品核心，而不是把它们误交给 kube-apiserver。 +- 原生 Kubernetes workload 对象不能成为所有 adapter 的最低公共语义；Kubernetes 只是其中一种 + 执行后端。 - 可以把机器与人工执行统一建模为异步控制循环。 - 必须维护 CRD 版本、conversion、认证、备份和控制面升级。 - 不在 API 中保存日志、指标、大对象或业务数据，只保存控制所需状态及引用。