# Cluster Page UI **Status:** Approved target-state behavior **Substrate exists I0; minimum worker-enrollment operation:** I7a accelerated during I2; **full product activation:** I7. ## Page Job Directly answer the user's stated question: > **Is my execution infrastructure healthy, and what is it currently doing?** Secondary questions: ```text What is running where? What is queued and why? Which machines are constrained/degraded? Which capabilities are available? Can I safely add/drain/remove a machine? Why was a workload placed here? ``` ## Top-Level Layout ```text Cluster header / health / capacity [+ Add Machine] Attention / degraded resources (if any) Machines name health CPU memory disk capabilities running queued Workloads / queues Factory / Agent / CI workloads, requested capabilities, status Capacity / history aggregate CPU/mem/storage and pressure trends ``` Do not bury machine health beneath generic Kubernetes object lists. ## Machine Row / Detail Show hostname/display name, Ready/degraded/maintenance, CPU/memory/disk usage and capacity, GPU/runtime/trust labels, roles (`factory`, `ci`), running workloads, queue/pressure and last observation. Clicking opens detail drawer/subpage with lifecycle/events/capabilities/provider node info. ## Add Machine One primary `+ Add Machine` launches the machine-enrollment workflow: host/SSH/auth/labels -> preflight -> review -> enroll -> verify. User should not need K3s command knowledge. Preflight clearly surfaces already-enrolled/conflicting state before privileged action. ## Workloads / Placement Workloads are AWP primitives mapped to K8s resources. Rows show Project/Plan/Task/Agent or CI context, requested capabilities/resources, selected machine and status. Placement explanation available where AWP constraints influenced scheduling. ## Queues Show why queued: capacity, capability mismatch, trust profile, policy, maintenance or provider issue. Do not show a single opaque queue count. ## Maintenance Drain/maintenance/remove actions display affected workloads and safe migration/checkpoint state before confirmation. High-risk machine removal is PolicyRequired. ## States empty/no cluster, loading, healthy, partially degraded, disconnected/stale observations, enrollment in progress/failed, maintenance, no eligible capacity, provider/K8s error. ## Responsive / Accessibility Desktop uses dense machine table + workload panels. Small screens use machine cards and filterable workload list; charts are supplementary with textual values. Status/capability badges have accessible text. ## URL Truth Cluster route can select Machine/workload/filter; Machine has stable route/subroute. Enrollment progress survives refresh and is reopenable. ## Increment Realization I0 basic infrastructure exists without polished page. **I7a activates only a minimum owner-facing worker Add Machine operation during I2.** I7 activates the full Cluster page plus richer enrollment/lifecycle/capacity/maintenance/placement. I9 may add fleet/tenant/quota views. ## High-Fidelity Requirements I7a acceptance covers the minimum Add Machine preflight/enrollment/success/failure path only. Before full I7: healthy populated cluster, degraded machine/attention, queue/capability constraint, maintenance confirmation and responsive full-page states remain design work. ## Target State Cluster is the product-level execution-infrastructure surface over AWP Cluster/Machine/Capability/Workload/Placement semantics. Kubernetes is the substrate; the user sees health, capacity, queues, placement reasons and safe lifecycle operations rather than a Kubernetes object browser. ## Primary Users / Jobs - owner/operator: know whether execution infrastructure is healthy and what it is doing; - infrastructure lead: manage machine enrollment/maintenance/capacity without hand-running K3s commands; - delivery engineer: explain why Agent/CI work is queued or placed on a particular machine. ## Entry / Exit Points Entry: `OPERATIONS -> Cluster`, Home health, Project/Factory/Agent machine links, Attention, search. Exit: Machine detail, Workload/Agent/CI context, Add Machine enrollment, Incident, Settings/Connection, or optional Headlamp/provider detail for expert debugging. ## User Journeys ### J1 — Inspect health and capacity ```text open Cluster -> scan aggregate health/capacity/attention -> identify degraded/constrained Machine -> open Machine detail -> inspect observations/workloads/events -> return with filters/selection preserved ``` ### J2 — Explain a queue/placement ```text queued workload -> inspect requested resources/capabilities/trust -> see eligible/ineligible machine reasons -> identify capacity/policy/maintenance blocker -> follow owning Task/Agent/CI or adjust authorized policy/capacity -> scheduler continues when eligible ``` ### J3 — Add a Machine ```text + Add Machine -> enter host + SSH credential reference + optional role/labels -> preflight connectivity/OS/arch/resources/ports/runtime/existing membership -> review detected state + privileged actions -> enroll through durable workflow -> verify node Ready/network/storage/scheduling/runtime -> Machine appears canonical and usable ``` ### J4 — Safe maintenance/removal ```text select Machine -> Drain/Maintenance/Remove -> enumerate affected workloads + WIP/checkpoint state -> policy/Approval where required -> durable drain/migration/removal operation -> verify workloads safe + desired cluster state -> terminal result or Incident ``` ## Data / Source of Truth Cluster/Machine/Capability/Workload/PlacementDecision are AWP domain identities. Kubernetes Node/Pod status and metrics-server/NFD/NPD/exporter data are provider observations/evidence with freshness. Kubernetes scheduler binding is mechanics; PlacementDecision explains AWP constraints when product-visible. ## Actions / Authorization Enrollment, maintenance, drain, labels/roles and removal require infrastructure capability and applicable Approval policy. SSH/Kubernetes credentials are CredentialReferences/Connections, never rendered raw. Normal AgentRuns cannot invoke machine lifecycle operations. ## Async / Duplicate-Mutation Safety Enrollment/drain/remove are durable workflows with immediate acknowledgement, idempotent request identity, resumable progress and explicit reconciliation after interruption. Duplicate `Add Machine` detects already-enrolled/partial state rather than reinstalling blindly. High-risk lifecycle actions require live authoritative connectivity. ## Invariants From Day 1 - Machine identity is not merely Kubernetes Node UID; - machine capabilities are data, not hostname rules; - queue state always exposes reason and next eligibility condition; - metrics/health observations are freshness-stamped; - machine lifecycle cannot destroy the only safe copy of active WIP; - raw Kubernetes administration remains secondary expert detail; - provider mechanics cannot broaden Agent workload authority. ## Current Implementation State Target page remains I7 authority. K3s substrate exists from I0; I7a may add the minimum owner-facing Add Machine operation, while polished full Cluster product UI waits for I7. ## Deferred Realization NFD, NPD, historical exporters, Kueue, Cilium/Hubble, advanced autoscaling/fleet and tenant isolation activate only on documented triggers. I9 may add quotas/fleet/tenant context. ## Temporary Dogfood Behavior I0/I1 cluster may be bootstrapped/observed through CLI/operator tools while the same canonical Machine/Workload/Capability semantics are captured. Do not build a temporary dashboard or expose kubectl as product UX. ## Related Contracts / Decisions - [`../domains/cluster.md`](../domains/cluster.md) - [`../workflows/machine-enrollment.md`](../workflows/machine-enrollment.md) - [`../architecture/workspace-execution.md`](../architecture/workspace-execution.md) - [`factory-run.md`](factory-run.md), [`agents.md`](agents.md), [`incident.md`](incident.md), [`settings.md`](settings.md) - K3s-native-first and trigger-only provider decisions come from the reuse/FOSS authority. ## Visual Mockup Authority No full I7 Cluster high-fi is approved yet. The 2026-08-24 owner priority amendment authorizes only the minimum I7a Add Machine operational flow. Healthy/degraded/queued placement, maintenance and polished responsive full-page states still require explicit I7 design approval. ## Acceptance A user can understand cluster health/capacity/work placement and enroll/manage machines without opening kubectl or deciphering Kubernetes resource JSON.