Bernd Worsch
871c31a95d
State Hub update pending: tunnel was offline during this session. Run from local machine: cd ~/the-custodian/state-hub && make tunnel HOST=tegwick@92.205.130.254 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
176 lines
4.4 KiB
Markdown
176 lines
4.4 KiB
Markdown
---
|
|
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
|