Consolidate platform workplans and assess intent gaps
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a06ecb-456a-71c2-b41e-0755d336e883
This commit is contained in:
codex
parent
9d958f8e09
commit
9f83e426c7
40 changed files with 2985 additions and 295 deletions
199
SCOPE.md
199
SCOPE.md
|
|
@ -1,169 +1,114 @@
|
|||
# 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.
|
||||
Reviewed 2026-09-05 against repository source, dated operating evidence and
|
||||
adjacent owner contracts. This is a scope assessment, not a fresh live audit.
|
||||
[INTENT.md](INTENT.md) remains the stable aspiration.
|
||||
|
||||
---
|
||||
## Purpose and boundary
|
||||
|
||||
## One-liner
|
||||
Railiance's S3 shared stateful services: database provision and placement,
|
||||
secret custody and delivery, and platform-data backup and recovery behind
|
||||
versioned consumer interfaces. Cache, general object storage and messaging
|
||||
remain demand-led capabilities; their inclusion in INTENT does not mean they
|
||||
are deployed or justify running them without consumers.
|
||||
|
||||
S3 Platform Services layer of the Railiance OAS Stack — owns shared cluster services: PostgreSQL HA, Valkey cache, secret management, identity integration, and object storage.
|
||||
S3 owns the service promise, custody and acceptance evidence. A `rapp-*` repo
|
||||
owns its deployable package; the cluster and host owners supply the runtime.
|
||||
Identity integration means consuming identity claims, not operating an identity
|
||||
or authorization authority. See [ADR-0001](docs/adr/ADR-0001-s3-platform-service-boundary.md).
|
||||
|
||||
---
|
||||
## Current evidenced capability
|
||||
|
||||
## Core Idea
|
||||
| Service | Implemented / evidenced | Limit and authority |
|
||||
| --- | --- | --- |
|
||||
| `apps-pg` | CNPG source, per-consumer database ACLs, 20-connection allowances, 15-second timeouts; daily backup, continuous WAL and 30-day retention; 56-second scratch restore and 14/14 boundary probes on 2026-08-20 | One instance; restart recovery, no HA or measured latency SLO. Ceiling 3, overflow `apps-pg-2` provisionable but demand-gated. S3 owns this CR and its controls. |
|
||||
| `platform-pg` | Package-operated CNPG service, governed dynamic credentials, backup/restore evidence, Core Hub admission and private shadow evidence | `rapp-postgres` owns CR/provisioning/restore. S3 owns custody, placement policy and consumer disclosure. Published ceiling 4 declarations, counting the probe; reconcile current occupancy before admission. One instance is not HA. |
|
||||
| OpenBao and credential delivery | CCR validation, policy/grant boundaries, approved apply interfaces, runtime KV/ESO and short-lived database lanes, ephemeral custody lifecycle | Package assets belong to `rapp-openbao`; custody/policy remains here. Existing helpers are not authority to mint arbitrary credentials. Operator-only access cutover and incident residuals remain open. |
|
||||
| Backup storage consumption | Governed off-cluster S3 backup destination and credential lane used by CNPG; encrypted upload tooling for other backup consumers | Resource procurement belongs to `resource-control`/`reef-storage`. This does not establish a general S3 service or deployed MinIO. One successful restore does not establish a recurring recovery guarantee. |
|
||||
| Cache / general object storage / messaging | Valkey deployment is gated; no supported consumer interface or deployed shared broker/general in-cluster object store is established by this review | Demand, reuse, ownership, service contract and recovery design must precede deployment. No engine/provider choice is made here. |
|
||||
|
||||
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.
|
||||
Evidence and contracts: [consumer interfaces](docs/s3-consumer-interfaces.md),
|
||||
[apps-pg restore](docs/evidence/RPF-WP-0019-backup-restore-2026-08-20.md),
|
||||
[apps-pg isolation](docs/evidence/RPF-WP-0019-isolation-2026-08-20.md),
|
||||
[placement](docs/placement-policy.md), [tenancy](tenancy.yaml), and
|
||||
[Core Hub capacity admission](docs/evidence/core-hub-postgres-capacity-admission-2026-08-20.md).
|
||||
The former “apps-pg has no backup” and “both ceilings missing” scope statements
|
||||
were stale. Dated evidence above must not be presented as current health.
|
||||
|
||||
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.
|
||||
## Responsibility split
|
||||
|
||||
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.
|
||||
| S3 retains | Other owner / handoff |
|
||||
| --- | --- |
|
||||
| Database service placement, custody and acceptance | `rapp-postgres`: package, admission enforcement and restore; consumers: schemas, migrations, workload SLOs and app verification |
|
||||
| OpenBao service custody, ACL/role review, approved delivery and revocation proof | `rapp-openbao`: package; `key-cape`/`net-kingdom`: issuer, OIDC/MFA, directory/provider reconciliation |
|
||||
| Platform acceptance of a credential lane | `secrets-engine`: lifecycle engine; `ops-mason`: construction coordination through engine APIs; `flex-auth`/access-engine and `approval-engine`: decisions and approval consumption |
|
||||
| Service health semantics, recovery expectations and evidence production | `railiance-telemetry`: Q2 collection, retention and alert transport; it is not S3's monitoring implementation to build |
|
||||
| Platform snapshot/unseal/readiness contribution to an outage | `railiance-infra`: host/reboot; `railiance-cluster`: Kubernetes/restart; consumer owner: synthetic load and application acceptance |
|
||||
| Database/object-store/credential interfaces consumed by the forge | `railiance-forge`: forge backup orchestration, artifact retention and pruning; `activity-core`: automation execution |
|
||||
| Scope accuracy and file-backed source records | `railiance-master`: fleet taxonomy and Q3 placement; `repo-manager`/State Hub: derived record identity and projection correctness |
|
||||
|
||||
---
|
||||
DNS, host firewall, TLS/ingress primitives, Kubernetes runtime, CI templates,
|
||||
application releases, business logic and identity/authorization decisions are
|
||||
outside S3. Existing Forgejo helpers, ArgoCD bootstrap/application manifests,
|
||||
and OpenBao package compatibility assets are retained migration surfaces, not
|
||||
an expansion of that boundary. Transfer requires an accepting owner and tested
|
||||
replacement entry points; source files are not deleted merely to tidy scope.
|
||||
|
||||
## In Scope
|
||||
## Work that closes the intent gaps
|
||||
|
||||
- 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
|
||||
The [current work index](workplans/README.md) groups six open workplans.
|
||||
The [full assessment](history/2026-09-05-platform-intent-workplan-assessment.md)
|
||||
records every reviewed plan and the consolidation mapping.
|
||||
|
||||
---
|
||||
| Priority | Gap | Canonical work |
|
||||
| --- | --- | --- |
|
||||
| First | Reported credential exposures need final disposition and dependable operator custody | RPF-WP-0027: KeyCape/NetKingdom residual evidence and S3 custody; RPF-WP-0029: provider invalidation and replacement backup recovery |
|
||||
| First | Private attended OpenBao access remains unproven end to end | RPF-WP-0025-T03; keep its window separate from incident/recovery actions |
|
||||
| Next | Recovery procedures exist, but two cross-owner exercises still lack completion evidence | RPF-WP-0015-T02/T03: S3 contribution, with audit-core and S1/S2 executing their own parts |
|
||||
| Next | Three requested credential lanes have designs but no live acceptance | RPF-WP-0035: one queue with separate consumer/issuer/approval gates |
|
||||
| Next | Numeric availability/recovery promises, evidence freshness, recurring drills, emission and admission drift lack a complete S3 acceptance loop | RPF-WP-0036-T02–T05 |
|
||||
| Next | Compatibility ownership, stale Hub aliases, and undeployed capability demand need explicit disposition | RPF-WP-0036-T06/T07 |
|
||||
|
||||
## Out of Scope
|
||||
The ready work in RPF-WP-0036 can proceed while attended operations wait.
|
||||
It must define achievable promises for the existing single-node substrate,
|
||||
not declare HA through documentation. Any stronger availability target needs
|
||||
an S1/S2 dependency and a package-level failover proof. Fleet-wide Q3 ownership
|
||||
is an architecture question; it does not suspend S3's own recovery obligations.
|
||||
|
||||
- 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`.
|
||||
Tenancy posture and database placement policy are declared
|
||||
(`docs/tenancy-posture.md`, `docs/placement-policy.md`, `RPF-WP-0018`).
|
||||
Two open items they surfaced: `apps-pg` has no backup configured, and
|
||||
both shared clusters owe a declared consumer ceiling before their third
|
||||
consumer. Decisions are now recorded as ADRs in `docs/adr/` (ADR-0003).
|
||||
- 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
|
||||
## 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.
|
||||
description: Shared database service and placement policy with apps-pg controls and rapp-postgres package integration. Current evidenced deployments are single-instance; HA is not established.
|
||||
keywords: [postgresql, postgres, cnpg, cloudnative-pg, operator, database, kubernetes]
|
||||
```
|
||||
|
||||
```capability
|
||||
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.
|
||||
description: Declared shared cache capability, not a supported live service. Deployment stays gated on an accepted consumer and service contract.
|
||||
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.
|
||||
description: Governed external S3 backup-storage consumption exists. A general shared object-storage service, including in-cluster MinIO, remains undeployed and demand-gated.
|
||||
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.
|
||||
description: S3 custody, policy and approved runtime credential delivery; package assets belong to rapp-openbao. SOPS/age supports bootstrap custody. New lanes need independent live acceptance.
|
||||
keywords: [openbao, secrets, vault-compatible, secret-management, dynamic-credentials, audit, kubernetes-auth]
|
||||
```
|
||||
|
||||
---
|
||||
## Getting oriented
|
||||
|
||||
## 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)
|
||||
Read [AGENTS.md](AGENTS.md), [INTENT.md](INTENT.md), then
|
||||
[workplans/README.md](workplans/README.md). Completed plans are preserved under
|
||||
`workplans/archived/`; [WORK-RECORDS.md](WORK-RECORDS.md) is the generated current
|
||||
index (archives omitted). Routine sync follows AGENTS.md. The dated `.custodian-brief.md` and Hub
|
||||
legacy aliases are not additional authoritative obligations.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue