cbc961ca09
The central finding. OAS defines six canonical dimensions and states that each architecture description MUST use them. Railiance has modelled itself almost entirely on Stack. Everything that did not fit a stack level was treated as an anomaly - "unplaced", "beside the stack" - and accumulated as exceptions. They were never anomalies. They are concerns on dimensions Railiance was not using, and the Quality dimension's sub-levels map almost one-to-one onto the capability gaps this review found independently: Q2 Observability is railiance-telemetry, named in canon in exactly those words; Q7 Governance is the conformance loop; Q3 is restore proof; Q6 is cost attribution. The self-evidencing thread across five stack layers is five Stack repos each independently asking for Q2 and Q7 - what a missing dimension looks like from inside the one you are using. Also records four contradictions (C1-C4), of which C1 is actionable here: the hub attributes ~11 capabilities to this repo including Terraform, Ansible, k3s, CI/CD and app deployment, which S3 does not own. SCOPE.md declares four, all correctly S3, and is authoritative. ArgoCD decision closed: keep it, documentation stays accurate; relocating GitOps to Helix Forge noted as possible future cleanup. SCOPE.md: corrects the "five independent repos per OAS Stack layer" claim, records the ArgoCD deployment path, the telemetry emission relationship, and the hub capability drift. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
165 lines
7.3 KiB
Markdown
165 lines
7.3 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 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 active migration is from Bitnami postgresql-ha (repmgr + pgpool, deployed
|
||
historically as part of the Gitea subchart in S2 — the forge itself is now
|
||
Forgejo) 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
|
||
- 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 and legacy postgresql-ha extraction remain active; the
|
||
OpenBao package boundary and PAT consumer cutover are now documented and
|
||
closed; `rapp-openbao`/`rapp-postgres` declaration conformance
|
||
(`RAILIANCE-WP-0015-T02`) is held pending the `railiance-master` schema
|
||
- 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
|
||
|
||
```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)
|