railiance-cluster/SCOPE.md

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

---

## Related / Overlapping Repositories

- `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

```capability
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]
```

```capability
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]
```

```capability
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 is currently deployed here as a Helm release (boundary violation: architecturally belongs to S5 — migration pending).