coulomb/railiance-infra
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-infra/SCOPE.md
codex d0e8f9f24e
Some checks are pending
CI Smoke / container-smoke (push) Waiting to run
Details
CI Smoke / host-smoke (push) Successful in 0s
Details
Apply Railiance01 firewall-only converge and close RAIL-HO-WP-0009 
Operator-approved playbooks/firewall.yaml --tags firewall removed the
three public 6443 grants. Live UFW now matches ADR-005 (OpenSSH + Nydus).
2026-08-15 17:57:17 +02:00

6.3 KiB
Raw Blame History

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

S1 Infrastructure Substrate of the Railiance OAS Stack — Git-driven OS provisioning, security hardening, and server baseline using Terraform, cloud-init, and Ansible.

Core Idea

Railiance is structured as five independent repos per OAS Stack layer. This repo is S1 — the foundation and the canonical ownership home for infrastructure substrate facts. It provisions bare-metal or cloud servers (Hetzner, HostEurope), hardens the OS, manages secrets (SOPS/age), and validates the resulting baseline with Goss tests. Future reef-* repos will model purpose-bound substrates, but the source-backed OS baseline, inventory, and server identity facts start here. S1 must be converged and verified before any higher layer (Kubernetes, platform, etc.) can run.

In Scope

  • OS provisioning via Terraform (Hetzner, HostEurope providers)
  • First-boot configuration via cloud-init
  • OS convergence via Ansible (base, security, sops_agent roles)
  • Security hardening and firewall rules
  • Secret management: SOPS/age encryption at rest in Git
  • Goss specification and test suite for OS baseline validation
  • Server inventory management (inventory/servers.yaml — source of truth)
  • SSH access management
  • Canonical S1 identity and substrate-fact base for future reef-* repos
  • Source-backed server and workstation substrate facts needed by higher-layer architecture work

Out of Scope

  • Kubernetes runtime → railiance-cluster (S2)
  • Platform services → railiance-platform (S3)
  • Developer tooling → railiance-enablement (S4)
  • Application deployments → railiance-apps (S5)
  • Workload execution semantics or rail contracts → rail-* repos
  • Purpose-specific reef repo ownership and workload-placement policy beyond the S1 source-backed substrate facts
  • No cross-layer re-configuration from higher layers

Relevant When

  • Provisioning new servers for the Railiance stack
  • OS hardening, Ansible convergence, or Goss verification
  • Managing server inventory or SSH access
  • Rotating SOPS/age keys or updating secrets
  • Preparing or validating first-wave reef-* rollout identity facts

Not Relevant When

  • Kubernetes, platform services, or application work (wrong layer)
  • Server is already provisioned and converged (use cluster/platform repos)

Current State

  • Status: maintained / productive
  • Implementation: HostEurope substrate baseline active for Railiance01 and CoulombCore; server spec + test suite active; first reef rollout source map defined. Railiance is classified along four repo-family axes (railiance-*, rail-*, rapp-*, reef-*), of which five railiance-* repos cover S1–S5; this file previously said "5-repo stack architecture", which predates that model
  • Stability: high for the current single-server and transitional two-server substrate reality; proven in production on 92.205.62.239
  • Usage: foundation for all Railiance deployments; canonical S1 source for higher-layer and future reef planning. railiance-hosts is superseded by this repo and carries a banner saying so; its retirement is pending in railiance-master
  • Firewall posture: RAIL-HO-WP-0009 finished. k3s API is tunnel-only (ADR-005); live Railiance01 UFW matches the declaration. CoulombCore UFW stays unmanaged (ufw_manage: false)

How It Fits

  • Upstream dependencies: Terraform, Ansible, SOPS/age (external tools); cloud provider APIs
  • Downstream consumers: railiance-cluster (S2) depends on a converged, verified OS from this layer; all higher layers transitively depend on S1
  • Future substrate-boundary consumers: first-wave reef-* repos should project from the source-backed facts here rather than creating a second S1 inventory
  • Often used with: railiance-cluster (next layer), ops-bridge (SSH tunnel for remote State Hub access)

Terminology

  • Preferred terms: OAS Stack Level S1, convergence, verification, SOPS/age, Goss specification, boundary rule
  • Potentially confusing terms: "convergence" = applying Ansible to reach desired state; "verification" = running Goss tests to validate it

Related / Overlapping

  • railiance-cluster (S2) — consumes the OS baseline provided by S1
  • railiance-hosts — predecessor or migration-duplicate S1 line; not the canonical repo for new architecture work
  • ops-bridge — used to reach local State Hub from remote HostEurope server

Getting Oriented

  • Start with: CLAUDE.md (session protocol, remote execution), README.md (provisioning workflow)
  • Key files / directories: inventory/servers.yaml (authoritative server list), ansible/ (playbooks/roles), terraform/ (provider configs), goss/ (spec + tests), docs/reef-first-wave-source-map.md, docs/adr/ADR-003-railiance-5repo-stack-architecture.md
  • Entry points: make tf-plan, make tf-apply, make converge, make verify

Provided Capabilities

type: infrastructure
title: Server provisioning (Terraform)
description: Provision bare-metal and cloud servers on Hetzner and HostEurope via Terraform with cloud-init first-boot configuration.
keywords: [terraform, server, provisioning, hetzner, hosteurope, cloud-init, infrastructure]

type: infrastructure
title: OS hardening and convergence (Ansible)
description: Harden and converge server OS via Ansible (base, security, sops_agent roles) with Goss test suite for baseline validation.
keywords: [ansible, os, hardening, convergence, goss, security, baseline, validation]

type: security
title: Secret management (SOPS/age)
description: Manage encrypted secrets at rest in Git using SOPS/age — encrypt, rotate, and distribute secrets for Railiance infrastructure components.
keywords: [sops, age, secrets, encryption, gitops, key-rotation, credential]

Notes

Targets two current server substrates: CoulombCore (92.205.130.254) and Railiance01 (92.205.62.239). The first-wave reef rollout also recognizes a grouped operator workstation substrate. State Hub access uses ops-bridge — bridge up state-hub-coulombcore or bridge up state-hub-railiance01 from the workstation (see ADR-004).