121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# 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.
|