coulomb/railiance-platform
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-platform/SCOPE.md
codex 1eb5fa51ed
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Has been cancelled
Details
Finish architecture-cleanup RAILIANCE-WP-0016 T05 
Item 13 is the restore RESOURCE-WP-0002 already proved. Item 14 retires
the dead Bitnami postgresql-ha deploy path and gates Valkey until a
consumer exists. Item 17 publishes the versioned S3 consumer-interface
index.
2026-08-15 14:43:44 +02:00

7.2 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

S3 Platform Services layer of the Railiance OAS Stack — owns shared cluster services: PostgreSQL HA, Valkey cache, secret management, identity integration, and object storage.

Core Idea

Railiance classifies repos along four orthogonal axes — railiance-* (ownership), rail-* (execution contract), rapp-* (managed workload package), reef-* (substrate boundary). This repo is railiance-*, at S3 on the OAS Stack dimension: the platform services that multiple applications share. Five repos cover S1–S5; other railiance-* repos sit on other OAS dimensions rather than on the stack. See ArchitectureBlueprint.md for the full backbone.

The database operator is CloudNative PG. Bitnami postgresql-ha is retired (no live release; make pg-deploy fail-closed, RAILIANCE-WP-0016 item 14). Valkey is a declared capability with no live instance and nothing left in S2 to extract; make valkey-deploy is gated until a consumer rapp exists.

OpenBao is a platform capability in this repo, but not every OpenBao-related file belongs in the long-term S3 ownership home. The deployable package surface now has a wave-1 repo home in rapp-openbao, while this repo retains custody, policy, and lane governance.

In Scope

  • PostgreSQL via CloudNative PG operator (cnpg) — operator deployed, databases namespace active
  • Valkey / Redis-compatible cache as a standalone Helm release (to be extracted from S2)
  • Secret management infrastructure (OpenBao as the platform service, SOPS/age for Git-at-rest bootstrap material)
  • Identity services integration point (with net-kingdom)
  • Message brokers (RabbitMQ, similar)
  • Object storage (MinIO / S3-compatible)
  • Backup and recovery services for platform data

Out of Scope

  • OS-level concerns → railiance-infra (S1)
  • Kubernetes runtime → railiance-cluster (S2)
  • Developer tooling, CI/CD → railiance-enablement (S4)
  • Application deployments → railiance-apps (S5)
  • Standalone workload-package ownership for OpenBao deployment assets -> rapp-openbao, while S3 retains secrets custody and policy
  • No re-configuration of S1/S2 concerns from this repo

Relevant When

  • Deploying or managing shared services that multiple S5 applications depend on
  • Extracting platform services from application Helm subcharts (boundary enforcement)
  • S2 cluster is operational and platform layer can now be established
  • Defining which OpenBao concerns are workload package assets versus retained platform governance

Not Relevant When

  • S2 (cluster runtime) is not yet operational (pre-condition not met)
  • Application-specific database schemas or migrations (those belong in S5 apps)
  • Infrastructure or cluster work (wrong layer)

Current State

  • Status: maintained / emerging
  • Implementation: CloudNative PG operator live; databases namespace holds the platform clusters; OpenBao is the S3 secrets service. Bitnami postgresql-ha is retired. Valkey is undeployed.
  • Stability: emerging — CNPG clusters are live; cache and in-cluster object storage are not
  • Usage: shared database and secrets layer; cnpg-system, databases, and openbao namespaces are live
  • Deploys via ArgoCD: four Applications (external-secrets, issue-core, openbao-secretstore, target-revenue) plus AppProjects under argocd/bootstrap/; see docs/argocd-gitops.md
  • Emits to railiance-telemetry (Q2 Observability) once the evidence plane exists — seeded 2026-08-11, not yet implemented
  • Open work: Valkey remains a declared-but-unbuilt cache; MinIO is likewise declared, not deployed. OpenBao package boundary and PAT cutover are closed. Platform rapp declarations conform (RAILIANCE-WP-0015). Versioned consumer interfaces: docs/s3-consumer-interfaces.md.
  • Known drift: State Hub attributes ~11 capabilities to this repo, including S1/S2/S4/S5 concerns it does not own. The four capability blocks in this file are authoritative; the hub carries stale pre-split attributions (ArchitectureBlueprint.md C1)

How It Fits

  • Upstream dependencies: railiance-cluster (S2) — k3s running, Helm available, smoke tests passing
  • Downstream consumers: railiance-enablement (S4), railiance-apps (S5) — all depend on platform services
  • Often used with: net-kingdom (identity services integration), railiance-cluster (prior layer)
  • Emits to: railiance-telemetry (evidence plane) — S3 services are expected to emit health and readiness through the standard emission contract rather than per-service bespoke integrations
  • Structural backbone: ArchitectureBlueprint.md in this repo records the four repo-family axes, the stack, repository status, and the open placement decisions that railiance-master owns

Terminology

  • Preferred terms: OAS Stack Level S3, platform services, boundary rule, migration (extracting from S2 subcharts)
  • Potentially confusing terms: "migration" here means moving Helm releases between layers, not database schema migration; rapp-openbao packages OpenBao, but it does not own platform custody or policy

Related / Overlapping

  • railiance-cluster (S2) — pre-condition; PostgreSQL was previously managed here (being extracted to S3)
  • railiance-apps (S5) — consumes database and cache services from S3
  • net-kingdom — identity services integration point at the platform layer

Provided Capabilities

type: infrastructure
title: PostgreSQL via CloudNative PG (cnpg)
description: PostgreSQL database clusters managed by the CloudNative PG operator — shared database service for all platform applications. Operator deployed in cnpg-system namespace; database clusters defined in the databases namespace.
keywords: [postgresql, postgres, cnpg, cloudnative-pg, operator, database, kubernetes]

type: infrastructure
title: Valkey / Redis-compatible cache
description: Declared shared Redis-compatible cache. Not deployed on railiance01 as of 2026-08-15; no S2 instance remains to extract.
keywords: [valkey, redis, cache, shared, session, queue]

type: data
title: Object storage (MinIO / S3-compatible)
description: S3-compatible object storage service (MinIO) for artifact storage, backups, and large file handling across platform applications.
keywords: [minio, s3, object-storage, storage, artifacts, backup]

type: security
title: OpenBao platform secrets service
description: Canonical S3 secrets service for runtime secrets, dynamic credentials, audit, and future workload integrations. SOPS/age remains the bootstrap mechanism for Git-at-rest secrets.
keywords: [openbao, secrets, vault-compatible, secret-management, dynamic-credentials, audit, kubernetes-auth]

Getting Oriented

  • Start with: CLAUDE.md (session protocol, boundary rules)
  • Key files / directories: workplans/RAIL-PL-WP-0001-platform-baseline.md, workplans/RAIL-PL-WP-0002-openbao-platform-secrets-service.md, helm/ (platform Helm charts), docs/openbao.md, Makefile
  • Pre-conditions: railiance-cluster (S2) converged with k3s running; cluster backup verified before migration steps (sudo make backup in railiance-cluster)