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 atinfo, below Kong'snoticelevel, 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:
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:
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 examplerequest-audit). It must match thenamein yourschema.lua. handler.luaandschema.luaare required. Other Lua files in the folder are copied too and can be required askong.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:
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:
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 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:
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.
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.