diff --git a/fleet/ARCHITECTURE.html b/fleet/ARCHITECTURE.html index 48b1eff3..db9b2d92 100644 --- a/fleet/ARCHITECTURE.html +++ b/fleet/ARCHITECTURE.html @@ -211,6 +211,19 @@ text-align: center; overflow-x: auto; } + .diagram { + background: var(--paper); + border: 1px solid var(--rule); + border-radius: 8px; + padding: 1.2rem; + margin: 1.5rem 0; + overflow-x: auto; + } + .diagram img { + display: block; + width: 100%; + height: auto; + } hr { border: none; border-top: 1px solid var(--rule); @@ -257,13 +270,13 @@ each layer adds one idea on top of the previous one.

Layer 0 One picture

-

Topologie physique. Tout ce qui n'est pas un humain ou un device -tourne dans le cluster Kubernetes : Fleet Operator, NATS + -JetStream, l'Auth Callout, Zitadel — tous des pods. Les devices -(Raspberry Pi, VM, bare-metal) sont à l'extérieur, et se branchent -sur NATS via la callout pour s'authentifier. Un opérateur pousse -les déploiements depuis le haut via le dashboard ou kubectl; -un sysadmin enrôle chaque device une fois en SSH.

+

Physical topology. Everything that is not a human or an edge device +runs inside the Kubernetes cluster: Fleet Operator, NATS + +JetStream, the auth callout, and Zitadel — all as pods. Devices +(Raspberry Pi, VM, bare-metal) live outside the cluster and connect to +NATS through the callout-authenticated path. An operator pushes +deployments from the top via the dashboard or kubectl; a +sysadmin enrolls each device once over SSH.

flowchart TB @@ -278,7 +291,7 @@ flowchart TB subgraph CLUSTER [Kubernetes cluster  k3d / OKD / any] direction LR - KAPI["Kubernetes Control Plane
deployment.harmony, device.harmony CRDs"]:::kube + KAPI["Kubernetes Control Plane
Deployment and Device CRDs"]:::kube OP["Harmony Fleet Operator
reconciles CRDs ↔ KV"]:::kube KV[("NATS JetStream
desired-state · device-info
device-state · device-heartbeat")]:::bus CALLOUT["NATS Auth Callout"]:::auth @@ -286,7 +299,7 @@ flowchart TB KAPI --- OP OP -- writes / watches KV --> KV - KV -- delegates auth --> CALLOUT + KV -- NATS delegates auth --> CALLOUT CALLOUT -- validates JWT --> ZITADEL end @@ -447,7 +460,7 @@ sequenceDiagram device-info Agent - Operator (reflects to Device CR) + Operator (watches; creates/patches Device CR) info.<device> Routing labels, inventory snapshot, agent version @@ -461,24 +474,12 @@ sequenceDiagram -
-flowchart LR - OP[Operator] - AG[Agent] - DS[(desired-state)] - ST[(device-state)] - IN[(device-info)] - HB[(device-heartbeat)] - - OP -- writes --> DS - DS -- watches --> AG - AG -- writes --> ST - AG -- writes --> IN - AG -- writes --> HB - ST -- watches --> OP - IN -- reflects to Device CR --> OP - HB -. queries .- OP -
+
+ Layer 3 KV bucket data flow between the operator, NATS stores, and agent +

These four bucket names are the contract between agent and operator. They live in one place to keep cross-component drift from happening:

@@ -551,8 +552,8 @@ sequenceDiagram
  • Drops the agent binary at /usr/local/bin/fleet-agent.
  • Enables fleet-agent.service (systemd).
  • Agent boots, connects to NATS with bearer token from the keyfile.
    • -
  • Agent publishes initial DeviceInfo into device-info.<device_id>.
    • -
  • Agent starts watching desired-state.<device_id>.>.
    • +
  • Agent publishes initial DeviceInfo into the device-info bucket at key info.<device_id>.
    • +
  • Agent starts watching the desired-state bucket for keys matching <device_id>.>.
  • Agent answers device-commands.<device_id>.ping.
    • @@ -590,7 +591,7 @@ flowchart TB OP <-->|in-cluster NATS| NATS NATS -. callout .- CO CO -. JWT introspect .- ZT - OP --- ZT + OP -. dashboard SSO / JWKS .- ZT
    diff --git a/fleet/harmony-fleet-assets/layer-3-kv-buckets.svg b/fleet/harmony-fleet-assets/layer-3-kv-buckets.svg new file mode 100644 index 00000000..eb8f494e --- /dev/null +++ b/fleet/harmony-fleet-assets/layer-3-kv-buckets.svg @@ -0,0 +1,4 @@ + + +Operator / Agent ArchitectureOperatorAgentStoresOperatorAgentdesired-statedevice-statedevice-infodevice-heartbeatwriteswatcheswriteswriteswriteswatcheswatches,reflects to CRqueries/watches \ No newline at end of file