For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/customization/kong-plugins.md.

Kong Plugins

Kong ships with a long list of bundled plugins (CORS, rate limiting, request size limits, caching, and so on); you enable those in kong.user.yml without any extra setup, see Kong Customization. This page is about the other case: your own Lua plugin, baked into the gateway image.

The gateway image

tsdevstack builds one Kong image, the same one locally and in every cloud environment. The generated Dockerfile starts from kong:3.9.4, the newest open-source Kong, and adds:

  • the OIDC plugin (oidc) that validates JWTs, with nginx shared memory caches for the discovery document and the signing keys (fetched once and reused for 24 hours; a token signed with a key Kong has not seen yet triggers a refetch). A client's bad token (expired, signed with an old key, forged) gets a 401 and is logged at info, below Kong's notice level, so it doesn't show up as an error. If Kong can't fetch the discovery document or the signing keys, that is still logged as an error,
  • the framework plugins shipped with the CLI (see below),
  • every plugin in the kong-plugins/ folder at your project root.

All of them are copied into the image and listed in KONG_PLUGINS, next to Kong's bundled plugins. Local and cloud differ only in runtime settings. Locally, the config file is mounted and the Admin API is on (port 8001). In the cloud, the config is baked into the image and the Admin API is off. Three values never go into the config, locally or in the cloud: the Redis password, the trust token and the frontend token. The config refers to them ({vault://env/redis-password}), and Kong reads them from its environment when it starts.

The image definition lives in two generated files:

infrastructure/kong/
├── Dockerfile      # Generated, do not edit
├── .dockerignore   # Generated, do not edit
├── kong-plugins/   # Generated copy of the framework plugins and yours (gitignored)
└── declarative/    # Generated, empty locally (gitignored)

generate-kong (and sync) rewrite all of them. Editing the Dockerfile has no lasting effect: your changes are overwritten on the next run, and cloud builds never used that file anyway (infra:build-kong writes its own copy of the same Dockerfile into a temporary build context). If you had a hand-written Dockerfile from an older version, generate-kong overwrites it with a warning; move custom plugins into kong-plugins/.

Adding a plugin

Create one folder per plugin in kong-plugins/ at the project root:

kong-plugins/
└── request-audit/
    ├── handler.lua
    └── schema.lua

Rules, checked by generate-kong and infra:build-kong:

  • The folder name is the plugin name. Lowercase letters and digits, words joined by - or _ (for example request-audit). It must match the name in your schema.lua.
  • handler.lua and schema.lua are required. Other Lua files in the folder are copied too and can be required as kong.plugins.<name>.<file>.
  • No name collisions. A folder named like a plugin bundled with Kong (for example cors), like the OIDC plugin (oidc) or like a framework plugin fails generation with a hint. Rename it.
  • Hidden folders and loose files in kong-plugins/ are ignored. Symlinked folders are copied as their targets.

A minimal plugin that adds a response header:

-- kong-plugins/request-audit/handler.lua
local RequestAudit = {
  PRIORITY = 10,
  VERSION = "1.0.0",
}

function RequestAudit:header_filter(conf)
  kong.response.set_header(conf.header_name, "audited")
end

return RequestAudit
-- kong-plugins/request-audit/schema.lua
local typedefs = require "kong.db.schema.typedefs"

return {
  name = "request-audit",
  fields = {
    { protocols = typedefs.protocols_http },
    { config = {
        type = "record",
        fields = {
          { header_name = { type = "string", default = "X-Audit" } },
        },
      },
    },
  },
}

PRIORITY decides where your plugin runs relative to the others (higher runs first). The framework's identity-stripping plugin runs at 50000 in the access phase: a plugin with a higher priority would still see identity headers sent by the client, so keep yours below that unless you know why you need it. See Kong's plugin development guide for the handler phases and schema format.

Commit kong-plugins/. CI builds the cloud image from the repository, so a plugin that exists only on your machine never reaches the cloud.

Enabling it

Being in the image only makes a plugin available. Turn it on in kong.user.yml, like any bundled plugin, globally or on one of your custom services:

# kong.user.yml
plugins:
  - name: request-audit
    config:
      header_name: X-Audit

Getting it running

Locally, npx tsdevstack sync regenerates the build context and restarts the stack with docker compose up --build, so the gateway image is rebuilt with your plugin. If you only ran generate-kong, rebuild the gateway yourself:

docker compose up -d --build gateway

docker compose up without --build keeps the old image, which does not know your plugin, and Kong refuses to start when the config enables a plugin the image lacks.

In the cloud, the plugin ships with the gateway image:

npx tsdevstack infra:generate-kong --env dev   # after changing kong.user.yml
npx tsdevstack infra:build-kong --env dev      # builds the image with kong-plugins/ inside
npx tsdevstack infra:deploy-kong --env dev

A full npx tsdevstack infra:deploy --env dev runs these steps as well.

A fresh clone needs npx tsdevstack sync (or generate-kong) before the first docker compose up: the build context folders under infrastructure/kong/ are generated and not committed.

Framework plugins

Six plugins ship with the CLI and are always in the image. You don't enable or configure them. generate-kong does.

PluginWhereWhat it does
tsdevstack-strip-identityGlobal, in kong.tsdevstack.ymlRemoves identity headers sent by clients (X-Userinfo, X-Consumer-*, X-Credential-Identifier, X-Kong-Trust and similar) before any authentication plugin runs, so backends only ever see identity that Kong set
tsdevstack-client-ipGlobal, in kong.tsdevstack.ymlLets the Next.js frontend name the visitor it calls the gateway for, checked with the secret KONG_FRONTEND_TOKEN, so rate limits apply per visitor. Passes the client address to services in X-Tsdevstack-Real-IP. See Client addresses
tsdevstack-trustGlobal, in kong.tsdevstack.ymlSets the trust header X-Kong-Trust on every request it forwards, so your services know it came through the gateway. The token (KONG_TRUST_TOKEN) is read when Kong starts and never stored in the image
tsdevstack-opentelemetryGlobal, in kong.tsdevstack.ymlKong's own OpenTelemetry plugin with two changes: a trace the Next.js frontend already kept stays kept, whatever tracing.sampleRate says, and the trace also travels in X-Tsdevstack-Traceparent, which platforms don't rewrite. See Sampling
tsdevstack-api-keyOn each partner serviceChecks the x-api-key against the key records in Redis and enforces the key's limits; see API Keys
tsdevstack-api-prefixOn each partner servicePartner routes match /api/...; this plugin removes /api before the request reaches your service, which serves the path without it

The six are open source (Apache-2.0) and work in any open-source Kong 3.9, not only in tsdevstack projects. They are published as the tsdevstack/kong-plugins repository on GitHub, as LuaRocks packages (luarocks install tsdevstack-api-key), and as the image ghcr.io/tsdevstack/kong: Kong 3.9.4 with the six plugins and the OIDC plugin, all switched on. Each CLI release pins one version of them. Your project's gateway image is still built from the copy the CLI ships, so a project never depends on those downloads.

Don't declare them in kong.user.yml: Kong allows one global instance per plugin name, so generation fails. The same goes for Kong's bundled opentelemetry plugin, which would trace every request a second time. Don't reuse their names in kong-plugins/ either. The only place to add them yourself is a full kong.custom.yml override.