api-gateway (Kong) — Data Model

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

1. Purpose

Document where Kong stores its configuration and operational state. Kong holds no tenant business data — no customer PII, no SMS messages, no billing records, no account profiles.

2. Configuration storage

Two modes. Ghasi-SMS-Gateway prefers DB-less.

2.1 DB-less mode (preferred)

Kong data plane loads its entire configuration from a declarative YAML file at startup and on SIGHUP.

• Source of truth: ops/kong/<env>.kong.yaml in the application monorepo, managed as GitOps.
• Tool: decK (deck gateway sync in CI).
• Scope: Services, Routes, Plugins, Consumers, Credentials (via vault refs), Upstreams.
• Secrets: Referenced via Kong vault ({vault://env/<name>}). Resolved at request time from env vars, K8s secrets, or HashiCorp Vault.

Advantages: No database to operate/back up; config diff is a Git diff; rollback is a git revert + deck sync. Trade-off: Admin API is read-only; runtime consumer creation requires a config reload. That is acceptable because runtime consumer resolution uses the custom ghasi-api-key-lookup plugin, not Kong Consumer rows.

2.2 DB mode (fallback)

If Kong Enterprise features requiring the DB are later adopted (e.g. advanced rate-limiting with async sync, workspace RBAC, developer portal), we switch to PostgreSQL:

• Kong-owned PostgreSQL instance (separate from platform application DBs).
• Schema: managed by Kong migrations (kong migrations up).
• Backups: daily snapshots, PITR via WAL. RPO ≤ 1 h.
• No foreign keys to application services' databases — Kong DB is isolated.

3. Redis keyspace

Kong uses Redis only for rate limiting (the rate-limiting-advanced plugin). Cluster is shared with the platform but scoped by key prefix.

Prefix	Owner	Purpose	TTL
kong:rl:global:*	Kong	Global per-second burst counter	window
kong:rl:key:<api_key_id>:*	Kong	Per-API-key counters	window
kong:rl:acct:<account_id>:*	Kong	Per-account counters	window
kong:rl:op:<operator_id>:*	Kong	Per-operator TPS counters	window
kong:jwks:<issuer>	Kong JWT plugin	Cached JWKS (if Redis-backed rather than in-process)	5 min
kong:ghasi:apikey:<sha256>	Custom plugin	Cached API-key resolution	60 s

Namespace isolation: kong:* is reserved for Kong. Service-owned keyspaces (idempotency:*, session:*, tps:*, cache:*) belong to upstream services — see 01 Enterprise Architecture §7.

Failure mode: If Redis is unavailable, rate-limiting-advanced is configured per route to fail-closed (SMS send) or fail-open (read-only routes). See FAILURE_MODES §3.

4. decK YAML shape (illustrative)

_format_version: "3.0"
_transform: true

services:
  - name: svc-sms-orchestrator
    host: sms-orchestrator.default.svc.cluster.local
    port: 3000
    protocol: http
    connect_timeout: 2000
    read_timeout: 10000
    routes:
      - name: rt-sms-v1-send
        methods: [POST]
        paths: ["/v1/sms/send"]
        strip_path: false
        tags: [env:prod, owner:platform]
        plugins:
          - name: key-auth
            config:
              key_names: [X-Api-Key]
              hide_credentials: true
          - name: rate-limiting-advanced
            config:
              limit: [10, 300]
              window_size: [1, 60]
              identifier: consumer
              strategy: redis
              redis:
                host: "{vault://env/REDIS_HOST}"
                port: 6379
                password: "{vault://env/REDIS_PASS}"
              sync_rate: 1
          - name: request-size-limiting
            config:
              allowed_payload_size: 64  # KB

5. Tenant data

None. Kong is stateless with respect to tenant (account) business data. Rate-limit counters reference an account_id but store only an integer counter; the account_id itself is opaque to Kong and owned by auth-service.

6. Backups

Data	Location	Backup	Recovery
decK YAML	Git (ops/kong/)	Git history + backup remote	git checkout <sha> + deck sync
Vault secrets	HashiCorp Vault / K8s Secrets	Vault's own DR	Per Vault runbook
Rate-limit counters	Redis cluster	Redis AOF / snapshot	Counter loss is acceptable (short window)
Prometheus metrics	Prometheus TSDB	30-day retention; long-term via Thanos/Cortex	N/A for Kong
Access logs	Loki	14 d hot, 90 d cold archive	S3-compatible cold store

7. Storage sizing

Resource	Estimate
decK YAML	< 1 MB (all envs combined)
Kong process memory	1–2 GB per pod (Lua SHM, connection pools)
Redis rate-limit footprint	~100 B per active counter; millions of keys at peak
Loki ingest (access logs)	~500 B/request compressed
Prom metrics	~100 active series per Route × number of routes

8. PII and data residency

No PII is stored. Access logs contain IPs and user agents — scrubbed per SECURITY_MODEL. Data residency: Redis, Loki, and Prometheus all sit in the same region as Kong; see DEPLOYMENT_TOPOLOGY.

9. Open questions

• Dedicated Redis cluster for Kong vs shared platform Redis.
• If DB mode is adopted, backup cadence and DR region.