21f097d9a8
Source commit: 6d1a121b0a8a636aac95998fe5d15c24c78eb7d0 Public tree identity: sha256:2bc22807f5b838286678b65d3f550b8ae4714ae673622041d4c2516a7c5b7926
57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
# Architecture
|
|
|
|
Clusterflux separates a control plane from execution nodes.
|
|
|
|
## Coordinator
|
|
|
|
The coordinator owns identity scope, one-active-process admission, task
|
|
placement, attempt history, Debug Epoch coordination, VFS metadata, artifact
|
|
metadata, quotas, and secure relay reservations. Its async main may park and wake
|
|
without consuming node compute.
|
|
|
|
The coordinator does not execute arbitrary native commands or hosted
|
|
containers. It also does not become a durable artifact store merely because it
|
|
coordinates a download.
|
|
|
|
## Nodes
|
|
|
|
A node is an enrolled public-key identity. It reports capabilities and periodic
|
|
heartbeats. The coordinator derives whether it is live from the last accepted
|
|
heartbeat; a client-supplied "online" field is not placement authority.
|
|
|
|
Nodes resolve bundle environments, execute Wasm tasks, run native commands, and
|
|
retain artifact bytes. A node must prove the tenant, project, process, task, and
|
|
key scope on every signed request.
|
|
|
|
## Virtual process and tasks
|
|
|
|
A Coordinator Project admits one active virtual process. The process contains:
|
|
|
|
- one coordinator-hosted async main;
|
|
- logical task instances created by that main;
|
|
- one or more attempts for each logical task;
|
|
- joins tied to the logical task, not to an individual attempt.
|
|
|
|
"FailFast" makes a terminal failure visible to the join immediately.
|
|
"AwaitOperator" keeps the join pending while an operator accepts, cancels, or
|
|
restarts the failed task. Restart creates a distinct attempt but preserves the
|
|
logical task identity.
|
|
|
|
A terminal process releases the active slot automatically. A task parked for an
|
|
operator is not terminal and continues to occupy the slot.
|
|
|
|
## Durable and live state
|
|
|
|
Projects, identities, credentials, permissions, hosted policy records, relay
|
|
period usage, and relay reservation accounting may be stored in Postgres.
|
|
Active processes, task placement, Debug Epochs, transient VFS state, relay byte
|
|
streams, and live node state are bounded in memory and are not reconstructed as
|
|
running after a coordinator restart. Pre-restart relay reservations are
|
|
reconciled as abandoned before new links can be issued.
|
|
|
|
## Protocol lanes
|
|
|
|
Human clients use scoped sessions. Agents and nodes use separate signed
|
|
public-key identities. Operator actions use a separate administrative
|
|
credential. Authority comes from the authenticated lane and server-side scope,
|
|
never from identity fields in an untrusted request body.
|