railiance-platform/docs/s3-consumer-interfaces.md

# S3 consumer service interfaces

Work record: `RAILIANCE-WP-0016` item 17  
Date: 2026-08-15  
Contract version of this index: `1.0.0`

Consumers bind to these contracts, not to Helm chart names or pod topology.
Changing an engine behind a versioned interface does not bump the interface
unless the consumer-visible fields change.

| Interface | Version | Who it is for | Authority |
| --- | --- | --- | --- |
| Shared application database | `apps-pg.v1` | S5 apps that need an isolated database on `apps-pg` | `docs/apps-pg.md` |
| Isolated platform database | `rapp-postgres.v1` | Platform services that need a CNPG consumer on `platform-pg` | `rapp-postgres/declarations/rapp.yaml` `consumer_contract` |
| Standing runtime secret | `ccr-workload-kv.v1` | Workloads that need a KV path via External Secrets | `schemas/credential-change-request.schema.yaml` |
| Short-lived lease | `credential-grant.v1` | Operators/agents and dynamic DB roles | `credential-grants/catalog.yaml` |
| Rapp credential bind | `rapp-lane.v1` | How a rapp names the two lanes above | `docs/rapp-credential-lane-binding.md` |
| Consumption-mode gate | `consumption-mode.v1` | New orders for a restricted financial entity | `docs/consumption-mode-enforcement.md` |

## Compatibility rules

- A `vN` document may add optional fields. Removing or renaming a
  required field is `vN+1`.
- Values never appear in an interface document. Paths, grant ids, CCR
  ids, and role names are the contract.
- `make pg-deploy` / Bitnami DSN
  `postgresql-ha-pgpool.platform.svc.cluster.local` is **not** an
  interface. That stack is retired.

## `apps-pg.v1`

Consumer supplies: app name, namespace, database name, role name. Platform
provisions the role and CNPG `Database`, labels the namespace
`railiance.io/postgres-client=apps-pg`, and publishes a runtime Secret.
RW endpoint: `apps-pg-rw.databases.svc.cluster.local:5432`. Bootstrap
role `apps_admin` is not a consumer credential.

## `rapp-postgres.v1`

Consumer is a `consumers[].declaration`. Boundary unit is
`database-per-consumer`. Credential type is
`openbao-dynamic-database-credential` via grant
`rapp-postgres/<consumer>-<role>`. Tenant identifiers are opaque.

## `ccr-workload-kv.v1` and `credential-grant.v1`

Unchanged semantics from `docs/credential-change-approval.md` and
`docs/credential-broker.md`. The version name exists so a rapp can cite
the lane without restating TTL, delivery, or revocation rules.

## Not yet an interface

Valkey and in-cluster MinIO have capability blocks in `SCOPE.md` and no
live service. They do not receive a `v1` until a consumer exists.