docs: add Railiance app wrapper best-practice guide
Record how rapp-* repos wrap first-party apps for Railiance, using user-engine as the pilot. Opens RMGR-WP-0006 (T01 done) and includes fix-consistency ID writeback for WP-0004/0005/0006.
This commit is contained in:
parent
c7fbd57800
commit
5197aa7425
6 changed files with 1002 additions and 0 deletions
|
|
@ -198,6 +198,7 @@ with compatibility tests. Cover:
|
|||
id: RMGR-WP-0004-T08
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "fc7395b0-e86d-4231-baac-ea7fa5dc2174"
|
||||
```
|
||||
|
||||
Implement `ADR-007` decision 1 as a repository standard: `PREFIX-WP-NNNN` names
|
||||
|
|
@ -239,6 +240,7 @@ non-unique identifier would manufacture UUID collisions rather than remove them.
|
|||
id: RMGR-WP-0004-T09
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "3a6ba954-4e35-4b2d-8dff-d3db84ed832c"
|
||||
```
|
||||
|
||||
Three prefixes are shared across seven repositories, each a single number line
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ related:
|
|||
- STATE-WP-0080
|
||||
- STATE-WP-0068
|
||||
- CFED-WP-0001
|
||||
state_hub_workstream_id: "7ddb5421-d960-4a3c-94b1-40b6c96abfab"
|
||||
---
|
||||
|
||||
# Registrar consolidation and deterministic hub identifiers
|
||||
|
|
@ -51,6 +52,7 @@ model; a file carrying a hub's private key is the file holding hub state.
|
|||
id: RMGR-WP-0005-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "b57a6882-280d-4f0a-9c73-899843dfc3d3"
|
||||
```
|
||||
|
||||
Until derivation ships, exactly one instance may write hub identifiers into
|
||||
|
|
@ -73,6 +75,7 @@ removes the need for the trade.
|
|||
id: RMGR-WP-0005-T02
|
||||
status: wait
|
||||
priority: medium
|
||||
state_hub_task_id: "8e679ddb-9845-457f-8672-1fd4b7455e7b"
|
||||
```
|
||||
|
||||
Records minted by non-registrar instances before T01 need reconciliation. Known
|
||||
|
|
@ -94,6 +97,7 @@ before then.
|
|||
id: RMGR-WP-0005-T03
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "28067729-498d-4f47-89bd-5b9718e999c7"
|
||||
```
|
||||
|
||||
Replace minted UUIDs with UUIDv5 derived from the globally unique
|
||||
|
|
@ -116,6 +120,7 @@ same UUID for different workplans. Uniqueness must be enforced first.
|
|||
id: RMGR-WP-0005-T04
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "503a23a9-ede1-4cf1-bd32-e9669b84ce58"
|
||||
```
|
||||
|
||||
One-time pass over the 758 files carrying hub identifiers: compute the derived
|
||||
|
|
@ -135,6 +140,7 @@ value, update the database to match, and write the file.
|
|||
id: RMGR-WP-0005-T05
|
||||
status: wait
|
||||
priority: low
|
||||
state_hub_task_id: "3946d1fc-2137-4d7b-a400-29b447ca83de"
|
||||
```
|
||||
|
||||
Once derivation is live fleet-wide, remove the single-writer restriction from
|
||||
|
|
@ -150,6 +156,7 @@ byte-identical writeback, and neither creates a duplicate record.
|
|||
id: RMGR-WP-0005-T07
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "70f83359-0b61-4dc0-83b0-33f289b64e83"
|
||||
```
|
||||
|
||||
Implement `ADR-010` decisions 1–3: the central hub on railiance is authoritative
|
||||
|
|
@ -171,6 +178,7 @@ portion of the divergence is redundant and needs no merge — only a rebuild.
|
|||
id: RMGR-WP-0005-T08
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "241cf058-2f3e-4d49-8cc9-5c714be4a1cf"
|
||||
```
|
||||
|
||||
Implement `ADR-010` decision 4. The two kinds need opposite handling:
|
||||
|
|
@ -197,6 +205,7 @@ reduces its scope.
|
|||
id: RMGR-WP-0005-T09
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "d40cc4a8-4280-4940-ac1d-dc1049f1b678"
|
||||
```
|
||||
|
||||
28 records exist in the local instance with no backing file. They are the only
|
||||
|
|
@ -227,6 +236,7 @@ register collision)` in `repo-manager`, independent corroboration of the
|
|||
id: RMGR-WP-0005-T10
|
||||
status: wait
|
||||
priority: medium
|
||||
state_hub_task_id: "15f0f167-a8d0-4d5c-8576-3e93b1e8792f"
|
||||
```
|
||||
|
||||
Implement `ADR-010` decision 7. The retirement splits one hub into several, which
|
||||
|
|
@ -245,6 +255,7 @@ Coordinate with the hub-extension architecture in
|
|||
id: RMGR-WP-0005-T06
|
||||
status: wait
|
||||
priority: medium
|
||||
state_hub_task_id: "d440d59c-f78e-4752-84c7-f3d5fdf7d3c3"
|
||||
```
|
||||
|
||||
Implement `ADR-007` decision 3: an automated normalization pass may report
|
||||
|
|
|
|||
126
workplans/RMGR-WP-0006-railiance-app-wrapper-setup.md
Normal file
126
workplans/RMGR-WP-0006-railiance-app-wrapper-setup.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
id: RMGR-WP-0006
|
||||
type: workplan
|
||||
title: "Railiance managed-app wrapper setup"
|
||||
domain: infotech
|
||||
repo: repo-manager
|
||||
status: active
|
||||
owner: grok
|
||||
topic_slug: infotech
|
||||
created: "2026-08-18"
|
||||
updated: "2026-08-18"
|
||||
parent_project: prj-state-hub-retirement
|
||||
related:
|
||||
- RMGR-WP-0004
|
||||
state_hub_workstream_id: "0d6d2ebf-4b74-4908-995c-17b8987ede05"
|
||||
---
|
||||
|
||||
# Railiance managed-app wrapper setup
|
||||
|
||||
## Goal
|
||||
|
||||
Give Repo Manager a governed path to set up `rapp-<app>` repositories so
|
||||
ordinary applications (starting with `user-engine`) can run on Railiance
|
||||
as managed workloads: declared, packaged, bound to a rail and reef, and
|
||||
operable without copying charts into `railiance-apps`.
|
||||
|
||||
This specializes `RMGR-WP-0004` scaffolding for the `rapp-*` family. It
|
||||
does not move family schemas out of `railiance-master`, and it does not
|
||||
operate the cluster.
|
||||
|
||||
Practice and remaining work are structured in
|
||||
[`docs/RailianceAppDeploymentGuide.md`](../docs/RailianceAppDeploymentGuide.md).
|
||||
|
||||
## Record the wrapper best-practice guide
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0006-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "cb1e2e4e-9aef-4669-89f6-86ea8512b7d2"
|
||||
```
|
||||
|
||||
Survey live rails (`rail-kubernetes`, `rail-knative`), reefs
|
||||
(`reef-railiance`, `reef-storage`), existing rapps, and the `user-engine`
|
||||
/ `rapp-user-engine` pair. Write
|
||||
`docs/RailianceAppDeploymentGuide.md` as the best-practice shape and the
|
||||
work breakdown for later scaffolder phases.
|
||||
|
||||
**Result (2026-08-18):** guide written. Pilot target is
|
||||
`rapp-user-engine` (empty stub). Copy targets are `rapp-policy-nexus` and
|
||||
`rapp-openbao`, not drifted `rapp-qonto`.
|
||||
|
||||
## Bootstrap the user-engine wrapper to `declared`
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0006-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "f0e53954-403a-4e2c-b39f-0bab00eed3cc"
|
||||
```
|
||||
|
||||
Fill `rapp-user-engine` with the bootstrap baseline and a schema-valid
|
||||
`declarations/rapp.yaml` at `readiness_state: declared` (or `draft` if
|
||||
image/consumer pins are still missing). Follow the worked example in the
|
||||
guide. Validate with
|
||||
`railiance-master/tools/validate-family-declarations.py --root ..`.
|
||||
|
||||
Do not place the rapp (`bound_reefs` stays empty) and do not set public
|
||||
exposure.
|
||||
|
||||
## Generate the Kubernetes package skeleton
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0006-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "3ba6828e-7514-4f4d-a1d3-54134e039f55"
|
||||
```
|
||||
|
||||
Add the Helm chart, Makefile operator targets, `railiance/app.toml`, and
|
||||
runtime-contract doc described in the guide, derived from `user-engine`
|
||||
port, health paths, Containerfile user, and documented env/secret names.
|
||||
|
||||
`make render` and `make lint` must pass with dummy digests. No cluster
|
||||
deploy in this task.
|
||||
|
||||
## Draft platform handoffs
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0006-T04
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "0c2846d9-5db2-4b97-becd-0367b5737188"
|
||||
```
|
||||
|
||||
Draft the `rapp-postgres` consumer and secret-reference list for
|
||||
user-engine. Apply them only in the owning repos (`rapp-postgres`,
|
||||
`railiance-platform`) after those owners accept the draft. This repo
|
||||
records the request; it does not become the credential home.
|
||||
|
||||
## Implement `rmgr rapp` scaffolding
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0006-T05
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "6cf89776-ff31-4dd1-aa9a-39474fc387aa"
|
||||
```
|
||||
|
||||
Turn P1–P4 from the guide into Repo Manager commands (`rapp init`,
|
||||
`rapp skeleton`, `rapp validate`) that are idempotent, secret-free, and
|
||||
refuse to invent rails, reefs, or package types. Pilot by regenerating
|
||||
the user-engine wrapper (or the next engine stub) without hand-editing
|
||||
the baseline files.
|
||||
|
||||
Depends on the shape proven in T02–T03 and on `RMGR-WP-0004` scaffolding
|
||||
ownership.
|
||||
|
||||
## Residuals
|
||||
|
||||
- `rapp-secrets-engine` and `rapp-tenant-engine` remain undeclared stubs;
|
||||
wrap them only after the user-engine path validates.
|
||||
- `rapp-vergabe-teilnahme` extraction stays a `railiance-apps` residual
|
||||
(ADR-0003). This workplan does not close that item.
|
||||
- Schema enum `helm-managed-application` would be a `railiance-master`
|
||||
change if the platform-service name proves misleading.
|
||||
Loading…
Add table
Add a link
Reference in a new issue