# Cluster Domain

**Status:** Approved target-state baseline  
**Substrate:** I0  
**Worker enrollment MVP activation:** I7a accelerated during I2; **remaining Cluster product activation:** I7.

## Target State

AWP models execution infrastructure as first-class `Cluster`, `Machine`, `MachineCapability`, `Workload` and `PlacementDecision` primitives while Kubernetes/K3s owns scheduling/runtime mechanics.

```text
Cluster
  ├─ Machine*
  │    └─ MachineCapability*
  ├─ Workload* (observed AWP-relevant execution)
  └─ PlacementDecision*

K3s adapter
  -> node provisioning / Kubernetes API
```

## Cluster

Stable AWP identity for one execution cluster/provider context, connection/resource mapping, desired/observed health and policy.

## Machine

Stable enrolled machine/node identity with host/provider mapping, lifecycle, hardware/resource observation, labels/roles, health and enrollment provenance.

## MachineCapability

Declarative capabilities such as CPU architecture/count, memory, disk, GPU, runtime classes, trust profiles, labels (`factory=true`, `ci=true`) and specialized services.

## Workload

AWP-relevant workload projection (AgentRun, CI runner/job, service) mapped to Kubernetes resources. Kubernetes Pod is not the product identity.

## PlacementDecision

Records why AWP/provider selected a machine/profile when placement needs explainability: required capabilities, eligible set, chosen target and reasons.

## Invariants From Day 1

- Kubernetes node/Pod UID is provider mapping, not sole Machine/Workload identity;
- machine capabilities are data, not hard-coded hostname rules;
- normal agents/CI run only on eligible trust/capability profiles;
- resource/health observations can be stale and are timestamped;
- machine enrollment is durable/idempotent/recoverable;
- scheduler placement remains Kubernetes mechanics unless AWP has a concrete reason to constrain it;
- adding machine does not require user to understand K3s commands.

## Machine Enrollment Target Flow

```text
Cluster -> Add Machine
  -> hostname/IP + SSH identity/auth + optional labels/role
  -> preflight SSH/OS/arch/CPU/RAM/disk/ports/runtime/existing enrollment
  -> install/configure K3s node
  -> join cluster
  -> verify Ready/network/storage/scheduling/runtime capabilities
  -> Machine active and visible
```

Credential is handled through Connection/CredentialReference and not stored in Machine plaintext.

## Machine Lifecycle

```text
discovered/onboarding -> enrolling -> ready
 -> draining/maintenance -> ready
 -> degraded/unreachable
 -> removing -> removed
```

Safe removal/drain respects active workloads and preserves work/checkpoints.

## Increment Realization

| Increment | Cluster realization |
|---|---|
| I0 | K3s cluster, Workspace/ARC workloads, basic node/capability observation. |
| I1 | Agent/CI workload placement/status enough for dogfood. |
| I7a | accelerated worker enrollment MVP: durable Add Machine, preflight, K3s join, Ready verification, capability persistence. |
| I7 | remaining Cluster/Machine lifecycle, capacity, queues, maintenance, placement UX. |
| I9 | quotas/tenant isolation/fleet support as needed. |

## Current Implementation State

Target spec; infrastructure is needed early, polished management product is later.

## Deferred Realization

Kueue, Cilium/Hubble, advanced autoscaling/fleet/cloud machine provisioning are trigger-based providers, not baseline.

## Temporary Dogfood Behavior

I0 cluster may be manually bootstrapped before product enrollment exists. The owner-authorized I7a acceleration introduces the minimum Add Machine worker-enrollment operation during I2 while preserving final Machine/Capability primitives; the remaining Cluster product surface stays I7.

## Failure / Recovery

Enrollment is durable and detects partial installation/already-enrolled nodes. Failed drain/removal creates attention/Incident rather than silently deleting Machine identity.

## UI Implications

Cluster page answers: “Is execution infrastructure healthy, what is running where, what is queued, and why?” It shows machine CPU/mem/disk/load, health, capabilities, workloads, queues and maintenance actions.

## Decisions / ADRs

K3s is execution baseline. Machine scheduling enhancements require evidence and adapter/provider decisions.