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 is structured as five independent repos per OAS Stack layer. This repo is S3 — the platform services that multiple applications share. The active migration is from Bitnami postgresql-ha (repmgr + pgpool, currently a Gitea subchart in S2) to CloudNative PG (cnpg operator, already deployed in the cnpg-system namespace) as the canonical database operator. Valkey cluster is also in scope for S3 extraction from S2.

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)
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

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: active / emerging
Implementation: CloudNative PG operator (cnpg) deployed; databases namespace active; Valkey + legacy postgresql-ha extraction from S2 in progress (RAIL-PL-WP-0001)
Stability: emerging — cnpg deployed but database cluster definitions not yet migrated from S2
Usage: will be the shared database and cache layer; currently cnpg-system + databases namespaces are live

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)

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

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: Shared Redis-compatible cache service (Valkey) for all applications in the Railiance stack.
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)

5.1 KiB Raw Blame History