diff --git a/SCOPE.md b/SCOPE.md index 2ccbb2b..2950e58 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -14,7 +14,17 @@ S3 Platform Services layer of the Railiance OAS Stack — owns shared cluster se ## 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. +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 necessarily belongs in the long-term S3 ownership home. Deployment package +assets are being separated from custody, policy, and lane governance as part of +the future `rapp-openbao` extraction. --- @@ -37,6 +47,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo - 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 -> future `rapp-openbao`, while S3 retains secrets custody and policy - No re-configuration of S1/S2 concerns from this repo --- @@ -46,6 +57,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo - 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 --- @@ -60,9 +72,10 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo ## 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) +- 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: will be the shared database and cache layer; currently cnpg-system + databases namespaces are live +- Usage: shared database, cache, and secrets layer; cnpg-system, databases, and openbao namespaces are live +- Open work: `RAILIANCE-WP-0012` rapp-openbao extraction boundary (active); `RAILIANCE-WP-0013` Forgejo admin PAT OpenBao consumer cutover (active) --- @@ -77,7 +90,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo ## 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 +- Potentially confusing terms: "migration" here means moving Helm releases between layers, not database schema migration; `rapp-openbao` would package OpenBao, but it would not own platform custody or policy --- diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 3bbbc9d..10a5555 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -48,9 +48,9 @@ | task | RAILIANCE-WP-0011-T02 | done | — | workplans/RAILIANCE-WP-0011-reuse-surface-runtime-secrets-openbao-lane.md | | task | RAILIANCE-WP-0011-T03 | done | — | workplans/RAILIANCE-WP-0011-reuse-surface-runtime-secrets-openbao-lane.md | | task | RAILIANCE-WP-0011-T04 | done | — | workplans/RAILIANCE-WP-0011-reuse-surface-runtime-secrets-openbao-lane.md | -| task | RAILIANCE-WP-0012-T01 | todo | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md | -| task | RAILIANCE-WP-0012-T02 | todo | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md | -| task | RAILIANCE-WP-0012-T03 | todo | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md | +| task | RAILIANCE-WP-0012-T01 | done | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md | +| task | RAILIANCE-WP-0012-T02 | done | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md | +| task | RAILIANCE-WP-0012-T03 | done | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md | | task | RAILIANCE-WP-0012-T04 | wait | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md | | task | RAILIANCE-WP-0013-T01 | todo | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md | | task | RAILIANCE-WP-0013-T02 | todo | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md | diff --git a/docs/openbao.md b/docs/openbao.md index bedd234..c9e4b0f 100644 --- a/docs/openbao.md +++ b/docs/openbao.md @@ -10,6 +10,13 @@ --- +Ownership note: the deployable OpenBao package surface documented here is the +candidate for a future `rapp-openbao` repo. Platform custody, policy, +credential lanes, delegated automation, and root-of-trust handling remain +`railiance-platform` responsibilities even after that package extraction. + +--- + ## Architecture ``` diff --git a/docs/rapp-openbao-boundary.md b/docs/rapp-openbao-boundary.md new file mode 100644 index 0000000..f0df7f3 --- /dev/null +++ b/docs/rapp-openbao-boundary.md @@ -0,0 +1,83 @@ +# rapp-openbao Boundary + +This document records the first-wave boundary for extracting a future +`rapp-openbao` repo out of `railiance-platform`. + +The rule is simple: + +- `rapp-openbao` owns the deployable OpenBao package surface +- `railiance-platform` keeps secret custody, policy, lane governance, and + platform-wide operator controls + +## Package Assets For Future `rapp-openbao` + +These files describe or implement the OpenBao workload package itself and are +valid candidates for a dedicated wrapper repo. + +| Path | Why it belongs with the package | +| --- | --- | +| `helm/openbao-values.yaml` | Helm values for the OpenBao workload | +| `helm/openbao-middleware.yaml` | OpenBao-specific ingress/middleware surface | +| `helm/openbao-ui-overlay-k8s.yaml` | OpenBao UI gateway Deployment/Service/Ingress manifest | +| `helm/openbao-ui-overlay/` | UI overlay assets and gateway config for the OpenBao service | +| `scripts/openbao-ui-overlay-apply.sh` | Applies package-owned UI overlay assets | +| `scripts/openbao-verify.sh` | Non-secret workload deployment verification | +| `scripts/openbao-verify-login-overlay.sh` | Verifies package-owned public UI overlay behavior | +| `docs/openbao-emergency-drill-evidence.example.json` | Example workload-specific emergency evidence format | +| `docs/openbao-restore-drill-evidence.example.json` | Example workload-specific restore evidence format | +| `scripts/openbao-validate-emergency-drill-evidence.sh` | Validates workload-specific emergency drill evidence | +| `scripts/openbao-validate-restore-evidence.sh` | Validates workload-specific restore drill evidence | + +## Split-Before-Move Assets + +These files mix package bring-up with retained S3 governance. They should be +split before a clean repo move. + +| Path | Why it needs splitting | +| --- | --- | +| `docs/openbao.md` | Contains both package deployment/runbook material and retained platform custody/bootstrap policy | +| `scripts/openbao-apply-initial-config.sh` | Combines workload bootstrap with S3-owned `platform-admin` / `platform-readonly` policy loading and Kubernetes auth setup | +| `Makefile` target `openbao-configure-initial` | Thin wrapper around the mixed script above | +| `scripts/openbao-verify-authenticated.sh` | Verifies retained policy/auth/audit surfaces, not just package health | + +## Retained `railiance-platform` Responsibilities + +These files and concerns stay in S3 even after a wrapper repo exists. + +| Path or family | Why it stays in S3 | +| --- | --- | +| `openbao/policies/platform-admin.hcl`, `openbao/policies/platform-readonly.hcl` | Platform operator and read-only policy surface | +| `docs/openbao-approved-automation-delegation.md` | Governance for approved metadata mutation under platform control | +| `openbao/policies/credential-change-*.hcl` and `scripts/openbao-apply-credential-change-appliers.py` | Delegated metadata-apply policy and role management | +| `docs/credential-change-approval.md`, `docs/credential-lane-lifecycle-runbook.md`, `docs/workload-kv-access-lanes.md`, `credential-change-requests/` | Source of truth for lane approval, lifecycle, and custody decisions | +| `openbao/policies/workload-kv-read-*.hcl` and `scripts/openbao-apply-workload-kv-lanes.sh` | Cross-workload runtime secret lane governance | +| `openbao/policies/external-secrets-*.hcl` and `scripts/openbao-apply-external-secrets-issue-core.sh` | Cross-workload External Secrets / ESO integration policy | +| `openbao/ssh/roles-spec.yaml`, `openbao/policies/warden-sign.hcl`, `scripts/openbao-apply-ssh-engine.sh`, `scripts/openbao-verify-ssh-engine.sh` | Platform SSH signing capability for ops-warden, not an OpenBao package concern | +| `docs/credential-broker.md`, `credential-grants/`, `scripts/credential.py`, `scripts/openbao-apply-token-grants.py`, `scripts/openbao-verify-token-grants.py`, `openbao/policies/credential-broker-*.hcl` | Platform credential-broker and token-grant governance | +| `scripts/forgejo-admin-pat-provision.sh` and other workload-lane provisioning helpers | Provision secrets for other workloads through OpenBao; not part of the OpenBao package itself | + +## First Move Set + +The first repo-creation handoff for `rapp-openbao` should start with the least +coupled package assets: + +- `helm/openbao-values.yaml` +- `helm/openbao-middleware.yaml` +- `helm/openbao-ui-overlay-k8s.yaml` +- `helm/openbao-ui-overlay/` +- `scripts/openbao-ui-overlay-apply.sh` +- `scripts/openbao-verify.sh` +- `scripts/openbao-verify-login-overlay.sh` +- the `Makefile` targets `openbao-repo`, `openbao-dry-run`, `openbao-overlay-apply`, + `openbao-deploy`, `openbao-status`, `openbao-verify`, and + `openbao-verify-login-overlay` + +This first move set is enough to establish a package repo that can render, +deploy, and verify OpenBao without inheriting platform lane governance. + +## Resulting Rule + +`rapp-openbao` may own how OpenBao is packaged, deployed, verified, and skinned +for Railiance. It must not become the home for platform-admin policy, workload +KV lane policy, delegated metadata authority, credential grants, or human root +custody procedure. diff --git a/workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md b/workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md index ce6567d..f7140b0 100644 --- a/workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md +++ b/workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md @@ -40,7 +40,7 @@ It must not: ```task id: RAILIANCE-WP-0012-T01 -status: todo +status: done priority: high state_hub_task_id: "498a89e1-67e1-4860-8c73-cc38dd92083c" ``` @@ -52,11 +52,15 @@ Classify the current OpenBao-related files into: Done when the distinction is written against real file paths and current usage. +2026-07-25: Added `docs/rapp-openbao-boundary.md` with file-path classification +for OpenBao package assets, split-before-move assets, and retained S3 +governance material. + ## T02 - Define the first `rapp-openbao` move set ```task id: RAILIANCE-WP-0012-T02 -status: todo +status: done priority: high state_hub_task_id: "67526f71-0220-45fb-ab9d-8cef5628257c" ``` @@ -70,11 +74,15 @@ Prepare the first move set for the wrapper, including likely candidates such as: Done when the future wrapper has a concrete first file inventory. +2026-07-25: Recorded the first move set in +`docs/rapp-openbao-boundary.md`, centered on Helm values, UI overlay assets, +OpenBao deploy/verify helpers, and the matching `Makefile` targets. + ## T03 - Record the retained S3 platform responsibilities ```task id: RAILIANCE-WP-0012-T03 -status: todo +status: done priority: high state_hub_task_id: "30036060-85ec-4a24-a428-9f31dd58f853" ``` @@ -88,6 +96,10 @@ Record what must remain in `railiance-platform`, including: Done when the wrapper cannot be mistaken for the new S3 ownership home. +2026-07-25: Recorded retained S3 responsibilities in +`docs/rapp-openbao-boundary.md`, including platform-admin policy, workload KV +lane governance, delegated automation, credential grants, and SSH signing. + ## T04 - Prepare the repo-creation handoff for `rapp-openbao` ```task