127 lines
4.6 KiB
Markdown
127 lines
4.6 KiB
Markdown
# 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. It provisions bare-metal/cloud servers (Hetzner, HostEurope), hardens the OS, manages secrets (SOPS/age), and validates the resulting baseline with Goss tests. 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
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- Kubernetes runtime → railiance-cluster (S2)
|
|
- Platform services → railiance-platform (S3)
|
|
- Developer tooling → railiance-enablement (S4)
|
|
- Application deployments → railiance-apps (S5)
|
|
- 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
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- Kubernetes, platform services, or application work (wrong layer)
|
|
- Server is already provisioned and converged (use cluster/platform repos)
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: active / productive
|
|
- Implementation: single-server HostEurope baseline complete (RAIL-HO-WP-0001); server spec + test suite active (WP-0002); 5-repo stack restructure active (WP-0003)
|
|
- Stability: high for single-server bootstrap; proven in production (92.205.62.239)
|
|
- Usage: foundation for all Railiance deployments; used daily for convergence and verification
|
|
|
|
---
|
|
|
|
## 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
|
|
- 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
|
|
- `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/adr/ADR-003-railiance-5repo-stack-architecture.md`
|
|
- Entry points: `make tf-plan`, `make tf-apply`, `make converge`, `make verify`
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
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]
|
|
```
|
|
|
|
```capability
|
|
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]
|
|
```
|
|
|
|
```capability
|
|
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 servers: COULOMBCORE (92.205.130.254) and Railiance01 (92.205.62.239). State Hub access via ops-bridge — `bridge up state-hub-coulombcore` or `bridge up state-hub-railiance01` from the workstation (see ADR-004).
|