API Gateway

API Gateway Guidelines

MANDATORY FOR ALL AI AGENTS: Every public REST API in a multi-service platform sits behind an API gateway. The gateway terminates TLS, validates auth, enforces edge rate limits, propagates trace context, and aggregates responses where it makes sense. Services downstream MUST trust forwarded identity headers ONLY when set by the gateway (mTLS or private network). The gateway is part of the edge tier — distinct from per-service Spring Security, which is the defense-in-depth tier.

Project-agnostic: code samples use placeholder service names (platform-auth-service, platform-payment-service), domains (api.example.com, auth.example.com), and base package (com.example.platform). Replace with your project’s actual values.

Reference implementation: KrakenD 2.13.x with Flexible Configuration + Go custom plugins. KrakenD is the recommended default for declarative, code-light gateways in JVM platforms (no JVM dependency in the gateway itself, ~10ms p99 overhead, declarative JSON config).

Companion guides:

• api-design.md — endpoint contracts that the gateway routes.
• security.md — auth tier defense in depth; JWT validation downstream.
• obs-tracing.md — W3C Trace Context propagation through and beyond the gateway.
• adr.md — gateway choice + topology + auth model are ADR-worthy.
• arch-doc-spec.md §System Context — gateway is the C1 boundary.

Companion commands:

• /arch-threat — threat-model the edge.
• /arch-deps — gateway image dependency audit.

Table of Contents

1. Principles
2. Tier Responsibilities
3. Gateway Selection Matrix
4. KrakenD — Canonical Reference
5. Configuration Split
6. Flexible Configuration Template
7. Backend Hosts + Env Overrides
8. Authentication at the Edge
9. Claims-to-Headers Forwarding
10. Skip-Paths Pattern
11. Rate Limiting at the Edge
12. CORS
13. W3C Trace Context Propagation
14. Custom Plugins (Go)
15. TLS / mTLS
16. Aggregation Patterns
17. Caching at the Edge
18. Service Discovery
19. Observability
20. Deployment
21. Anti-Patterns
22. Pre-Merge Checklist

1. Principles

• The gateway is dumb glue. Business logic NEVER lives there. The gateway routes, authenticates, rate-limits, traces, and aggregates — nothing else.
• Defense in depth. Gateway enforcement does NOT replace per-service Spring Security. Downstream services re-validate JWT (signature, exp, aud) — gateway crashes or misconfig should not be a security breach.
• Stateless. No gateway session. Every request authenticates independently via JWT.
• Declarative > imperative. Prefer declarative config (JSON / template) over plugin code. Plugins are an escape hatch for behavior that the declarative layer cannot express.
• Configuration is data. Split per concern, commit to repo, version with the gateway. Never edit configuration in a running gateway dashboard.
• Trace context is non-negotiable. The gateway MUST propagate W3C traceparent to downstream services or generate one if absent. See §13.
• mTLS between gateway and services in production. Or at minimum, services trust forwarded identity only when on a private network with mTLS at the cluster edge.

2. Tier Responsibilities

Hard rule: the gateway authenticates; it does NOT authorize per-resource. Per-resource authorization (e.g., “can user X read invoice Y?”) is a domain concern that lives in the service.

3. Gateway Selection Matrix

Decision is an ADR. Document choice + rejected options.

4. KrakenD — Canonical Reference

KrakenD is Go-based, stateless, declarative. Configuration is a single JSON file (or a template that compiles to one). Custom plugins are Go .so files dropped in a folder. No runtime DB.

4.1 Repo layout

1
platform-gw/
2
├── config/
3
│   ├── krakend.tmpl                  # Flexible Configuration template (Go template syntax)
4
│   └── settings/
5
│       ├── service.json              # name, port, timeouts
6
│       ├── hosts.json                # backend service hosts
7
│       ├── cors.json                 # CORS policy
8
│       ├── jwt.json                  # JWT + JWKS (Keycloak/Auth0/etc.)
9
│       ├── ip_resolver.json          # IP geolocation
10
│       ├── trace_context.json        # W3C Trace Context propagation
11
│       ├── rate_limit.json           # rate limiting
12
│       ├── logging.json              # structured logging
13
│       ├── metrics.json              # metrics + collection interval
14
│       ├── tls.json                  # server TLS
15
│       └── client_tls.json           # outbound TLS (to backends)
16
├── plugins/
17
│   ├── jwt-headers/                  # custom plugin: JWT → headers + skip-paths
18
│   ├── ip-resolver/                  # custom plugin: geolocation
19
│   ├── trace-context/                # custom plugin: W3C trace propagation
20
│   └── build/                        # compiled .so files (gitignored)
21
├── Dockerfile                        # multi-stage production image
22
├── docker-compose.yml                # local dev environment
23
└── Makefile                          # build + dev commands

