# 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-01
- Initiatives: Semi-autonomous Software Development (https://robbiepalmer.me/initiatives/semi-autonomous-software-development.md)
- Inherited from project: homelab (https://robbiepalmer.me/projects/homelab/adrs/023-k3s-declarative-workloads.md)

## Source summary

Most homelab applications already run from OCI images. Docker Compose wires those images together on the Mac mini, while launchd restarts the Compose groups after a reboot. The current operational description also has launchd running a shell wrapper around the Ente CLI, export...

## Notes for Agent-friendly Remote Development

# 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

Each user 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. Namespace and container boundaries suit the trusted
pilot. Hostile tenant isolation requires a virtual-machine or microVM boundary.

# kube-hetzner

[kube-hetzner](https://github.com/kube-hetzner/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 pilot node needs. Use direct K3s configuration for the first host.
Reconsider kube-hetzner when a new cluster needs three or more nodes, automated node
replacement, or autoscaling.

# Project checks

Keep this inherited decision Proposed until the workspace pilot proves 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;
* one namespace cannot read another namespace's storage or ordinary service
  traffic; and
* cluster and workspace backups restore onto a replacement NixOS host.

---

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