# ADR 002: K3s for workspace workloads

- HTML version: https://robbiepalmer.me/projects/agent-friendly-remote-development/adrs/002-k3s-workloads
- Project: Agent-friendly Remote Development (https://robbiepalmer.me/projects/agent-friendly-remote-development.md)
- Status: Proposed
- Date: 2026-09-06
- Initiatives: Semi-autonomous Software Development (https://robbiepalmer.me/initiatives/semi-autonomous-software-development.md)

# Project-specific context

The Home Lab ADR chooses K3s as the API for declarative container workloads.
This project starts with one cloud host, so it uses a smaller part of that
decision. It needs namespaces, persistent volumes, Services, network policy,
resource limits, Jobs, and reconciliation after a process failure.

[ADR 000](/projects/agent-friendly-remote-development/adrs/000-hetzner-cloud)
supplies the virtual machine.
[ADR 001](/projects/agent-friendly-remote-development/adrs/001-nixos-host)
supplies the operating system. K3s owns the workspace workloads running on that
host.

# Application to this project

The current operator gets a namespace, T3 Code workload, persistent-volume
claim, private Service, runtime identity, and resource allocation. Checked-in
manifests own those resources. The host configuration owns K3s installation,
node identity, storage mounts, and backup of cluster state.

The first cluster has one server. A control-plane outage stops reconciliation
until that host recovers, so encrypted workspace backups must remain usable on a
replacement machine. Do not add a second user to this single-node cluster.
Namespace and container boundaries do not isolate node capacity or remove the
shared host as a failure domain.

# kube-hetzner

[Kube-Hetzner](https://github.com/mysticaltech/terraform-hcloud-kube-hetzner)
can build K3s or RKE2 clusters on Hetzner with openSUSE MicroOS or Leap Micro.
It also manages private networking, load balancers, storage drivers, upgrades,
and autoscaling.

The module would replace the NixOS host choice and own more cluster machinery
than one personal node needs. Use direct K3s configuration for the current
host. Evaluate Kube-Hetzner in a separate cluster when multi-user capacity
needs three or more control-plane nodes, dedicated workspace workers, automated
node replacement, or autoscaling for disposable workloads.

# Project checks

Keep this decision Proposed until the operator workspace and a disposable
multi-node evaluation prove that:

* checked-in manifests converge without unexplained changes;
* persistent state survives pod and K3s restarts;
* private endpoints remain reachable through Tailscale;
* resource limits contain a busy workspace;
* a failed worker can be replaced and its workspace volume reattached;
* pressure on one workspace node does not interrupt another workspace; and
* cluster and workspace backups restore onto replacement infrastructure.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt