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

Repurpose as the Railiance bootstrap path
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details

Browse source 
This repo carried a copied declaration identifying it as the S2 cluster runtime
layer - byte-similar to railiance-cluster, with which it shares no git history
but nearly all of its content. It was one of four repos (bootstrap, cluster,
hosts, infra) created by copying working trees as the S1/S2 layering idea
emerged, and the INTENT was copied along with everything else.

Its own QUICKSTART.md - set up your very first Railiance host - describes what
the repo is actually for. INTENT.md and SCOPE.md now declare that: turning a
single bare virtual machine into a working Railiance, then handing off to the
ordinary layers.

Inherited S2-era content in ansible/, helm/, docs/ and wiki/ is not yet sorted;
SCOPE records that restructuring is in progress rather than claiming it is done.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-11 22:41:29 +02:00
parent 607f3960cf
commit 0814ed3a19
2 changed files with 148 additions and 132 deletions
Download patch file Download diff file Expand all files Collapse all files

144
INTENT.md
View file

@ -9,25 +9,31 @@
## One-liner ## One-liner
**The cluster runtime layer — turning hardened servers into a healthy, ready-to-use orchestration platform for workloads.** **The bootstrap path — turning a single bare virtual machine into a working Railiance, so that standing up a new Railiance is a repeatable procedure rather than an act of memory.**
--- ---
## Why This Exists ## Why This Exists
A hardened set of servers is not yet somewhere workloads can run. Railiance's layers each describe how to operate a system that **already
Something must install and configure the **orchestration runtime** — its exists**. S1 converges a substrate, S2 runs a cluster on it, S3 provides shared
scheduler, networking, ingress, admission controls, and the operators that services, and so on. Every one of them assumes the thing beneath it is already
extend it — and then **prove the cluster is healthy**. there.
Without a disciplined runtime layer: Nothing owns the first step: *you have one virtual machine and an intention —
now what?*
* cluster configuration drifts between environments, Without a bootstrap path:
* extension and addon boundaries blur,
* and higher layers deploy onto an unproven runtime.
This layer exists to provide that runtime **consistently and verifiably**, * standing up a new Railiance depends on the memory of whoever did it last,
so the layers above can deploy onto a known-good cluster. * the ordering between substrate, cluster, secrets, and forge is rediscovered
each time,
* the chicken-and-egg problems (secrets needed to fetch the code that manages
secrets) are solved ad hoc and differently each time,
* and "Railiance is easy to adopt" stays an aspiration nobody can test.
This repo exists so that a new Railiance can be **initiated from nothing**, by
someone who was not present when the first one was built.
--- ---
@ -35,75 +41,78 @@ so the layers above can deploy onto a known-good cluster.
> *Where we are going.* > *Where we are going.*
To become the **canonical home for the cluster runtime** — installation To become the **canonical entry point into Railiance** — the one repository a
and baseline configuration of the orchestrator, its networking and newcomer clones to turn a bare machine into a Railiance that can then manage
ingress, admission controls, cluster-level operators and addons, and itself through the ordinary layers.
runtime access — operated to a **verified-healthy** standard.
This means: This means:
* The runtime is configured to a **consistent baseline** every time * The path from **one VM to a working Railiance** is a documented, runnable
* Cluster health is **proven by tests**, not assumed sequence
* Capabilities are extended through **operators and addons** behind clear * **Ordering and prerequisites** between layers are explicit, not folklore
boundaries * Bootstrap **chicken-and-egg problems** are named and solved deliberately
* Runtime **access is managed and rotatable** * The procedure is **testable** — a new Railiance can be raised from scratch to
prove the path still works
* Once bootstrapped, the system **hands off** to the ordinary layers and this
repo steps out of the way
--- ---
## Core Principles ## Core Principles
### 1. Runtime, Not Workloads ### 1. From Nothing, Repeatably
Provide the place where things run. Do not own the things that run there. The path assumes no pre-existing Railiance, no prepared secrets, and no
institutional memory. If a step depends on something that already exists, that
dependency is stated.
### 2. Healthy by Verification ### 2. Hand Off, Do Not Hold
Cluster health is demonstrated by smoke tests and checks, never assumed. This repo raises a Railiance and then yields. Ongoing operation belongs to S1–S5.
Anything this repo keeps operating is a boundary violation.
### 3. Consistent Baseline ### 3. The Path Is Tested by Walking It
The runtime is brought up the same way every time, so environments stay A bootstrap procedure that has not been run from scratch recently is a
comparable and predictable. hypothesis. Proving it means raising a new Railiance, not reviewing the
document.
### 4. Built on a Verified Substrate ### 4. Honest About Manual Steps
Assumes a converged, hardened foundation beneath it; it does not reach Some bootstrap steps genuinely require a human — provisioning a machine,
down and reconfigure that foundation. entering a root credential. These are named as such rather than hidden behind
automation that pretends otherwise.
### 5. Extensible by Operators ### 5. Adoption Is the Point
Cluster capabilities are added through operators and addons within clear Ease of initiation is a Railiance goal, not a convenience. A Railiance that only
boundaries, not by ad-hoc mutation. its author can stand up is not a framework.
### 6. Managed Access
Access to the runtime is controlled, auditable, and rotatable.
--- ---
## What This Is (Conceptually) ## What This Is (Conceptually)
This layer is: The **ignition sequence** for a Railiance:
* a **cluster runtime** layer * the newcomer quickstart and its prerequisites
* an **orchestrator installation and configuration** * the ordering contract between substrate, cluster, secrets, and forge
* a **networking, ingress, and admission** baseline * bootstrap secret material handling, and how it is replaced by the real custody
* a host for **cluster-level operators and addons** path once one exists
* a **health-verification gate** * the handoff point where the ordinary layers take over
* **runtime access** management * a test that the whole path still works
--- ---
## What This Is Not ## What This Is Not
This layer is not: * **Not the cluster runtime.** k3s, Helm, ingress, CNI, operators and kubeconfig
management belong to `railiance-cluster` (S2). This repo previously declared
* the infrastructure substrate beneath it itself S2 — that was a copied declaration, not an intent.
* a provider of shared, stateful platform services * **Not the infrastructure substrate.** OS provisioning, hardening and baseline
* an application or business-capability provider belong to `railiance-infra` (S1).
* an owner of the workloads it runs * **Not a second home for layer content.** It sequences the layers; it does not
duplicate what they own.
It is the **runtime an entire landscape's workloads depend on**. * **Not an ongoing operations repo.** After handoff, it has no running role.
--- ---
@ -111,14 +120,33 @@ It is the **runtime an entire landscape's workloads depend on**.
This layer is expected to evolve toward: This layer is expected to evolve toward:
* Stronger, continuous **health verification** * A **single documented path** from bare VM to working Railiance
* Smoother, safer **runtime upgrades** * Explicit **prerequisite and ordering** contracts with S1 and S2
* Clearer **operator and addon** boundaries * Deliberate handling of **bootstrap secret material** and its retirement
* More robust **access rotation** * A **rehearsable** bootstrap — proven by raising a fresh Railiance, not by review
* Self-evidencing, **auditable** runtime state * Reduced manual steps over time, with the remaining ones **named honestly**
* Eventually, bootstrapping onto **substrates other than the current one**
without changing the model
---
## History
This repository previously carried a copied declaration identifying it as the
S2 cluster runtime layer — identical in intent to `railiance-cluster`, with
which it shares no git history but nearly all of its content. It was one of four
repos (`bootstrap`, `cluster`, `hosts`, `infra`) created by copying working
trees as the S1/S2 layering idea emerged.
That declaration was wrong. The repository's own `QUICKSTART.md` — *"set up your
very first Railiance host"* — describes what this repo is actually for, and this
INTENT now states it.
See `railiance-platform/ArchitectureBlueprint.md` §4 for the full lineage and
`history/2026-08-11-railiance-architecture-in-aspiration.md` for the assessment.
--- ---
## Guiding Question ## Guiding Question
> **How can the runtime an entire landscape's workloads depend on be made consistently healthy, upgradable, and trustworthy?** > *Could someone who was not there raise a new Railiance from this?*

