railiance-cluster/workplans/RAIL-BS-WP-0002-k3s-baseline.md

id, type, title, domain, repo, status, owner, topic_slug, repo_goal_id, state_hub_workstream_id, created, updated, completed

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

# 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)

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:

  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

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

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:

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

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

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):

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