5.4 KiB
ADR-0002：采用 k0s 与可选工作负载运行时
- 状态：Accepted
- 日期：2026-09-17
背景
Ayatori 需要 Kubernetes API machinery 提供 CRD、watch、RBAC、admission 和 controller 运行模型，但它并不天然要求在同一环境中调度容器 workload。最小控制面应能够仅作为 基础设施 API 使用。
k0s 的 controller 角色默认不运行 kubelet 或容器运行时，因此控制节点不可被用户调度。 这符合将 Kubernetes API 作为独立控制面运行时的需求。
然而 Ayatori 的完整 GitOps 模式需要运行 Flux controllers；Ayatori controllers、 Crossplane 组件以及 Kubernetes Pod executor 也适合以 Pod 交付。因此正常运行形态仍然 需要工作负载调度能力。
决策
Ayatori 采用 k0s 作为 Kubernetes API/control-plane 发行版，并将工作负载运行时视为 可选部署组件，而不是 API 控制面的固有组成。
定义两种受支持的运行 profile。
API-only
k0s controller-only
├── kube-apiserver
├── control-plane components
└── external controllers/processes
该 profile 不存在可调度 Node，不运行 Flux。它是可选的最小形态，用于 bootstrap、 恢复、API 开发和不需要 in-cluster controller 的特殊部署。
API-only 描述的是运行拓扑，而不是 API 功能子集。其他组件仍可以作为本地进程、systemd 服务、普通容器或远程 Job，通过 kubeconfig 连接该 API。开发者可以使用一个临时的 API-only 实例测试真实 CRD、admission、watch 和 reconcile 行为，而不必先准备 CNI、 worker 与完整 GitOps 环境。
API-only 的主要用途是 CI 中的临时集成环境：每个 job 启动独立的真实 API server，安装 CRD，运行待测试的 controller 二进制，完成后整体销毁。由于不启动 worker、CNI 和容器 runtime，它适合验证 API、watch、admission、reconcile、finalizer 和 status 行为，而不必 为每个测试任务建立完整 Kubernetes workload cluster。
它也可以用于隔离 API 实验、bootstrap 与恢复开发，但不构成独立的长期环境，也不是日常 本地开发的默认路径。日常开发进程直接连接 managed runtime Dev 的 API。Flux、in-cluster service discovery、Pod 调度和 executor 集成仍然必须在 Dev 中验证。
Managed runtime
k0s controller --enable-worker
├── Kubernetes control-plane components
├── Flux
├── Ayatori controllers
├── admission webhooks
└── platform operators
optional execution worker pool
└── Job Pod executor workloads
该 profile 是默认部署形态。k0s controller 使用 --enable-worker 同时运行 kubelet 与
容器 runtime，并注册为带 control-plane label/taint 的 Node。Flux、Ayatori controllers、
admission webhook 和平台 operator 本身就是管理控制面的一部分，应当调度到这些节点。
平台组件必须显式容忍 control-plane taint，并使用 affinity 或 node selector 约束到控制 节点。控制节点不接受普通应用或 Job workload。Job Pod executor 使用独立 execution worker pool；只有显式修改调度策略时才能在控制节点执行短期恢复或诊断任务。
启用 worker 只改变控制节点是否提供 Pod runtime，不改变 API、CRD、数据库与控制面身份。 API-only 与 managed runtime 因而是同一架构的两种运行配置，而不是两种平台实现。
Bootstrap 边界
Flux 无法负责为承载自身的控制节点启用 worker runtime，因此以下部分位于 GitOps 闭环 之外：
- k0s controller 初始安装；
- 控制面数据库和 PKI 恢复；
- control node 的
--enable-worker安装配置； - Flux 首次 bootstrap。
这些步骤必须由可重复执行的 bootstrap 流程管理，例如固定版本的 Ansible、安装脚本或 人工 Runbook。Flux 成功运行后，in-cluster controller、策略和后续 worker 配置进入 GitOps 管理。
平台必须保留从 API-only 恢复到 managed runtime 的流程，避免 Flux 故障形成无法恢复的 自举循环。独立 execution worker 的加入与退出可以在平台正常运行后自动化。
工作负载范围
引入 worker 不改变 Ayatori 的定位。该集群是专用 management environment，而不是通用 应用集群。允许的 workload 默认限于：
- Flux 与平台 controller/operator；
- admission webhook 和必要的控制面辅助组件；
- Job Service 选择 Pod executor 后创建的受管任务；
- 平台恢复和诊断所需的短期 workload。
普通长期应用仍运行在其所属 workload cluster、VM 或其他后端。
结果
- 保留纯 API 控制面的简洁性与恢复价值。
- 能够使用 Flux 完成平台组件的 GitOps 管理。
- 能够直接复用 Kubernetes 生态中的 operator，而无需改写为 systemd 服务。
- 默认不需要为 Flux 和 Ayatori controllers 建立独立 management worker VM。
- 控制节点同时承担平台控制 workload，需要设置资源预留、taint 和调度约束。
- Job 等非控制 workload 仍需要独立 execution worker 或外部执行后端。
- bootstrap 层不能完全由 Flux 自我管理，必须独立记录并验证恢复流程。