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

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 / stable
Implementation: k3s baseline complete (RAIL-BS-WP-0002 done); pgpool HA failover fix complete (RAIL-BS-WP-0003 done); integrated backup complete (RAIL-BS-WP-0004 done — age-encrypted local backup, daily cron under root)
Stability: high — no active open workplans
Usage: core Kubernetes runtime for all Railiance deployments; runs on COULOMBCORE (92.205.130.254)
Also deployed at cluster level: cert-manager, ArgoCD, CloudNative PG operator (cnpg), nginx ingress, SSO stack (mfa + sso namespaces via net-kingdom)

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

railiance-infra (S1) — must be converged before this layer runs
railiance-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: Makefile targets; remote work requires SSH tunnel to State Hub

Provided Capabilities

type: infrastructure
title: Kubernetes cluster provisioning (k3s)
description: Install and configure a production k3s cluster including Helm, ingress controller, CNI plugin, and kubeconfig management on Railiance servers.
keywords: [kubernetes, k3s, cluster, helm, ingress, cni, k8s, provisioning]

type: infrastructure
title: Cluster operators and addon management
description: Deploy and manage cluster-wide operators and addons (cert-manager, CloudNative PG operator, ArgoCD, nginx ingress) on the running Railiance Kubernetes cluster.
keywords: [operator, addon, cert-manager, cnpg, argocd, admission, kubernetes, cluster]

type: operations
title: Kubernetes runtime backup (age-encrypted)
description: Daily encrypted backup of k3s cluster state (SQLite hot copy), Helm release values, and kubeconfig to /opt/backup/railiance/cluster/ using age encryption. Run via sudo make backup.
keywords: [backup, restore, age, encryption, k3s, state, helm, kubeconfig, disaster-recovery]

Notes

Runs on COULOMBCORE (92.205.130.254). State Hub access via ops-bridge reverse tunnel — bridge up state-hub-coulombcore from the workstation (see ADR-004). Gitea Helm values were migrated to S5 (railiance-apps) in RAIL-HO-WP-0004-T06 — boundary violation resolved.

4.5 KiB Raw Blame History