4.2 Pinning

• KrakenD 2.13.x — pin minor in Dockerfile.
• Plugins compiled with the same Go toolchain version as the KrakenD image; mismatch breaks loading. Use a plugins/Dockerfile.builder aligned to KrakenD’s documented Go version.

5. Configuration Split

Each concern lives in its own JSON under config/settings/. The template (§6) composes them.

Split benefits: review per concern, env-promote per concern (e.g., different rate_limit.json per env), reusable across services in the platform.

5.1 Examples

service.json:

1
{
2
  "name": "platform-gw",
3
  "port": 8080,
4
  "timeout": "30s",
5
  "cache_ttl": "300s"
6
}

hosts.json (defaults, overridable via env — see §7):

1
{
2
  "auth":          "http://platform-auth-service:8080",
3
  "payment":       "http://platform-payment-service:8080",
4
  "notifications": "http://platform-notifications-service:8080"
5
}

rate_limit.json:

1
{
2
  "service_max_rate": 500,
3
  "service_client_max_rate": 50,
4
  "endpoint_max_rate": 100,
5
  "endpoint_client_max_rate": 20,
6
  "strategy": "ip"
7
}

cors.json:

1
{
2
  "allow_origins": ["https://app.example.com"],
3
  "allow_methods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
4
  "allow_headers": ["Content-Type", "Authorization", "Idempotency-Key", "Traceparent", "Tracestate"],
5
  "expose_headers": ["Content-Length", "Content-Type", "Traceparent", "Tracestate", "Trace-Id"],
6
  "max_age": "12h"
7
}

CORS rule: include Traceparent, Tracestate, and Trace-Id in expose_headers so browser clients can correlate traces in DevTools.

6. Flexible Configuration Template

KrakenD’s Flexible Configuration compiles a Go template into the runtime JSON. Settings are exposed as .<filename> variables.

config/krakend.tmpl (excerpt):

1
{
2
  "$schema": "https://www.krakend.io/schema/krakend.json",
3
  "version": 3,
4
  "name": "{{ .service.name }}",
5
  "port": {{ .service.port }},
6
  "timeout": "{{ .service.timeout }}",
7
  "cache_ttl": "{{ .service.cache_ttl }}",
8
  {{- if not .tls.disabled }}
9
  "tls": {
10
    "keys": {{ marshal .tls.keys }},
11
    "min_version": "{{ .tls.min_version }}"
12
  },
13
  {{- end }}
14
  "plugin": {
15
    "pattern": ".so",
16
    "folder": "/opt/krakend/plugins/"
17
  },
18
  "extra_config": {
19
    "plugin/http-server": {
20
      "name": [
21
        {{- if .trace_context.enabled }}"krakend-trace-context",{{ end }}
22
        {{- if .jwt.enabled }}"krakend-jwt-headers"{{ end }}
23
      ],
24
      "krakend-jwt-headers": {{ marshal .jwt }}
25
    },
26
    "telemetry/logging":  {{ marshal .logging }},
27
    "telemetry/metrics":  {{ marshal .metrics }},
28
    "router": {
29
      "@comment": "expose tracing-related response headers for browser clients",
30
      "expose_headers": ["Traceparent", "Tracestate", "Trace-Id"]
31
    }
32
  },
33
  "endpoints": [
34
    {{- range $i, $endpoint := .endpoints.list }}{{- if $i }},{{ end }}
35
    {
36
      "endpoint":      "{{ $endpoint.path }}",
37
      "method":        "{{ $endpoint.method }}",
38
      "output_encoding": "{{ default "no-op" $endpoint.output_encoding }}",
39
      "backend": [
40
        {
41
          "host":     [{{ printf "%q" (env $endpoint.host_env | default $endpoint.host_default) }}],
42
          "url_pattern": "{{ $endpoint.url_pattern }}",
43
          "encoding": "{{ default "no-op" $endpoint.backend_encoding }}"
44
        }
45
      ]
46
    }
47
    {{- end }}
48
  ]
49
}

