Define derived rail and Qonto readiness architecture
This commit is contained in:
codex
parent
0b95c3029c
commit
8901ae4b15
9 changed files with 845 additions and 0 deletions
|
|
@ -15,10 +15,15 @@ recorded before they are spread across implementation repos.
|
|||
- [docs/reef-first-wave-rollout.md](docs/reef-first-wave-rollout.md)
|
||||
- [docs/fabric-state-hub-adaptation.md](docs/fabric-state-hub-adaptation.md)
|
||||
- [docs/repo-family-bootstrap-contract.md](docs/repo-family-bootstrap-contract.md)
|
||||
- [docs/rail-composition-contract.md](docs/rail-composition-contract.md)
|
||||
- [docs/reef-production-readiness-contract.md](docs/reef-production-readiness-contract.md)
|
||||
- [docs/qonto-knative-runtime-contract.md](docs/qonto-knative-runtime-contract.md)
|
||||
- [docs/adr/ADR-0001-repository-prefix-architecture.md](docs/adr/ADR-0001-repository-prefix-architecture.md)
|
||||
- [docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md](docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md)
|
||||
- [docs/adr/ADR-0003-rapp-first-wave-selection.md](docs/adr/ADR-0003-rapp-first-wave-selection.md)
|
||||
- [docs/adr/ADR-0004-first-wave-reef-rollout.md](docs/adr/ADR-0004-first-wave-reef-rollout.md)
|
||||
- [docs/adr/ADR-0005-derived-rail-composition.md](docs/adr/ADR-0005-derived-rail-composition.md)
|
||||
- [docs/adr/ADR-0006-reef-production-admission.md](docs/adr/ADR-0006-reef-production-admission.md)
|
||||
|
||||
## Current Explorations
|
||||
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@
|
|||
| --- | --- | --- | --- | --- |
|
||||
| workplan | RAILIANCE-WP-0017 | finished | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
|
||||
| workplan | RAILIANCE-WP-0018 | finished | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
|
||||
| workplan | RAILIANCE-WP-0019 | active | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0017-T01 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
|
||||
| task | RAILIANCE-WP-0017-T02 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
|
||||
| task | RAILIANCE-WP-0017-T03 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
|
||||
|
|
@ -23,3 +24,13 @@
|
|||
| task | RAILIANCE-WP-0018-T04 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
|
||||
| task | RAILIANCE-WP-0018-T05 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
|
||||
| task | RAILIANCE-WP-0018-T06 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md |
|
||||
| task | RAILIANCE-WP-0019-T01 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T02 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T03 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T04 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T05 | done | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T06 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T07 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T08 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T09 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
| task | RAILIANCE-WP-0019-T10 | progress | — | workplans/RAILIANCE-WP-0019-knative-qonto-runtime-on-reef-railiance.md |
|
||||
|
|
|
|||
31
docs/adr/ADR-0005-derived-rail-composition.md
Normal file
31
docs/adr/ADR-0005-derived-rail-composition.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# ADR-0005: Derived Rail Composition
|
||||
|
||||
Date: 2026-07-26
|
||||
Status: Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Knative provides distinct workload activation and revision semantics but runs
|
||||
on Kubernetes. Treating it as an unrelated peer rail would duplicate generic
|
||||
workload lifecycle and substrate assumptions.
|
||||
|
||||
## Decision
|
||||
|
||||
Railiance distinguishes base and derived rails.
|
||||
|
||||
`rail-kubernetes` is the default base rail for platform workloads.
|
||||
`rail-knative` is a derived rail that inherits a versioned
|
||||
`rail-kubernetes` common contract and overrides only Knative-specific
|
||||
activation, revision, autoscaling, traffic, cold-start, and rollback semantics.
|
||||
|
||||
The detailed contract is
|
||||
[`docs/rail-composition-contract.md`](../rail-composition-contract.md).
|
||||
|
||||
## Consequences
|
||||
|
||||
- New platform workloads continue to use `rail-kubernetes` unless a specialized
|
||||
rail is justified.
|
||||
- Derived rails declare base-rail compatibility rather than copying lifecycle
|
||||
contracts.
|
||||
- Fabric and conformance tooling must understand rail dependency and readiness.
|
||||
- Knative installation stays with the S2 substrate owner.
|
||||
29
docs/adr/ADR-0006-reef-production-admission.md
Normal file
29
docs/adr/ADR-0006-reef-production-admission.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# ADR-0006: Reef Production Admission
|
||||
|
||||
Date: 2026-07-26
|
||||
Status: Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Fabric topology can say that a reef hosts a rail or binds a workload, but that
|
||||
does not demonstrate capacity, isolation, recoverability, or approval for a
|
||||
critical internet-facing service.
|
||||
|
||||
## Decision
|
||||
|
||||
Rail and `rapp` bindings use explicit readiness states: `declared`,
|
||||
`installed`, `verified`, `production-approved`, and `deprecated`.
|
||||
|
||||
Critical workloads require machine-readable conformance evidence plus explicit
|
||||
acceptance of residual risks that cannot be automated. Mixed-rail reefs use
|
||||
defined split triggers.
|
||||
|
||||
The detailed contract is
|
||||
[`docs/reef-production-readiness-contract.md`](../reef-production-readiness-contract.md).
|
||||
|
||||
## Consequences
|
||||
|
||||
- `hosts_rail` and `binds_rapp` no longer imply deployability.
|
||||
- `reef-railiance` may host Knative in wave 2, but Qonto cannot be called
|
||||
production-approved solely from that declaration.
|
||||
- Repeated evidence collection should become functional automation.
|
||||
121
docs/qonto-knative-runtime-contract.md
Normal file
121
docs/qonto-knative-runtime-contract.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
# Qonto Knative Runtime Contract
|
||||
|
||||
Date: 2026-07-26
|
||||
Status: Architecture baseline; implementation values require measured evidence
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the end-to-end runtime boundary for an internet-reachable Qonto service
|
||||
that holds access to a company bank credential and scales to zero.
|
||||
|
||||
## Ownership And Flow
|
||||
|
||||
```text
|
||||
authenticated client
|
||||
-> reef ingress capability
|
||||
-> rail-knative request activation and revision routing
|
||||
-> rapp-qonto package
|
||||
-> qonto-assistant domain service
|
||||
-> OpenBao credential lane
|
||||
-> Qonto API
|
||||
```
|
||||
|
||||
- `railiance-cluster` owns ingress, DNS, certificate, Knative installation,
|
||||
and cluster-level network capabilities.
|
||||
- `rail-knative` owns activation, buffering, revisions, autoscaling, traffic,
|
||||
cold-start, and rail-specific rollback semantics.
|
||||
- `rapp-qonto` owns package manifests, runtime configuration, rail bindings,
|
||||
workload-specific smoke checks, and secret references.
|
||||
- `qonto-assistant` owns Qonto domain behavior, default-deny financial policy,
|
||||
authorization integration, and application audit events.
|
||||
- `reef-railiance` owns placement, local binding, and readiness evidence.
|
||||
|
||||
The raw workload service is never a public unauthenticated endpoint.
|
||||
|
||||
## Steady-State Identity And Secret Names
|
||||
|
||||
The steady runtime identity is named for `rapp-qonto`, not its source repo.
|
||||
|
||||
Recommended stable identifiers:
|
||||
|
||||
- workload principal: `rapp-qonto`
|
||||
- tenant: the canon-approved Binky tenant identifier
|
||||
- Kubernetes service account: `rapp-qonto`
|
||||
- OpenBao role: `rapp-qonto`
|
||||
- bank credential reference: `tenants/binky/qonto-api`
|
||||
- caller OIDC client: `rapp-qonto-client`
|
||||
|
||||
Any `qonto-assistant` runtime principal or secret role is a time-bounded
|
||||
migration bridge and must not become the steady-state declaration.
|
||||
|
||||
## Request And Cold-Start Contract
|
||||
|
||||
Implementation must measure and publish:
|
||||
|
||||
- cold-start service-level objective
|
||||
- caller timeout
|
||||
- activator or gateway buffering timeout
|
||||
- maximum concurrency
|
||||
- retry ownership and retry limit
|
||||
- readiness deadline
|
||||
- scale-down grace period
|
||||
|
||||
Financial or side-effecting operations must carry an idempotency key across
|
||||
activation, retries, and client reconnects. A timeout must not silently imply
|
||||
that an operation did not reach Qonto.
|
||||
|
||||
Until measured values exist, implementation may use conservative development
|
||||
defaults but must not claim `production-approved`.
|
||||
|
||||
## Dependency Failure Rules
|
||||
|
||||
- If caller identity cannot be verified: deny before activation when possible.
|
||||
- If workload identity cannot be established: fail closed.
|
||||
- If OpenBao or the bank-credential lane is unavailable: fail closed and emit
|
||||
an audit event; never fall back to a static embedded secret.
|
||||
- If Qonto is unavailable: return a bounded upstream failure and preserve
|
||||
idempotency/audit context.
|
||||
- If audit delivery is unavailable: follow the application security contract;
|
||||
critical mutations must not become unaudited best-effort operations.
|
||||
|
||||
## Network And Secret Controls
|
||||
|
||||
- default-deny ingress and egress
|
||||
- ingress only through the approved authenticated entry path
|
||||
- egress only to DNS, the approved OpenBao endpoint, required identity and
|
||||
authorization services, and Qonto API endpoints
|
||||
- `0.0.0.0/0:443` is not production-approved without a documented exception
|
||||
and compensating control
|
||||
- short-lived workload identity and least-privilege secret access
|
||||
- no secret value in Git, logs, State Hub, chat, or parent-shell output
|
||||
- automated revocation and negative-access tests
|
||||
|
||||
## Rollback And Fallback
|
||||
|
||||
Rollback order is:
|
||||
|
||||
1. previous verified Knative revision
|
||||
2. keep the verified revision warm by setting a temporary minimum scale
|
||||
3. declare the service unavailable
|
||||
|
||||
A direct `rail-kubernetes` deployment is an exceptional, time-bounded fallback.
|
||||
It requires an explicit exception record, the same security controls, an owner,
|
||||
and an expiry. It is not a parallel steady-state production path.
|
||||
|
||||
## Verification
|
||||
|
||||
Before production approval, automated evidence must cover:
|
||||
|
||||
- authenticated activation from scale zero
|
||||
- rejected unauthenticated and wrong-tenant requests
|
||||
- bounded cold start and timeout behavior
|
||||
- idempotent retry behavior
|
||||
- OpenBao positive and negative access
|
||||
- Qonto-only egress enforcement
|
||||
- audit delivery
|
||||
- revision rollback
|
||||
- credential revocation
|
||||
- dependency-failure behavior
|
||||
|
||||
The implementation path should progress from attended proof to agent-executed
|
||||
conformance and finally to scheduled functional automation.
|
||||
143
docs/rail-composition-contract.md
Normal file
143
docs/rail-composition-contract.md
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
# Rail Composition Contract
|
||||
|
||||
Date: 2026-07-26
|
||||
Status: Adopted for the second implementation wave
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how a specialized Railiance execution rail composes with the default
|
||||
`rail-kubernetes` contract without duplicating it.
|
||||
|
||||
Railiance platform workloads use `rail-kubernetes` by default. A specialized
|
||||
rail is justified only when a workload needs materially different execution
|
||||
semantics and those semantics cannot be expressed safely as a small workload
|
||||
profile.
|
||||
|
||||
## Rail Kinds
|
||||
|
||||
Rails have one of two composition kinds:
|
||||
|
||||
- `base`: owns a complete workload execution contract for a substrate class
|
||||
- `derived`: inherits a versioned base-rail contract and owns only its
|
||||
specialization
|
||||
|
||||
`rail-kubernetes` is the default base rail.
|
||||
|
||||
`rail-knative` is a derived rail:
|
||||
|
||||
```text
|
||||
Kubernetes substrate profile
|
||||
-> rail-kubernetes common workload contract
|
||||
-> rail-knative activation and revision specialization
|
||||
-> rapp-qonto workload binding
|
||||
```
|
||||
|
||||
Knative installation remains an S2 cluster capability. The derived rail owns
|
||||
how Railiance workloads use that installed capability.
|
||||
|
||||
## Required Declaration Fields
|
||||
|
||||
Every rail declaration must publish:
|
||||
|
||||
- `contract_version`
|
||||
- `composition_kind`
|
||||
- `ownership_repo`
|
||||
- `execution_architecture`
|
||||
- `required_substrate_capabilities`
|
||||
- `supported_rollout_modes`
|
||||
- `readiness_state`
|
||||
|
||||
A derived rail must additionally publish:
|
||||
|
||||
- `base_rail`
|
||||
- `base_rail_contract`
|
||||
- `inherited_semantics`
|
||||
- `overridden_semantics`
|
||||
- `compatibility_constraints`
|
||||
|
||||
## Inheritance Rule
|
||||
|
||||
A derived rail inherits, rather than copies:
|
||||
|
||||
- workload identity and ownership metadata
|
||||
- common criticality and approval semantics
|
||||
- health, evidence, promotion, and rollback vocabulary
|
||||
- common dependency and secret-reference representation
|
||||
- common audit and conformance requirements
|
||||
|
||||
A derived rail may override only semantics intrinsic to its execution model.
|
||||
For `rail-knative`, those are:
|
||||
|
||||
- revisions
|
||||
- request activation and buffering
|
||||
- scale-to-zero and minimum scale
|
||||
- concurrency and autoscaling
|
||||
- traffic splitting between revisions
|
||||
- cold-start readiness and timeout behavior
|
||||
- Knative-specific rollback
|
||||
|
||||
## Non-Goals For `rail-knative`
|
||||
|
||||
`rail-knative` must not own:
|
||||
|
||||
- Kubernetes or k3s bootstrap
|
||||
- Knative operator installation or cluster-scoped lifecycle
|
||||
- generic namespace, RBAC, ingress-controller, certificate, storage, or
|
||||
observability ownership
|
||||
- Qonto-specific manifests, policies, secret paths, or health checks
|
||||
- a fork of the generic Railiance promotion vocabulary
|
||||
|
||||
## Rail-Neutral Workload Contract
|
||||
|
||||
Managed workload declarations have a common section and one or more rail
|
||||
bindings.
|
||||
|
||||
The common section owns:
|
||||
|
||||
- workload and ownership identity
|
||||
- criticality and data classification
|
||||
- dependencies
|
||||
- workload identity and secret references
|
||||
- health, smoke, audit, recovery, and approval requirements
|
||||
- reliability objectives
|
||||
|
||||
Each rail binding owns:
|
||||
|
||||
- rail and contract version constraint
|
||||
- rail-specific deployment artifacts
|
||||
- scaling, routing, rollout, and rollback parameters
|
||||
- required substrate capabilities
|
||||
|
||||
This makes Kubernetes the default binding while allowing a workload such as
|
||||
Qonto to add a justified Knative binding without changing domain ownership.
|
||||
|
||||
## Compatibility And Readiness
|
||||
|
||||
Declarations distinguish:
|
||||
|
||||
- `declared`: source-controlled contract exists
|
||||
- `installed`: required runtime components are present
|
||||
- `verified`: conformance and smoke evidence passes
|
||||
- `production-approved`: criticality-specific admission gates pass
|
||||
- `deprecated`: no new bindings are accepted
|
||||
|
||||
Fabric relations describe topology, not readiness. A `hosts_rail` or
|
||||
`binds_rapp` edge must carry or resolve a readiness state before automation
|
||||
may treat it as deployable.
|
||||
|
||||
## Automation Requirement
|
||||
|
||||
All deterministic checks should be function-executable and idempotent:
|
||||
|
||||
- schema validation
|
||||
- base-rail compatibility resolution
|
||||
- substrate-capability matching
|
||||
- binding and ownership integrity
|
||||
- readiness evidence freshness
|
||||
- drift detection
|
||||
|
||||
Human interaction is reserved for policy acceptance, exceptional risk, or
|
||||
authority that cannot safely be delegated. Repeated evidence collection,
|
||||
credential routing, reconciliation, and deployment verification should move
|
||||
from human operation to agentic interaction and then to functional automation
|
||||
as the contract stabilizes.
|
||||
79
docs/reef-production-readiness-contract.md
Normal file
79
docs/reef-production-readiness-contract.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# Reef Production Readiness Contract
|
||||
|
||||
Date: 2026-07-26
|
||||
Status: Adopted for the second implementation wave
|
||||
|
||||
## Purpose
|
||||
|
||||
Prevent a topology declaration from being mistaken for permission to run a
|
||||
critical workload.
|
||||
|
||||
`hosts_rail` and `binds_rapp` describe intended composition. Production use
|
||||
requires explicit readiness evidence.
|
||||
|
||||
## Admission States
|
||||
|
||||
Every hosted rail and bound `rapp` uses:
|
||||
|
||||
- `declared`
|
||||
- `installed`
|
||||
- `verified`
|
||||
- `production-approved`
|
||||
- `deprecated`
|
||||
|
||||
Promotion is monotonic only while its evidence remains current. Failed or
|
||||
expired evidence returns the binding to the last proven state.
|
||||
|
||||
## Required Reef Evidence
|
||||
|
||||
Before a rail becomes `verified`, the reef must provide machine-readable
|
||||
evidence for:
|
||||
|
||||
- substrate and Kubernetes version compatibility
|
||||
- control-plane and workload capacity with documented headroom
|
||||
- ingress, DNS, and certificate path
|
||||
- storage and stateful-workload constraints
|
||||
- workload identity and approved secret-delivery path
|
||||
- network isolation and egress enforcement
|
||||
- logs, metrics, traces, alerting, and audit delivery
|
||||
- backup, restore, and rollback path
|
||||
- upgrade and maintenance ownership
|
||||
- failure-domain and recovery assumptions
|
||||
|
||||
## Critical Workload Gate
|
||||
|
||||
Before a critical, internet-facing, or high-value-credential workload becomes
|
||||
`production-approved`, its binding must additionally record:
|
||||
|
||||
- threat-model reference
|
||||
- availability, cold-start, and recovery objectives
|
||||
- identity, secret revocation, and audit evidence
|
||||
- negative authorization and network tests
|
||||
- rollback and temporary-fallback rules
|
||||
- accepted residual risks and their owner
|
||||
|
||||
The single-server and shared-control-plane risks of `reef-railiance` must be
|
||||
explicitly accepted or mitigated for `rapp-qonto`; the reef name or `high`
|
||||
criticality label is not evidence by itself.
|
||||
|
||||
## Mixed-Rail Rule
|
||||
|
||||
`reef-railiance` may host `rail-kubernetes` and `rail-knative` during the
|
||||
second wave, while `rail-kubernetes` remains primary.
|
||||
|
||||
Reassess or split the reef when any of these triggers occurs:
|
||||
|
||||
- incompatible maintenance or upgrade windows
|
||||
- inability to meet a critical workload recovery objective
|
||||
- control-plane or workload resource contention
|
||||
- materially different network or tenant-isolation requirements
|
||||
- independent scaling or availability requirements
|
||||
- failure in one rail cannot be contained from the other
|
||||
- premium-security or regulatory policy requires a separate boundary
|
||||
|
||||
## Automation Requirement
|
||||
|
||||
Readiness evidence should be produced by idempotent probes and stored as
|
||||
source-linked, timestamped records. Agents may execute and reconcile the
|
||||
probes. Human approval should consume the evidence only where policy requires
|
||||
explicit risk acceptance; it should not be used as a substitute for tests.
|
||||
|
|
@ -31,6 +31,11 @@ For the current phase of Railiance:
|
|||
|
||||
This means the repo model is intentionally ahead of the repo count.
|
||||
|
||||
Rails may compose. `rail-kubernetes` is the default base rail, while
|
||||
Kubernetes-hosted execution specializations such as `rail-knative` are derived
|
||||
rails with an explicit, versioned base-rail dependency. A derived rail owns
|
||||
only the semantics it changes; it does not fork the common workload lifecycle.
|
||||
|
||||
## The Four Repo Families
|
||||
|
||||
| Prefix | Axis | Unit | Primary question answered |
|
||||
|
|
@ -90,6 +95,10 @@ A rail owns the execution semantics for workloads on that architecture:
|
|||
|
||||
A rail is not the workload itself and not the substrate it runs on.
|
||||
|
||||
A rail declaration identifies whether it is a `base` or `derived` rail. A
|
||||
derived rail names its base contract, inherited semantics, overrides,
|
||||
compatibility constraints, and readiness state.
|
||||
|
||||
In the current Railiance model, `rail-kubernetes` is the default base rail.
|
||||
Other rails should be introduced only when their runtime semantics justify a
|
||||
distinct lifecycle, contract, or operator model.
|
||||
|
|
@ -187,6 +196,10 @@ This separation reduces confusion between:
|
|||
- workload identity
|
||||
- deployment location
|
||||
|
||||
Topology and readiness are also separate. A reef may declare that it hosts a
|
||||
rail or binds a `rapp` without that combination yet being installed, verified,
|
||||
or production-approved.
|
||||
|
||||
## Creation Rules
|
||||
|
||||
Use the following default rules.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,413 @@
|
|||
---
|
||||
id: RAILIANCE-WP-0019
|
||||
type: workplan
|
||||
title: "Knative Qonto Runtime on reef-railiance"
|
||||
domain: financials
|
||||
repo: railiance-master
|
||||
status: active
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 19
|
||||
created: "2026-07-26"
|
||||
updated: "2026-07-26"
|
||||
related_repos:
|
||||
- railiance-master
|
||||
- qonto-assistant
|
||||
- key-cape
|
||||
- rail-kubernetes
|
||||
- reef-railiance
|
||||
- railiance-platform
|
||||
- railiance-fabric
|
||||
state_hub_workstream_id: "d2b082db-ecc3-4322-8be3-22aa00a2af5c"
|
||||
---
|
||||
|
||||
# RAILIANCE-WP-0019 - Knative Qonto Runtime on reef-railiance
|
||||
|
||||
## Goal
|
||||
|
||||
Turn the Qonto internet-runtime direction into an explicit second-wave
|
||||
Railiance repo-family plan: `reef-railiance` hosts a new `rail-knative`, and
|
||||
that rail dynamically runs a new `rapp-qonto` package extracted from the
|
||||
current `qonto-assistant` deployment path.
|
||||
|
||||
This workplan exists to replace the remaining "custom activator or maybe
|
||||
Knative" ambiguity with a concrete cross-repo architecture path before new
|
||||
runtime implementation starts.
|
||||
|
||||
The second-wave design also establishes a general rule for reliable and
|
||||
cost-efficient operation: deterministic work should progress from attended
|
||||
human operation, to agent-executable interaction, to idempotent functional
|
||||
automation as its contract stabilizes. Human interaction remains appropriate
|
||||
for irreducible policy acceptance and privileged authority, not for repeated
|
||||
evidence collection or routine reconciliation.
|
||||
|
||||
## Why This Exists
|
||||
|
||||
`RAILIANCE-WP-0018` finished the first wave:
|
||||
|
||||
- `rail-kubernetes` exists as the default base rail
|
||||
- `reef-railiance` exists as the grouped home reef for the Railiance servers
|
||||
- `rapp-openbao` proved the first managed package split
|
||||
- Fabric can now project `governed_by`, `supports_rail`, `hosts_rail`, and
|
||||
`binds_rapp`
|
||||
|
||||
The next concrete runtime pressure comes from `QONTO-WP-0004`. That workload
|
||||
needs internet reachability, bounded cold-start behavior, strong identity, and
|
||||
strict secret custody. Those are exactly the conditions that justify a second
|
||||
rail instead of extending the direct `rail-kubernetes` path indefinitely.
|
||||
|
||||
At the same time, `KEY-WP-0004` is provisioning the first tenant and workload
|
||||
identity lane for Binky Hedgehog GmbH. That lane should target the future
|
||||
runtime package and not harden a permanent direct deployment shape that the
|
||||
framework now intends to replace.
|
||||
|
||||
## Current Starting Point
|
||||
|
||||
The current ecosystem state is:
|
||||
|
||||
- `reef-railiance` is the grouped reef for the Railiance server fleet
|
||||
- `rail-kubernetes` owns the current baseline deployment and lifecycle contract
|
||||
- `qonto-assistant` already contains the Qonto domain code, hardening work, and
|
||||
an initial direct Kubernetes placement request
|
||||
- `key-cape` has `KEY-WP-0004` open for the Binky tenant and qonto workload
|
||||
identity lane
|
||||
- no `rail-knative` repo exists yet
|
||||
- no `rapp-qonto` repo exists yet
|
||||
|
||||
## Target Outcome
|
||||
|
||||
When this workplan is complete:
|
||||
|
||||
1. The boundary between `rail-kubernetes` and a new derived `rail-knative` is
|
||||
written and approved.
|
||||
2. The boundary between `qonto-assistant` and a future `rapp-qonto` is written
|
||||
and approved.
|
||||
3. `reef-railiance` is confirmed as the first host reef for this runtime path,
|
||||
including the rail/reef binding assumptions.
|
||||
4. Identity, secret, and routing lanes are aligned to the future
|
||||
`rapp-qonto` runtime instead of a permanent direct `qonto-assistant`
|
||||
deployment.
|
||||
5. Repo-local follow-up workplans can launch `rail-knative` and `rapp-qonto`
|
||||
without reopening the architecture question.
|
||||
6. Reef admission, contract compatibility, credential routing, and operational
|
||||
evidence have automation-ready contracts before production implementation.
|
||||
|
||||
## Boundaries
|
||||
|
||||
This workplan may define architecture, sequencing, and repo-boundary contracts
|
||||
across Railiance, `qonto-assistant`, and `key-cape`.
|
||||
|
||||
It must not:
|
||||
|
||||
- bootstrap `rail-knative` yet
|
||||
- bootstrap `rapp-qonto` yet
|
||||
- move code or manifests between repos
|
||||
- implement runtime changes in `reef-railiance`, `rail-kubernetes`,
|
||||
`qonto-assistant`, or `key-cape`
|
||||
|
||||
Implementation starts only after the follow-up workplans opened from this plan
|
||||
are reviewed and accepted.
|
||||
|
||||
## Tasks
|
||||
|
||||
## T01 - Define the `rail-knative` boundary against `rail-kubernetes`
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "336cb298-9107-4519-ad64-5b23853c84fa"
|
||||
```
|
||||
|
||||
Write the contract for what `rail-knative` must own versus what remains owned
|
||||
by `rail-kubernetes`.
|
||||
|
||||
At minimum this boundary must decide ownership for:
|
||||
|
||||
- scale-to-zero and cold-start semantics
|
||||
- service activation / ingress entry behavior
|
||||
- Knative Serving primitives versus generic Railiance lifecycle semantics
|
||||
- compatibility expectations for `reef-railiance`
|
||||
- what stays reusable from the base Kubernetes rail instead of being forked
|
||||
|
||||
Acceptance:
|
||||
|
||||
- one written boundary contract exists
|
||||
- the contract names explicit non-goals for `rail-knative`
|
||||
- the split does not duplicate the generic lifecycle contract already owned by
|
||||
`rail-kubernetes`
|
||||
|
||||
2026-07-26: Added `docs/rail-composition-contract.md` and
|
||||
`docs/adr/ADR-0005-derived-rail-composition.md`. `rail-knative` is now a
|
||||
derived rail with a versioned `rail-kubernetes` base contract. The contract
|
||||
defines inheritance, overrides, non-goals, readiness states, and a rail-neutral
|
||||
workload/binding model.
|
||||
|
||||
## T02 - Define the `rapp-qonto` extraction boundary from `qonto-assistant`
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "54fcea7d-3c4e-444f-b184-f18f3c4b3a7c"
|
||||
```
|
||||
|
||||
Write the contract for what moves into `rapp-qonto` and what stays in
|
||||
`qonto-assistant`.
|
||||
|
||||
This task must keep `qonto-assistant` as the ownership home for the Qonto
|
||||
domain logic while using `rapp-qonto` as the managed runtime/package boundary.
|
||||
|
||||
At minimum the contract must decide ownership for:
|
||||
|
||||
- deployment packaging and runtime manifests
|
||||
- runtime configuration and secret references
|
||||
- smoke, rollout, rollback, and promotion expectations
|
||||
- how the current direct Kubernetes material becomes migration input rather
|
||||
than a permanent target shape
|
||||
|
||||
Acceptance:
|
||||
|
||||
- one written boundary contract exists
|
||||
- `qonto-assistant` remains the ownership repo in the contract
|
||||
- `rapp-qonto` is justified as a managed package repo and not as a new
|
||||
ownership mirror
|
||||
|
||||
2026-07-26: Added the ownership and request-flow boundary in
|
||||
`docs/qonto-knative-runtime-contract.md`. `qonto-assistant` retains domain
|
||||
logic, financial policy, authorization integration, and application audit
|
||||
events. `rapp-qonto` owns packaging, rail bindings, runtime configuration,
|
||||
secret references, and workload-specific rollout evidence.
|
||||
|
||||
## T03 - Define the `reef-railiance` hosting model for the qonto runtime
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "b0233f06-3dee-4cac-bae4-d8add5ac29c8"
|
||||
```
|
||||
|
||||
Confirm how `reef-railiance` hosts the first `rail-knative` runtime slice and
|
||||
what that means for ingress, isolation, and criticality.
|
||||
|
||||
This task must decide:
|
||||
|
||||
- whether the qonto path lives entirely on `reef-railiance` in wave 2
|
||||
- how `rail-knative` is declared as a hosted rail there
|
||||
- whether a primary-rail versus mixed-rail statement needs revision
|
||||
- what existing S1/S2 approvals or substrate notes must be updated before
|
||||
runtime work starts
|
||||
|
||||
Acceptance:
|
||||
|
||||
- the hosting assumption is written
|
||||
- the reef/rail relation update path is named
|
||||
- unresolved substrate risks are listed instead of buried in repo-local work
|
||||
|
||||
2026-07-26: Added `docs/reef-production-readiness-contract.md` and
|
||||
`docs/adr/ADR-0006-reef-production-admission.md`. `reef-railiance` may host
|
||||
`rail-knative` during wave 2 while keeping `rail-kubernetes` primary, but
|
||||
topology no longer implies readiness. Critical Qonto admission requires
|
||||
capacity, ingress, identity, isolation, observability, recovery, and explicit
|
||||
single-server/shared-control-plane risk evidence.
|
||||
|
||||
## T04 - Align identity and secret custody to the future runtime path
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "0086eb68-a852-4fe7-834c-4a19dd763b77"
|
||||
```
|
||||
|
||||
Align `KEY-WP-0004`, the OpenBao lane, and the ops-warden routing lane so the
|
||||
credential path terminates at the future `rapp-qonto` runtime on
|
||||
`rail-knative`, while still allowing a clearly temporary migration bridge from
|
||||
the current `qonto-assistant` repo.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- the future runtime principal and lane names are defined
|
||||
- the transitional use of any current `qonto-assistant` runtime role is
|
||||
explicitly marked temporary
|
||||
- no workplan still assumes a permanent direct deployment target for the lane
|
||||
|
||||
2026-07-26: `docs/qonto-knative-runtime-contract.md` defines steady identifiers
|
||||
for `rapp-qonto`, its service account, OpenBao role, and caller client while
|
||||
making any `qonto-assistant` role a time-bounded bridge. Credential values must
|
||||
use sanctioned custody and execution transports; only route and conformance
|
||||
metadata may enter workplans, Git, chat, or State Hub.
|
||||
|
||||
## T05 - Define second-wave bootstrap and Fabric registration sequence
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "8905d447-dee9-460d-bbfe-3f0c8e42c7c6"
|
||||
```
|
||||
|
||||
Define the repo-creation and registration sequence for `rail-knative` and
|
||||
`rapp-qonto`, using the first-wave bootstrap contract already proven by
|
||||
`RAILIANCE-WP-0018`.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- the bootstrap order is named
|
||||
- the minimum declaration files are named for both future repos
|
||||
- the expected Fabric relations (`supports_rail`, `hosts_rail`, `binds_rapp`,
|
||||
`governed_by`) are named before repo creation starts
|
||||
|
||||
Bootstrap order:
|
||||
|
||||
1. publish the common contract/schema additions in `rail-kubernetes`
|
||||
2. add readiness and compatibility support in Fabric
|
||||
3. open the `reef-railiance` admission work and collect baseline evidence
|
||||
4. bootstrap `rail-knative` with a derived-rail declaration
|
||||
5. bootstrap `rapp-qonto` with common and Knative binding declarations
|
||||
6. register `governed_by`, `base_rail`, `supports_rail`, `hosts_rail`, and
|
||||
`binds_rapp` relations
|
||||
7. promote relations through `declared`, `installed`, `verified`, and
|
||||
`production-approved` only as evidence lands
|
||||
|
||||
The minimum declaration files remain `declarations/rail.yaml`,
|
||||
`declarations/rapp.yaml`, and `declarations/reef.yaml`. Rail-neutral workload
|
||||
and rail-binding schemas must be source-controlled before repo creation is
|
||||
treated as implementation completion.
|
||||
|
||||
## T06 - Open the repo-local follow-up workplans for implementation
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T06
|
||||
status: progress
|
||||
priority: medium
|
||||
state_hub_task_id: "18fe6f04-f8c5-451b-8e3f-38c19f05f682"
|
||||
```
|
||||
|
||||
Once the boundary and sequencing documents exist, open or update the concrete
|
||||
repo-local implementation workplans that will execute them.
|
||||
|
||||
At minimum, this should cover:
|
||||
|
||||
- `qonto-assistant`
|
||||
- `key-cape`
|
||||
- `reef-railiance`
|
||||
- the future `rail-knative` repo at bootstrap time
|
||||
- the future `rapp-qonto` repo at bootstrap time
|
||||
|
||||
Acceptance:
|
||||
|
||||
- each implementation-owning repo has a concrete follow-up workplan
|
||||
- no implementation starts from an unwritten architecture assumption
|
||||
- this framework workplan can later close with repo-local execution delegated
|
||||
|
||||
2026-07-26: Architecture is ready for repo-local workplan creation. Workplans
|
||||
must separate source-repo, package, derived-rail, reef admission, Fabric
|
||||
compatibility, identity/custody, and S2 runtime installation responsibilities.
|
||||
|
||||
## T07 - Version the rail-neutral workload and compatibility contract
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T07
|
||||
status: progress
|
||||
priority: high
|
||||
state_hub_task_id: "5b5f2d41-2860-44ee-a8b6-8b9e1d32854f"
|
||||
```
|
||||
|
||||
Turn the composition decision into source-controlled schemas and conformance
|
||||
checks.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- workload declarations separate common facts from rail bindings
|
||||
- base and derived rails declare contract versions and compatibility
|
||||
- validation rejects missing owners, incompatible base rails, and unsupported
|
||||
substrate capabilities
|
||||
- Kubernetes remains the default binding for platform workloads
|
||||
|
||||
## T08 - Establish reef admission evidence and mixed-rail split triggers
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T08
|
||||
status: progress
|
||||
priority: high
|
||||
state_hub_task_id: "663a319e-2a05-4a35-90a2-4f6b7b5afa22"
|
||||
```
|
||||
|
||||
Implement the production-readiness states and evidence model in
|
||||
`reef-railiance` and Fabric.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- topology is distinct from installed, verified, and production-approved state
|
||||
- capacity, ingress, network, identity, observability, recovery, and failure
|
||||
domain evidence have machine-readable locations
|
||||
- Qonto's single-server/shared-control-plane residual risk is explicit
|
||||
- mixed-rail split triggers are represented
|
||||
|
||||
## T09 - Establish Qonto SLO, threat, rollback, and fallback evidence
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T09
|
||||
status: progress
|
||||
priority: high
|
||||
state_hub_task_id: "6cc2d3a7-33b6-47a7-b59d-04be9318c861"
|
||||
```
|
||||
|
||||
Turn `docs/qonto-knative-runtime-contract.md` into executable package and
|
||||
source-repo verification.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- cold start, request timeout, buffering, concurrency, and scale-down values
|
||||
are measured before production approval
|
||||
- retry and idempotency behavior is explicit for financial operations
|
||||
- public ingress and raw service exposure boundaries are testable
|
||||
- egress is narrower than unrestricted HTTPS or has an approved exception
|
||||
- rollback prefers a verified Knative revision; direct Kubernetes fallback is
|
||||
time-bounded and exceptional
|
||||
|
||||
## T10 - Automate routing, conformance, reconciliation, and evidence
|
||||
|
||||
```task
|
||||
id: RAILIANCE-WP-0019-T10
|
||||
status: progress
|
||||
priority: high
|
||||
state_hub_task_id: "1b75308f-f968-4443-aefe-af37550545a1"
|
||||
```
|
||||
|
||||
Move repeatable operation toward reliable functional automation while
|
||||
preserving least privilege and explicit risk authority.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- `warden plan` and route lookup cover implementation credential needs before
|
||||
any founder interaction is proposed
|
||||
- agents use sanctioned `--exec`, `--out`, or wrapped transports rather than
|
||||
reading secret values
|
||||
- conformance checks are idempotent and suitable for CI or scheduled execution
|
||||
- Fabric/State Hub reconciliation consumes source declarations and evidence
|
||||
- human steps are limited to named authority or residual-risk decisions and
|
||||
have an automation follow-up path
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- [x] `rail-knative` has a written boundary against `rail-kubernetes`
|
||||
- [x] `rapp-qonto` has a written boundary against `qonto-assistant`
|
||||
- [x] `reef-railiance` is explicitly named as the first host reef
|
||||
- [x] identity and secret custody point at the future runtime path
|
||||
- [x] derived-rail composition and non-duplication are decided
|
||||
- [x] reef readiness and mixed-rail split rules are decided
|
||||
- [x] Qonto end-to-end failure, rollback, and security boundaries are written
|
||||
- [ ] common and rail-binding schemas are implemented
|
||||
- [ ] repo-local implementation workplans are registered and active
|
||||
- [ ] conformance and credential-routing paths are agent-executable
|
||||
- [x] second-wave repo bootstrap order is defined
|
||||
- [ ] repo-local implementation workplans exist before implementation begins
|
||||
|
||||
## Notes
|
||||
|
||||
This is a second-wave framework plan. It should stay at the planning and
|
||||
coordination layer until the relevant repo-local workplans are in place.
|
||||
Loading…
Add table
Add a link
Reference in a new issue