---
id: RAIL-BS-WP-0002
type: workplan
title: "k3s and Kubernetes Platform Baseline"
domain: railiance
repo: railiance-cluster
status: completed
owner: railiance
topic_slug: railiance
repo_goal_id: "70ab2379-fb9d-4fec-a09d-b2a717e4ace8"
state_hub_workstream_id: "4c63dfc6-9eac-4e79-9f77-8f644ad7147d"
created: "2026-03-09"
updated: "2026-03-10"
completed: "2026-03-10"
---

# k3s and Kubernetes Platform Baseline

## Goal

Install k3s, Helm, and the baseline Kubernetes services on the converged
HostEurope node. This workplan picks up exactly where `railiance-hosts`
leaves off: a hardened, verified OS node that is ready for Kubernetes.

## Pre-condition

`railiance-infra` converge + Goss verify must pass before any task here
is executed:

```bash
# In railiance-infra/
make converge
make verify    # must exit 0
```

## Boundary

This repo owns everything from k3s upward. It must not re-configure items
defined in `railiance-infra/spec/server-baseline.yaml`. See ADR-003:
`railiance-infra/docs/adr/ADR-003-railiance-5repo-stack-architecture.md`.

**Out of scope here:** platform services (PostgreSQL, storage, identity)
→ `railiance-platform`. Application deployments (Gitea, coulomb services)
→ `railiance-apps`.

---

## Tasks

### T01 — Ansible playbook: install k3s (server mode)

```task
id: T01
status: done
priority: high
state_hub_task_id: "3f042630-eab0-4c6a-9167-e2b28ff20e40"
completed: "2026-03-10"
```

Harden `ansible/bootstrap.yml` to a production-ready k3s install:

- Use the official k3s install script pinned to a specific version
  (`INSTALL_K3S_VERSION=v1.35.1+k3s1`)
- `INSTALL_K3S_EXEC="server --cluster-init --write-kubeconfig-mode=644"`
  (cluster-init enables embedded etcd for future HA expansion)
- Wait for node `Ready` before proceeding:
  ```bash
  k3s kubectl wait node --all --for=condition=Ready --timeout=120s
  ```
- Fetch kubeconfig to the control node as `~/.kube/config-hosteurope`

**Done when:** `k3s kubectl get nodes` returns `Ready` from both the server
and the control node (via kubeconfig).

---

### T02 — Helm installation

```task
id: T02
status: done
priority: high
state_hub_task_id: "e8510646-46ed-4697-a345-f3d3009eea78"
completed: "2026-03-10"
```

Add a task (or a role `roles/helm/`) that:

1. Downloads the Helm binary (pinned version) to `/usr/local/bin/helm`
2. Verifies the checksum
3. Confirms `helm version` succeeds

**Done when:** `helm version` succeeds on the HostEurope node.

---

### T03 — Smoke test: k3s + Helm

```task
id: T03
status: done
priority: high
state_hub_task_id: "dab2c07f-8aa0-4635-8df6-857e87e93fc5"
completed: "2026-03-10"
```

Extend `tests/smoke_kube.sh` to assert:

- `k3s kubectl get nodes` → node in Ready state
- `helm version` exits 0
- CoreDNS pod running in `kube-system`
- Traefik ingress controller pod running (default in k3s)

Run via:
```bash
ansible-playbook -i ansible/hosts.ini ansible/smoke.yml
```
or directly over SSH if the kubeconfig is available locally.

**Done when:** all assertions pass and the script exits 0.

---

### T04 — Commit kubeconfig management notes

```task
id: T04
status: done
priority: medium
state_hub_task_id: "5c3d40e4-239b-488e-9519-6f7a38d2325f"
completed: "2026-03-10"
```

Document in `docs/kubeconfig.md`:

- Where the kubeconfig is fetched to (`~/.kube/config-hosteurope`)
- How to merge it into `~/.kube/config`
- How to switch context: `kubectl config use-context default`
- Security note: kubeconfig is gitignored (contains cluster CA + client cert)

**Done when:** doc written and committed.

---

### T05 — Add `make k3s-install` and `make smoke` targets

```task
id: T05
status: done
priority: medium
state_hub_task_id: "7f9e0e58-a130-467a-a2d0-b3f2564e496f"
completed: "2026-03-10"
```

Add to Makefile (create one if none exists):

```makefile
k3s-install: ## Install k3s and Helm on all inventory hosts
	ansible-playbook -i ansible/hosts.ini ansible/bootstrap.yml

smoke: ## Run Kubernetes smoke tests
	bash tests/smoke_kube.sh
```

**Done when:** both targets work and are listed in `make help`.

---

## References

- Repo goal: `70ab2379-fb9d-4fec-a09d-b2a717e4ace8` (Install k3s and Kubernetes Baseline)
- Domain goal: `6f96c712-60e6-4ea9-ab06-168878eafbce` (Three-Phoenix Secure Kubernetes Infrastructure)
- Pre-condition: railiance-infra WP-0001 (Secure Single-Server Bootstrap) — completed 2026-03-09
- Boundary ADR: `railiance-infra/docs/adr/ADR-003-railiance-5repo-stack-architecture.md`
- k3s releases: https://github.com/k3s-io/k3s/releases