photoncloud-monorepo/plans/nixos-deployment-scheduler-roadmap-2026-03-20.md

# NixOS Deployment / Scheduler Roadmap (2026-03-20)

## 背景

このリポジトリにはすでに次の材料がある。

- `NixOS` モジュール群: 各サービスの systemd 化とテストクラスタ構成
- `deployer`: bare metal/bootstrap 用の phone-home と node inventory
- `deployer-ctl`: ChainFire 上の cluster desired state を apply する CLI
- `fleet-scheduler`: native service の配置決定
- `node-agent`: 各ノードで process/container を reconcile
- `plasmavmc` / `k8shost`: VM と Pod の個別スケジューラ

ただし、これらがまだ 1 本の「Nix から始まるデプロイ経路」になっていない。

現状は、

- `Nix` で host configuration を作る経路
- `deployer-ctl` の YAML/JSON で cluster state を入れる経路
- `deployer` の phone-home で node を登録する経路
- `fleet-scheduler` / `node-agent` で native service を動かす経路

が並立していて、単一正本と責務境界がまだ弱い。

## いま見えている重要な不足

### 1. `Nix` が単一正本になっていない

- `plasmacloud-cluster.nix` / `nix-nos` / `deployer-ctl` の `ClusterStateSpec` が並立している
- static topology をどこで持つかが定まっていない
- node class / pool / enrollment rule / service schedule が Nix から一気通貫で生成されていない

### 2. bootstrap はあるが「NixOS を適用する agent」がない

- `deployer` は `nix_profile` を返せる
- しかし bootstrap ISO は `node-config.json` の `hostname` / `ip` しか実質使っていない
- `node-agent` は process/container 用であり、NixOS generation を apply しない

つまり、`NixOS deployment` と `runtime scheduling` が別々で、間をつなぐ node-side reconciler が存在しない。

### 3. ISO / netboot が generic bootstrap になり切っていない

- ISO は `node01|node02|node03` と `nix/nodes/vm-cluster/$NODE_ID` に寄っている
- real bare metal 用の node class / profile / disk layout 選択器としてはまだ固定的
- `cloud-init` endpoint はあるが、本流はまだ「Nix native bootstrap API」ではない

### 4. `first-boot-automation` は設計途中で本流に乗っていない

- モジュールはあるが実利用配線が薄い
- ChainFire / FlareDB / IAM bootstrap の責務が中途半端
- 現状の main path は `initialPeers` と固定 node 定義で成立しており、ここは未整理

### 5. scheduler の層分離がまだ曖昧

- `fleet-scheduler`: native service 配置
- `plasmavmc`: VM 配置
- `k8shost`: Pod 配置

この 3 つは全部「scheduler」だが、対象が違う。
それぞれの責務を意図的に分離しないと、NixOS 配備責務まで混ざる。

### 6. MaaS 代替としては inventory / commissioning がまだ弱い

- machine-id と enrollment rule はある
- しかし hardware facts, NIC facts, disk facts, BMC/Redfish, power cycle, reprovision, rescue の層は未整備

MaaS を本当に置き換えるなら、少なくとも commission/inventory/reinstall/power の最小セットが必要。

### 7. CI が bootstrap 経路の閉じ方を保証していない

- CI は主に build / fmt / clippy / unit test
- `deployer` + `fleet-scheduler` + `node-agent` + `test-cluster` の end-to-end は publishable gate になっていない

## 目標アーキテクチャ

### 原則

`Nix` を static desired state の単一正本にする。  
動的な reconcile は PhotonCloud の各 agent / control plane に任せる。

分け方は以下。

### 1. Static layer: `Nix`

ここで定義するもの:

- cluster / datacenter / rack / VLAN / BGP / IP pool
- node class / pool / hardware policy
- bootstrap seed set
- disk layout policy
- host profile
- native service の desired policy
- install image / bootstrap image の生成

`Terraform` の static な部分はここで置き換える。

### 2. Bootstrap layer: `deployer`

ここでやること:

- node discovery
- enrollment rule による class/pool/profile 決定
- machine-id/MAC/DMI 等と node-id の束縛
- install-time secrets / SSH host key / TLS 発行
- install plan の返却

`cloud-init` / `MaaS` の bootstrap 部分をここで置き換える。

### 3. Node system reconcile layer: 新しい `nix-agent` 相当

ここでやること:

- desired NixOS generation / flake attr / closure を受け取る
- closure を取得
- `switch-to-configuration` を実行
- activation 成功/失敗を report
- 世代 rollback と health gating

ここがない限り、NixOS デプロイは phone-home 後に止まる。

これは既存 `node-agent` の責務とは別物なので、最初は別 agent に分ける方が安全。

### 4. Native runtime layer: `fleet-scheduler` + `node-agent`

ここでやること:

- stateless / movable な native service を worker pool 上に配置
- process/container の desired state を ChainFire に書く
- node-agent が実行と health を担う

`Kubernetes Deployment/DaemonSet/Service` のうち、PhotonCloud 自前 native service 用の部分をここで置き換える。

### 5. Tenant workload layer: `plasmavmc` / `k8shost`

ここは別 scheduler のままでよい。

- VM は `plasmavmc`
- Pod は `k8shost`

これらは NixOS host deployment とは分離して扱う。

## やるべきこと

### Phase 0: 単一正本を決める

最優先はここ。

