coulomb/railiance-cluster
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clarify cluster boundary for rail-kubernetes
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 6s
Details

Browse source
This commit is contained in:
codex 2026-07-25 11:17:51 +02:00
parent 74b490a31e
commit be3b8ff31e
9 changed files with 329 additions and 146 deletions
Download patch file Download diff file Expand all files Collapse all files

50
SCOPE.md
View file

@ -8,13 +8,23 @@
## One-liner
S2 Cluster Runtime layer of the Railiance OAS Stack — owns k3s installation, Helm, ingress, CNI, admission controllers, operators, and kubeconfig management.
S2 Cluster Runtime layer of the Railiance OAS Stack - owns k3s installation,
Helm, ingress, CNI, admission controllers, operators, kubeconfig management,
and the substrate facts published to downstream workload rails.
---
## 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.
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.
Some generic workload lifecycle docs and commands still live here as a temporary
compatibility layer. That material is transition debt pending extraction to a
future `rail-kubernetes` repo and must not be treated as long-term S2 scope.
---
@ -27,15 +37,17 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
- Cluster addons (cert-manager, etc.)
- kubeconfig management and access
- Smoke tests to validate cluster health
- Published substrate facts and safety expectations for downstream workload rails
---
## 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)
- 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)
- Generic workload lifecycle semantics, `railiance/app.toml`, and wrapper scaffolding as long-term ownership concerns -> future `rail-kubernetes` / `rapp-*`
- No re-configuration of S1 concerns from this repo
---
@ -46,6 +58,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
- Installing or updating cluster-level operators and addons
- Diagnosing cluster health (smoke tests)
- k3s upgrades or kubeconfig rotation
- Defining what the current Kubernetes substrate guarantees to downstream workload rails
---
@ -60,8 +73,8 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
## Current State
- Status: active / stable
- Implementation: k3s baseline, pgpool HA failover fix, age-encrypted backup, kubeconfig delivery, staged promotion lifecycle, and activity-core/llm-connect reconcile gates all finished (RAIL-BS-WP-0002…0006, RAILIANCE-WP-0012…0014)
- Open work: RAIL-BS-WP-0007 ThreePhoenix HA cluster (active, 0/7); RAIL-BS-WP-0008 activity-core WP-0016 deploy (ready); RAIL-BS-WP-0009 admin-sync smoke (ready)
- Implementation: k3s baseline, age-encrypted backup, kubeconfig delivery, and cluster operator/addon management are established; generic workload lifecycle docs/tooling remain here as transition debt pending `rail-kubernetes` extraction
- Open work: RAIL-BS-WP-0007 ThreePhoenix HA cluster (active, 0/7); RAIL-BS-WP-0008 activity-core WP-0016 deploy (ready); RAIL-BS-WP-0009 admin-sync smoke (ready); RAIL-BS-WP-0012 rail-kubernetes extraction (active)
- 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)
@ -69,7 +82,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
## How It Fits
- Upstream dependencies: railiance-infra (S1) — OS must be converged and verified
- 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)
@ -78,21 +91,21 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
## 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
- Potentially confusing terms: cluster runtime != platform services; cluster runtime != generic workload rail; Gitea and databases are not S2 concerns
---
## Related / Overlapping
- `railiance-infra` (S1) — must be converged before this layer runs
- `railiance-platform` (S3) — consumes the cluster runtime provided by S2
- `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)
- Start with: `CLAUDE.md`, `README.md`
- Key files / directories: `workplans/`, `.sops.yaml`, `docs/rail-kubernetes-extraction-map.md`, `docs/rail-kubernetes-substrate-profile.md`
- Entry points: `Makefile` targets; remote work requires SSH tunnel to State Hub
---
@ -124,4 +137,11 @@ keywords: [backup, restore, age, encryption, k3s, state, helm, kubeconfig, disas
## 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.
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.
`bin/railiance` lifecycle subcommands, `railiance/app.toml`, and overlay/wrapper
scaffolding stay in this repo only as a migration bridge. They are not the
steady-state S2 identity.