Build at startup (KrakenD reads the compiled JSON):

krakend run -c krakend.json -d -t

7. Backend Hosts + Env Overrides

Backends declared in hosts.json should be defaults that env vars override. Lets the same template ship to all environments.

Template pattern:

1
{{ env "AUTH_HOST" | default .hosts.auth }}

Resolved at template compile time: env var if set, otherwise the hosts.json value.

Compose forwards env vars to the gateway container:

1
services:
2
  gateway:
3
    image: platform/gw:latest
4
    environment:
5
      AUTH_HOST: ${AUTH_HOST:-http://platform-auth-service:8080}
6
      PAYMENT_HOST: ${PAYMENT_HOST:-http://platform-payment-service:8080}

8. Authentication at the Edge

The gateway validates JWT at the edge. Downstream services re-validate (defense in depth).

jwt.json:

1
{
2
  "enabled": true,
3
  "jwks_url": "https://auth.example.com/realms/platform/protocol/openid-connect/certs",
4
  "issuer":   "https://auth.example.com/realms/platform",
5
  "cache_ttl_minutes": 60,
6
  "claims_to_headers": [
7
    { "claim": "preferred_username",   "header": "x-username" },
8
    { "claim": "realm_access.roles",   "header": "x-user-roles" },
9
    { "claim": "sub",                  "header": "x-user-id" }
10
  ],
11
  "skip_paths": [
12
    "/public/*",
13
    "/<service>/api/v1/login",
14
    "/<service>/api/v1/accounts/register",
15
    "/<service>/api/v1/token/refresh",
16
    "/<service>/api/v1/forgot-password",
17
    "/<service>/v1/api-docs",
18
    "/<service>/swagger-ui",
19
    "/<service>/actuator/health",
20
    "/<service>/api/v1/webhooks/*"
21
  ],
22
  "add_ip_header": true,
23
  "ip_header_name": "x-ip"
24
}

Validation contract (whether built-in KrakenD or custom plugin):

• Verify JWT signature against JWKS public keys.
• Verify iss matches configured issuer.
• Verify aud, exp, nbf claims.
• Cache JWKS keys with TTL (60 min default; refresh on rotation event if available).
• On failure: respond 401 with WWW-Authenticate: Bearer error="invalid_token".

JWKS cache rule: fail closed if cache empty AND fetch fails — never allow tokens with un-verifiable signatures.

9. Claims-to-Headers Forwarding

After validation, the gateway extracts JWT claims into forwarded request headers. Downstream services read these instead of parsing JWT themselves (Spring Security still re-validates the original token for defense in depth).

Forwarding nested claims (e.g. realm_access.roles — dot path) requires custom plugin (KrakenD built-in only forwards top-level claims).

Downstream rule: services MUST trust x-* headers only when reached via mTLS or private network. On a public network, treat them as user-controlled and re-derive from JWT.

10. Skip-Paths Pattern

Endpoints that MUST be reachable without JWT:

Pattern rules:

• Exact match: full path.
• Prefix match: trailing /* — /public/* matches /public/anything/here.
• Order independent (the matcher checks all).

Webhook rule: skip JWT, then enforce HMAC signature verification inside the service. Never expose a webhook endpoint with no signature check.

Swagger rule: in prod, EITHER disable Swagger entirely OR skip-path it but require an internal-network IP. Public Swagger leaks API surface.

11. Rate Limiting at the Edge

The gateway implements layer 1 rate limiting (broad). Per-tenant fine-grained limiting still belongs in the service.

rate_limit.json semantics:

Defaults (tune per traffic):

1
{
2
  "service_max_rate": 500,
3
  "service_client_max_rate": 50,
4
  "endpoint_max_rate": 100,
5
  "endpoint_client_max_rate": 20,
6
  "strategy": "ip"
7
}

Strategy choice:

• ip — public APIs (simple but bypassable via proxy chains; combine with CDN/WAF in front).
• header:x-user-id — authenticated APIs (post-JWT validation; cost: rate-limit applied after auth, so attacker can still cost JWT validation cycles).
• header:x-api-key — partner integrations.

Response on exceed:

1
HTTP/1.1 429 Too Many Requests
2
Retry-After: 47
3
RateLimit-Limit: 100
4
RateLimit-Remaining: 0

12. CORS

Edge-only. Browser preflight handled here; services never see OPTIONS.

1
{
2
  "allow_origins": ["https://app.example.com", "https://admin.example.com"],
3
  "allow_methods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
4
  "allow_headers": ["Content-Type", "Authorization", "Idempotency-Key", "Traceparent", "Tracestate"],
5
  "expose_headers": ["Content-Length", "Content-Type", "Traceparent", "Tracestate", "Trace-Id"],
6
  "max_age": "12h"
7
}

Hard rules:

• allow_origins: ["*"] forbidden when Access-Control-Allow-Credentials: true.
• Per-env allowlist (different cors.json for dev/staging/prod).
• Always expose Traceparent so browser clients can correlate.

13. W3C Trace Context Propagation

Full reference: obs-tracing.md §W3C Trace Context.

The gateway MUST propagate or generate W3C Trace Context. Without it, distributed tracing is incomplete from the user’s first hop.

13.1 W3C traceparent format

1
traceparent: 00-<trace-id>-<parent-id>-<flags>
2
              ^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3
              |  32 hex chars (16 bytes) — trace-id, identifies the whole trace
4
              |  16 hex chars (8 bytes)  — parent-id (span-id of the caller)
5
              |  02 hex chars (1 byte)   — flags, e.g. "01" = sampled
6
              02 hex chars version, currently always "00"

Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

13.2 Gateway behavior (canonical)

For every inbound request:

1. Parse Traceparent header. If valid → propagate as-is.
2. Else, parse legacy Trace-Id (bare 32-hex). If valid → construct 00-<traceId>-<newParentId>-01.
3. Else, generate fresh trace-id (16 random bytes hex) + parent-id (8 random bytes hex), flags 01.
4. Set both Traceparent and X-Traceparent headers on the outbound request to the backend (latter as a defensive copy for legacy consumers).
5. Log traceId, method, path, source (propagated | from-trace-id | generated), client_ip.

13.3 Custom plugin (Go) — minimal

KrakenD ships a built-in trace-context flag, but a custom plugin gives logging + legacy Trace-Id fallback. Reference shape:

1
var traceparentRegex = regexp.MustCompile(`^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$`)
2
var traceIDRegex     = regexp.MustCompile(`^[0-9a-f]{32}$`)
3

4
func handle(w http.ResponseWriter, req *http.Request) {
5
    traceparent := req.Header.Get("Traceparent")
6
    source := "propagated"
7

8
    if !traceparentRegex.MatchString(traceparent) {
9
        traceID := req.Header.Get("Trace-Id")
10
        if traceIDRegex.MatchString(traceID) {
11
            source = "from-trace-id"
12
        } else {
13
            traceID = randomHex(16)
14
            source = "generated"
15
        }
16
        parentID := randomHex(8)
17
        traceparent = fmt.Sprintf("00-%s-%s-01", traceID, parentID)
18
        req.Header.Set("Traceparent", traceparent)
19
    }
20

21
    req.Header.Set("X-Traceparent", traceparent)
22
    logger.Info("trace resolved",
23
        "traceId", traceparent[3:35],
24
        "method", req.Method,
25
        "path", req.URL.Path,
26
        "source", source,
27
        "client_ip", req.RemoteAddr,
28
    )
29
    next.ServeHTTP(w, req)
30
}

13.4 Tracestate

Vendor-specific span context — usually opaque to the gateway. Propagate as-is. Do NOT parse or generate. Order preserved.

13.5 Downstream contract

Backend services MUST:

1. Read Traceparent from inbound headers.
2. Continue the span (Micrometer Tracing auto-handles this on Spring Boot 3 when a bridge — micrometer-tracing-bridge-otel or micrometer-tracing-bridge-brave — plus a reporter — OTLP exporter or zipkin-reporter-brave — is on the classpath — see obs-tracing.md).
3. Propagate to further outbound calls (HTTP + Kafka + RabbitMQ).
4. Stamp traceId in MDC for log correlation.

14. Custom Plugins (Go)

KrakenD plugin types:

• HTTP server plugin — wraps incoming requests (before any backend call). Pattern: name: "krakend-<name>" registered in plugin/http-server.
• HTTP client plugin — wraps outgoing backend calls.
• Modifier plugin — request/response body transformation.

14.1 When to write a plugin

• Built-in KrakenD lacks a feature (nested-claim header forwarding, legacy trace-id fallback, IP geolocation).
• A behavior must be tested independently and shipped across services (write once, deploy as .so).

14.2 When NOT to

• Logic that belongs in the service domain.
• Anything stateful (gateway is stateless — DB lookups break this).
• Heavy CPU work — adds tail-latency to every request.

14.3 Build constraints

• Go toolchain version MUST match the KrakenD image’s documented Go version. Mismatch → plugin fails to load with cryptic error.
• Plugins are loaded via pattern: ".so" from folder: "/opt/krakend/plugins/". Build .so artifacts in a plugins/Dockerfile.builder that copies the same Go version.
• Test plugins in isolation with Go unit tests before integration.

14.4 Required plugin contract (minimum)

1
var HandlerRegisterer = registerer("krakend-<name>")
2

3
type registerer string
4

5
func (r registerer) RegisterHandlers(f func(
6
    name string,
7
    handler func(context.Context, map[string]interface{}, http.Handler) (http.Handler, error),
8
)) {
9
    f(string(r), r.registerHandlers)
10
}
11

12
func (r registerer) registerHandlers(_ context.Context, extra map[string]interface{}, h http.Handler) (http.Handler, error) {
13
    // parse extra config from "extra_config.plugin/http-server.<plugin name>"
14
    return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
15
        // logic here
16
        h.ServeHTTP(w, req)
17
    }), nil
18
}
19

20
func main() {} // required, never called

15. TLS / mTLS

15.1 Server-side TLS (gateway-facing)

1
{
2
  "disabled": false,
3
  "keys": [
4
    { "private_key_path": "/certs/tls.key", "public_key_path": "/certs/tls.crt" }
5
  ],
6
  "min_version": "TLS12",
7
  "max_version": "TLS13"
8
}

Hard rules:

• TLS 1.2 minimum; TLS 1.3 preferred.
• HSTS header on all HTTPS responses: Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
• Disable RC4, 3DES, CBC-with-SHA1 cipher suites.
• Automate cert rotation via cert-manager (ACME) — manual rotation is a future incident.

15.2 Outbound TLS to backends (gateway → service)

client_tls.json:

1
{
2
  "allow_insecure_connections": false,
3
  "ca_certs": ["/certs/ca.crt"],
4
  "client_certificate":         "/certs/gw-client.crt",
5
  "client_private_key":         "/certs/gw-client.key"
6
}

Production rule: mTLS to backends. Backend services authenticate the gateway via client cert.

15.3 Don’t

• "allow_insecure_connections": true in production. Audit and ban.

16. Aggregation Patterns

16.1 Single backend (the default)

1
{
2
  "endpoint": "/payments/{id}",
3
  "method": "GET",
4
  "backend": [
5
    { "host": ["{{env "PAYMENT_HOST"}}"], "url_pattern": "/api/v1/payments/{id}" }
6
  ]
7
}

16.2 Aggregation (thin client, thick gateway)

Combine multiple backends into one response. Useful when the client (mobile, SPA) would otherwise make N parallel calls.

1
{
2
  "endpoint": "/dashboard",
3
  "method": "GET",
4
  "backend": [
5
    { "host": ["{{env "USER_HOST"}}"],    "url_pattern": "/api/v1/users/me",      "group": "user" },
6
    { "host": ["{{env "INVOICE_HOST"}}"], "url_pattern": "/api/v1/invoices?limit=5", "group": "invoices" },
7
    { "host": ["{{env "BALANCE_HOST"}}"], "url_pattern": "/api/v1/balance",       "group": "balance" }
8
  ]
9
}

Trade-offs:

• • One request from client.
• • Parallel backend fan-out reduces client-perceived latency.
• − Gateway becomes coupled to backend response shapes.
• − Schema changes downstream require gateway template updates.

Rule: use aggregation for read endpoints serving a specific UI screen. NEVER aggregate for write operations (transactions are a domain concern, never a gateway concern).

16.3 Sequential calls

Use sequential: true when one backend’s response feeds another’s request. Use sparingly — couples the gateway to ordering logic.

1
{
2
  "endpoint": "/order-summary/{id}",
3
  "method": "GET",
4
  "extra_config": { "proxy": { "sequential": true } },
5
  "backend": [
6
    { "host": ["{{env "ORDER_HOST"}}"],   "url_pattern": "/api/v1/orders/{id}" },
7
    { "host": ["{{env "INVOICE_HOST"}}"], "url_pattern": "/api/v1/invoices/{resp0_invoiceId}" }
8
  ]
9
}

17. Caching at the Edge

Gateway caches GET responses for high-traffic catalog endpoints. NEVER for authenticated user-specific data.

1
{
2
  "endpoint": "/public/catalog/{id}",
3
  "method": "GET",
4
  "extra_config": {
5
    "qos/http-cache": {
6
      "max-age": 300,
7
      "shared": true
8
    }
9
  }
10
}

Rules:

• Authenticated endpoints: no-store (no edge cache).
• Public catalog: max-age 60-300 typically.
• Invalidation: avoid manual invalidation; pick a TTL the data tolerates being stale.

18. Service Discovery

Three modes:

Recommendation: keep discovery in the platform layer (K8s, Consul), not the gateway. Gateway just hits stable DNS names or env-supplied URLs.

19. Observability

19.1 Metrics

metrics.json:

1
{
2
  "collection_time": "30s",
3
  "listen_address": ":8090"
4
}

Prometheus scrape:

1
scrape_configs:
2
  - job_name: "platform-gw"
3
    metrics_path: /__stats/
4
    static_configs: [{ targets: ["gateway:8090"] }]

Key metrics to alert on:

19.2 Logs

JSON in production. Structured fields: traceId, method, path, status, latency_ms, client_ip. Never log full Authorization headers or request bodies.

1
{ "level": "INFO", "logging": { "format": "json", "level": "INFO" } }

19.3 Traces

Gateway propagates W3C trace context (§13). For gateway’s own spans (TLS termination, JWT validation, backend call), enable KrakenD’s OpenTelemetry integration:

1
{
2
  "telemetry/opentelemetry": {
3
    "service_name": "platform-gw",
4
    "exporters": {
5
      "otlp": [
6
        { "name": "otel-collector", "host": "otel-collector", "port": 4317, "use_http": false }
7
      ]
8
    }
9
  }
10
}

20. Deployment

20.1 Dockerfile (multi-stage)

1
# Stage 1: build plugins
2
FROM golang:1.22 AS plugin-builder
3
WORKDIR /plugins
4
COPY plugins/ .
5
RUN find . -name "main.go" -execdir go build -buildmode=plugin -o ../build/{}.so . \;
6

7
# Stage 2: runtime
8
FROM krakend:2.13.1
9
COPY --from=plugin-builder /plugins/build/*.so /opt/krakend/plugins/
10
COPY config/ /etc/krakend/
11
USER krakend
12
EXPOSE 8080 8090

20.2 K8s

• Deploy as Deployment with HPA (CPU + custom metric req/s).
• PodSecurityContext: non-root, read-only root FS, drop all capabilities.
• NetworkPolicy: ingress only from CDN/WAF; egress to backend services + JWKS endpoint.
• Liveness probe: GET /__health.
• Readiness probe: GET /__health after JWKS fetch succeeded.

20.3 Resource sizing

Baseline (tune per traffic):

• requests: cpu: 200m, memory: 128Mi
• limits: cpu: 1, memory: 256Mi
• 2 replicas minimum (HA), HPA up to 10.

21. Anti-Patterns

22. Pre-Merge Checklist

For PRs touching platform-gw/ or any gateway configuration:

• Change documented in PR description with rationale (decision = ADR if it affects auth model, topology, plugin set).
• service.json / hosts.json / per-concern files validated against the KrakenD JSON schema (krakend check -d -t -c krakend.json).
• No business logic added to a plugin.
• Plugin builds against the documented Go version matching the KrakenD image.
• jwt.json skip_paths reviewed — only auth flows + webhooks + health (no write endpoints).
• CORS allow_origins per env (no * with credentials).
• Traceparent, Tracestate, Trace-Id in CORS expose_headers.
• Trace context plugin (or built-in) enabled; legacy Trace-Id fallback considered.
• Rate-limit values tuned for the route (avoid one-size-fits-all 100 req/s).
• Outbound mTLS configured for production (client_tls.json).
• HSTS + TLS 1.2+ enforced; TLS 1.0/1.1 disabled.
• Metrics endpoint scraped by Prometheus; alerts updated.
• Structured JSON logging in production; no PII in logs.
• Plugin .so files NOT committed (build artifacts in CI only).
• Docker image scanned (Trivy / Grype); zero CRITICAL CVEs.
• Smoke test executed against staging — /__health returns 200, JWT validation works, trace context propagates end-to-end.
• ADR drafted if changing gateway product (KrakenD → other), aggregation policy, or JWT validation contract.