# Machine Enrollment Workflow

**Status:** Approved target-state baseline  
**Infrastructure may be manually bootstrapped I0; product activation:** I7.

## Target State

The user adds a machine through AWP without learning K3s commands.

```text
Cluster -> Add Machine
  -> enter hostname/IP, SSH identity/auth, optional labels/role
  -> create durable enrollment request
  -> preflight
       connectivity
       OS / architecture
       CPU/RAM/disk
       required ports/network
       container/Kubernetes runtime
       existing enrollment/cluster ownership
  -> show result / conflicts
  -> install/configure correct K3s role
  -> join target Cluster
  -> wait for node registration
  -> verify Ready/network/storage/scheduling/runtime capabilities
  -> discover MachineCapability
  -> apply labels/policy
  -> Machine ready + visible
```

## Credentials

SSH authentication is a Connection/CredentialReference. Raw private key/password is not stored on Machine. Enrollment workflow receives only scoped credential projection.

## Idempotency

Enrollment has stable operation identity and can resume after controller/network failure. Before installation it detects whether the machine:

- is already correctly enrolled;
- belongs to another cluster;
- has conflicting K8s/runtime state;
- has partial prior installation;
- is unsupported.

Never blindly rerun installation over unknown cluster membership.

## Capabilities

After join, discover and persist machine facts/capabilities with timestamp/provenance. User labels/roles remain desired config; observed resources update independently.

## Removal / Maintenance

The reverse lifecycle supports drain/maintenance/remove with active-work protection and WIP preservation. Node disappearance alone does not delete Machine history.

## Failure / Recovery

Partial install remains `enrollment failed/needs attention` with detected state and safe retry/repair/uninstall options. AWP verifies cleanup before removing identity. Provider/network timeout reconciles node state first.

## Security

Host-level enrollment is high privilege and PolicyRequired. UI explains target host/cluster/action before confirmation. Enrollment credentials are never exposed to ordinary AgentRuns.

## Increment Realization

I0 may use operator/manual cluster setup but architecture captures Machine/Capability observations. I7 activates full Add Machine/maintenance/removal UI and workflow. I9 may add cloud/fleet/tenant enrollment adapters.

## Acceptance

A user can enroll a clean supported machine, safely detect an already/incorrectly enrolled machine, recover a partial failure, and understand resulting capabilities without shelling into K3s.