1. `Nix` を cluster source of truth に固定する
2. `deployer-ctl` の YAML/JSON は hand-written ではなく `Nix` から生成する
3. `plasmacloud-cluster` と `nix-nos` の重複生成ロジックを統一する

推奨:

- `nix/lib/cluster-schema.nix` を作る
- そこから次を生成する
  - `nixosConfigurations.<node>`
  - bootstrap 用 install plan
  - `ClusterStateSpec` 相当の JSON
  - test-cluster 用 topology

### Phase 1: generic bootstrap を完成させる

1. ISO / netboot を node 固定実装から profile/class ベースへ変更する
2. `deployer` の返却値を `node-config` ではなく `install-plan` に寄せる
3. `install-plan` には最低限以下を含める
   - node id
   - hostname
   - primary IP / network facts
   - disk layout ref
   - flake attr or system profile ref
   - SSH host key / TLS / bootstrap token
4. ISO 側は `nix_profile` を実際に使って install target を決める
5. `disko` 参照も node 固定 path ではなく profile/class から生成する

この段階で、`cloud-init` endpoint は compatibility として残してもよいが、本流ではなくすべき。

### Phase 2: NixOS apply agent を入れる

1. `node-agent` とは別に `nix-agent` を追加する
2. responsibilities:
   - desired generation の取得
   - closure prefetch
   - activation
   - success/failure/report
   - rollback
3. state model を ChainFire に持つ
   - `nodes/<id>/desired-system`
   - `nodes/<id>/observed-system`
   - `deployments/<generation-id>`
4. health gate を入れる
   - reboot required
   - activation timeout
   - rollback on failed health check

これで初めて「Terraform なしで host rollout する基盤」になる。

### Phase 3: native service scheduling を Nix と接続する

1. `ServiceSpec` / `PlacementPolicy` を Nix から生成する
2. `deployer-ctl apply` を human CLI ではなく generator/exporter の受け口にする
3. `fleet-scheduler` は以下だけに責務を限定する
   - node selection
   - rollout budget
   - failover
   - publication trigger
4. `node-agent` は以下だけに責務を限定する
   - process/container reconcile
   - health reporting
   - observed state update

重要:

- ChainFire
- FlareDB
- IAM bootstrap
- Deployer 自体
- Scheduler 自体

のような基盤コアは、最初は scheduler 対象にせず NixOS 固定配置のままにする方がよい。  
いきなり全部 movable service にすると bootstrap が壊れやすい。

### Phase 4: inventory / MaaS 代替を広げる

1. phone-home payload に hardware facts を追加する
   - CPU
   - memory
   - disks
   - NICs
   - virtualization capability
   - serial / DMI
2. enrollment rule を machine-id 依存から広げる
   - MAC
   - DMI
   - hardware traits
   - rack / TOR port metadata
3. node lifecycle を増やす
   - discovered
   - commissioned
   - install-pending
   - installing
   - active
   - draining
   - reprovisioning
   - rescue
4. 余力があれば Redfish/IPMI を追加する
   - power on/off
   - reboot
   - virtual media

ここまで来ると MaaS の最小代替になる。

### Phase 5: validation path を本流化する

1. `nix/test-cluster` に bootstrap end-to-end を追加する
   - generic ISO/netboot
   - deployer enrollment
   - install-plan
   - install
   - first boot
   - nix-agent apply
2. `fleet-scheduler` native runtime flow を CI gate に入れる
3. node loss / reboot / reprovision / rollback の試験を追加する

## 実装優先順位

### P0

- `Nix` を single source of truth に固定
- `nix_profile` を実際の install/apply 経路に接続
- generic install-plan を定義
- node 固定 ISO install path を撤廃
- `nix-agent` の最小版を作る

### P1

- Nix -> `ClusterStateSpec` generator
- `fleet-scheduler` と `node-agent` の Nix-generated service spec 化
- hardware inventory / enrollment 強化
- bootstrap E2E を `nix/test-cluster` に組み込み

### P2

- Redfish/IPMI
- reprovision / rescue
- publication と host rollout の連携
- drain / cordon / maintenance window

## このリポジトリに対する具体的な backlog

1. `nix_profile` を受け取って実際に install target を決める bootstrap API と ISO 処理を作る
2. `nix/nodes/vm-cluster/node01` のような node 固定構成を、class/profile 生成へ寄せる
3. `deployer-ctl` 用の YAML を手書きせず、Nix から JSON export する generator を追加する
4. `first-boot-automation` は使うなら bootstrap API 契約に合わせて作り直す。使わないなら一旦凍結する
5. `node-agent` とは別に `nix-agent` crate と NixOS module を追加する
6. `deployer` に hardware inventory と install state report を足す
7. `nix/test-cluster` に bare-metal-like bootstrap scenario を追加する
8. CI で `deployer/scripts/verify-deployer-bootstrap-e2e.sh` と `verify-fleet-scheduler-e2e.sh` 相当を gate に入れる

## 結論

このプロジェクトで不足しているのは、scheduler 単体ではない。  
足りていないのは次の 1 本の経路である。

`Nix cluster declaration`
-> `bootstrap/install plan generation`
-> `deployer enrollment`
-> `NixOS installation`
-> `node-side NixOS reconcile`
-> `native service scheduling`
-> `runtime health/rollback`

いまは各部品はあるが、1 本の pipeline になっていない。  
最優先でやるべきは、`Nix` を単一正本に固定し、その宣言から

- host install
- host rollout
- native service scheduling

の 3 つを生成・reconcile できるようにすること。