centra/photoncloud-monorepo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
photoncloud-monorepo/docs/component-matrix.md

4.6 KiB
Raw Blame History

Component Matrix

UltraCloud now fixes the public support surface to three canonical profiles. This page defines the required and optional component bundles for each profile and keeps everything else explicitly outside the core contract.

Canonical Profiles

single-node dev

  • Required components: chainfire, flaredb, iam, plasmavmc, prismnet
  • Optional components: lightningstor, coronafs, flashdns, fiberlb, apigateway, nightlight, creditservice, k8shost, deployer
  • Primary Nix outputs: nix run .#single-node-quickstart, nixosConfigurations.single-node-quickstart, and companion install image nixosConfigurations.netboot-all-in-one
  • Optional component toggles: ultracloud.quickstart.enableLightningStor, enableCoronafs, enableFlashDNS, enableFiberLB, enableApiGateway, enableNightlight, enableCreditService, enableK8sHost
  • Primary use: one-command local bring-up, API development, and one-box VM experimentation without the HA control-plane overhead

3-node HA control plane

  • Required components: chainfire, flaredb, iam, nix-agent on every control-plane node, plus deployer on the bootstrap node
  • Optional components: fleet-scheduler, node-agent, prismnet, flashdns, fiberlb, plasmavmc, lightningstor, coronafs, k8shost, apigateway, nightlight, creditservice
  • Primary Nix outputs: nixosConfigurations.node01, node02, node03, netboot-control-plane
  • Primary use: stable replicated control plane that can later accept worker, storage, and edge bundles without redefining the bootstrap path

bare-metal bootstrap

  • Required components: deployer, first-boot-automation, install-target, nix-agent
  • Optional components: netboot-control-plane, netboot-worker, and netboot-all-in-one as experimental helper images, plus node-agent, fleet-scheduler, and higher-level storage or edge services after the first successful rollout
  • Primary Nix outputs: nixosConfigurations.ultracloud-iso, nixosConfigurations.baremetal-qemu-control-plane, nixosConfigurations.baremetal-qemu-worker, checks.x86_64-linux.baremetal-iso-e2e
  • Primary use: boot the installer ISO, phone home to deployer, fetch the flake bundle, run Disko, reboot, and converge QEMU-emulated or real machines into either the single-node or HA profile

Optional Composition Bundles

The optional bundles below remain important, but they are layered on top of the canonical profiles rather than treated as separate top-level products:

  • control-plane core: chainfire + flaredb + iam
  • network provider bundle: prismnet + flashdns + fiberlb
  • VM hosting bundle: plasmavmc + prismnet + coronafs + lightningstor
  • Kubernetes-style hosting bundle: k8shost + prismnet + flashdns + fiberlb
  • edge and tenant bundle: apigateway + iam + nightlight + creditservice
  • native rollout bundle: deployer + chainfire + nix-agent + fleet-scheduler + node-agent

fresh-matrix is the publishable composition proof because it rebuilds the host-side VM images before validating these bundles on the VM cluster.

Responsibility Boundaries

  • k8shost: tenant workload API surface. It manages pod, deployment, and service semantics, then delegates network publication to prismnet, flashdns, and fiberlb.
  • fleet-scheduler: bare-metal service placement surface. It schedules host-native service instances from declarative cluster state and node-agent heartbeats, without exposing Kubernetes APIs.
  • deployer: enrollment and rollout authority. It serves /api/v1/phone-home, stores install plans and desired-system references, and seeds cluster metadata.
  • nix-agent: host OS reconciler. It turns deployer desired-system references into switch-to-configuration actions plus rollback and health-check handling.
  • node-agent: host runtime reconciler. It applies scheduled service-instance state, keeps runtime heartbeats fresh, and reports host-local execution status back to the scheduler.

The intended layering is deployer -> nix-agent for machine image or NixOS generation changes, and deployer -> fleet-scheduler -> node-agent for host-native service placement changes. k8shost stays separate because it is the tenant workload control plane, not the native service scheduler.

Non-Canonical Paths

  • baremetal/vm-cluster remains legacy/manual
  • netboot-control-plane, netboot-worker, netboot-all-in-one, netboot-base, and pxe-server are internal or experimental helpers, not supported profiles by themselves
  • ad hoc shell-driven cluster bring-up is for debugging only and should not be presented as the canonical public path