Skip to content

Architecture Overview

Nodewright is a standard Kubernetes operator with one twist: it is deliberately split into a control plane that decides and a node plane that acts. This page walks up from the system context to the containers that make it work.

System context

Nodewright lives inside each edge cluster. SpectroCloud Palette delivers it (as a cluster-profile pack); operators drive it through a CLI and a thin UI; and it orchestrates the storage/virt substrate already running on the nodes — it orchestrates, it does not replace LINSTOR, KubeVirt, or Kairos.

Site Engineer / OperatorSpectroCloud PaletteEdge ClusterNodewright(operator + agents)Cluster substrateKubernetes APILINSTOR / Piraeus+ DRBDKubeVirt VMsKairos / host OS nwctl / UIdelivered as acluster-profile packreconciles CRDsobserves / coordinatesprotects during flipshost mutation (via agent)

The control plane / node plane split

This is the load-bearing decision. Responsibilities divide cleanly:

  • Owns cluster-wide intent and decisions: who flips first, when to bump replica placement, when to release a lock.
  • Reads and writes CRD .spec / .status; coordinates with Piraeus and KubeVirt objects.
  • Runs one controller-manager, one controller per CRD, with a single leader-election lease.
  • Runs unprivileged (restricted pod security).
  • Owns host-level mutation only: ip link, networkctl, writes under /etc/systemd/network and /oem, kairos-agent invocations, local drbdadm pause/resume.
  • Executes the one-shot operations the operator delegates, then reports observed state back up.
  • Runs privileged, in a single labelled namespace, with per-mount justification.

Why it matters: today's bash DaemonSet conflates both. A node deciding cluster-wide policy from stale ConfigMap state is the exact failure class that has driven the incident history. With the split, the operator decides, the agent acts, the agent reports, the operator rolls forward.

Containers

Control planeNode plane (per node)InterfacesNodewright OperatorKubernetes API serverCRDsVMVolumeMigration · NodewrightClusterNodewrightAgentStatus · …Node agent(DaemonSet)Host: bond/VLAN · DRBD · Kairosnwctl (CLI)Web UIControllers(one per CRD)Admission webhook(validate + default) apply / get CRDsapply / get CRDswatch + reconcilestoresintent (via CRD status / lease)host mutationreports observed state

Built vs. not-yet-live

The node agent is now a thin Go process — a DaemonSet (default-off) that renews a per-node liveness Lease — and the operator drives host work through a typed HostOperation instruction/result protocol, not stale ConfigMap state. What isn't live yet is the actuation: the agent's host-op primitives (bond rewrite, networkctl, drbdadm) are dormant and fake-tested — no real host mutation until the hardware-lab phase. Until per-cluster cut-over, the legacy bash DaemonSet still runs the live cluster. See Roadmap & Status.

Next: the components — the CRDs, controllers, and the pluggable interfaces that make the whole thing extensible beyond one customer's hardware.