136
SCOPE.md
View file

@ -8,120 +8,108 @@
## One-liner ## One-liner
S2 Cluster Runtime layer of the Railiance OAS Stack — owns k3s installation, Helm, ingress, CNI, admission controllers, operators, and kubeconfig management. The Railiance bootstrap path — turning a single bare virtual machine into a working Railiance, then handing off to the ordinary layers.
--- ---
## Core Idea ## 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. Every Railiance layer describes how to operate a system that already exists.
S1 converges a substrate, S2 runs a cluster on it, S3 provides shared services.
None of them owns the first step: *you have one virtual machine and an
intention — now what?*
This repo owns that step. It sequences the layers into a runnable path from
nothing to a working Railiance, and then gets out of the way. One of Railiance's
goals is that initiating a new Railiance should be easy; this repo is where that
claim is made testable.
**Repository status:** this repo previously carried a copied declaration
identifying it as the S2 cluster runtime layer, duplicating `railiance-cluster`.
That was wrong and has been corrected — see `INTENT.md` → History. Restructuring
of the inherited content is in progress; expect S2-era material still present in
`ansible/`, `helm/`, `docs/` and `wiki/` that has not yet been sorted into
"bootstrap path" versus "belongs to S1/S2".
--- ---
## In Scope ## In Scope
- k3s installation and baseline configuration - The newcomer path from bare VM to working Railiance (`QUICKSTART.md`)
- Helm chart management - Prerequisite and ordering contracts between substrate, cluster, secrets, forge
- Ingress controller, CNI plugin - Bootstrap secret material: how it is introduced, and how it is retired once
- Admission controllers and cluster operators the real custody path (OpenBao, S3) exists
- Cluster addons (cert-manager, etc.) - The handoff point where the ordinary layers take over
- kubeconfig management and access - A rehearsable test that the bootstrap path still works
- Smoke tests to validate cluster health
--- ---
## Out of Scope ## Out of Scope
- OS security hardening, SSH, firewall → railiance-infra (S1) - OS provisioning, hardening, server baseline → `railiance-infra` (S1)
- Platform services (PostgreSQL HA, Valkey, object storage) → railiance-platform (S3) - k3s, Helm, ingress, CNI, admission controllers, operators, kubeconfig
- CI/CD and developer tooling → railiance-enablement (S4) management → `railiance-cluster` (S2)
- Application deployments → railiance-apps (S5) - Shared stateful services: databases, cache, secrets, object storage
- No re-configuration of S1 concerns from this repo → `railiance-platform` (S3)
- Ongoing operation of anything. After handoff this repo has no running role
- Duplicating layer content — this repo sequences layers, it does not own what
they own
--- ---
## Relevant When ## Relevant When
- Setting up or maintaining the Kubernetes cluster runtime - Standing up a **new** Railiance from nothing
- Installing or updating cluster-level operators and addons - Establishing or changing the ordering between substrate, cluster and secrets
- Diagnosing cluster health (smoke tests) - Resolving a bootstrap chicken-and-egg problem (needing a secret to fetch the
- k3s upgrades or kubeconfig rotation code that manages secrets)
- Testing that the adoption path still works by raising a fresh Railiance
---
## Not Relevant When ## Not Relevant When
- OS-level work (use railiance-infra) - Operating, upgrading, or troubleshooting an existing Railiance — that belongs
- Platform service configuration (use railiance-platform) to the layer that owns the concern
- Application deployments (use railiance-apps) - Deploying a workload (that is `rapp-*` and S5)
--- ---
## Current State ## Current State
- Status: active / stable - Status: **repurposed, restructuring in progress**
- 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) - The bootstrap intent is declared (`INTENT.md`, 2026-08-11); the inherited S2
- 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) content has not yet been sorted
- Usage: core Kubernetes runtime for all Railiance deployments; runs on COULOMBCORE (92.205.130.254) - `QUICKSTART.md` is the existing seed of the newcomer path; a near-identical
- Also deployed at cluster level: cert-manager, ArgoCD, CloudNative PG operator (cnpg), nginx ingress, SSO stack (mfa + sso namespaces via net-kingdom) copy also exists in `railiance-cluster` and the two need consolidating
- `install/` exists in `railiance-cluster` but not here, and is a candidate to
move
- Open: whether the bootstrap path has ever been walked end to end from scratch
--- ---
## How It Fits ## How It Fits
- Upstream dependencies: railiance-infra (S1) — OS must be converged and verified - Sequences: `railiance-infra` (S1) → `railiance-cluster` (S2) →
- Downstream consumers: railiance-platform (S3), railiance-enablement (S4), railiance-apps (S5) `railiance-platform` (S3), and hands off once they can run themselves
- Often used with: railiance-platform (next layer to configure after cluster is up) - Downstream: everything, indirectly — this is the entry point
- Often used with: `railiance-master` (which owns the layer model this
sequences), `railiance-platform` (which takes over secret custody after
bootstrap material is retired)
--- ---
## Terminology ## Terminology
- Preferred terms: OAS Stack Level S2, smoke test, pre-condition chain, boundary rule - Preferred terms: bootstrap path, ignition sequence, handoff point,
- Potentially confusing terms: cluster runtime ≠ platform services; Gitea and databases are NOT S2 concerns bootstrap secret material
- Potentially confusing: "bootstrap" here means *initiating a whole Railiance*,
--- not `cluster bootstrap` in the k3s sense (that is S2), and not ArgoCD
app-of-apps bootstrapping (that is S3's `argocd/bootstrap/`)
## Related / Overlapping
- `railiance-infra` (S1) — must be converged before this layer runs
- `railiance-platform` (S3) — consumes the cluster runtime provided by S2
--- ---
## Getting Oriented ## Getting Oriented
- Start with: `CLAUDE.md` (session protocol, remote execution via SSH tunnel), `README.md` - Start with: `INTENT.md`, then `QUICKSTART.md`
- Key files / directories: `workplans/` (4 active), `.sops.yaml` (secret encryption) - Context: `railiance-platform/ArchitectureBlueprint.md` §4 records this repo's
- Entry points: `Makefile` targets; remote work requires SSH tunnel to State Hub lineage and status
- Pre-conditions: one reachable virtual machine, and nothing else
---
## 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 Helm values were migrated to S5 (railiance-apps) in RAIL-HO-WP-0004-T06 — boundary violation resolved.