143 lines
5.8 KiB
Markdown
143 lines
5.8 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
|
|
|
|
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.
|
|
|
|
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 (cnpg) deployed; `databases` namespace active; OpenBao is live as the S3 secrets service; Valkey + legacy postgresql-ha extraction from S2 remain in progress
|
|
- Stability: emerging — cnpg deployed but database cluster definitions not yet migrated from S2
|
|
- Usage: shared database, cache, and secrets layer; cnpg-system, databases, and openbao namespaces are live
|
|
- Open work: Valkey and legacy postgresql-ha extraction remain active; the
|
|
OpenBao package boundary and PAT consumer cutover are now documented and
|
|
closed
|
|
|
|
---
|
|
|
|
## 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; `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
|
|
|
|
```capability
|
|
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]
|
|
```
|
|
|
|
```capability
|
|
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]
|
|
```
|
|
|
|
```capability
|
|
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]
|
|
```
|
|
|
|
```capability
|
|
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)
|