Build payments-api REST layer (Layer 3), mirroring customers-api

6 routes over Payment, composite key (customernumber + checknumber),
proxying to classic-models-api. openid-connect with RFC 8693 token
exchange to classic-models-api audience, rate-limiting, proxy-cache,
audit-log — same structure as customers-api's REST layer.

Keycloak (local): payments-api-audience client scope + payments-api
resource client added, attached to kong-token-exchange-broker's
default scopes. No dedicated protocol mappers on payments-api
itself, same practice as customers-api/mcp-customers.

No MCP layer — same as customers-api, not needed yet.
This commit is contained in:
Stéphane Tailland
2026-08-23 16:23:00 +02:00
parent 79d0b5a078
commit bf5adadb24
19 changed files with 660 additions and 11 deletions
+49 -9
View File
@@ -1,12 +1,52 @@
# payments-api
Placeholder component repo for the **payments** slice of
`classic-models-api` (see /Users/stephanetailland/git/classic-models-api),
split out per the DDD decomposition documented in
`../kong-konnect-deployment-strategy.md`.
Kong routing/policy layer for the **payments** slice of
`classic-models-api` (see `/Users/stephanetailland/git/classic-models-api`),
split out per the DDD decomposition in `../kong-konnect-deployment-strategy.md`.
The backend itself stays a single monolith — only Kong does the domain
split. Structure mirrors `../customers-api`, not `../catalog-api` — see
`../STATUS.md` section 18 for why (`catalog-api`'s two-route MCP pattern
has a latent bug; `customers-api`'s single-route pattern is the corrected
one to copy going forward).
This repo does not yet contain migrated application code — only the
routing scaffold (layer 3: `HTTPRoute`/`KongPlugin`/`KongConsumer`,
alongside the eventual app manifests), targeting the Control Plane(s)
provisioned for `payments` (see `../konnect-platform/domains/payments/`
and `../dataplane-payments`).
**REST only, no MCP layer.** 6 routes over `Payment`, which uses a
**composite key** (`customernumber` + `checknumber`, not a single id like
`Customer`/`Product`) — both URI segments are captured and passed through
to the backend's own composite-key URL pattern.
| Route | Method | Backend path |
|---|---|---|
| `/payments/v1/payments/` | GET, POST | `/classic-models/api/v1/payments/` |
| `/payments/v1/payments/{customernumber}/{checknumber}/` | GET, PUT, PATCH, DELETE | `/classic-models/api/v1/payments/{customernumber}/{checknumber}/` |
## Auth
`openid-connect`, `audience_required`/token-exchange target =
`classic-models-api` (`BACKEND_AUDIENCE`) — same second-hop-exchange
pattern as `customers-api`'s REST layer: a caller gets a
`payments-api`-audience token from `kong-token-exchange-broker` directly
(no MCP hop exists for this domain), and this layer exchanges it again to
`classic-models-api` before the backend ever sees it. IdP is the local
Keycloak (`https://keycloak.sttlab.local/realms/classic-models`) — see
`../STATUS.md` sections 15/16. **No `payments-api` Keycloak client or
`payments-api-audience` client scope exists yet** — unlike `customers-api`,
this hasn't been created on the local Keycloak (nor attached to
`kong-token-exchange-broker`'s default scopes) as of this repo's initial
build. Nothing can actually authenticate against these routes until that's
done — same missing piece as `customers-api` had before its own Keycloak
wiring step.
## Other policies
Per-consumer rate limiting, response caching (GET/HEAD), audit log
(`http-log`, endpoint still a placeholder — no real log collector in this
lab, same caveat as the other domains).
## Structure
Same `dev/` + `kong/rest/` layout as `customers-api`. Deploy key
(`kong-v2/payments-api/git-deploy-key`) is a **copy of `catalog-api`'s**,
not a freshly generated one — per the user's explicit instruction this
session ("no reason a working key for catalog-api wouldn't work for
customers-api"), the same reused key is used here too rather than minting
yet another one per domain.
+25
View File
@@ -0,0 +1,25 @@
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: payments-api-git-auth
namespace: payments
spec:
refreshInterval: 1h
secretStoreRef:
kind: ClusterSecretStore
name: vault-kong-v2
target:
name: payments-api-git-auth
data:
- secretKey: identity
remoteRef:
key: kong-v2/payments-api/git-deploy-key
property: identity
- secretKey: identity.pub
remoteRef:
key: kong-v2/payments-api/git-deploy-key
property: identity.pub
- secretKey: known_hosts
remoteRef:
key: kong-v2/payments-api/git-deploy-key
property: known_hosts
+31
View File
@@ -0,0 +1,31 @@
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: payments-dev-api
namespace: payments
spec:
interval: 10m
sourceRef:
kind: GitRepository
name: payments-api-dev
path: ./kong
prune: true
dependsOn:
- name: payments-dev-api-gateway
namespace: flux-system
postBuild:
substitute:
NAME: payments-dev
NAMESPACE: payments
CONTROL_PLANE_REF_NAME: payments-dev-bz6vs
BACKEND_HOST: classic-models-api.classic-models.svc.cluster.local
OIDC_ISSUER: https://keycloak.sttlab.local/realms/classic-models
BACKEND_AUDIENCE: '["classic-models-api"]'
BACKEND_SCOPES: '[]'
API_RATE_LIMIT_MINUTE: "60"
AUDIT_LOG_ENDPOINT: http://audit-log-collector.observability.svc.cluster.local/logs
REST_HOSTNAME: payments-dev.sttlab.local
TOKEN_EXCHANGE_CLIENT_ID: kong-token-exchange-broker
substituteFrom:
- kind: Secret
name: payments-token-exchange-broker
+12
View File
@@ -0,0 +1,12 @@
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: payments-api-dev
namespace: payments
spec:
interval: 5m
url: ssh://git@gitea.sttlab.eu:2222/stt/kong-payments-api.git
secretRef:
name: payments-api-git-auth
ref:
branch: main
@@ -0,0 +1,17 @@
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: payments-token-exchange-broker
namespace: payments
spec:
refreshInterval: 1h
secretStoreRef:
kind: ClusterSecretStore
name: vault-kong-v2
target:
name: payments-token-exchange-broker
data:
- secretKey: TOKEN_EXCHANGE_CLIENT_SECRET
remoteRef:
key: kong-v2/payments-api/token-exchange-broker
property: client_secret
-1
View File
@@ -1 +0,0 @@
# TODO: HTTPRoute for payments's resources
-1
View File
@@ -1 +0,0 @@
# TODO: KongPlugin(s) specific to payments
+14
View File
@@ -0,0 +1,14 @@
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- rest/service.yaml
- rest/routes.yaml
- rest/path-rewrite.yaml
- rest/path-rewrite-bindings.yaml
- rest/kongplugin.yaml
- rest/rate-limiting.yaml
- rest/proxy-cache.yaml
- rest/audit-log.yaml
- rest/audit-log-body-capture.yaml
- rest/audit-log-body-capture-bindings.yaml
- rest/pluginbindings.yaml
@@ -0,0 +1,35 @@
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-audit-capture-request-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-audit-capture-request
targets:
serviceRef:
group: configuration.konghq.com
kind: KongService
name: ${NAME}-payments-api
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-audit-capture-response-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-audit-capture-response
targets:
serviceRef:
group: configuration.konghq.com
kind: KongService
name: ${NAME}-payments-api
+27
View File
@@ -0,0 +1,27 @@
# dev only: captures raw request/response bodies into kong.ctx.shared for
# audit-log.yaml's custom_fields_by_lua to read back in the log phase.
# Drop this file (and its bindings) to stop body capture without touching
# audit-log.yaml itself — it degrades gracefully to metadata-only logging.
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-audit-capture-request
namespace: ${NAMESPACE}
plugin: pre-function
config:
access:
- "kong.ctx.shared.audit_request_body = kong.request.get_raw_body()"
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-audit-capture-response
namespace: ${NAMESPACE}
plugin: post-function
config:
body_filter:
- |
local chunk = ngx.arg[1]
if chunk then
kong.ctx.shared.audit_response_body = (kong.ctx.shared.audit_response_body or "") .. chunk
end
+17
View File
@@ -0,0 +1,17 @@
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-audit-log
namespace: ${NAMESPACE}
plugin: http-log
# dev only: the raw Authorization (JWT) header is captured in clear text,
# not acceptable as-is for a non-dev environment. request_body/response_body
# below read from kong.ctx.shared, populated by audit-log-body-capture.yaml
# — nil (and silently omitted) if that file isn't applied.
config:
http_endpoint: ${AUDIT_LOG_ENDPOINT}
method: POST
content_type: application/json
custom_fields_by_lua:
request_body: "return kong.ctx.shared.audit_request_body"
response_body: "return kong.ctx.shared.audit_response_body"
+30
View File
@@ -0,0 +1,30 @@
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-openid-connect
namespace: ${NAMESPACE}
plugin: openid-connect
config:
issuer: ${OIDC_ISSUER}
audience_required: ${BACKEND_AUDIENCE}
auth_methods:
- bearer
display_errors: false
ssl_verify: true
consumer_claims:
- - sub
consumer_by:
- custom_id
- username
consumer_optional: true
client_id:
- ${TOKEN_EXCHANGE_CLIENT_ID}
client_secret:
- ${TOKEN_EXCHANGE_CLIENT_SECRET}
token_exchange:
subject_token_issuers:
- issuer: ${OIDC_ISSUER}
conditions: {}
request:
audience: ${BACKEND_AUDIENCE}
scopes: ${BACKEND_SCOPES}
+107
View File
@@ -0,0 +1,107 @@
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-rewrite-listpayments-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-rewrite-listpayments
targets:
routeRef:
group: configuration.konghq.com
kind: KongRoute
name: ${NAME}-payments-api-listpayments
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-rewrite-createpayment-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-rewrite-createpayment
targets:
routeRef:
group: configuration.konghq.com
kind: KongRoute
name: ${NAME}-payments-api-createpayment
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-rewrite-getpayment-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-rewrite-getpayment
targets:
routeRef:
group: configuration.konghq.com
kind: KongRoute
name: ${NAME}-payments-api-getpayment
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-rewrite-updatepayment-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-rewrite-updatepayment
targets:
routeRef:
group: configuration.konghq.com
kind: KongRoute
name: ${NAME}-payments-api-updatepayment
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-rewrite-patchpayment-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-rewrite-patchpayment
targets:
routeRef:
group: configuration.konghq.com
kind: KongRoute
name: ${NAME}-payments-api-patchpayment
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-rewrite-deletepayment-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-rewrite-deletepayment
targets:
routeRef:
group: configuration.konghq.com
kind: KongRoute
name: ${NAME}-payments-api-deletepayment
+59
View File
@@ -0,0 +1,59 @@
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-rewrite-listpayments
namespace: ${NAMESPACE}
plugin: request-transformer-advanced
config:
replace:
uri: /classic-models/api/v1/payments/
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-rewrite-createpayment
namespace: ${NAMESPACE}
plugin: request-transformer-advanced
config:
replace:
uri: /classic-models/api/v1/payments/
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-rewrite-getpayment
namespace: ${NAMESPACE}
plugin: request-transformer-advanced
config:
replace:
uri: /classic-models/api/v1/payments/$(uri_captures.customernumber)/$(uri_captures.checknumber)/
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-rewrite-updatepayment
namespace: ${NAMESPACE}
plugin: request-transformer-advanced
config:
replace:
uri: /classic-models/api/v1/payments/$(uri_captures.customernumber)/$(uri_captures.checknumber)/
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-rewrite-patchpayment
namespace: ${NAMESPACE}
plugin: request-transformer-advanced
config:
replace:
uri: /classic-models/api/v1/payments/$(uri_captures.customernumber)/$(uri_captures.checknumber)/
---
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-rewrite-deletepayment
namespace: ${NAMESPACE}
plugin: request-transformer-advanced
config:
replace:
uri: /classic-models/api/v1/payments/$(uri_captures.customernumber)/$(uri_captures.checknumber)/
+71
View File
@@ -0,0 +1,71 @@
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-openid-connect-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-openid-connect
targets:
serviceRef:
group: configuration.konghq.com
kind: KongService
name: ${NAME}-payments-api
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-rate-limiting-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-rate-limiting
targets:
serviceRef:
group: configuration.konghq.com
kind: KongService
name: ${NAME}-payments-api
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-proxy-cache-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-proxy-cache
targets:
serviceRef:
group: configuration.konghq.com
kind: KongService
name: ${NAME}-payments-api
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: ${NAME}-payments-api-audit-log-binding
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
pluginRef:
name: ${NAME}-payments-api-audit-log
targets:
serviceRef:
group: configuration.konghq.com
kind: KongService
name: ${NAME}-payments-api
+16
View File
@@ -0,0 +1,16 @@
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-proxy-cache
namespace: ${NAMESPACE}
plugin: proxy-cache-advanced
config:
strategy: memory
request_method:
- GET
- HEAD
response_code:
- 200
content_type:
- application/json
cache_ttl: 60
+14
View File
@@ -0,0 +1,14 @@
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: ${NAME}-payments-api-rate-limiting
namespace: ${NAMESPACE}
plugin: rate-limiting-advanced
config:
limit:
- ${API_RATE_LIMIT_MINUTE}
window_size:
- 60
identifier: consumer
sync_rate: -1
strategy: local
+119
View File
@@ -0,0 +1,119 @@
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
name: ${NAME}-payments-api-listpayments
namespace: ${NAMESPACE}
spec:
serviceRef:
type: namespacedRef
namespacedRef:
name: ${NAME}-payments-api
name: payments-api_listpayments
methods:
- GET
- OPTIONS
paths:
- /payments/v1/payments/
strip_path: false
tags:
- payments
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
name: ${NAME}-payments-api-createpayment
namespace: ${NAMESPACE}
spec:
serviceRef:
type: namespacedRef
namespacedRef:
name: ${NAME}-payments-api
name: payments-api_createpayment
methods:
- POST
- OPTIONS
paths:
- /payments/v1/payments/
strip_path: false
tags:
- payments
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
name: ${NAME}-payments-api-getpayment
namespace: ${NAMESPACE}
spec:
serviceRef:
type: namespacedRef
namespacedRef:
name: ${NAME}-payments-api
name: payments-api_getpayment
methods:
- GET
- OPTIONS
paths:
- ~/payments/v1/payments/(?<customernumber>[^#?/]+)/(?<checknumber>[^#?/]+)/$
strip_path: false
tags:
- payments
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
name: ${NAME}-payments-api-updatepayment
namespace: ${NAMESPACE}
spec:
serviceRef:
type: namespacedRef
namespacedRef:
name: ${NAME}-payments-api
name: payments-api_updatepayment
methods:
- PUT
- OPTIONS
paths:
- ~/payments/v1/payments/(?<customernumber>[^#?/]+)/(?<checknumber>[^#?/]+)/$
strip_path: false
tags:
- payments
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
name: ${NAME}-payments-api-patchpayment
namespace: ${NAMESPACE}
spec:
serviceRef:
type: namespacedRef
namespacedRef:
name: ${NAME}-payments-api
name: payments-api_patchpayment
methods:
- PATCH
- OPTIONS
paths:
- ~/payments/v1/payments/(?<customernumber>[^#?/]+)/(?<checknumber>[^#?/]+)/$
strip_path: false
tags:
- payments
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
name: ${NAME}-payments-api-deletepayment
namespace: ${NAMESPACE}
spec:
serviceRef:
type: namespacedRef
namespacedRef:
name: ${NAME}-payments-api
name: payments-api_deletepayment
methods:
- DELETE
- OPTIONS
paths:
- ~/payments/v1/payments/(?<customernumber>[^#?/]+)/(?<checknumber>[^#?/]+)/$
strip_path: false
tags:
- payments
+17
View File
@@ -0,0 +1,17 @@
apiVersion: configuration.konghq.com/v1alpha1
kind: KongService
metadata:
name: ${NAME}-payments-api
namespace: ${NAMESPACE}
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: ${CONTROL_PLANE_REF_NAME}
name: payments-api
host: ${BACKEND_HOST}
port: 8000
protocol: http
path: /
tags:
- payments