Kong Customization
The framework generates Kong Gateway configuration automatically, but you can customize it for your specific needs. This guide explains the configuration file system and how to add your own settings.
Configuration files
Kong configuration uses a layered file system:
The framework merges kong.tsdevstack.yml and kong.user.yml to create the final kong.yml. The merge is structured per key:
- Services — combined from both files (framework routes first, then your custom services)
- Consumers: taken from
kong.user.ymlas written. The framework generates none, and no generated route authenticates with them (see Partner API keys) - Plugins: framework global plugins first (
tsdevstack-strip-identity,tsdevstack-client-ipandtsdevstack-trust), then yours fromkong.user.yml. Service-level plugins are attached inside each service definition: oidc on JWT routes, and the API key check, the per-IP ceiling andtsdevstack-api-prefixon partner routes. Kong allows one global instance per plugin name. Akong.user.ymlthat declares a framework global plugin fails generation with a hint
Customizing with kong.user.yml
Edit kong.user.yml to add global plugins or custom services. This file is created once and preserved across regenerations.
The trust header and the request-transformer
Kong proves to your backends that a request came through it with the trust header, X-Kong-Trust. Its value is the secret KONG_TRUST_TOKEN. The framework plugin tsdevstack-trust sets it on every request. Backends reject identity headers on requests without a valid trust token. See Protected Routes.
The generated kong.user.yml starts with a request-transformer that only removes Kong's request id:
Only X-Kong-Request-Id belongs in its remove list. Client-sent identity headers (X-Userinfo, X-Consumer-*, X-Credential-Identifier, X-Kong-Trust and so on) are removed by the framework plugin tsdevstack-strip-identity, which runs before authentication. The request-transformer runs after authentication, so removing identity headers there deletes the values Kong itself just set. For example, removing X-Api-Key-Consumer leaves @Partner() without a consumer name.
Files created before 0.11 add the trust header themselves, with X-Kong-Trust:${KONG_TRUST_TOKEN} under add.headers and X-Kong-Trust under remove.headers. Delete both lines. Until you do, generate-kong, infra:generate-kong and infra:build-kong stop and show the lines to delete. The gateway reads the token when it starts, and a request-transformer can't use a token read that way.
Older files may also list X-Consumer-Id, X-Consumer-Username and sometimes X-JWT-Claim-* headers in the remove list. Delete those too and keep only X-Kong-Request-Id. Generation prints a warning while identity headers are still listed.
Global plugins
Add plugins that apply to all routes:
The global rate limiter and API keys
The global rate-limiting plugin limits each caller. On routes that require login, the caller is the user from the token. On other routes, it is the client address. Visitors of the Next.js frontend count by their own address (see Client addresses).
Partner routes (/api/...) work differently. The plugin's minute, hour, day and month values are the default limits of every API key, counted per key; a key's own limits replace them. These routes also have a per-IP ceiling: framework.apiKeys.ipLimitPerMinute in .tsdevstack/config.json, 600 by default. Details in API Keys.
Client addresses
On routes without login, the gateway limits each client address. It also passes that address to your services in X-Tsdevstack-Real-IP, for their own per-IP limits (RateLimitGuard with keyGenerator: 'ip'). Routes with login are limited per user.
In the cloud, the address comes from a header set by your provider's edge. Clients cannot forge it:
Visitors of the Next.js frontend
The Next.js frontend calls the gateway from its server, in route handlers such as login and signup. On each call it tells the gateway which visitor it acts for:
- The frontend sends two headers: the visitor's address in
X-Tsdevstack-Client-IPand the secretKONG_FRONTEND_TOKENinX-Tsdevstack-Frontend-Token. It reads the visitor's address from the header named inTSDEVSTACK_CLIENT_IP_HEADER, which the deploy sets (table above). - The gateway plugin
tsdevstack-client-ipchecks the token. If it matches, the gateway limits the visitor and passes the visitor's address to your services. Routes with login still count the user. - If the token is missing or wrong, the gateway drops both headers. A client cannot pick the address it is counted by.
The frontend template does this in lib/externalApi/auth-service.api.ts. If your server calls the gateway through another generated client, add the same interceptor:
A single-page app calls the gateway from the browser. The gateway sees each visitor directly, so none of this is needed.
Partner API keys
Partner keys are not configured here. Admins create, limit, rotate and revoke them at runtime through the auth-service admin API, and the gateway checks them against Redis. See API Keys.
Earlier versions defined partners as consumers with keyauth_credentials in this file. Those keys no longer work on partner routes; generate-kong and infra:generate-kong warn while such consumers are still listed. Move the partners to API keys (Migrating from static partner keys), then delete the consumers and their key secrets.
Custom services
Add services not managed by the framework:
CORS configuration
Configure allowed origins in your secrets file:
The framework automatically converts this comma-separated string to an array in the final configuration. In the cloud, Kong's image build also adds every domain from infrastructure.json that the list is missing.
Escape hatch with kong.custom.yml
For complete control, create kong.custom.yml. When this file exists, the framework skips automatic route generation and only resolves secret placeholders.
In custom mode you own everything the framework would otherwise generate, including the security pieces:
tsdevstack-strip-identityas a global plugin. Without it, clients can send forged identity headers (X-Userinfo,X-Consumer-*) to your backends.generate-kongwarns when it is missing.tsdevstack-client-ipas a global plugin, withfrontend_token: ${KONG_FRONTEND_TOKEN}, if a Next.js frontend calls the gateway, so the gateway counts its visitors rather than the frontend server (see Client addresses).tsdevstack-trustas a global plugin, withtoken: ${KONG_TRUST_TOKEN}. Without it, backends reject identity headers. See above.tsdevstack-api-prefixon partner services (config.prefix: /api) if you publish partner routes at/api/...and your services serve the path without/api.tsdevstack-api-keyon partner services, with the Redis connection anddefault_limits, plus a service-scopedrate-limitingcounted per IP as the ceiling. Without the key plugin, partner routes check no key at all. Copy both from a generatedkong.tsdevstack.yml.
The same request-transformer check applies: identity headers in its remove list produce a warning. See Kong Plugins for what the framework plugins do.
To return to automatic generation, rename or delete the file:
Custom Lua plugins
Your own Lua plugins go in the kong-plugins/ folder at the project root and are baked into the gateway image, locally and in the cloud. See Kong Plugins.
Applying changes
After editing configuration files:
This regenerates Kong configuration and restarts the gateway.
Secret placeholders
Use ${SECRET_NAME} syntax in configuration files. The framework resolves these from your secrets files during generation:
The value is written into the gateway config, which in the cloud is part of the gateway image. Three placeholders are different: ${REDIS_PASSWORD}, ${KONG_TRUST_TOKEN} and ${KONG_FRONTEND_TOKEN}. They become references, such as {vault://env/redis-password}, that Kong resolves from its environment when it starts. Their values never reach the config or the image. A reference works only in fields Kong allows, such as the Redis password of rate-limiting and the framework plugins' tokens. A request-transformer header is not one of them.
Common customizations
Increase rate limits for a partner
Raise the limits of the partner's API key through the admin API (PATCH /auth/v1/admin/api-keys/:id). It applies on the next request, with no gateway redeploy. See API Keys.
Configure upload size limits
The default maximum request body size is 10MB, configurable via infrastructure.json:
This sets Kong's nginx client_max_body_size. Values use nginx-style format: "10m", "50m", "1g", "0" for unlimited. Requests exceeding this limit receive 413 Content Too Large.
For files larger than the configured limit, use presigned URL uploads which bypass Kong entirely. See Object Storage — File Uploads.
Add request size limits (per-route via plugin)
For more granular control, use the Kong request-size-limiting plugin in kong.user.yml:
Enable response caching
Troubleshooting
Changes not taking effect
- Run
npx tsdevstack syncto regenerate and restart
API key rejected
- Check the
errorcode in the response body against the table in API Keys - Keys from
consumersinkong.user.ymlno longer work; create the key through the admin API
Customizations lost after sync
- Edit
kong.user.yml, notkong.tsdevstack.yml - The framework file is regenerated; the user file is preserved