Skip to main content

api-gateway (Kong) — Sync Contract

Status: populated Owner: TBD (Platform / SRE) Last updated: 2026-04-17 Companion: SERVICE_OVERVIEW · DATA_MODEL · Service Template

1. Applicability​

Not applicable. The platform sync contract (edTech sync-service and SMS-Gateway equivalents) covers offline-capable client sync for business data. Kong holds no business data and is not a client-sync participant.

Ghasi-SMS-Gateway's sync contract taxonomy (server_authoritative, append_only, crdt_yjs, lww, etc.) does not map to Kong configuration.

2. How Kong configuration is kept consistent​

Configuration is declarative GitOps:

  • Source: ops/kong/<env>.kong.yaml in the application monorepo.
  • Apply: deck gateway sync from a CI runner after merge to main (staging) or tag (production).
  • Drift detection: a periodic CI job runs deck gateway diff against the live Kong and fails if the live config diverges from Git. See TESTING_STRATEGY §3.
  • Rollback: git revert + re-run deck sync (or deck gateway reset + resync from a known-good tag).

There is no offline sync, no CRDT merge, no client-side replication of Kong config.

3. JWKS cache sync​

Kong's JWT plugin pulls JWKS from auth-service at /.well-known/jwks.json (or equivalent).

AspectBehaviour
Cache TTL5 minutes (configurable)
Refresh onTTL expiry; 401-from-kid-not-found triggers an out-of-band refresh
Source of truthauth-service
Conflict policyserver_authoritative — Kong always honours the latest JWKS; local cache is best-effort

If auth-service is down during a refresh, Kong continues to validate tokens against the last-known JWKS until it expires. After expiry without refresh, JWT validation returns 503.

4. Consumer sync (when decK manages consumers)​

For static consumers (partners, internal callers) pre-provisioned in Git:

  • auth-service generates a snapshot of consumers + credentials at release time.
  • CI includes it into the decK YAML under ops/kong/consumers.yaml.
  • On deploy, Kong config is replaced atomically.

For runtime consumers (customer API keys), no Kong Consumer row exists — resolution happens per-request via the custom ghasi-api-key-lookup plugin (see APPLICATION_LOGIC §5). Cache TTL: 60 s; auth-service is the authority.

5. Summary​

Configuration is CI-deployed via decK; no offline sync applies.

6. Open questions​

  • Should consumer snapshot generation from auth-service be event-driven (pub/sub) instead of release-time batch?