coulomb/railiance-master
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-master/docs/qonto-knative-runtime-contract.md

4.3 KiB
Raw Blame History

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

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.