Overdeck → k3s | Audited migration plan

Skip to presentation
Phase 0 prepared Factory plan blocked Live state unverified

# One migration,
two execution tracks.

The attached repository does not contain one continuous K3s implementation. It contains a legacy scheduler compatibility lane and a stricter Factory execution design. The safe process shares the cluster foundation while keeping their workload transports separate.

2
files changed in the attached worktree
0
Factory “preserved WIP” files attached
9
gated phases through final retirement
Audit verdict

## Start with evidence, not another install.

Phase 0 lands the useful supplied change safely and gathers current, redacted facts. The first mutating cluster package is generated from that receipt.
Recommended decision

### Reconcile the plans before expanding the cluster.

The old scheduler path can be canaried as a temporary adapter. The Factory path must use immutable input, Kubernetes API lifecycle, constrained publication, and no reusable host credential in the coding pod.

01
Land safely

Repair the attached rollback defect and preserve the original unmanaged file.

02
Observe live state

Collect current cluster, node, policy, storage and recovery-door evidence.

03
Mutate in gates

Each later phase is one package, one command, one receipt, one review.

Architecture boundary

## Share the foundation. Do not share the risk.

The two tracks may reuse safe policy and lifecycle primitives, but the compatibility transport cannot become the Factory security model.
Compatibility lane

### Legacy remote-build scheduler

Incremental migration around existing buildbox/SSH behavior. Feature-gated and suitable only for bounded canaries.

●Existing submitter and watcher are present.
●Uses host-coupled workspace/credential mechanisms.
●Must remain off by default until measured.
●Retained only as an explicit transition/fallback lane.
shared safe foundation
Target lane

### Factory Kubernetes execution

Restricted, immutable, API-observed execution for coding workloads. This is the long-term architecture.

●Digest-pinned image and immutable input ref.
●No hostPath, SSH fan-out or node affinity.
●Trusted, attempt-bound result publication.
●Total cleanup, cancellation and recovery lifecycle.

### Cluster foundation

Versioned config, node enrollment, registry, namespaces, RBAC, resources and networking.

### Operations

Receipts, observability, backup/restore, upgrades, outage drills and rollback.

### Source of truth

Fleet roles plus concrete host identity, committed together after proof.

Attached evidence

## What is present, partial, or absent.

Historical markdown claims are treated as documentary evidence until the live collector reproduces them.
Verified in archive
Fleet plane

Declaration, loader, expansion, engine, hardening and CLI are present.

Partial
Legacy K3s

Submitter/watcher exist, focused tests pass, global flag remains off.

Blocked design
Factory K8s

Baseline runner exists; stricter plan records unresolved ship blockers.

Absent
Enrollment

No one-command transactional node enrollment implementation exists.

MODIFIED
`modules/workstation/claude/lib/remote-seat-provision.mjs`
copy migration logic
MODIFIED
`modules/workstation/claude/tests/remote-seat-provision.test.mjs`
migration coverage
MISSING
`factory-agent-k3s.mjs and related “preserved WIP” files`
not in either ZIP
STALE REF
`origin/wt/factory-kubernetes-job`
5 ahead / 84 behind
Correctness review

## Holes converted into phase gates.

Critical

### Conflicting workload transports

The older plan relies on host-coupled SSH/hostPath mechanisms that the newer Factory plan explicitly forbids.

Separate tracks
Critical

### Reusable host credential in untrusted pod

The Factory plan records a general host GitHub token crossing the coding-container boundary.

Trusted publisher
Critical

### Incomplete attempt/ref lifecycle

Cleanup, cancellation, init failure and bounded recovery-retention are not total across every exit path.

State machine
High

### Historical receipt treated as current

Host availability and recovery history make a dated plan insufficient proof of today’s cluster.

Live collector
High

### Split registration source of truth

Fleet roles and concrete access identity live in separate files; old onboarding instructions target a removed hosts array.

Atomic Git update
High

### No accepted backup/restore contract

A single K3s server is not ready for critical cutover without datastore + server-token backup and restore proof.

Phase 1 gate
High

### Static join credential risk

A non-expiring agent/server token must not be copied into package files, logs, shell history or candidate storage.

Short-lived token
High

### Candidate self-declares trust

Trusted-builder labels must be applied after identity verification by the control plane, not by the joining kubelet.

Protected labels
Medium

### Cutover and fallback deletion are conflated

The plan both deletes and depends on the direct SSH path. Those are separate operational decisions.

Two gates
Medium

### One command without a transaction ledger

Compressing manual steps is not enough; enrollment needs resumability, proof-before-register and exact rollback.

Durable ledger
Phased execution

## Click a phase to inspect its contract.

No phase advances from generated code alone. It advances from returned live evidence and an exact Git result.
Machine onboarding

## One trusted-workstation command.

After the OS and Tailscale are ready, the new machine does not need repository, GitHub or cluster-admin credentials.
Target interface

### Enroll a named Tailscale machine

`bash tools/k3s/enroll-node.sh debian4`
Responsibility boundary

## Nearly all deterministic work is packaged.

### AAssistant package

- Audit plans, branches and implementation.
- Write code, tests, manifests, policies and rollback.
- Build changed-files ZIP and one application script.
- Create worktree, branch, commit, push and PR automation.
- Analyze returned receipt and produce the next phase.

### OOwner / physical boundary

- Install base OS and Tailscale; admit the device.
- Approve root, tailnet, registry and GitHub App policy.
- Run one supplied command on the trusted workstation.
- Keep console/physical recovery available for reboot/storage work.
- Approve protected-main merges and return the receipt.

Delivery loop

## ZIP → command → evidence → next phase.

The loop keeps execution local to the owner’s trusted system while moving design, implementation and analysis into repeatable packages.
1 · Auditread plans + prior receipt
2 · Buildcode, tests, rollback
3 · PackageZIP + one script
4 · Executetrusted workstation
5 · Proveredacted receipt
6 · Landbranch / PR / main

A failed gate does not produce the next mutating phase. It produces a correction package or explicit rollback based on captured evidence.

Executable now

## Phase 0: safe landing + read-only receipt.

This phase changes repository code in a new worktree branch. It does not install K3s, restart services, harden hosts or mutate Kubernetes.
No live cluster mutation

### Run from the trusted workstation

`bash apply-overdeck-k3s-phase0.sh /home/user/Projects/overdeck`
Verifies package checksums and base compatibility.
Creates an isolated worktree from current `origin/main`.
Applies the rollback repair, audit docs and collector.
Runs focused gates before committing.
Collects live state without reading Secret/token values.
Pushes a branch and opens a PR when authentication is available.
Produces one result archive to return for Phase 1.
Non-zero discovery probes are evidence, not automatic defects. An unreachable node or absent command is recorded for analysis instead of aborting the receipt.

### Verification already performed

Gate | Audit result
--- | ---
Remote seat focused suite | Pass
Rollback failure injection | Pass
Legacy K3s unit suite | Pass
Factory K8s focused tests | 6 passed
Fleet focused suites | Pass as non-root
Live K3s integration | Skipped: no audit kubeconfig
Collector offline test | Pass

The owner-side script repeats deterministic gates in the real checkout and records environmental skips rather than manufacturing a green result.