3.2 KiB
SCOPE
This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.
One-liner
S2 Cluster Runtime layer of the Railiance OAS Stack — owns k3s installation, Helm, ingress, CNI, admission controllers, operators, and kubeconfig management.
Core Idea
Railiance is structured as five independent repos per OAS Stack layer. This repo is S2. It installs and configures the Kubernetes cluster runtime: k3s, Helm, ingress controller, CNI plugin, cluster addons and operators. S1 (OS) must be converged before S2 can run. S2 explicitly does not own platform services (PostgreSQL, caches) — those are S3.
In Scope
- k3s installation and baseline configuration
- Helm chart management
- Ingress controller, CNI plugin
- Admission controllers and cluster operators
- Cluster addons (cert-manager, etc.)
- kubeconfig management and access
- Smoke tests to validate cluster health
Out of Scope (per ADR-003)
- OS security hardening, SSH, firewall → railiance-infra (S1)
- Platform services (PostgreSQL HA, Valkey, object storage) → railiance-platform (S3)
- CI/CD and developer tooling → railiance-enablement (S4)
- Application deployments → railiance-apps (S5)
- No re-configuration of S1 concerns from this repo
Relevant When
- Setting up or maintaining the Kubernetes cluster runtime
- Installing or updating cluster-level operators and addons
- Diagnosing cluster health (smoke tests)
- k3s upgrades or kubeconfig rotation
Not Relevant When
- OS-level work (use railiance-infra)
- Platform service configuration (use railiance-platform)
- Application deployments (use railiance-apps)
Current State
- Status: active / mostly complete
- Implementation: k3s baseline complete (RAIL-BS-WP-0002); active bug fixes (RAIL-BS-WP-0003 pgpool HA failover); safety net tooling in progress (RAIL-BS-WP-0004)
- Stability: high for k3s baseline; active improvements ongoing
- Usage: core Kubernetes runtime for all Railiance deployments; runs on HostEurope server
How It Fits
- Upstream dependencies: railiance-infra (S1) — OS must be converged and verified
- Downstream consumers: railiance-platform (S3), railiance-enablement (S4), railiance-apps (S5)
- Often used with: railiance-platform (next layer to configure after cluster is up)
Terminology
- Preferred terms: OAS Stack Level S2, smoke test, pre-condition chain, boundary rule
- Potentially confusing terms: cluster runtime ≠ platform services; Gitea and databases are NOT S2 concerns
Related / Overlapping Repositories
railiance-infra(S1) — must be converged before this layer runsrailiance-platform(S3) — consumes the cluster runtime provided by S2
Getting Oriented
- Start with:
CLAUDE.md(session protocol, remote execution via SSH tunnel),README.md - Key files / directories:
workplans/(4 active),.sops.yaml(secret encryption) - Entry points:
Makefiletargets; remote work requires SSH tunnel to State Hub
Notes
Designed for remote execution from HostEurope (92.205.130.254). Requires SSH reverse tunnel: ssh -R 8000:127.0.0.1:8000 <user>@remote.